Enable the Azure Blob Storage module for Sitecore blobs
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.
Install the Azure Blob Storage module in Sitecore PaaS
You can install the Azure Blob Storage module in Sitecore PaaS in two ways:
-
Use the Sitecore Azure Toolkit:
-
Use a new Sitecore installation with Sitecore Azure Toolkit
-
-
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:
-
Download the Sitecore Azure Toolkit.
-
Prepare the Azure Resource Manager (ARM) templates and WDPs for Sitecore.
-
Prepare the ARM template parameters for Sitecore.
-
Download the Azure Blob Storage module ARM templates from GitHub.
-
Download the Azure Blob Storage module WDP from the Sitecore Downloads page.
-
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.
-
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.
-
-
Run the Deployment cmdlets of the Sitecore Azure Toolkit with the Sitecore main ARM template Uniform Resource Identifier (URI), and 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:
-
Log in to the Microsoft Azure® portal and, in the left-hand bar, click Create a resource.
-
In the Search field, enter Sitecore® Experience Cloud, select it, and then click Create.
-
In the Subscription drop-down menu, click the subscription that you want to install Sitecore on.
-
In Resource Group, click Create new and enter a resource group name.
NoteIf you have an existing empty resource group, click Use existing and select the name from the drop-down menu, then click OK.
-
Under Sitecore Settings, click Configure required settings (this opens a wizard).
-
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.
-
On the Credentials tab, enter the required information to create a new storage account to use for blob storage.
NoteIf you have an existing account, provide your storage account information to use as the blob storage.
-
On the Region tab, click the location for your installation.
-
On the Summary tab, check all the information for your installation is correct, then click OK.
-
Click Legal Terms, review the cost and legal terms, then click Create.
-
To start Sitecore with an Azure Blob Storage module installation, click OK.
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.
Install the Azure Blob Storage module on an on-premise Sitecore instance
To install the Azure Blob Storage module on an on-premise Sitecore installation:
-
Download the Azure Blob Storage module WDP from the Sitecore Downloads page.
-
Use
MsDeploy
to install the WDP by running it in the command prompt, (ensuremsdeploy.exe
is available in the server that you are using to run this command):RequestResponse"<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. -
Go to nuget. and download the
Microsoft.Web.XmlTransform.dll
file. -
In the Sitecore
ConnectionString.config
file, run the following PowerShell command to update the Azure Storage connection string:RequestResponsefunction 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"
You must repeat these steps for every role or web application that uses media items.
Manually install the Azure Blob Storage module in PaaS or on-premise
To manually install the Azure Blob Storage module on any Sitecore installation:
-
Download the Azure Blob Storage module WDP from the Sitecore Downloads page.
-
Extract (unzip) the WDP.
-
Copy the contents of the
bin
folder of the WDP into the Sitecore web applicationbin
folder. -
Copy the contents of the
App_Config
folder of the WDP into the Sitecore web applicationApp_Config
folder. -
Copy the contents of the
App_Data
folder of the WDP into the Sitecore web applicationApp_Data
folder. -
Add the following connection string to the
App_Config\ConnectionStrings.config
file of the Sitecore web application.RequestResponse<add name="azureblob" connectionString="<AzureStorageConnectionString>"/>
-
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).
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.
Verify deployment for all installations
To verify whether your deployment is correct:
-
Log in to Sitecore as a Content Author.
-
Upload some media files to ensure that you can download them properly, and that they have been correctly created as media items.
-
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).
Configure the default provider
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>
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.
Configure the AzureStorageBlobProvider provider
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:
Parameter |
Description |
---|---|
|
(Required) The name of the connection string from the |
|
(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 |
|
(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: |
|
(Optional) The providers method to log an error. You can implement a custom class of the same type by using |
|
(Optional) The name of the blob container in Azure Blob Storage. The default value is: |
|
(Optional) The maximum number of retries allowed when there is a transient error. The default value is: |
|
(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: |
|
(Optional) The maximum amount of time in seconds to perform a request, (including retries). The default value is: |
|
(Optional) The number of exceptions that are allowed before the circuit breaker breaks due to a transient error that exceeded the |
|
(Optional) The default value is: |