--- title: Starting with ASP.NET Core development related: - https://docs.kentico.com/13/installation/installing-xperience.md - https://docs.kentico.com/13/configuring-xperience/managing-sites/managing-site-license-keys/licensing-for-xperience-applications.md - https://docs.kentico.com/13/developing-websites/defining-website-content-structure.md - https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/deploying-and-hosting-asp-net-core-applications.md --- > 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). This page covers how to set up an environment for developing Xperience applications under ASP.NET Core. The process consists of the following main steps: 1. [Install](#installing-asp.net-core-projects) a blank ASP.NET Core project. 2. [Set up a local hosting environment](#setting-up-local-hosting-for-the-core-application). 3. [Configure the project's startup](#configuring-application-startup). 4. (Optional) [Enable additional 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) according to your requirements. 5. (Optional) Configure the application's [preview mode](#setting-up-preview-mode-for-pages). 6. [Start developing your site](#next-steps). ## Installing ASP.NET Core projects The recommended way of creating new ASP.NET Core projects is via the installer: 1. Run the Xperience installer. 2. Select the **Custom installation** option and then the **ASP.NET Core** development model. 3. In the **Installation type** step, choose the **New site** option and enter a **Name** for your new site and project. 4. Configure the remaining options and finish the installation. > **Info:** See [Installing Xperience](https://docs.kentico.com/13/installation/installing-xperience.md) for a step-by-step guide. After completing the installation, you have two separate web projects – a blank ASP.NET Core project suitable for the development of a new site, and an Xperience project that provides the content editing and administration interface. Both projects are connected to the same database and automatically configured to work together. See [next steps](#next-steps) for a list of follow-up topics concerned with building Xperience applications. > **Tip:** If you already have an existing Xperience administration instance and do not wish to add new Core projects using the installer, you can also set up a new Core site manually. See [Manually setting up ASP.NET Core projects](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development/manually-setting-up-asp-net-core-projects.md). ## Setting up local hosting for the Core application You have two options when setting up a development hosting environment for the installed Core 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). > **Tip:** **Minimal APIs support** > > Xperience supports application hosting using the minimal APIs approach introduced in .NET 6. Hosting setup using this method is described on [Hosting ASP.NET Core applications using minimal APIs](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development/hosting-asp-net-core-applications-using-minimal-apis.md). ### 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 correctly set client-side cookies (due to missing SameSite prerequisites) by disabling the corresponding authentication checks. When using this configuration, you do not need to perform the aforementioned setup to get started developing locally. > **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 public IWebHostEnvironment Environment { get; } // Constructor for the application's startup class used to inject required dependencies public Startup(IWebHostEnvironment environment) { Environment = environment; } // This method gets called by the runtime. Use this method to add services to the container. public void ConfigureServices(IServiceCollection services) { var kenticoServiceCollection = services.AddKentico(); if (Environment.IsDevelopment()) { kenticoServiceCollection.DisableVirtualContextSecurityForLocalhost(); } ... } ``` ## Configuring application startup The Xperience ASP.NET Core integration requires specific service and middleware components to function. You need to configure you application's startup with the following requirements in mind. Add the following services to the application's container: - Xperience services – added via **IServiceCollection.AddKentico**. > **Info:** 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). - 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/) needs to contain the following middleware: - [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)) middlewares. - Cookie policy (UseCookiePolicy) – required due to the dual-application architecture of Xperience sites, 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 add the corresponding service classes (using _IServiceCollection.AddCors_) explicitly. 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 required service registration and recommended middleware order. Ellipsis indicate breaks where other middleware may be inserted: ```csharp title="Recommended middleware order" public void ConfigureServices(IServiceCollection services) { services.AddKentico(); services.AddControllersWithViews(); services.AddAuthentication(); ... } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { ... app.UseStaticFiles(); ... app.UseKentico(); ...- app.UseCookiePolicy(); ... app.UseCors(); ... app.UseAuthentication(); ... app.UseEndpoints(endpoints => { // Adds system routes such as HTTP handlers and feature-specific routes. endpoints.Kentico().MapRoutes(); ... }); } ``` > **Tip:** The blank ASP.NET Core project created by the [installation process](https://docs.kentico.com/13tutorial/developer-tutorial/asp-net-core-development-tutorial/setting-up-an-xperience-core-project.md) comes with a startup class configured according to the specified requirements. ### Configuring required middleware The Xperience integration configures the required middleware using options from the application's service container. When adding custom middleware configuration for your project, **do not** configure middleware components directly within the corresponding _UseMiddleware_ methods. 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 will break Xperience functionality dependent on the corresponding middleware. Instead, register custom middleware configuration directly within the application's service container in **ConfigureServices** using [IServiceCollection.ConfigureOptions](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.optionsservicecollectionextensions.configureoptions) methods. This way no configuration set by the Xperience integration gets overridden. > **Note:** **Options post-configuration** > > Xperience sets the following options during [options post-configuration](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/options#options-post-configuration): > > - **SessionOptions.IdleTimeout** to 20 minutes. > - **SessionOptions.Cookie.IsEssential** to **true**. > > If you need to override these settings, call the _PostConfigure_ method after _IServiceCollection.AddKentico_. ## Setting up preview mode for pages Preview mode in Xperience provides a way to view the latest version of pages before they are published (for example when using [Workflows](https://docs.kentico.com/13/managing-website-content/working-with-pages/using-workflows.md)). The system supports preview mode by default, but you may need to set up and configure related functionality. The configuration required to use preview mode differs based on your site's [routing mode](https://docs.kentico.com/13/developing-websites/implementing-routing.md): - On sites using [content tree-based](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md) routing, preview mode works automatically for all [page types](https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types.md) with the [URL feature](https://docs.kentico.com/13/developing-websites/defining-website-content-structure/managing-page-types/creating-page-types.md) enabled. - On sites running in the [custom routing](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md) mode, you need to specify the URL pattern (in the Xperience administration) for your page types. The URL pattern is then used to create URLs to the content presented by the external application. Preview URLs for pages are used in the following scenarios: - When viewing pages in **Preview** mode in the **Pages** application. - When editing pages via the [page builder](https://docs.kentico.com/13/developing-websites/page-builder-development.md) on the **Page** tab of the **Pages** application. - When generating preview links for pages in **Pages -> Properties -> URLs -> Preview URL**. See: [Sending links to unpublished pages](https://docs.kentico.com/13/managing-website-content/working-with-pages/sending-links-to-unpublished-pages.md) The preview URLs the system generates for pages consist of additional information, such as a hash for validating the URL. > **Note:** **Preview mode and cookie SameSite requirements** > > Preview mode is used by the Xperience administration to preview content from the live site application. The feature relies on certain cookies transmitted between the two applications to work correctly. > > If your administration and live site applications are hosted on separate domains, you need to configure the system to send cookies with the appropriate _SameSite_ mode when communicating under preview mode. See [Configuring cookie SameSite mode](https://docs.kentico.com/13/developing-websites/working-with-cookies/configuring-cookie-samesite-mode.md). ## Application configuration This section covers miscellaneous configuration options you may wish to implement for your application. ### Replacing the default service container Xperience adds all of its services into the application's [IServiceCollection](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.iservicecollection) during the _IServiceCollection.AddKentico()_ call in the _ConfigureServices_ method. This approach is completely independent of the dependency injection provider used by the application. You can use any third-party service container that [supports ASP.NET Core 3.1 or higher](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-3.1#default-service-container-replacement). For example, to substitute the default Microsoft service container with [Autofac](https://autofac.org/): 1. Add the **Autofac.Extensions.DependencyInjection** NuGet package to your project. 2. In the **CreateHostBuilder** method call _IHostBuilder.UseServiceProviderFactory(new AutofacServiceProviderFactory())_. ```csharp public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) // The UseServiceProviderFactory call attaches the // Autofac provider to the generic hosting mechanism. .UseServiceProviderFactory(new AutofacServiceProviderFactory()) .ConfigureWebHostDefaults(webBuilder => { webBuilder .UseStartup(); }); ``` 3. (Optional) Add a **ConfigureContainer(ContainerBuilder builder)** method to your application's startup class (**Startup.cs** by default). Within this method, you can add services using Autofac's registration API. See the [Autofac documentation](https://autofaccn.readthedocs.io/en/latest/integration/aspnetcore.html#asp-net-core-3-0-and-generic-hosting) for details. The application now uses Autofac for dependency resolution. ### Working with application settings Xperience applications running on ASP.NET Core support the [configuration provider](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration) approach for application settings. The system looks for application settings in the sources specified by the application's _[IConfigurationBuilder](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration#default-configuration)_ . Similar to any other .NET Core application, you can use the _Microsoft.Extensions.Configuration.IConfiguration_ service to retrieve the values of individual keys. For example: ```csharp 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"]; ``` > **Info:** **Application settings in .NET Core console applications** > > When calling Xperience API from [console applications](https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-xperience-api-externally.md), 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](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md). For example: > > ```csharp > > 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(() => new ConfigurationBuilder() > .AddJsonFile("appsettings.json", true, true) > .Build()); > } > > ``` ## Next steps After you have a new project up and running, you can continue with building your website. Here are some topics to get you started: - [Defining website content structure](https://docs.kentico.com/13/developing-websites/defining-website-content-structure.md) - [Page builder development](https://docs.kentico.com/13/developing-websites/page-builder-development.md) - [Integrating Xperience membership](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/integrating-xperience-membership.md) > **Tip:** Set up your ASP.NET Core site to provide a redirect that sends users to the administration interface of the connected Xperience instance upon accessing a predetermined URL (e.g., **\~/admin**). The redirect can provide a smoother experience for content editors and other staff working on the site by eliminating the need to manually switch between multiple domains. See [Adding an administration redirect to ASP.NET Core sites](https://docs.kentico.com/13/developing-websites/developing-xperience-applications-using-asp-net-core/starting-with-asp-net-core-development/adding-an-administration-redirect-to-asp-net-core-sites.md) for more information.