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

Limitations of SaaS deployments

You cannot connect to Xperience applications deployed to the SaaS environment from external .NET applications.

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

  1. Obtain and register additional license keys, if needed:

    Note: Xperience by Kentico versions 29.3.0 and newer introduce an updated licensing model that doesn’t require registering a license key for each active domain. The information below applies for Xperience versions lower than 29.3.0 and will be removed with the end of the licensing transition period.
    • The Xperience API performs license checks even when running in an external application. For applications that run under a different domain than your main site (web applications, web services, etc.), you need to have a valid license key for the given domain. Add the license via the administration interface of the connected Xperience application – the license is available in the shared database.
    • In some cases, e.g., when an external web application needs to modify data in Xperience, you may also need to add the application’s domain as a domain alias of your main site.
  2. Connect to the Xperience database

  3. Add the Xperience API NuGet packages

  4. 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.

If you are storing application configuration in files on the file system, make sure their Copy to output directory is set to Always in the .csproj.

XML
Example

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

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

JSON


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

Tip: We recommend copying the exact connection string from the configuration file of your Xperience application.

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.

Maintaining Kentico.Xperience.Core package version

If you update the related Xperience project and its database to a newer version, you also need to update the NuGet packages to a matching version in your external application.

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.

C#
Program.cs - web app

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
    
     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.

Custom code that requires discovery

For external projects that compile into a different output type than a DLL assembly (console applications, etc.), do NOT directly add any custom classes that need to be detected during the API initialization. This includes classes registered using attributes, such as custom module classes, custom implementations of services or providers, etc. The system is only able to discover such code within assemblies.

Instead, add the code into a Class Library project with the AssemblyDiscoverable attribute and reference the assembly from your project. See Integrate custom code.

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.

C#
Example


// 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.

C#
Example

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");
}