Using the Xperience API externally

This page describes how to configure external ASP.NET applications so that they support the Kentico Xperience API. Using Xperience functionality externally allows you to create scenarios such as:

Separate applications integrated with your main Xperience website
Custom websites or applications that use Xperience as a content repository

Start Visual Studio and open your external application’s project. You need to perform the following steps:

Connect to the Xperience database
Integrate the Xperience API libraries
Initialize the Xperience application

License requirements

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, WCF services, etc.), you need to have a valid license for the given domain.

Add the license via the administration interface of the connected Xperience application – the license is available through 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.

Connecting to the Xperience database

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

Add the connection string into the configuration/connectionStrings section using an <add> element named CMSConnectionString.




 <configuration>
  <connectionStrings>

    ...

    <add name="CMSConnectionString" connectionString="Persist Security Info=False;database=Xperience;server=myserver;user id=username;password=mypassword;Current Language=English;Connection Timeout=120;" />

  </connectionStrings>

Tip: We recommend copying the exact connection string from the web.config file of your Xperience administration web project.

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

By default, the system looks for application settings in the following root-level file:

web applications: appsettings.json
other (e.g., Console applications): app.config

Add the connection string into the ConnectionStrings section 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.

Integrating Xperience API libraries

Before you can use Xperience functionality in your application, you need to add the libraries containing the required code:

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

Maintaining Kentico.Xperience.Libraries

If you upgrade or hotfix 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.

Initializing the Xperience application

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

Web applications

Edit your application’s Global.asax file (create the file if necessary).

Execute the CMSApplication.Init method in the Application_BeginRequest method:




 using CMS.DataEngine;

 ...

 void Application_BeginRequest(object sender, EventArgs e)
 {
     CMSApplication.Init();
 }

Non-web applications (for example Console applications)

Edit your application’s Main method.
Execute the CMSApplication.Init method at any point before the first call of 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.

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.
Execute the CMSApplication.Init method at any point before the first call of 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.

Using 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 generated wrapper classes for objects, custom module classes, custom implementations of interfaces 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 Adding custom assemblies.

WCF services

If implementing custom WCF services within the Xperience web project, you need to initialize the application before calling the Xperience API within the service code.

Otherwise you may encounter errors if the first request that starts the application is destined for the WCF service. The standard initialization does not occur, because WCF requests are not processed by the ASP.NET HTTP runtime. For more information, see the WCF Services and ASP.NET article.

For example, you can execute the CMSApplication.Init method within the constructor of your WCF service class.

Additional configuration and tips

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. For example, you can use this approach if you wish to externally update or rebuild the files of locally stored search indexes.

Set the SystemContext.WebApplicationPhysicalPath property to the path of your Xperience project’s CMS folder. Map the path before you initialize the Xperience API (i.e. call CMSApplication.Init), for example in the Application_Start method of Global.asax, or in your application’s Main method.

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\\CMS";

Working with the user context

When working with the Xperience API in an external application, the default Xperience user context is not available. The standard API for getting the current user ( CMS.Membership.MembershipContext.AuthenticatedUser ) always returns the “public” user when called externally.

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

Handling application settings in ASP.NET Core console applications

When calling the Xperience API outside of web applications (e.g., console applications), the system is by default configured to look for application settings in a root-level app.config file.

If you wish to store application settings in a different file or location, create a custom code-only module and substitute the default implementation with a custom IConfiguration provider during the module’s preinitilization. For example:




using Microsoft.Extensions.Configuration;
using CMS.Core;

...

protected override void OnPreInit()
{
    // Registers a configuration provider configured to look
    // for application settings in an 'appsettings.json' file.
    // This overrides the default registration.
    Service.Use<IConfiguration>(() => new ConfigurationBuilder()
        .AddJsonFile("appsettings.json", true, true)
        .Build());
}