---
title: Hosting ASP.NET Core applications using minimal APIs
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Xperience ASP.NET Core live sites support hosting configuration using [minimal APIs](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/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](https://docs.microsoft.com/aspnet/core/fundamentals/logging/) and by default logs all application errors to the [Xperience event log](https://docs.kentico.com/13/developing-websites/troubleshooting-websites/working-with-the-system-event-log.md). The logging severity and verbosity can be configured via [application settings](https://learn.microsoft.com/aspnet/core/fundamentals/logging#configure-logging).
  - Moreover, this method call is also used to enable certain [Xperience features](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development/enabling-xperience-features-in-asp-net-core-applications.md) 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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/middleware/) must contain the following middleware:

- System initialization (InitKentico) – bootstraps the Kentico integration. **Must** be called first in the middleware pipeline.
- [Static files](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/static-files/) (UseStaticFiles) – used by Xperience to serve files required by the [page](https://docs.kentico.com/13/developing-websites/page-builder-development.md) and [form](https://docs.kentico.com/13/developing-websites/form-builder-development.md) builder features, [media library](https://docs.kentico.com/13/managing-website-content/working-with-files/media-library-files.md) files, etc.
- Xperience middleware (UseKentico) – registers middleware and configuration required by the system. This call also adds the framework's routing ([UseRouting](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.endpointroutingapplicationbuilderextensions.userouting)) and session ([UseSession](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.builder.sessionmiddlewareextensions.usesession)) middleware.
- Cookie policy (UseCookiePolicy) – required due to the dual-application architecture of Xperience sites, and for the system's [cookie support](https://docs.kentico.com/13/developing-websites/working-with-cookies.md).
- [Cross-origin resource sharing](https://docs.microsoft.com/en-us/aspnet/core/security/cors/) (UseCors) – required due to Xperience's [dual-application architecture](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core.md). 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:

```csharp title="Program.cs"

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](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development.md).

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](#hosting-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-different-domains).

### 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](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/).

The main benefits of this approach are:

- no need to configure cookie [SameSite](https://docs.kentico.com/13/developing-websites/working-with-cookies/configuring-cookie-samesite-mode.md).
- 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](https://docs.kentico.com/13/developing-websites/working-with-cookies/configuring-cookie-samesite-mode.md) requirements imposed by modern browsers. This involves performing the following:

- Set up hosting for the Core application. See [Host and deploy ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy).
- Generate and register development SSL certificates for your local servers.
- Configure Xperience to send cookies with the appropriate [SameSite configuration](https://docs.kentico.com/13/developing-websites/working-with-cookies/configuring-cookie-samesite-mode.md).

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.

> **Warning:** **Warning:** Use _DisableVirtualContextSecurityForLocalhost_ **ONLY** for local development. The method disables authentication checks for [preview links](https://docs.kentico.com/13/developing-websites/retrieving-content/adding-preview-mode-support.md), allowing anyone with valid preview URLs unrestricted access to the site.

```csharp title="Program.cs - application service registrations"

var builder = WebApplication.CreateBuilder(args);

var kenticoServiceCollection = builder.Services.AddKentico(); 

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

```