Area: Optimizely Commerce
Applies to versions: 8 and higher

Upgrading and deploying Commerce to Azure

Recommended reading 

Note: Azure Web Apps used to be called Azure Web Sites, see Microsoft’s announcement for details. 


This document describes how to set up an EPiServer Commerce site (8.0 and above) to run with Azure Web Apps. In this scenario a Commerce Core site is installed and most steps can also be applied to sites by installing Nuget packages. Refer to Azure Websites for more detailed information about Azure.

Note that this document does not describe how to create/update a working EPiServer Commerce site, which is required for the Azure deployment. Refer to Installing EPiServer updates for more information on how to do this.


  • The Azure Management Portal requires an account with login details.
  • A specific cloud enabled license is required, refer to the EPiServer License Center to get this.
  • Deploying to cloud based websites requires that each deployed application and module is designed for cloud.

Note: since Azure does not support some features in EPiServer.CommonFramework, the CommonFramework assemblies, configuration and database need to be removed. Refer to the section Common Framework is not used in Removing dependency on Common Framework for more information on how to do this.

Cloud website setup

Like EPiServer CMS webite on Azure, the Commerce website can be run on Azure Web Apps environment with multiple instances. The website instances share the same Azure SQL database, and the blob storage in Azure is used for storing of the file binary data. Load balancing is applied and the Azure Service Bus manages events between the CMS websites.

Using Auto Scale, you have the ability to scale in or out automatically by defining a set of rules.

Follow the steps below to create an EPiServer Commerce website running in an Azure website environment.

1. Creating Azure resources

Log in to the Azure management portal and follow the steps below to create Websites, Storages, and the Service Bus.

Creating Azure websites

  • In the Azure management portal, select WEB SITES in the left menu.
  • Select NEW in the bottom left corner, and in the dialog select CUSTOM CREATE.
  • Provide a URL for your website, select a region and choose No dabase in DATABASE field.

Note that two websites are needed, one for the EPiServer Commerce front-end site, and one for Commerce Manager.

Creating an Azure storage

When running on Azure, the media (for example images) should be stored in the Azure BLOB storage to enable scaling.

  • In the Azure Management portal, select STORAGE from the left menu.
  • Select NEW in the bottom left corner, and in the dialog select QUICK CREATE.
  • Provide a URL for the storage and chose the option to create the storage account. Note that the storage container name must be in lowercase, for instance "mysitemedia", for DNS compatibility.

Note that if you are using Lucene Search Provider as default search, you need to create one more storage container for the storage index.

Creating a Service Bus

To be able to scale the site to run on several instances, we need to set up a Service Bus in Azure to handle messages between the site instances.

Follow the steps below to create a service bus.

  • In the Azure Management portal, select SERVICE BUS from the left menu.
  • Select CREATE in the bottom menu, and in the dialog select a namespace name and a region.

2. Upgrading NuGet packages and make the site ready for Azure

Refer to Get started developing with EPiServer Commerce for information on how to set up a Commerce project. When you have a project with a working site, continue steps below.

  • Open EPiServer Commerce front-end site project using Visual Studio.
  • Upgrade your Commerce site to latest version (or 8.0 at least).
  • Install the NuGet package EPiServer.Commerce.Azure to the project. Remember running Update-EPiDatabase on Package Manager Console.
  • Open Commerce database in Microsoft SQL Server Management Studio, then execute PrepareForSqlAzure.sql file in \package\EPiServer.Commerce.Azure\tools\epiupdates_commerce\sql\manual.
  • Move to updating configuration following step 3.

If you install CommerceManager besides EPiServer Commerce Core, some extra steps are needed:

  • Install the NuGet package EPiServer.Commerce.UI.ManagerIntegration to the front-end site.
  • Open Mediachase.ConsoleManagerUpdate, and upgrade it to latest version (or 8.0 at least, refer to Installing EPiServer updates, go to Updating Commerce Manager for more details).
  • Install the NuGet package EPiServer.CommerceManager.Azure to the Mediachase.ConsoleManagerUpdate project, and update the configuration following step 3 - the same as for the front-end part.

3. Updating configurations

Mapping of BLOB and event providers

Open EPiServerFramework.config and note the configuration under the episerver.framework section to map BLOB/Event providers to Azure.

<blob defaultProvider="azureblobs">
        <add name="azureblobs" type="EPiServer.Azure.Blobs.AzureBlobProvider,EPiServer.Azure" connectionStringName="EPiServerAzureBlobs" container="mysitemedia"/>
<event defaultProvider="azureevents">
        <add name="azureevents" type="EPiServer.Azure.Events.AzureEventProvider,EPiServer.Azure" connectionStringName="EPiServerAzureEvents" topic="mysiteevents"/>

Connection strings for Blobs and Events

  • Open connectionStrings.config, edit the connection string named EPiServerAzureBlobs (matching the setting in episerver.framework for the provider). The connection string to the BLOB storage should be in the format: connectionString="DefaultEndpointsProtocol=https;AccountName=<name>;AccountKey=<key>", where <name> is what was given in section Create Azure Storage, and <key> can be found in the Azure Management portal under Storage, if you select the name and then select MANAGE ACCESS KEYS in the bottom menu.
  • Edit connection string named EPiServerAzureEvents (matching the setting in episerver.framework, too). This connection string can be copied from your Azure Services Bus.

Example of database connection strings in connectionStrings.config, defined for Azure:

    <add name="EPiServerDB" connectionString="<do_not_change_right_now>" />
    <add name="EcfSqlConnection" connectionString="<do_not_change_right_now>" />
    <add name="EPiServerAzureBlobs" connectionString="DefaultEndpointsProtocol=https;AccountName={my_storage_ccount};AccountKey={account_key}" />
    <add name="EPiServerAzureEvents" connectionString="Endpoint=sb://{myservicebus}.servicebus.windows.net/;
		SharedAccessKeyName={RootManageSharedAccessKey};SharedAccessKey={access_key}" />

After changing connection string for Blobs and Events, make sure your site is migrated and working before continuing.

Note: If you are using LuceneSearchProvider as default search provider, you need to change this to use LuceneAzureSearchProvider as default search:

  • Open Mediachase.Search.config, in SearchProviders, set the attribute defaultProvider to LuceneAzureSearchProvider.
  • Set your connectionStringName so that the provider has name="LuceneAzureSearchProvider" matching with your Azure Storage name (in connectionStrings.config) and storage="<container you want to index>"
  • Set your connectionStringName in Indexers tab matching with your Azure Storage name (in connectionStrings.config) and basePath is "<container where you want to store build info>"

Example of search config in Mediachase.Search.config, defined for using Lucene on Azure:

<?xml version="1.0" encoding="utf-8"?>
  <SearchProviders defaultProvider="LuceneAzureSearchProvider">
      <add name="LuceneSearchProvider" type="Mediachase.Search.Providers.Lucene.LuceneSearchProvider, Mediachase.Search.LuceneSearchProvider" 
        queryBuilderType="Mediachase.Search.Providers.Lucene.LuceneSearchQueryBuilder, Mediachase.Search.LuceneSearchProvider"
        storage="<your_physical_path_index>" simulateFaceting="true"/>
      <add name="LuceneAzureSearchProvider" type="Mediachase.Search.Providers.Lucene.LuceneAzureSearchProvider, Mediachase.Search.LuceneSearchProvider"
        queryBuilderType="Mediachase.Search.Providers.Lucene.LuceneSearchQueryBuilder, Mediachase.Search.LuceneSearchProvider" 
        storage="indexcontainer" connectionStringName="EPiServerAzureBlobs" simulateFaceting="true"/>
  <Indexers basePath="indexcontainer" connectionStringName="EPiServerAzureBlobs"> 
    <add name="catalog" type="Mediachase.Search.Extensions.Indexers.CatalogIndexBuilder, Mediachase.Search.Extensions"/>

The Commerce site is now ready for Azure deployment.

4. Deploying

Migrating Database to Azure SQL Database

Refer to Migrating Commerce databases to Azure for more detailed information.

Note that for EPiServer Commerce, two databases need to be migrated to Azure SQL Database.

  • Open connectionStrings.config, change the connection string for EPiServerDB, EcfSqlConnection to the connection string from Azure SQL Database. Remember to keep the setting MultipleActiveResultSets=true.
    <add name="EPiServerDB" connectionString="Server={your_database_server_for_front_end};Database={database_name_for_front_end};User ID={user_id};Password={password};
                Trusted_Connection=False;Encrypt=True;Connection Timeout=30;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
    <add name="EcfSqlConnection" connectionString="Server={your_database_server_for_back_end};Database={database_name_for_back_end};User ID={user_id};Password={password};
                Trusted_Connection=False;Encrypt=True;Connection Timeout=30;MultipleActiveResultSets=True" providerName="System.Data.SqlClient" />
    <add name="EPiServerAzureBlobs" connectionString="DefaultEndpointsProtocol=https;AccountName={my_storage_ccount};AccountKey={account_key}" />
    <add name="EPiServerAzureEvents" connectionString="Endpoint=sb://{myservicebus}.servicebus.windows.net/;
                SharedAccessKeyName={RootManageSharedAccessKey};SharedAccessKey={access_key}" />

Transfer the sites BLOBs to Windows Azure Storage

Usually, EPiServer BLOBs are stored in C:\EPiServer\<MyEPiServerSite>\appdata\blobs.

There are different ways of transferring BLOBs from a local site to the Azure Storage.

Refer to Blob Transfer Utility for Windows Azure Blob Storage for more information on how to transfer BLOBs to Azure Storage.

Deploy website to Windows Azure Web Sites

Refer to How to Deploy an Azure Web Site for more detailed deployment information.

5. Add your EPiServer cloud license to your site

  • Access https://license.episerver.com and get a cloud license.
  • Upload your license to the Azure website.
  • Refer to Changing the site URL section on Deploying to Azure websites for more information about how to config site URL.
  • Go to Admin mode > Config tab > Manage Websites > Cloud License tab, to activate your license.

6. Build site index

Build content index

Refer to Search in Azure section on Deploying to Azure websites for more information about how to build content index.

Rebuild catalog index

  • Access Commerce Manager.
  • Go to Administration > System Settings > Search Index, click on Rebuild Index, catalog index will be restored in your storage.

See also

Do you find this information helpful? Please log in to provide feedback.

Last updated: Oct 20, 2016

Recommended reading