Hosting ASP.NET Core applications using minimal APIs

Xperience ASP.NET Core live sites support hosting configuration using minimal APIs introduced with .NET 6.

The Xperience integration requires specific service and middleware components to function. You need to configure the application with the following requirements in mind.

The following services need to be added to the application’s IoC container:

• 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 .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.
  • Moreover, this method call is also used to enable certain Xperience features for the live site.

• Support for controllers and views – added via IServiceCollection.AddControllersWithViews.

• Authentication services – added via IServiceCollection.AddAuthentication.

And the project’s middleware pipeline must contain the following middleware:

• System initialization (InitKentico) – bootstraps the Kentico integration. Must be called first in the middleware pipeline.
• Static files (UseStaticFiles) – used by Xperience to serve files required by the page and form builder features, media library files, etc.
• Xperience middleware (UseKentico) – registers middleware and configuration required by the system. This call also adds the framework’s routing (UseRouting) and session (UseSession) middleware.
• Cookie policy (UseCookiePolicy) – required due to the dual-application architecture of Xperience sites, and for the system’s cookie support.
• Cross-origin resource sharing (UseCors) – required due to Xperience’s dual-application architecture. You do not need to explicitly add the corresponding service classes (using IServiceCollection.AddCors). These services are added as part of the IServiceCollection.AddKentico method.
• Authentication middleware (UseAuthentication) – required by certain system features, such as the page builder (when accessing the live site via the administration application).

The following code demonstrates the required service registration and recommended middleware order. Ellipsis indicate breaks where additional middleware may be inserted:

using Kentico.Web.Mvc;

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

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

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

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

// These three middleware components must be called in this specific order, without anything in between
app.InitKentico();
app.UseStaticFiles();
app.UseKentico();
...

app.UseCookiePolicy();
...

app.UseCors();
...

app.UseAuthentication();
...

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

// Starts the application
app.Run();

The Xperience live site application is now configured. For information about the general configuration process and more optional customizations, see Starting with ASP.NET Core development.

Continue by setting up local hosting for the application.

Setting up local hosting for the Core application

You have two options when setting up a development hosting environment for the live site project:

1. Host the Core application on the same domain under IIS together with the Xperience administration application (registered to IIS by the installation process).
2. Host the Core application on a different domain.

Hosting on the same domain

In this case, you need to set up either in-process or out-of-process hosting under IIS. For a detailed configuration guide, see Host ASP.NET Core on Windows with IIS.

The main benefits of this approach are:

• no need to configure cookie SameSite.
• the site does not need to run under HTTPS (no need to generate a local SSL certificate).

Hosting on different domains

When hosting the Xperience administration and the Core live site project on different domains (e.g., when testing/debugging changes using IIS Express), you need to use HTTPS for both applications due to cookie SameSite requirements imposed by modern browsers. This involves performing the following:

• Set up hosting for the Core application. See Host and deploy ASP.NET Core.
• Generate and register development SSL certificates for your local servers.
• Configure Xperience to send cookies with the appropriate SameSite configuration.

This approach has the benefit of closely mimicking the final configuration of the production deployment.

Alternatively, you can use IKenticoServiceCollection.DisableVirtualContextSecurityForLocalhost from the Kentico.Web.Mvc namespace (present by default in the blank Core project created by the installation process). Call the method when adding application services in the ConfigureServices method in the application startup class. 

The method ensures preview links work even without correct client-side cookies (due to missing SameSite prerequisites) by disabling the corresponding authentication checks. This allows you to skip the aforementioned environment setup.

var builder = WebApplication.CreateBuilder(args);

var kenticoServiceCollection = builder.Services.AddKentico(); 

if (builder.Environment.IsDevelopment())
{
    kenticoServiceCollection.DisableVirtualContextSecurityForLocalhost();
}