Manually setting up ASP.NET Core projects

If you already have an existing Xperience administration instance and do not wish to add new projects using the installer, you can set up a new ASP.NET Core site via the following process: 

  1. Set up a new site in the Xperience administration
  2. Create and configure a new live site ASP.NET Core project

This process mimics steps the installer performs in the background when installing new ASP.NET Core projects.

Setting up a new site in the Xperience administration interface

Install a new Xperience administration instance or use an existing one.

  1. Open the Xperience administration interface.
  2. Navigate to the Sites application.
  3. Click New site.
  4. Continue with the remaining steps of the wizard and finish creating the new site.
  5. Edit your new site and make sure the Presentation URL on the General tab is set correctly. This is the URL that will be used for the site presented by your ASP.NET Core application. For example, http://localhost/CoreApplication or
  6. Click Save.

Next, you need to set up the synchronization mechanism:

  1. Open the Settings application.
  2. Navigate to Versioning & Synchronization -> Web farm.
  3. Set the Web farm mode to Automatic.
  4. Click Save.

At this point the new site and your Xperience instance are set up to be used with an ASP.NET Core application.

Creating a new ASP.NET Core live site project

  1. Open Visual Studio and create a new project.

  2. Select ASP.NET Core Web App.

    .NET 6 application templates

    The default application template for ASP.NET Core Web Apps in .NET 6 and later is based on minimal APIs. See Hosting ASP.NET Core applications using minimal APIs to learn how to set up the application pipeline using the minimal APIs approach.

    • Enter a name for the project and click Create.
  3. Select a template and click Create.

  4. Open the NuGet package manager and install the Kentico.Xperience.AspNetCore.WebApp (with all dependencies).

  5. Open the application’s settings file and:

    • Add a connection string to your Xperience database. We recommend copying the exact connection string from the web.config file of the related Xperience administration project.

        "ConnectionStrings": {
                "CMSConnectionString": "Persist Security Info=False;database=Xperience;server=myserver;user id=username;password=mypassword;Current Language=English;Connection Timeout=120;"
    • Copy the value of the CMSHashStringSalt appSettings key from the web.config of the Xperience project. This ensures that the Core application generates hashes using the same salt value as the Xperience application (for example for macro signatures or page preview links).

        "CMSHashStringSalt": "e68b9ad6-a461-4707-8e3e-ece73f03dd02"
  6. In the application’s startup class, add service classes and middleware required by the Xperience integration.

  7. (Optional) Enable additional Xperience features you wish to use in your project.

  8. Configure hosting for the application. This step depends on your environment and requirements. If you are unsure, refer to the Microsoft documentation for help in choosing a suitable hosting model.

The ASP.NET Core web application is now connected to the Xperience administration application. If you run the Core site, the Xperience application registers the connected projected as a new web farm server. You can see it in the Web Farms application in the Xperience administration interface.