Configure new projects

This page covers the configuration of newly installed Xperience projects. The process can be divided into the following main steps:

1. Configure the project’s startup.
2. (Optional) Enable email-sending functionality.
3. (Optional) Enable additional Xperience features according to your requirements.
4. (Optional) Miscellaneous application configuration.

Configure application startup

The Xperience ASP.NET Core integration requires specific service and middleware components to function. You need to configure your application’s startup with the following requirements in mind.

Add the following services to the application’s service collection:

• Xperience services – added via IServiceCollection.AddKentico.
  • The AddKentico call also adds a logging provider with the KenticoEventLog alias. The logging provider is built using conventional ASP.NET Core logging API and by default logs all application errors to the Xperience event log. The logging severity and verbosity can be configured via application settings.
• Framework support for the MVC architecture – added via IServiceCollection.AddControllersWithViews.
  Newtonsoft.Json response data formatters not supported

  Response data formatters based on Newtonsoft.Json are not globally compatible with Xperience applications. Installing the Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet package and calling AddNewtonsoftJson in the application’s service configuration may cause issues with certain parts of the system’s functionality.

The project’s middleware pipeline must contain the following middleware in the listed order (see the code snippet below):

• System initialization (InitKentico) – bootstraps the Xperience by Kentico integration. Must be called first in the middleware pipeline.
• Static files (UseStaticFiles) – used by Xperience to serve files required by the Page Builder and Form Builder features, media library files, etc.
• Cookie policy (UseCookiePolicy) – required for the system’s cookie support.
• Authentication middleware (UseAuthentication) – required by certain features, such as Page Builder (when accessing the live site via the Xperience administration).
• SaaS environment initialization (UseKenticoCloud) – only for projects that will be deployed to the SaaS environment.
• Xperience middleware (UseKentico) – registers middleware and configuration required by the system. This call also adds the framework’s routing (UseRouting) middleware.

The following code demonstrates required service registration and recommended middleware order. Ellipsis indicate breaks where other middleware may be added:

using Kentico.Web.Mvc;

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

// Application service registrations
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKentico();
builder.Services.AddAuthentication();
builder.Services.AddControllersWithViews();

// Application middleware pipeline configuration
var app = builder.Build();

// These middleware components need to be called in this specific order
app.InitKentico();
app.UseStaticFiles();

...
app.UseCookiePolicy();
...

app.UseAuthentication();

// Required for projects that will be deployed to the SaaS environment
app.UseKenticoCloud();

app.UseKentico();
...

// Adds system routes such as HTTP handlers and feature-specific routes
app.Kentico().MapRoutes();

// Starts the application
app.Run();

using Kentico.Web.Mvc;
...

builder.Services.Configure<IISApplicationInitializationOptions>(options =>
{
    options.UseDefaultSystemResponseForPreload = true;
});

Middleware required by Xperience

The Xperience integration configures its required middleware components using options classes stored in the application’s service container (following the options pattern).

When adding custom configuration for middleware used by the Xperience integration, do not configure the middleware components directly within the corresponding Use<Middleware> methods (by directly passing their options objects). If a configuration object is passed directly to middleware registration, the framework disregards all configuration stored in the service container. As Xperience relies on certain configuration options stored within the service container, overriding middleware configuration in this fashion may break Xperience functionality dependent on the corresponding middleware.

Instead, add custom middleware configuration into the application’s service container using IServiceCollection.Configure or IServiceCollection.ConfigureOptions methods. This way configuration set by the Xperience integration does not get overridden.

// Configures options for the Static files middleware
builder.Services.Configure<StaticFileOptions>(o =>
{
    //...
});

...

app.UseStaticFiles();

Application configuration

This section covers miscellaneous configuration options you may wish to implement for your application.

Application setting keys

Xperience applications support the ASP.NET Core configuration provider approach for application settings (configuration keys). The system looks for application settings in the sources specified by the application’s IConfigurationBuilder.

Similar to any other .NET application, you can use the Microsoft.Extensions.Configuration.IConfiguration service to retrieve the values of individual keys. For example:

using Microsoft.Extensions.Configuration;

// Service instance provided by dependency injection
private readonly IConfiguration configuration;

// Retrieves the value of the 'CMSCIRepositoryPath' key
var path = configuration["CMSCIRepositoryPath"];

// Retrieves the value of the 'CMSConnectionString' key nested within the ConnectionStrings object
var connectionString = configuration["ConnectionStrings:CMSConnectionString"];

Additionally, Xperience provides various settings that allow users in the administration to enable and configure individual features. Such settings store their values in the database. To learn how to work with Xperience settings, see Settings.

Application settings for different SaaS deployment environments

You can use dedicated appsettings.{Environment}.json files to configure different application configuration values for each environment. Apart from default ASP.NET Core environments, QA and UAT environments are available for SaaS deployments according to your service plan. Corresponding names for application settings files are appsettings.Qa.json and appsettings.Uat.json.

Once you create these files locally, they are included in the deployment package when it’s generated and later uploaded to the Xperience Portal.

Startup options in configuration files

You can use ASP.NET Core configuration providers to separate the options from the application’s startup code to a configuration source, such as the default appsettings.json file. This allows you to make runtime changes to options, without needing to adjust the startup code or restart the application (depending on the specifics of your selected configuration source).

// Separates the SmtpOptions to a configuration file section
builder.Services.AddXperienceSmtp();
builder.Services.Configure<SmtpOptions>(builder.Configuration.GetSection("SmtpOptions"));

{
  "SmtpOptions": {
    "Server" : {
      "Host":"smtp.server.com",
      "Port": 587
    }
  }
  ...
}