Azure Blob storage

Xperience by Kentico supports file system providers that allow you to map parts of the file system to Microsoft Azure Blob Storage. You can use Blob storage when:

• Deploying Xperience projects to the SaaS environment
• Deploying to private cloud
• You need to store parts of the application file system in a shared storage. For example, shared storage is a requirement for all scaled Xperience deployments.

Blob storage is particularly suitable for storing content item assets, and all other unmanaged binary files referenced by the Xperience application. Some application deployment environments, like Azure Web Apps for example, do not guarantee a persistent file system for files created outside of the original deployment package. Therefore, if Azure needs to recycle the application due to rolling infrastructure updates or unexpected outages, all but the image with the original deployment is lost. Blob storage does not suffer from these limitations, as the infrastructure ensures redundancy in case of an outage.

Follow the instructions on this page to create Azure Blob storage providers for:

• projects deployed to the SaaS environment
• private cloud deployments

Media library files in Azure Blob storage

Media library files stored in Azure Blob storage have the following limitations:

• Storing a large number (thousands) of media library files in a single media library can significantly affect the performance and user experience of the Media libraries application.
  • We recommend structuring media library files into multiple media libraries and storing at most 100 files in a single media library folder.
• Mapping subfolders of media libraries is not supported. You can map either the directory containing the media libraries (~/assets/media), or individual media libraries (~/assets/media/<MediaLibraryName>).
• The system’s automatic clearing of files from the server-side cache does not work for files stored in an external storage. If you modify a media file, the website may still display the old version until the cache expires (unless you manually clear the application’s cache). See also: File caching.

Azure Blob storage for Kentico’s SaaS

When developing an Xperience application that you want to deploy to the SaaS environment, use the storage path mapping system to route application files to Azure Blob Storage.

Azure Blob storage is part of your Xperience by Kentico SaaS subscription and is used when deploying projects to the SaaS environment, as storing persistent data alongside Xperience application binaries deployed in Azure App Service is not recommended.

Default Kentico-managed Azure Blob storage configuration

Projects created with the --cloud parameter include AddXperienceCloudStoragePathMapping() in Program.cs and the Export-DeploymentPackage.ps1 deployment script. Xperience provides Azure Blob storage with the required accounts as part of every subscription.

The default configuration automatically maps all system paths based on the detected environment:

• Cloud environments (QA, UAT, Custom, Staging, Production) – all SharedPersistent paths (content item assets, media libraries, AIRA images, files uploaded via the Upload file form component) are mapped to Azure Blob Storage. The default container name is default.
• Local development – media library files are mapped to a local directory (~/$StorageAssets/default/assets/media) so they can be included in the deployment package.

All system paths are registered automatically by Xperience modules. See System-registered paths for the full list.

Customize the storage path mapping

To use a different container name or multiple containers for different paths, configure the options callback in Program.cs. The following table lists all available options:

using CMS.IO.Extensions;
using Kentico.Xperience.Cloud;

builder.Services.AddXperienceCloudStoragePathMapping(options =>
{
    // Set the default container name (default value is "default")
    options.ContainerName = "default";

    // Use a different container for specific paths
    options.ConfigureContainerForPath = (registration, setup) =>
    {
        if (registration.IsMediaLibraryPath())
        {
            setup.ContainerName = "media-files";
        }
    };
});

With this setup, media library files are stored in the media-files Azure Blob container in cloud environments and under $StorageAssets/media-files/ in local development. All other paths use the default container (or $StorageAssets/default/ locally).

Use container names conforming to Azure Blob storage container naming requirements.

If your application stores files in custom directories beyond what modules register, register them before the mapping call. See Register custom paths.

Migrate from StorageInitializationModule

Prior to version 31.6.0, SaaS projects configured storage path mapping using a custom StorageInitializationModule class (typically StorageInitializationModule.cs). This module manually created AzureStorageProvider instances, called StorageHelper.MapStoragePath() for each path, and branched on the hosting environment.

This module is replaced by a single AddXperienceCloudStoragePathMapping() call in Program.cs. Platform modules now register their own paths automatically – the application only declares its hosting model. See Storage path mapping for details on how the new system works.

If your project still uses a StorageInitializationModule, migrate to the new approach. For most common cases, the entire module collapses to:

builder.Services.AddXperienceCloudStoragePathMapping();

Projects with custom container names, per-path overrides, or custom paths require additional configuration – see Customize the storage path mapping and Register custom paths.

Kentico provides a migrate-storage-module-guide.md as a downloadable Markdown file that can be used as input for an AI coding agent (such as GitHub Copilot, Cursor, or similar). The guide covers all migration scenarios, including complex cases like per-path container overrides and retained modules for inexpressible mappings.

Azure Blob storage for private cloud deployments

To map parts of the file system to Azure Blob storage when deploying to private cloud, use the storage path mapping system.

Recommendations

1. Use separate Azure Blob storage containers for each deployment environment for the same project (for example, production and testing environments). Such environments often contain identically named files that overwrite each other. To avoid collisions, use different container names per environment.
2. Use HTTPS to connect to Azure Blob Storage accounts (this behavior can be enabled via the Security transfer required setting available in the Azure portal). Xperience is by default configured to use HTTPS with Azure Blob Storage.

   • If you need to use HTTP (for example because of storage accounts supporting only unencrypted (HTTP) connections), include the CMSAzureBlobEndPoint configuration key in your application’s configuration file. Set the value of the key to the full endpoint URL of the external storage account and explicitly specify the HTTP protocol:

     JSON

     appsettings.json

     Copy

     
     
       {
       ...
     
           "CMSAzureBlobEndPoint": "http://_StorageAccountName_.blob.core.windows.net"
       }
     
       

Set up storage mapping

1. Choose your authentication method. See Authentication methods for Azure Blob storage for detailed configuration options.

2. Add the Kentico.Xperience.AzureStorage NuGet package to your project.

3. Call AddAppServiceStoragePathMapping() in Program.cs:

   C#

   Program.cs

   Copy

   
   
    using Kentico.Xperience.AzureStorage;
   
    var builder = WebApplication.CreateBuilder(args);
   
    builder.Services.AddAppServiceStoragePathMapping(options =>
    {
        // Disable mapping in local development to avoid connecting to Azure
        options.IsMappingEnabled = !builder.Environment.IsDevelopment();
    });
   
    

   This maps all registered SharedPersistent paths to Azure Blob Storage (default container: cmsstorage) and SharedTemp paths to a shared file system.

   Calling AddAppServiceStoragePathMapping() activates storage mapping unconditionally – there is no automatic environment detection. If you call this method without setting IsMappingEnabled, Azure Blob storage is active in all environments, including local development.

   Test your configuration in every environment before going to production. A mapping that compiles correctly may behave differently depending on Azure credentials and container availability.

   Custom mapping module approach

   AddAppServiceStoragePathMapping() is a smart default designed to cover standard Azure App Service deployments. If its options don’t meet your requirements – for example, you need advanced per-environment logic, non-standard authentication, or highly specific provider configuration – you can implement a custom mapping module instead. See Custom file system providers for instructions.

4. (Optional) Set Optional application settings for Azure storage.

If your application stores files in custom directories, register them before the mapping call. See Register custom paths.

Configure private cloud mapping options

Pass an options callback to AddAppServiceStoragePathMapping() to customize the mapping:

The following example routes media library files and form file attachments to dedicated Azure Blob containers:

using CMS.IO;
using CMS.IO.Extensions;
using Kentico.Xperience.AzureStorage;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAppServiceStoragePathMapping(options =>
{
    options.IsMappingEnabled = !builder.Environment.IsDevelopment();
    options.ContainerName = "cmsstorage";

    options.CreateProviderForPath = (PathRegistration pathRegistration) =>
    {
        if (pathRegistration.IsMediaLibraryPath())
        {
            return AzureStorageProvider.Create("media-files");
        }

        if (pathRegistration.IsBizFormFilesPath())
        {
            return AzureStorageProvider.Create("form-submissions", publicExternalFolderObject: false);
        }

        // Return null to use the default provider for other paths
        return null;
    };
});

Optional application settings for Azure storage

"CMSAzureTempPath": "C:\\AzureTemp"

"CMSAzureCachePath": "C:\\AzureCache"

"CMSAzureBlobEndPoint": "http://127.0.0.1:10000/devaccount"

"CMSAzurePublicContainer": true

"CMSDownloadBlobTimeout": "5"

Authentication methods for Azure Blob storage

For private cloud deployments, Xperience supports two authentication methods for Azure Blob storage connections:

• Shared key authentication – Uses the storage account name and access key.
• Managed identity authentication – Uses Microsoft Entra authentication with managed identities . This is the recommended approach for enhanced security as it eliminates the need to store sensitive access keys in your application configuration.

Shared key authentication

Specify the storage account name and primary access key in your application configuration file (appsettings.json by default).

1. Open the Azure Management Portal.

2. Open Storage accounts.

3. Select your storage.

4. Switch to the Access keys tab.

5. Use the Storage account name and one of the provided access key values.

   JSON

   appsettings.json

   Copy

   
   
    {
        "CMSAzureAccountName": "StorageAccountName",
        "CMSAzureSharedKey": "PrimaryAccessKey"
    }
   
    

Managed identity authentication

Configure managed identity authentication using Microsoft Entra ID. This method provides enhanced security by eliminating the need to store access keys.

1. Set up managed identity in Azure:

   1. Enable managed identity for your Azure resources. See the Azure managed identities documentation.

   2. Grant the managed identity appropriate roles and permissions to your storage account:

      • Role: Storage Blob Data Owner
      • This built-in role includes all necessary permissions for Xperience Azure Storage operations.
      • —OR—
      • Role: Storage Blob Data Contributor
      • With additional permissions:
        • Microsoft.Storage/storageAccounts/blobServices/containers/getAcl/action (Get Container ACL)
        • Microsoft.Storage/storageAccounts/blobServices/containers/setAcl/action (Set Container ACL)
      • The Storage Blob Data Contributor role provides blob read/write access but requires additional container ACL permissions for full functionality. Use this configuration to enforce the principle of least privilege.

2. Configure storage account details in your application configuration:

   JSON

   appsettings.json

   Copy

   
    {
        "CMSAzureAccountName": "StorageAccountName"
    }
    

3. Configure managed identity authentication in your application startup:

   C#

   Program.cs

   Copy

   
   
    using Azure.Identity;
    using Kentico.Xperience.AzureStorage;
   
    var builder = WebApplication.CreateBuilder(args);
   
    // Configure managed identity for Azure Storage
    builder.Services.AddAzureStorageCredential(serviceProvider =>
    {
        // For user-assigned managed identity, specify the client ID
        return new ManagedIdentityCredential("your-user-assigned-identity-client-id");
   
        // For system-assigned managed identity, use default constructor.
        // Note that for system-assigned identitites to work the connected
        // application must be deployed in Azure as well.
        return new ManagedIdentityCredential();
   
        // For DEVELOPMENT environments, you can also return
        // DefaultAzureCredential for automatic credential discovery.
        // See the Azure documentation for details.
        return new DefaultAzureCredential();
    });
   
    // ...
   
    

Prevent Azure cache folders from bloating

In private cloud, Xperience projects using Azure Blob storage cache data from the blob storage on the local file system. This cached data is stored in the AzureTemp and AzureCache folders (see Optional application settings for custom path configuration).

When these folders accumulate too much data, the local storage can become full, potentially causing errors in your application.

Xperience by Kentico automatically monitors and cleans the Azure cache folders using a background process. When the total size of the cache folders exceeds a configured threshold, the system deletes cached files starting from the oldest until the folder size is reduced.

The default cleanup threshold is 45 GB. This means the system only starts removing cached files once the combined size of the AzureTemp and AzureCache folders exceeds 45 GB.

Configure the cleanup threshold

Configure the cleanup threshold using the AzureStorageCleanerOptions class in your application’s startup code (Program.cs):

using Kentico.Xperience.AzureStorage;

builder.Services.Configure<AzureStorageCleanerOptions>(options =>
{
    // Sets the threshold to 10 GB (value is in bytes)
    options.Treshold = 10L * 1024L * 1024L * 1024L;
});

Set the Treshold property to a value in bytes that is lower than your hosting environment’s available disk space. Leave enough headroom for the application itself and other files on the disk.