Deploying and hosting ASP.NET Core applications

This page covers hosting requirements and basic deployment scenarios for the ASP.NET Core live site application. For hosting requirements of the Xperience administration application (running ASP.NET Web Forms), see System requirements.

Hosting requirements 

  • ASP.NET Core 3.1.5 or newer
  • A hosting environment supporting ASP.NET Core 3.1
  • Hosting plan parameters:
    • Minimum: 4 GB memory (RAM), 200 MB database size
    • Recommended: 8 GB memory, 1 GB database size

    Note: The recommended hosting parameters depend on the scale and implementation details of each project. Very large or heavily trafficked websites may have significantly higher requirements. For virtual hosting servers, the listed values refer to the memory capacity available for your web application, not the server's overall resources.

Publishing and deploying projects

This section describes a basic publishing and deployment process for Xperience ASP.NET Core applications. 

On this page

  1. Publish the Core project to the desired directory using dotnet publish.
  2. Set up a hosting environment and transfer the published project. For details, refer to Microsoft's documentation for your chosen hosting method and platform (on-premise Windows or Linux server, Azure, Docker, etc.): Host and deploy ASP.NET Core

  3. Deploy your Xperience database. You can choose between the following approaches:
    1. Restore a database backup on your hosting SQL server, and manually update the connection string of both projects.
      – OR – 
    2. Install a new database on your hosting SQL server and use the Xperience Export/import feature to transfer the site:
      1. Delete the connection string from the configuration files of the live site and administration projects.
      2. Open the Sites application on your local development instance and click Export site ( ) next to the site that you want to deploy.
      3. Go through the Site export wizard
        • The system saves the export package into the <administration project>\CMS\CMSSiteUtils\Export folder.
      4. Copy the exported package into the <administration project>\CMS\CMSSiteUtils\Import folder on the hosting server .
      5. Open the administration interface of the deployed project in a browser.
      6. Create a new Xperience database on your hosting SQL server.
      7. At the end of the Database installation wizard, choose to import your existing site (from the previously exported package).
      8. Copy the new connection string from the web.config of the deployed administration project into the configuration file of your live site project.

    Database server time zones

    If possible, use the same time zone for both your local environment and the production server hosting your database. Otherwise you may encounter time shift problems with the deployed data, for example in the settings of scheduled tasks.

    If you cannot synchronize the time zones, we recommend that you verify and reconfigure the timing settings of scheduled tasks after the deployment.

  4. (Optional) See Hosting configuration notes for additional configuration you should consider for the hosting environment.

Publishing the project's site folder

The project's site folder is used to store static files from media libraries and other site-specific files. It is by default located in the root of the project on the filesystem (~/<SiteCodeName>). Since the folder is not by default included in the project, it is not published when running dotnet publish.

To include the contents of the folder when publishing, add the following snippet into the Core project's .csproj file:

<ItemGroup>
  <Content Include="SiteFolderName\**">
    <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
  </Content>
</ItemGroup>

Hosting configuration notes

Automating application start

The Xperience ASP.NET Core application runs as a standard console application. The application's hosting environment needs to ensure the application starts after the server reboots, the application is restarted (e.g., via the administration application in System -> General -> Restart all web farm servers), or an unexpected error that causes the application to crash occurs.  

Automating starts and restarts is typically done using process managers such as Internet Information Services for Windows-based servers, or Nginx for Linux. Refer to the Microsoft documentation for guides on how to configure process managers based on your hosting environment.

Handling errors during application initialization

The Xperience ASP.NET Core integration package does not provide any support for error handling or recovery from errors that occur during application initialization. If an error occurs during the initialization process (e.g., the application's database experiences an outage), the hosting environment needs to ensure application recovery. For example, by terminating the application and attempting a restart during subsequent requests.

Refer to Microsoft documentation sources for recommended ways of handling error recovery during application initialization under various hosting types.

For example, when hosting the application under Internet Information Services (IIS) servers, you can use the CaptureStartupErrors web host configuration option:

Program.cs
public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .UseIISIntegration()
						 // When set to false, errors during startup result in the host exiting (the process terminating)
                        .CaptureStartupErrors(false)
                        .UseStartup<Startup>();
                });

Hosting the application under a virtual directory outside of IIS

If you wish to host the Core application in a virtual directory outside of an IIS server, you need to manually configure the application's base virtual path:

  1. Add the UsePathBase middleware to the application's middleware pipeline. Pass the full path from the server root to the application's virtual directory, including the leading '/' character, as the method's argument.
    • We recommend adding this middleware to the pipeline as soon as possible. For the earliest possible inclusion into the pipeline, use a startup filter:

      AddVirtualDirectoryToBasePathStartupFilter.cs
      public class AddVirtualDirectoryToBasePathStartupFilter : IStartupFilter
      {
          public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
          {
              return builder =>
              {
      			// Sets the root-relative application path to '<ServerRoot>/app'
                  builder.UsePathBase("/app");
                  next(builder);
              };
          }
      }
  2. Set the ApplicationPath property of the SystemContext class to the same path you provided to the UsePathBase middleware. Set the value at the beginning of the application's Configure method, before other Xperience-specific middleware sensitive to this configuration is run.

    Application's startup class
    using CMS.Base;
    ...
    
    public void Configure(IApplicationBuilder app, IConfiguration configuration)
    {
    	// Sets the root-relative application path to '<ServerRoot>/app'
    	SystemContext.ApplicationPath = "/app";
    	...
    }

The application is now configured to run in the specified virtual directory.

Linux deployments – known issues

System.ArgumentException when rendering resized images on the live site

When accessing pages that contain resized images (e.g., from media libraries), you may encounter the System.ArgumentException: Parameter is not valid exception when rendering certain images. This is caused by the Unix implementation of .NET Core's System.Drawing.Common library (specifically, libgdiplus), which occasionally incorrectly parses image metadata. This bug is completely independent of the application's integration with Xperience. As far as we understand, all image formats can be affected by this issue.

A possible workaround is to resave the affected images via an image editing program, which can fix potential issues with the file's metadata. However, this workaround is not guaranteed to work for all image formats.


Was this page helpful?