Use the Xperience by Kentico API externally

This page describes how to configure external .NET applications to work with the Xperience API. Using Xperience functionality externally is suitable for scenarios such as:

• Separate applications integrated with your main Xperience website (e.g., for the purposes of data synchronization with third party applications)
• Custom websites or applications that use Xperience as a content repository

To enable Xperience by Kentico API in your external .NET application:

1. Connect to the Xperience database
2. Add the Xperience API NuGet packages
3. Initialize the Xperience application

Connect to the Xperience database

To be able to access the Xperience database, you need to specify the appropriate connection string in your application’s configuration file.

<ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
    </None>
</ItemGroup>

Add the connection string into the ConnectionStrings object under the CMSConnectionString key:

"ConnectionStrings": {
    "CMSConnectionString": "Persist Security Info=False;database=Xperience;server=myserver;user id=username;password=mypassword;Current Language=English;Connection Timeout=120;"
 }

Add the Xperience API NuGet packages

Before you can use Xperience functionality in your application, you need to add the Xperience API NuGet packages:

1. Right-click your application’s project in the Visual Studio Solution Explorer and select Manage NuGet Packages.
2. Search for the Kentico.Xperience.Core package.
3. Install the Kentico.Xperience.Core version that matches the version of the connected Xperience database.

Initialize the Xperience application

You need to initialize the system before making calls to its API from an external project.

Web applications

Call the following code on application startup. The initialization sequence is performed only once and skipped during subsequent calls.

using CMS.Core;
using CMS.DataEngine;
using Microsoft.AspNetCore.Builder;

// ...

// Ensures a preconfigured environment (DI, configuration providers) for .NET web apps
var builder = WebApplication.CreateBuilder(args);

// Preinitializes Xperience by Kentico without building a custom DI container
CMSApplication.PreInit(false);
// Merges Xperience services with the application's service collection
Service.MergeDescriptors(builder.Services);

WebApplication app = builder.Build();

// Tells Xperience to use this app's service container for service resolution
Service.SetProvider(app.Services);

// Initializes Xperience APIs and database for use in the app
CMSApplication.Init();

Non-web applications (Console applications, etc.)

1. Edit your application’s Main method.

2. Call the following code on application startup:

   C#

   Program.cs - console app

   Copy

   
    using CMS.Core;
    using CMS.DataEngine;
    using Microsoft.Extensions.Hosting;
   
    // ...
   
    // Ensures a preconfigured environment (DI, configuration providers) for .NET console apps
    var builder = Host.CreateApplicationBuilder(args);
   
    // Preinitializes Xperience by Kentico without building a custom DI container
    CMSApplication.PreInit(false);
    // Merges Xperience services with the application's service collection
    Service.MergeDescriptors(builder.Services);
   
    var app = builder.Build();
   
    // Tells Xperience to use this app's service container for service resolution
    Service.SetProvider(app.Services);
   
    // Initializes Xperience APIs and database for use in the app
    CMSApplication.Init();
    

You can now use the Xperience API in your external application. The API allows you to perform any action available in the standard administration interface.

Additional configuration and tips

Share project files with the Xperience application

If you need to call API that works with a specific folder in the Xperience project, you can map the physical path used by the Xperience API in your external application to a specific Xperience project.

Set the SystemContext.WebApplicationPhysicalPath property to the path of your Xperience project’s root folder. Map the path before you initialize the Xperience API.

// Maps the physical path used by the Xperience API in the external application to the folder of the connected Xperience project
CMS.Base.SystemContext.WebApplicationPhysicalPath = "C:\\inetpub\\wwwroot\\Xperience";

Work with the user context

When working with the Xperience API in an external application, the default Xperience user context is not available.

To use API that relies on the context of a specific user, enclose the code into a using statement with a declared CMSActionContext instance and the appropriate UserInfo object as a parameter.

using CMS.Base;
using CMS.Core;
using CMS.Membership;

...

// Gets an object representing a specific Xperience user
UserInfo user = UserInfo.Provider.Get("Andy");

// Sets the context of the user
using (new CMSActionContext(user))
{
    // Logs an information event into the Xperience event log, with "Andy" as the user who caused the event
    Service.Resolve<IEventLogService>().LogEvent(EventType.INFORMATION, "External Application", "Event_Code", "Details");
}