Enable the Azure Blob Storage module for Sitecore blobs

Abstract

Install the Azure Blob Storage module to use Sitecore blobs with Azure Storage support.

Sitecore supports using SQL Database as the default storage for blobs and content. However, Azure Blob Storage support can replace SQL Database blob support, if you install the Azure Blob Storage module.

You can install the module using the Sitecore Azure Toolkit for PaaS installations, using Sitecore in the Azure Marketplace, or manually for on-premise installations.

The module supports using an Azure Storage account. If you do not have an existing account, then Sitecore can create a new Azure Storage account for you to use as blob storage. Both the Azure Marketplace and Sitecore Azure Toolkit deployments support this option. However, for an on-premise deployment, you must create an Azure Storage account separately and configure it for use in a Sitecore environment.

Consider the following before getting started with blob storage:

  • You can install the Azure Blob Storage module in both PaaS Sitecore and on-premise Sitecore instances. Use the Sitecore Azure Toolkit to simplify the process of adding the module to PaaS.

  • Sitecore in the Azure Marketplace offers an easy-to-use interface to install the Azure Blob Storage module on new Sitecore instances.

  • With an on-premise instance, you can also take advantage of Azure Blob Storage by downloading the Azure Blob Storage web deploy package (WDP) and following the necessary steps to configure it.

You can install the Azure Blob Storage module in Sitecore PaaS in two ways:

  1. Use the Sitecore Azure Toolkit:

    • Use a new Sitecore installation with Sitecore Azure Toolkit

    • Use an existing Sitecore installation with Sitecore Azure Toolkit

  2. Use Sitecore in the Azure Marketplace (for new Sitecore installations only)

Use a new Sitecore installation with Sitecore Azure Toolkit

Using the Sitecore Azure Toolkit documentation with your new Sitecore installation, to install the Azure Blob Storage module:

  1. Download the Sitecore Azure Toolkit.

  2. Prepare the Azure Resource Manager (ARM) templates and WDPs for Sitecore.

  3. Prepare the ARM template parameters for Sitecore.

  4. Download the Azure Blob Storage module ARM templates from GitHub.

  5. Download the Azure Blob Storage module WDP from the Sitecore Downloads page.

  6. Upload the ARM templates and WDPs to a publicly available location such as Azure Storage or, if you prefer, a private location with access tokens.

  7. To prepare the Azure Blob Storage module ARM template parameters that are required for deployment:

    • Open the modules section of the Sitecore ARM template parameters.

    • Select the appropriate topology for your solution, then work through the readme.md file of the associated Azure Blob Storage module ARM template.

  8. Run the Deployment cmdlets of the Sitecore Azure Toolkit with the Sitecore main ARM template Uniform Resource Identifier (URI), and ARM template parameters.

Use an existing Sitecore installation with Sitecore Azure Toolkit

Using the Sitecore Azure Toolkit documentation, to install the Azure Blob Storage module on an existing Sitecore installation:

  1. Download the Sitecore Azure Toolkit.

  2. Download the Azure Blob Storage module ARM templates from GitHub.

  3. Download the Azure Blob Storage module WDP from the Sitecore Downloads page.

  4. Upload the ARM templates and WDPs to a publicly available location such as Azure Storage or, if you prefer, a private location with access tokens.

  5. To prepare the Azure Blob Storage module ARM template parameters that are required for deployment:

    • Open the modules section of the Sitecore ARM template parameters.

    • Select the appropriate topology for your solution, then work through the readme.md file of the associated Azure Blob Storage module ARM template.

  6. Run the Deployment cmdlets of the Sitecore Azure Toolkit:

    • With an existing resource group name as the deployment ID.

    • Using the Azure Blob Storage module ARM template Uniform Resource Identifier (URI).

    • Using the Azure Blob Storage module ARM template parameters.

Use a new Sitecore installation in the Azure Marketplace

To install the Azure Blob Storage module with a new instance of Sitecore in the Azure Marketplace:

  1. Log in to the Microsoft Azure® portal and, in the left-hand bar, click Create a resource.

  2. In the Search field, enter Sitecore® Experience Cloud, select it, and then click Create.

  3. In the Subscription drop-down menu, click the subscription that you want to install Sitecore on.

  4. In Resource Group, click Create new and enter a resource group name.

    Note

    If you have an existing empty resource group, click Use existing and select the name from the drop-down menu, then click OK.

  5. Under Sitecore Settings, click Configure required settings (this opens a wizard).

  6. On the Environment tab, from the drop-down menus select the Sitecore version, topology, configuration, and size that you want for your solution. In the Additional Modules section, click Sitecore Azure Blob Storage module.

  7. On the Credentials tab, enter the required information to create a new storage account to use for blob storage.

    Note

    If you have an existing account, provide your storage account information to use as the blob storage.

    Create a blob storage account.
  8. On the Region tab, click the location for your installation.

  9. On the Summary tab, check all the information for your installation is correct, then click OK.

  10. Click Legal Terms, review the cost and legal terms, then click Create.

  11. To start Sitecore with an Azure Blob Storage module installation, click OK.

Note

You cannot install the Azure Blob Storage module on an existing PaaS Sitecore installation through the Azure Marketplace. However, it is possible to install it manually or with the Sitecore Azure Toolkit.

To install the Azure Blob Storage module on an on-premise Sitecore installation:

  1. Download the Azure Blob Storage module WDP from the Sitecore Downloads page.

  2. Use MsDeploy to install the WDP by running it in the command prompt, (ensure msdeploy.exe is available in the server that you are using to run this command):

    "<FolderPathOfMsDeploy>\msdeploy.exe" -verb:sync -source:package="<FilePathOfWDP>" -dest:auto="<RootUrlOfSitecoreInstance>" -setParam:"IIS Web Application Name"="<IISWebAppName>" -setParam:"AzureStorageConnectionString"="<AzureStorageConnectionString>" -setParam:"AzureStorageContainerName"="<AzureStorageBlobContainerName>" -setParam:"DefaultProvider"="azure" -enableRule:DoNotDeleteRule -verbose

    This command installs and configures the Azure Blob Storage module, and prepares the necessary XML Document Transform (XDT) files to update the Azure Storage connection string in the Sitecore ConnectionString.config file.

  3. Go to nuget. and download the Microsoft.Web.XmlTransform.dll file.

  4. In the Sitecore ConnectionString.config file, run the following PowerShell command to update the Azure Storage connection string:

    function XmlDocTransform($xml, $xdt)
    {
        if (!$xml -or !(Test-Path -path $xml -PathType Leaf)) {
            throw "File not found. $xml";
        }
        if (!$xdt -or !(Test-Path -path $xdt -PathType Leaf)) {
            throw "File not found. $xdt";
        }
    
        $scriptPath = (Get-Variable MyInvocation -Scope 1).Value.InvocationName | split-path -parent
        Add-Type -LiteralPath "$scriptPath\Microsoft.Web.XmlTransform.dll"
    
        $xmldoc = New-Object Microsoft.Web.XmlTransform.XmlTransformableDocument;
        $xmldoc.PreserveWhitespace = $true
        $xmldoc.Load($xml);
    
        $transf = New-Object Microsoft.Web.XmlTransform.XmlTransformation($xdt);
        if ($transf.Apply($xmldoc) -eq $false)
        {
            throw "Transformation failed."
        }
        $xmldoc.Save($xml);
    }
    
    XmlDocTransform -xml "<PhysicalFolderOfSitecoreWebApp>\App_Config\ConnectionStrings.config" -xdt "<PhysicalFolderOfSitecoreWebApp>\App_Data\Transforms\AzureBlobStorageProvider\Xdts\App_Config\ConnectionStrings.config.xdt"

Note

You must repeat these steps for every role or web application that uses media items.

To manually install the Azure Blob Storage module on any Sitecore installation:

  1. Download the Azure Blob Storage module WDP from the Sitecore Downloads page.

  2. Extract (unzip) the WDP.

  3. Copy the contents of the bin folder of the WDP into the Sitecore web application bin folder.

  4. Copy the contents of the App_Config folder of the WDP into the Sitecore web application App_Config folder.

  5. Copy the contents of the App_Data folder of the WDP into the Sitecore web application App_Data folder.

  6. Add the following connection string to the App_Config\ConnectionStrings.config file of the Sitecore web application.

    <add name="azureblob" connectionString="<AzureStorageConnectionString>"/>
  7. In the \App_Config\Modules\Sitecore.AzureBlobStorage\Sitecore.AzureBlobStorage.config file, ensure that <param name="containerName> points to the correct container. The Azure Blob Storage module uses shared storage for both Content Management (CM) and Content Delivery (CD).

Note

You must repeat the steps for every role that uses media items. By default, the roles are Content Management (CM) and Content Delivery (CD), however, you might have multiple CD roles in a solution.

To verify whether your deployment is correct:

  1. Log in to Sitecore as a Content Author.

  2. Upload some media files to ensure that you can download them properly, and that they have been correctly created as media items.

  3. Add the newly created media items to a page on your website to ensure the page renders properly, (that is, without any broken media links).

Sitecore can work with multiple Blob Storage accounts side by side. You can configure each Sitecore database with a list of blob providers for the Blob Storage account that it needs to support. Sitecore uses Blob ID to identify the respective blobs in the Blob Storage and retrieve or remove the blobs from the Blob Storage account. However, you must set a default blob provider for the new uploads.

When you install the Azure Blob Storage module, the preconfigured default provider is the Azure Storage Blob Provider. However, if necessary, you can change the default provider back to the ClassicSqlBlobProvider.

To change the default provider back to the ClassicSqlBlobProvider:

  • Update the App_Config\Modules\Sitecore.AzureBlobStorage\Sitecore.AzureBlobStorage.config file as follows:

<database id="master" role:require="Standalone or Reporting or Processing or ContentManagement">
  <BlobStorage>
    <providers default="classic">
      <provider name="classic" type="Sitecore.Data.Blobs.ClassicSqlBlobProvider, Sitecore.Kernel">
        <param desc="databaseName">$(id)</param>
      </provider>
      <provider name="azure" type="Sitecore.Framework.Data.Blobs.Azure.AzureStorageBlobProvider, Sitecore.Framework.Data.Blobs.Azure">
        <param name="connectionStringName">azureblob</param>
        <param name="usedBlobIdsPagedListProvider" type="Sitecore.Data.Blobs.UsedBlobIdsPagedListProviderFacade, Sitecore.Kernel">
          <param>$(id)</param>
        </param>
        <param name="logger" type="Sitecore.Data.Blobs.BlobStorageLogger, Sitecore.Kernel"></param>
        <param name="containerName">blobcontainer</param>
      </provider>
    </providers>
  </BlobStorage>
</database>

Important

The above example only shows the change to the master database configuration file. However, you must change this for all databases that have BlobStorage configured.

The AzureStorageBlobProvider provider uses a paged list provider pattern to retrieve the blob IDs that Sitecore media items use. It also uses Timeout, Circuit breaker pattern, and the Exponential retry pattern to handle transient errors. Even though the AzureStorageBlobProvider provider has default settings for these, you can customize the AzureStorageBlobProvider provider by changing the settings and parameters in your configuration. Refer to the following table for the available parameters:

Table 1. Parameters for AzureStorageBlobProvider

Parameter

Description

connectionStringName

(Required) The name of the connection string from the App_Config\ConnectionStrings.config file.

usedBlobIdsPagedListProvider

(Required) Provides methods to get the blob IDs that Sitecore Media items use page by page. You can implement a custom class of the same type by using Sitecore.Framework.Data.Blobs.Abstractions.IPagedListProvider

pageSize

(Optional) The maximum number of page items on a page when you get the blob IDs page by page. The default value of items per page is: 5000

logger

(Optional) The providers method to log an error. You can implement a custom class of the same type by using Sitecore.Framework.Data.Blobs.Abstractions.ILogger. The default value is: null

containerName

(Optional) The name of the blob container in Azure Blob Storage. The default value is: blobcontainer.

maxRetryAttempt

(Optional) The maximum number of retries allowed when there is a transient error. The default value is: 5

deltaBackOff

(Optional) When there is a transient error, this is the number of seconds between retries (the length of back-off time). The default value is: 4

maxExecutionTime

(Optional) The maximum amount of time in seconds to perform a request, (including retries). The default value is: 30

exceptionsAllowedBeforeBreaking

(Optional) The number of exceptions that are allowed before the circuit breaker breaks due to a transient error that exceeded the maxRetryAttempt. The default value is: 1

durationOfBreakInMinutes

(Optional) The default value is: 1