---
title: Writing a custom file system provider
---

> 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 the [Overview page](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api.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, for example named _CustomFileSystemProvider_.
3. Add the Xperience API libraries to the project:
   1. Right-click the solution in the **Solution Explorer** and select **Manage NuGet Packages for Solution**.
   2. Select the **Kentico.Xperience.Libraries** package.
   3. Install the package into the custom project (the version must match your MVC project's _Kentico.Xperience.AspNet.Mvc5_ package and the exact hotfix version of your Xperience administration project).
4. Reference the project from both your MVC project and the Xperience administration project (_CMSApp_).

The Xperience installation directory contains sample definitions of all classes required to implement a generic file system provider. To help with the implementation, you can copy these classes into the custom file system provider's project:

1. Open your Xperience program files directory (by default _C:\Program Files\Kentico\\_).
2. Expand the _CodeSamples\CustomizationSamples\CustomFileSystemProvider_ subfolder.
3. Copy all contained files into the _CustomFileSystemProvider_ directory in your solution\*\*.\*\*
4. Include the new files into the _CustomFileSystemProvider_ project in Visual Studio:
   1. Expand the _CustomFileSystemProvider_ project in the Solution Explorer.
   2. Click **Show all files** at the top of the Solution Explorer.
   3. Select the new files while holding the **Ctrl** key.
   4. Right-click one of the files and select **Include in Project**.
5. Edit the copied files and rename the namespaces to **exactly** match the assembly name of your custom project (_CustomFileSystemProvider_ in this example).

## Implementation

If you choose to take advantage of the prepared classes, go through all files contained in the project and replace the **NotImplementedExceptions** inside methods with your implementation, and implement property and method overrides. You can consult the following steps for reference or if you wish to create a provider from scratch.

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

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

1. Add the **CMSStorageProviderAssembly** key to the _appSettings_ section of your project's **web.config** file. Set the key's value to the assembly name of your custom provider.
2. Configure the project to use the provider.
   - Use the API to create an instance of the **CMS.IO.StorageProvider** class and [map specific project folders](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers.md) to your custom provider.

### Example

The following code registers a module that maps a site's media library folder to a custom storage 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 using the custom 'CustomFileSystemProvider' assembly
        var customMediaProvider = new StorageProvider("custom", "CustomFileSystemProvider");

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

```

> **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, or any string except _azure_ or _amazon_ for external providers, which are already reserved by default system providers. The value is assigned to the _ExternalStorageName_ property of the StorageProvider class.
> 2. The name of the code assembly 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: [Configuring file system providers](https://docs.kentico.com/13/custom-development/working-with-physical-files-using-the-api/configuring-file-system-providers.md)