Is this really the version you are looking for? Kentico Xperience 12 Service Pack Documentation is no longer updated. Use the switcher in the header to choose your product version.
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.
Mapping media files or the file system or storage accounts enforcing HTTPS connections
Storage accounts can be configured to communicate exclusively over HTTPS via the Security transfer required (opens in a new tab) setting available in the Azure portal (opens in a new tab). In such cases, additional configuration of the environment is required. See Mapping files to storage accounts enforcing HTTPS connections for details.
File name case
Unlike standard Windows file systems, the Microsoft Azure Blob storage is case-sensitive. To ensure consistent behavior, Kentico automatically converts all file and folder names to lower case when processing files on Azure storage.
Mapping files to Azure storage
To map media library folders to Azure storage, use the API and the built-in Azure storage provider:
Add the following keys to the appSettings section of your project's web.config file. Specify the storage account name and primary access key:
<add key="CMSAzureAccountName" value="StorageAccountName" />
<add key="CMSAzureSharedKey" value="PrimaryAccessKey" />To locate the values of these keys on Microsoft Azure:
If you are using the MVC development model, configure the same keys in the web.config of your MVC live site application.
Open the Kentico solution in Visual Studio (using the WebSite.sln or WebApp.sln file).
Create a custom module class. Add the class into a custom Class Library project within the solution.
Override the module's OnInit method and perform the following:
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 the local media library directory to the provider
StorageHelper.MapStoragePath("~/MySite/Media/", mediaProvider);
}
}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.
Mapping media folders on instances with multiple sites
By default, each site has its own separate media folder in the project's file system: ~/<site code name>/media
To map all media folders to Azure storage on Kentico instances with multiple sites, we recommend using a shared root folder for media libraries:
You can then map the shared media folder to your Azure storage (using the API described above).
If you wish to use the default media folder locations, you need to map each site's media folder in the code – for each site, create and configure a separate StorageProvider instance and call the StorageHelper.MapStoragePath method for the corresponding media folder.
Using Azure storage for multiple projects
We do not recommend using a single shared storage for multiple projects (for example production and testing instances), because the projects would overwrite each others' files.
However, you can use the mediaProvider.CustomRootPath property (as described on this page) to map each project to a different container. This way, each project has its own section of the Azure storage and overwriting of files does not occur.
Some external storage accounts may enforce HTTPS communication via the Security transfer required (opens in a new tab) setting configurable in the Azure portal (opens in a new tab). When mapping the file system or media library files to such accounts, you must include the CMSAzureBlobEndPoint configuration 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>Using the Azure Blob storage as an external storage for your project has some specific effects on media libraries.
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.
If all following conditions are true:
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.
Key | Description | Sample value |
|---|---|---|
CMSAzureTempPath | The system uses the specified folder to store temporary files on a local disk, for example when transferring large files to or from the storage account. | HTML |
CMSAzureCachePath | Specifies a folder on a local disk where files requested from the storage account are cached. This helps minimize the amount of blob storage operations, which saves time and resources. | HTML |
CMSAzureBlobEndPoint | Sets the endpoint used for the connection to the blob service of the specified storage account. If you wish to use the default endpoint, remove the setting completely from the appropriate files. | HTML |
CMSAzurePublicContainer | Indicates if the blob container used to store the application's file system is public. If true, it will be possible to access files directly through the URL of the appropriate blob service, for example: http://<StorageAccountName>.blob.core.windows.net/cmsroot/corporatesite/media/imagelibrary/logo.png When you set this key to true, please see the Media library notes section*.* | HTML |
CMSAzureCDNEndpoint | URL of the HTTP endpoint of a Azure Blob storage CDN. Note: If you set the CMSAzureCDNEndpoint key, you also need to set the blob storage container to public - <add key="CMSAzurePublicContainer" value="true" />. | HTML |
CMSDownloadBlobTimeout | Specifies the timeout interval in minutes for importing files from Azure Blob storage into Kentico. The default value is 1.5 minutes. Increase the interval if you encounter problems when importing large (about 2GB) files. | HTML |