Writing a custom file system provider

✖
Copy to clipboard

The purpose of the CMS.IO library is to provide a way of customizing Kentico to support a file system of your choice. As described in Working with physical files using the API, you can achieve this by developing a custom provider based on the classes contained within CMS.IO.

Preparation

A generic file system provider project is available in the CodeSamples directory in your Kentico installation (e.g. C:\Program Files (x86)\Kentico\<version>\). The project contains definitions of all required classes and their members for easy implementation.

  1. Copy the generic project folder (CustomFileSystemProvider) into your web project folder.
  2. Open your web project in Visual Studio.
  3. Click File -> Add -> Existing Project and select CustomFileSystemProvider.csproj in the CustomFileSystemProvider folder.
  4. Add a reference to CMS.IO to the new custom file system provider project.
  5. Add the custom file system provider project reference to the Kentico project.

Implementation

If you choose to take advantage of the prepared provider, 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)

    public FileStream(string path, CMS.IO.FileMode mode, CMS.IO.FileAccess access)

    public FileStream(string path, CMS.IO.FileMode mode, CMS.IO.FileAccess access, CMS.IO.FileShare share)

    public FileStream(string path, CMS.IO.FileMode mode, CMS.IO.FileAccess access, CMS.IO.FileShare share, int bSize)

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. Choose between the following options:

    • Add the CMSExternalStorageName key to the appSettings section of the web.config file and set the value to any identifier. This maps the project’s entire file system to the custom provider.

      – OR –

    • Use the API to create an instance of the CMS.IO.StorageProvider class and map specific project folders to your custom provider. See Configuring file system providers for more information.

For example, the following web.config keys configure the application to store its entire file system using a custom provider implemented in the “CustomFileSystemProvider” project with “custom” as the identifier:




<appSettings>
...
  <add key="CMSStorageProviderAssembly" value="CustomFileSystemProvider" />
  <add key="CMSExternalStorageName" value="custom" />
...
</appSettings>