Configuring Azure storage

In some situations, it may be beneficial to store files of an on‑premise website on a Microsoft Azure Blob Storage account rather than on a local disk.

• For example, if your server has a limited storage capacity and you need to save large amounts of file data. Using Microsoft Azure may be more convenient than upgrading your server, especially if the increased requirements are only temporary.
• The same applies when running Kentico in Azure Web Apps, where use of blob storage is optional (unlike with Cloud Services).

There are two approaches for connecting an Azure storage to your project:

• Store only media files on Azure storage (recommended)

  • We recommend that you map only media library folders to the Azure storage. This allows you to store large media files on a shared storage and optionally use an Azure CDN for this data, while avoiding issues related to local smart search indexes and Web analytics functionality.

• Map the whole file system to Azure storage

  • We do not recommend mapping the whole file system to the Azure storage because of possible problems with local smart search indexes and Web analytics functionality. These features use data that is not suitable for shared file systems.

Configuring Kentico to store only media files on Azure storage

To map media library folders to Azure storage, use the API and the built-in Azure storage provider:

1. Add the following keys to the appSettings section of your project’s web.config file. Specify the storage account name and primary access key:

   Copy

   
   
   
    <add key="CMSAzureAccountName" value="StorageAccountName" />
    <add key="CMSAzureSharedKey" value="PrimaryAccessKey" />
   
   
    

   To locate the values of these keys on Microsoft Azure:

   1. Open the Azure Management Portal in a browser and sign in.
   2. Open Storage accounts.
   3. Select your storage.
   4. Switch to the Access keys tab.
      • Use the Storage account name and one of the provided access key values.
   Important

   Do NOT set the CMSExternalStorageName key in your web.config (remove the key if it is present). Setting the key’s value to azure maps the project’s entire file system to the Azure storage, which is not recommended. See the Configuring Kentico to map its file system to Azure storage section for more information about this scenario.

2. Open the Kentico web project in Visual Studio (using the WebSite.sln or WebApp.sln file).

3. Create a custom module class.

   • Either add the class into a custom project within the Kentico solution (recommended) or directly into the Kentico web project (into the CMSApp project for web application installations, into the App_Code folder for web site installations).

     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 Kentico administration interface.

4. Override the module’s OnInit method and perform the following:

   • Create a new instance of the Azure storage provider.

   • (Optional) Specify the target container using the CustomRootPath property of the provider.

   • (Optional) You can specify whether you want the container to be publicly accessible using the PublicExternalFolderObject property of the provider. True means the container is publicly accessible.

   • Map a directory to the provider. This is the directory that you want to store in the container.

     Copy

     
     
     
       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 Azure
               var mediaProvider = StorageProvider.CreateAzureStorageProvider();
     
               // Specifies the target container
               mediaProvider.CustomRootPath = "mymediacontainer";
     
               // Makes the container publicly accessible
               mediaProvider.PublicExternalFolderObject = true;
     
               // Maps a directory to the provider
               StorageHelper.MapStoragePath("~/MySite/Media/", mediaProvider);
           }
       }
     
     
       

5. Save the file. If your project is installed in the web application format, rebuild the solution.

The system now stores files from the ~/MySite/Media/ folder in the mymediacontainer on the Azure storage. See the Media library notes section on this page for additional information about media libraries when using Azure storage.

Configuring Kentico to map its file system to Azure storage

1. Add the following key into the appSettings section of your project’s web.config file.

   Copy

   
   
   
    <add key="CMSExternalStorageName" value="azure" />
   
   
    

   This key maps the entire file system of your application to the Azure storage.

2. Add the following keys to specify the storage account name and primary access key:

   Copy

   
   
   
    <add key="CMSAzureAccountName" value="StorageAccountName" />
    <add key="CMSAzureSharedKey" value="PrimaryAccessKey" />
   
   
    

   To locate the values of these keys on Microsoft Azure:

   1. Open the Azure Management Portal in a browser and sign in.
   2. Open Storage accounts.
   3. Select your storage.
   4. Click Manage access keys on the bottom panel.
      • Use the Storage account name and one of the provided access key values.

Also see the Media library notes on this page for additional information about specifics of media libraries when using Azure storage.

Mapping files to storage accounts enforcing HTTPS connections

Some external storage accounts may enforce HTTPS communication via the Security transfer required setting configurable in the Azure portal. When mapping the file system or media library files to such accounts, you must include the CMSAzureBlobEndPointconfiguration key in the application’s web.config file. The key’s value needs to contain the full endpoint URL of the external storage account and explicitly use the https protocol:

<appSettings>
    ...
    <add key="CMSAzureBlobEndPoint" value="https://<StorageAccountName>.blob.core.windows.net" />
</appSettings>

Media library notes

Using the Azure Blob storage as an external storage for your project has some specific effects on media libraries.

Storing too many files in one media library folder

Note that storing a large number of media files in a single folder can significantly affect the performance of user interface when editing files in the Media library application. The performance of the website, however, is not affected. See Media library limitations when storing files in an external storage for details.

Using permanent links when CMSAzurePublicContainer key is set to true

If all following conditions are true:

• you use the Azure Blob storage as an external storage
• and you set the CMSAzurePublicContainer key to true
• and you want to use content staging

then use Permanent links when linking to media files in media libraries.

The reason is that when using the CMSAzurePublicContainer key, direct file links contain the name of the storage in the URL. These links are not updated when staging files to another server, which is typically connected to a different storage. As a result, staged links incorrectly target files from the source server’s storage, or may become broken if the files are not exactly mirrored on the staging servers. Permanent links do not contain the name of the storage, and automatically target the correct storage for each server.

Optional web.config settings for Azure storage

<add key="CMSAzureTempPath" value="C:\AzureTemp" />

 <add key="CMSAzureCachePath" value="C:\AzureCache" />

 <add key="CMSAzureBlobEndPoint" value="http://127.0.0.1:10000/devstoreaccount1" />

 <add key="CMSAzurePublicContainer" value="true" />

 <add key="CMSAzureCDNEndpoint" value="kentico123.vo.msecnd.net" />

<add key="CMSDownloadBlobTimeout" value="50" />