---
title: Configuring file system providers
related:
  - https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api.md
  - https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/writing-a-custom-file-system-provider.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 allows you to modify the behavior of file system providers. You can use different providers to access different parts of the application's file repository, and you can change the default locations of different types of files.

Use the Xperience CMS.IO API and the following general process:

1. Open the Xperience solution in Visual Studio.
2. Create a [custom module class](https://docs.kentico.com/13/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md). Add the class into a custom _Class Library_ project within the solution.

   > **Info:** For basic execution of initialization code, you only need to register a "code-only" module through the API. You do NOT need to create a new module within the **Modules** application in the administration interface.
3. Override the module's **OnInit** method and perform the required _StorageProvider_ modifications. See the following use cases:
4. Save all changes and rebuild the solution.

> **Note:** **Custom storage providers**
>
> Consider whether you need to deploy the assembly with the custom storage provider code to your live site (MVC) application, in addition to the Xperience administration project. Many folders, such as media libraries, are used both in the live site application and the administration application. In these cases, your custom file system configuration needs to be identical in both applications to work consistently.
>
> For additional information, see [Applying customizations in the Xperience environment](https://docs.kentico.com/13/custom-development/applying-customizations-in-the-xperience-environment.md).

## Changing content file paths to a shared storage

The system allows you to change default file paths to a shared storage directory on a specific server. This is important when you wish to share files between the live site and the administration application, or when using [web farms](https://docs.kentico.com/13/configuring-xperience/setting-up-web-farms.md) in general. For example, you can map media files to a folder shared between all web farm servers, and thus eliminate the need to synchronize these files among the servers.

1. Edit the custom project holding your storage provider logic in Visual Studio (see the general instructions at the start of this page).
2. Perform the following in your module's **OnInit** method:
   - Create a new instance of the **StorageProvider** class (the parameter of the _CreateFileSystemStorageProvider_ method must be _true_).
   - Specify the target directory via the **CustomRootPath** property of the provider. This sets the _**root**_ of the target path – the provider creates the relative path of the mapped folders within the given root directory.
   - Map a directory from your site to the provider.

```csharp

using CMS;
using CMS.Base;
using CMS.DataEngine;
using CMS.IO;

// 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()
    {
        base.OnInit();

        // Creates a new StorageProvider instance for the Windows file system
        var sharedMediaProvider = StorageProvider.CreateFileSystemStorageProvider(isSharedStorage : true);

        // Specifies the target root directory. The provider creates the relative path of the mapped folders within the given directory.
        sharedMediaProvider.CustomRootPath = @"\\Server\CustomMediaRoot";

        // Maps a directory from your website to the provider
        StorageHelper.MapStoragePath("~/MySite/Media/", sharedMediaProvider);
    }
}

```

> **Info:** To create a _StorageProvider_ instance for the Windows file system, call the **CreateFileSystemStorageProvider** static method of the StorageProvider class.
>
> The value of the method's _bool_ parameter specifies whether the storage is shared among web farm servers.

> **Note:** The mapping of the media library folders must be consistent across the live site and administration applications for the system's shared storage detection to work correctly. Non-matching mapping will lead to the media library content being duplicated.

Now every time the application requests or creates a file in the **\~/MySite/Media** directory, the location specified in the **CustomRootPath** property is used instead. In this example, the target folder is **\\\Server\CustomMediaRoot\MySite\Media**.

[Web farm servers](https://docs.kentico.com/13/configuring-xperience/setting-up-web-farms/configuring-web-farm-servers.md) will not attempt to synchronize media files and will instead use the files in the shared storage.

### Mapping the contents of the App\_Data folder to a shared storage

The **\~/App\_Data** folder is created and used by the system to store application-specific data and configuration files. Most of the files stored in the _App\_Data_ folder are created and updated by the application's runtime and **should not** be mapped to a shared storage. The configuration stored in the folder may differ for the live site and administration applications – sharing the configuration between both projects can lead to unintended side effects. However, some files remain unmodified after being created and can be safely mapped without affecting the other application.

The following folders from the _App\_Data_ directory can be safely mapped to a shared storage:

| Folder                                           | Contents                                                           | Note                                                                                                                                                                                          |
| ------------------------------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \~/App\_Data/CMSTemp                             | Temporary data storage for the Xperience administration.           | Only consider sharing these folders when running multiple instances of the administration application in a web farm. Sharing these folders with the live site application brings no benefits. |
| \~/App\_Data/Persistent                          | Contains application logs.                                         |                                                                                                                                                                                               |
| \~/App\_Data/CMSModules/CMSInstallation/Packages | Contains installable packages and modules (sample sites, etc.).    |                                                                                                                                                                                               |
| \~/App\_Data/CMSSiteUtils                        | Default destination for import & export and similar functionality. |                                                                                                                                                                                               |

## Using different file system providers for specific parts of the application's file repository

The CMS.IO API allows you to access different sections of the application's file repository using different file system providers. For example, you can store media files in the Azure blob storage, while all other files stay in the default Windows file system.

1. Edit the custom project holding your storage provider logic in Visual Studio (see the general instructions at the start of this page).
2. Perform the following in your module's **OnInit** method:

   - Create a new instance of the _StorageProvider_ class.
   - Map a directory to the provider.

```csharp

using CMS;
using CMS.Base;
using CMS.DataEngine;
using CMS.IO;

// 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()
    {
        base.OnInit();

        // Creates a new StorageProvider instance (Azure storage provider in this example)
        var mediaProvider = StorageProvider.CreateAzureStorageProvider();

        // Maps a directory to the provider
        StorageHelper.MapStoragePath("~/MySite/Media/", mediaProvider);
    }
}

```

> **Info:** To create _StorageProvider_ instances for the default file storage providers, call the following static methods of the StorageProvider class:
>
> - **CreateFileSystemStorageProvider** – returns instance of the default provider for the Windows file system. Has an optional _bool_ parameter that specifies whether the storage is shared.
> - **CreateAzureStorageProvider** – returns an instance of the default provider for the Microsoft Azure Blob storage. See [Configuring Azure storage](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers/configuring-azure-storage.md).
> - **CreateAmazonStorageProvider** – returns an instance of the default provider for the Amazon S3 storage service. See [Configuring Amazon S3](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers/configuring-amazon-s3.md).

The application now uses the given file system provider to access the specified project folder. In the case of the sample code above, the configured [Azure storage provider](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers/configuring-azure-storage.md) is used to store and retrieve files from the **\~/MySite/Media** directory.

## Changing content file paths to a different disk drive

The CMS.IO API allows you to change default file paths. For example, when using the Windows file system, you can store media files on a different disk drive.

1. Edit the custom project holding your storage provider logic in Visual Studio (see the general instructions at the start of this page).
2. Perform the following in your module's **OnInit** method:

   - Create a new instance of the **StorageProvider** class.
   - Specify the target directory via the **CustomRootPath** property of the provider. This sets the _**root**_ of the target path – the provider creates the relative path of the mapped folders within the given root directory.
   - Map a directory to the provider.

```csharp

using CMS;
using CMS.Base;
using CMS.DataEngine;
using CMS.IO;

// 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()
    {
        base.OnInit();

        // Creates a new StorageProvider instance for the Windows file system
        var mediaProvider = StorageProvider.CreateFileSystemStorageProvider();

        // Specifies the target root directory. The provider creates the relative path of the mapped folders within the given directory.
        mediaProvider.CustomRootPath = @"D:\CustomMediaRoot";

        // Maps a directory to the provider
        StorageHelper.MapStoragePath("~/MySite/Media/", mediaProvider);
    }
}

```

> **Info:** To create a _StorageProvider_ instance for the Windows file system, call the **CreateFileSystemStorageProvider** static method of the StorageProvider class.

This sample code ensures that every time the application requests or creates a file in the **\~/MySite/Media** directory, the location specified in the **CustomRootPath** property is used instead. In this example, the target folder is **D:\CustomMediaRoot\MySite\Media**.