---
title: Storage path mapping
related:
  - https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers.md
  - https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md
  - https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/amazon-s3.md
  - https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/custom-file-system-providers.md
  - https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io.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).

Xperience by Kentico uses a **storage path registry** to manage how application file system paths are routed to [file system providers](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers.md). Each Xperience module registers the file system paths it uses and classifies them by a [path type](#path-types). A mapping method reads these registrations and routes each path to the correct storage provider based on the hosting environment.

To activate storage path mapping, call the appropriate extension method in `Program.cs` for your hosting scenario. See [Choose a mapping approach](#choose-a-mapping-approach) for details.

All system paths (media libraries, content item assets, form file attachments, AIRA files, and others) are registered by Xperience modules during startup. You only need to [register custom paths](#register-custom-paths) if your application stores files in additional directories.

## How storage path mapping works

The mapping system consists of two parts:

1. **Path registration** – Each Xperience module declares which file system paths it uses and classifies them by [type](#path-types) (`SharedPersistent`, `SharedTemp`, or `LocalOnly`). These declarations are collected in a central path registry (`IStoragePathRegistry`).
2. **Path mapping** – A mapping method reads all registered paths and maps each to the correct storage provider. The mapping behavior depends on the hosting environment and the path type.

All file I/O in Xperience goes through the `CMS.IO` abstraction layer, which delegates to the configured storage provider for each path. Application code reads and writes files through `CMS.IO`, and the underlying provider handles the rest. See [Files API and CMS.IO](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io.md) for details.

## Path types

The `PathType` enum classifies registered paths so the mapping system knows how to route them:







> **Info:** On Azure App Service (both [SaaS](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-the-saas-environment.md) and [private cloud](https://docs.kentico.com/documentation/developers-and-admins/deployment/deploy-to-private-cloud.md)), all [instances](https://docs.kentico.com/documentation/developers-and-admins/configuration/auto-scaling-support.md) share the same local file system (an Azure-managed file share). Because of this, `LocalOnly` and `SharedTemp` paths both physically reside on storage accessible to all instances – the path type distinction has no practical effect on file accessibility between instances. The distinction matters in environments where each instance has a truly separate local disk (such as on-premises instances or container deployments without shared volumes), where `SharedTemp` paths are explicitly mapped to shared storage while `LocalOnly` paths remain instance-local.

## Choose a mapping approach

The mapping approach depends on your hosting environment:








## System-registered paths

Xperience modules register the following paths during application startup:












The **Identification method** column lists extension methods from the `CMS.IO.Extensions` namespace. Use these methods in per-path configuration callbacks (such as `CreateProviderForPath` or `ConfigureContainerForPath`) to identify system paths.

## Register custom paths

If your application stores files in custom directories beyond what modules register, register them so the mapping system includes them.

```csharp title="Program.cs"
using CMS.IO;

builder.Services.AddStoragePathRegistration("~/custom-uploads", PathType.SharedPersistent);
builder.Services.AddStoragePathRegistration("~/custom-temp", PathType.SharedTemp);
```

### Register paths in custom modules

If you develop custom Xperience modules that store files on the file system, register paths in the module's `OnPreInit` method:

```csharp title="Custom module"
using CMS;
using CMS.DataEngine;
using CMS.IO;

[assembly: RegisterModule(typeof(MyCustomModule))]

public class MyCustomModule : Module
{
    public MyCustomModule()
        : base(nameof(MyCustomModule)) { }

    protected override void OnPreInit(ModulePreInitParameters parameters)
    {
        base.OnPreInit(parameters);

        parameters.Services.AddStoragePathRegistration("~/assets/my-custom-data", PathType.SharedPersistent);
        parameters.Services.AddStoragePathRegistration("~/assets/my-custom-temp", PathType.SharedTemp);
    }
}
```

Registered custom paths participate in the mapping system alongside system paths. Choose the appropriate [path type](#path-types) based on the nature of the stored data.

## Best practices

- Register all custom paths – If your application stores files in directories outside what modules manage, always register them with `AddStoragePathRegistration()`. Unregistered paths are not included in automatic mapping, and files may be lost during redeployment or slot swaps.
- Choose the correct [path type](#path-types) for each registered path based on the nature of the stored data.
- Use path identification methods in callbacks – When configuring per-path overrides (via `CreateProviderForPath`, `ConfigureContainerForPath`, or similar callbacks), use extension methods from the `CMS.IO.Extensions` namespace (for example, `IsMediaLibraryPath()`, `IsBizFormFilesPath()`) to identify system paths. Avoid comparing against path strings directly, as paths may change between versions.