---
title: Custom file system providers
---

> 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).

The `CMS.IO` library allows you to customize Xperience to support a file system of your choice. As described in [Files API and CMS.IO](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io.md), you can achieve this by developing a custom provider based on the classes contained within `CMS.IO`.

## Preparation

To implement a custom file system provider, you need to add a new assembly to the Xperience solution:

1. Open your solution in Visual Studio.
2. [Add a new Class Library project](https://docs.kentico.com/documentation/developers-and-admins/customization/integrate-custom-code.md).

## Implementation

To create a file system provider, implement the following classes:

1. Create two separate classes that inherit from the following abstract classes:
   - CMS.IO.AbstractDirectory
   - CMS.IO.AbstractFile
2. Implement all methods defined in the abstract classes.
3. Create three other classes that inherit from the following classes:
   - CMS.IO.DirectoryInfo
   - CMS.IO.FileInfo
   - CMS.IO.FileStream
4. Override all methods and properties from those classes.
5. Create constructors for the classes listed in step 3 according to the following table:

   | Inherits from        | Constructors                                                                                                                                                                                                                                                                                                                                                          |
   | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | CMS.IO.DirectoryInfo | public DirectoryInfo(string path)                                                                                                                                                                                                                                                                                                                                     |
   | CMS.IO.FileInfo      | public FileInfo(string filename)                                                                                                                                                                                                                                                                                                                                      |
   | CMS.IO.FileStream    | public FileStream(string path, CMS.IO.FileMode mode)<br>public FileStream(string path, CMS.IO.FileMode mode, CMS.IO.FileAccess access)<br>public FileStream(string path, CMS.IO.FileMode mode, CMS.IO.FileAccess access, CMS.IO.FileShare share)<br>public FileStream(string path, CMS.IO.FileMode mode, CMS.IO.FileAccess access, CMS.IO.FileShare share, int bSize) |

> **Note:** **Note**: The custom file system provider classes must be placed into a namespace that **exactly** matches the name of the given assembly.

## Configuration

> **Tip:** When using a custom file system provider, register the paths it manages in the storage path registry using `AddStoragePathRegistration()` in `Program.cs`. This ensures the system is aware of all mapped paths. See [Register custom paths](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md#register-custom-paths).

Perform the following configuration steps to start using your custom file system provider:

1. Add the **CMSStorageProviderAssembly** application setting to your project. Set the key's value to the assembly name of your custom provider.
2. Create a [custom module](https://docs.kentico.com/documentation/developers-and-admins/customization/run-code-on-application-startup.md) that reads from the [storage path registry](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/storage-path-mapping.md) and maps registered paths to your custom provider.

### Example

The following code registers a module that maps all `SharedPersistent` paths to a custom storage provider:

```csharp
using CMS;
using CMS.DataEngine;
using CMS.IO;

using Microsoft.Extensions.DependencyInjection;

// Registers the custom module into the system
[assembly: RegisterModule(typeof(CustomInitializationModule))]

public class CustomInitializationModule : Module
{
    // Module class constructor, the system registers the module under the name "CustomInit"
    public CustomInitializationModule()
        : base("CustomInit")
    {
    }

    // Contains initialization code that is executed when the application starts
    protected override void OnInit(ModuleInitParameters parameters)
    {
        base.OnInit(parameters);

        var pathRegistry = parameters.Services.GetRequiredService<IStoragePathRegistry>();

        foreach (var registration in pathRegistry.GetRegistrations(PathType.SharedPersistent))
        {
            // Creates a new StorageProvider instance using the custom 'CustomFileSystemProvider' assembly
            var provider = new StorageProvider("custom", "CustomFileSystemProvider");

            // Maps the registered path to the provider
            StorageHelper.MapStoragePath(registration.MappedPath, provider);
        }
    }
}
```

> **Info:** To create an instance of the `StorageProvider` class for your custom file system provider, call the constructor with the following parameters:
>
> 1. The provider's external storage name. Can be an empty string for providers that use the local file system. If you are using [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md) or [Amazon S3](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/amazon-s3.md) providers in your project, the _Azure_ or _Amazon_ names are reserved by the corresponding providers.
> 2. The name of the class library containing the provider's implementation.
> 3. (Optional) A _bool_ parameter that specifies whether the storage is shared.
>
> For more information about storage provider mapping options, see [File system providers](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers.md).

> **Tip:** For Azure Blob storage hosting, use `AzureStorageProvider.Create()` with the container name as the first parameter. See [Azure Blob storage](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/azure-blob-storage.md) for Azure-specific configuration.
>
> For Amazon S3 hosting, use `AmazonStorageProvider.Create()` with the S3 bucket name as the first parameter. See [Amazon S3](https://docs.kentico.com/documentation/developers-and-admins/api/files-api-and-cms-io/file-system-providers/amazon-s3.md) for Amazon-specific configuration.
>
> For production deployments, we recommend mapping both `SharedPersistent` and `SharedTemp` paths, and using environment detection (`IHostEnvironment.IsDevelopment()`) to skip mapping in local development.