Use the Xperience by Kentico API externally

✖
Copy to clipboard

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:

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

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:

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

  1. Edit your application’s Main method.
  2. 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.

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.

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