Configuring file system providers

Kentico allows you to modify the behavior of file system providers. You can use different file system providers to access different parts of the application’s file repository, and you can change the default locations of different types of files.

See the following use cases:

• Using different file system providers for specific parts of the application’s file repository
• Changing content file paths to a different disk drive
• Changing content file paths to a shared storage

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. Open the Kentico web project in Visual Studio (using the WebSite.sln or WebApp.sln file).
2. Create a new class in the App_Code folder (or CMSApp_AppCode -> Old_App_Code on web application projects).
3. Extend the CMSModuleLoader partial class.
4. Create a new class inside CMSModuleLoader that inherits from CMSLoaderAttribute.
5. Add the attribute defined by the internal class before the definition of the CMSModuleLoader partial class.
6. Override the Init method inside the attribute class:

   • Create a new instance of the StorageProvider class.

   • Map a directory to the provider.

     Copy

     
     
     
       using CMS.IO;
       using CMS.Base;
     
       [CustomStorage]
       public partial class CMSModuleLoader
       {    
           private class CustomStorageAttribute : CMSLoaderAttribute
           {
               /// <summary>
               /// The system executes the Init method of the CMSModuleLoader attributes when the application starts.
               /// </summary>
               public override void Init()
               {
                   // Creates a new StorageProvider instance
                   AbstractStorageProvider mediaProvider = new StorageProvider("Azure", "CMS.AzureStorage");
     
                   // Maps a directory to the provider
                   StorageHelper.MapStoragePath("~/MySite/Media/", mediaProvider);
               }
           }
       }
     
     
       

     When creating the StorageProvider instance:

     • The first parameter must match the identifier of the provider that you wish to use.
     • The second parameter must match the assembly name of the provider.
     • The third parameter can be used to specify if the storage is shared.
     • Use the constructor without parameters to create an instance of the default provider for the Windows file system.See the File system provider names and assembliestable for values belonging to the built-in file system providers.
7. Save the file. If your project is installed in the web application format, rebuild the solution.

The application now uses the given file system provider to access the specified project folder.

Changing content file paths to a different disk drive

CMS.IO 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. Open the Kentico web project in Visual Studio (using the WebSite.sln or WebApp.sln file).
2. Create a new class in the App_Code folder (or CMSApp_AppCode -> Old_App_Code on web application projects).
3. Extend the CMSModuleLoader partial class.
4. Create a new class inside CMSModuleLoader that inherits from CMSLoaderAttribute.
5. Add the attribute defined by the internal class before the definition of the CMSModuleLoader partial class.
6. Override the Init method inside the attribute class:

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

     Copy

     
     
     
       using CMS.IO;
       using CMS.Base;
     
       [CustomStorage]
       public partial class CMSModuleLoader
       {    
           private class CustomStorageAttribute : CMSLoaderAttribute
           {
               /// <summary>
               /// The system executes the Init method of the CMSModuleLoader attributes when the application starts.
               /// </summary>
               public override void Init()
               {
                   // Creates a new StorageProvider instance            
                   AbstractStorageProvider mediaProvider = new StorageProvider();
     
                   // 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);  
               }
           }
       }
     
     
       

     Use the StorageProvider constructor without parameters to create a provider instance for the Windows file system. Otherwise the method expects at least two string parameters:

     • The value in the first parameter must match the identifier of the provider that you wish to use.
     • The value in the second parameter must match the assembly name of the provider.See the File system provider names and assembliestable for values belonging to the built-in file system providers.
7. Save the file. If your project is installed in the web application format, rebuild the solution.

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.

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 can be particularly useful if you are running a web farm. This way, you can for example map media files to a folder shared among all web farm servers, and thus eliminate the need to synchronize these files among the servers.

1. Open the Kentico web project in Visual Studio (using the WebSite.sln or WebApp.sln file).
2. Create a new class in the App_Code folder (or CMSApp_AppCode -> Old_App_Code on web application projects).
3. Extend the CMSModuleLoader partial class.
4. Create a new class inside CMSModuleLoader that inherits from CMSLoaderAttribute.
5. Add the attribute defined by the internal class before the definition of the CMSModuleLoader partial class.
6. Override the Init method inside the attribute class:

   • Create a new instance of the StorageProvider class (the third parameter 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.

     Copy

     
     
     
       using CMS.IO;
       using CMS.Base;
     
       [SharedStorage]
       public partial class CMSModuleLoader
       {
           private class SharedStorageAttribute : CMSLoaderAttribute
           {
               /// <summary>
               /// The system executes the Init method of the CMSModuleLoader attributes when the application starts.
               /// </summary>
               public override void Init()
               {
                   // Creates a new StorageProvider instance using the default Windows file system provider
                   AbstractStorageProvider mySharedMediaProvider = new StorageProvider(null, "CMS.FileSystemStorage", true);
     
                   // Specifies the target root directory. The provider creates the relative path of the mapped folders within the given directory.
                   mySharedMediaProvider.CustomRootPath = @"\\Server\CustomMediaRoot";
     
                   // Maps a directory from your website to the provider
                   StorageHelper.MapStoragePath("~/MySite/Media/", mySharedMediaProvider);
               }
           }
       }
     
     
       

     Use the StorageProvider constructor to create a provider instance with the following parameters:

     • When using the default Windows file system provider, the first parameter must be null.
     • The value in the second parameter must match the assembly name of the provider, in this case CMS.FileSystemStorage.
     • The value in the third parameter is a boolean value which specifies if the storage is shared among web farm servers.See the File system provider names and assembliestable for values belonging to the built-in file system providers.
7. Save the file. If your project is installed in the web application format, rebuild the solution.

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 will not attempt to synchronize media files and will instead use the files in the shared storage.

File system provider names and assemblies

The following table lists the file system providers that Kentico supports by default:

• The Identifier column shows the value that you need to specify as the first parameter when creating StorageProvider instances in your code.
• The Assembly column contains the name of the code assembly containing the provider’s implementation.