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:
- 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.
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 CMSApplication.Init
method before you begin interacting with the API (for example during application startup or within requests that make use of the API). The initialization sequence is performed only once and skipped during subsequent calls:
using CMS.DataEngine;
...
CMSApplication.Init();
Non-web applications (for example Console applications)
- Edit your application’s
Main
method. - Call the
CMSApplication.Init
method at any point before the first call to the Xperience API.
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 (for example Console applications), 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");
}