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:
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.
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.
<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;"
}
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:
- Right-click your application’s project in the Visual Studio Solution Explorer and select Manage NuGet Packages.
- Search for the Kentico.Xperience.Core package.
- 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.
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.)
Edit your application’s
Main
method.Call the following code on application startup:
C#Program.cs - console appusing 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.
// 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");
}