Troubleshooting Sitecore Azure


Troubleshoot problems and find answers to frequently asked questions about Sitecore Azure.

A useful reference for some of the most common troubleshooting queries about using Microsoft Azure, SQL Azure, and Sitecore Azure.

Sitecore Azure assembles the document root of a solution for deployment by:

  • Copying the document root subfolder of your on-premise Sitecore installation to $(datafolder)\AzurePackages\(xx)Azure\SitecoreWebSite for a Microsoft Azure deployment and to $(datafolder)\AzurePackages\(xx)DevFabric\SitecoreWebSite for a local emulator deployment.

  • Removing unnecessary files and subfolders from the SitecoreWebsite folder.

  • Copying the contents of the specified subfolder in the Override Sources Folder field of the Azure Deployment item to the document root of the content editing environment, the $(datafolder)\AzurePackages\(xx)Azure\SitecoreWebSite subfolder.

  • Preparing the web.config file by including files from the Include folder and the Sitecore section configuration source, which is App_Config\Sitecore.config by default. It also prepares the web.config file by carrying out an Extensible Stylesheet Language Transformation (XSLT) based on the XSLT patch in the Custom Web Config Patch field of the Azure deployment item.

  • Decreasing the size of the web.config file by the end of preparation, the Sitecore section of the web.config file is stored in the Sitecore section configuration source file, which is App_Config\Sitecore.config by default. Editing the connectionStrings element of the web.config file. The editing process removes unnecessary connection strings and adds new ones based on the databases that are stored in the Connection Strings Patch field of the Azure deployment item. Custom connection strings are supported.

  • Copying license information from the local installation to the content delivery package. If you need a different license file in the content delivery installation, add it to the \App Data\AzureOverrideFiles subfolder (the default path specified in the Override Sources Folder field of the Azure deployment item).

  • Modifying the configuration files in the content delivery package to configure or delete databases, archives, agents, sites, watchers, and other features.

If the correct credentials have not been established, you will be prompted to set up certificate access.

In the Install Management Certificate dialog, there are two installation options:

  • Basic installation – This is the fast and simple method offered by Microsoft. Click the link to get a .publishsetting file from Microsoft. Follow the instructions on the Microsoft Portal site, using your Windows Live account. To get the file, save the publishsetting file locally, then upload it using the Sitecore Azure Install Management Certificate dialog.

  • Advanced installation – This is the option for advanced users. You can use an existing certificate or generate a self-certificate. Upload the .pfx file for Sitecore. After you have selected either a .publishsettings or .pfx file, you must provide a password for a .pfx file. Click Upload.


If you do not already have a certificate from a certificate authority installed on your web server, you can create a self-generated certificate for development and testing purposes.

As a part of assembling a solution for deployment, the document root subfolder of your on-premise Sitecore installation (the Deployment server) is copied to a specific folder. During this process some paths to Sitecore documents that are copied to a specific folder can became too long. To avoid this, you can tune the path to the target folder by changing the value of the Build folder field of the appropriate Environment item. See Assemble a solution for deployment with Sitecore Azure for more details.


There is a configuration item for each environment under /Sitecore/system/Modules/Azure. During assembly, the Build folder for the configuration item is filed and specifies the target folder to copy the Sitecore documents to.

Consider the following for any ASP.NET application, such as Sitecore, on Microsoft Azure.

  • The default choice for ASP.NET session management is RedisSessionStateProvider. This is an out-of-process state provider, therefore factor this in to your code.

  • Before moving to the cloud, consider any internal applications integration within the solution.

  • Use configuration files rather than Windows IIS Manager.

  • You cannot deploy individual files to Microsoft Azure. You must deploy the entire document root.

  • Microsoft Azure uses local storage for custom files and folders that are large in size, such as disk caches. Use appropriate API’s for I/O tasks. Sitecore Azure is preconfigured to provide a default local storage called SitecoreWebSite.

  • You should use local storage for all custom I/O tasks that do not require persistence of data. Consider using the storage account for persisting data, but be aware that this approach can introduce a bottleneck in high performance environments.

  • Microsoft Azure instances are volatile by design. Design your architecture according to this premise.

When you use SQL Azure with Sitecore, you should consider the following:

  • When accessing a SQL Azure database from a remote location, the performance depends on network conditions and other factors.

  • Use an encrypted connection over port 1433 when accessing SQL Azure remotely, (outbound access from the content editing environment).

  • The maximum database size in SQL Azure depends on the service tier that you choose.

  • If SQL Server 2008 R2 is installed it must be with SP1.

  • SQL Azure uses IP address restrictions for database security.

  • If SQL Server is installed on a separate server, an appropriate Microsoft SQL Server Shared Management Objects package must be installed on the server where the Sitecore CMS is deployed.

The deployment name must be globally unique and can be used for multiple purposes in an Azure implementation. The deployment name is assigned using the following pattern:

[projectname][environmenttype][location][Farm Type][XX]Role[XX]Sc[first 3 chars of subscription id][UTCTimeStamp]

For example, a deployment name such as myprojectDevWeCd01Role01Sc561201304181010, indicates a project named: myproject is running as a development environment, using the West Europe hosting location, and the deployment type is a content delivery farm.

If you notice that some Dynamic Link Libraries (DLLs), were not automatically copied over, you must manually add the following DLLs to the bin folder of your website. Sitecore Azure will automatically include them in the next deployment.







The package for Sitecore Azure is encrypted by default. If you want to disable encryption, in the /App_Config/Include/Sitecore.Azure.config file, set the Azure.Package.NoEncryptPackage to true. For example:

<setting name="Azure.Package.NoEncryptPackage" value="true"/>

After you have successfully deployed your Sitecore instances to Azure, you can enable Remote desktop through the Microsoft Azure management portal. Remote desktop gives you access to the web role virtual machines.

You can find Sitecore settings that control SSL in the Service Configuration and Service Definition fields of the deployment item. Before you start deploying, add the appropriate information in these fields to enable SSL. For more information, see Where Sitecore Azure stores configuration information. You can find basic information about using SSL with Microsoft Azure on Microsoft's website.

Sitecore Azure does not support file media.

Sitecore Azure uses the same process as on-premise Sitecore solutions to clear caches. After completing a publishing operation, the Sitecore Azure content editing server writes a time stamp to the publishing target database. The Sitecore Azure content delivery server checks the time stamp on each request, and clears the caches accordingly.

Before you can configure a Sitecore Azure content delivery environment for multiple sites, you must configure a Web Role for Multiple Sites. To use the Sites section in the service definition file to configure a Web Role for multiple sites, refer to the WebRole Schema documentation on MSDN.


The service definition configuration is stored in the Service Definition field of the Azure Deployment item. To apply the service definition changes you must redeploy.

Test a Sitecore Azure content delivery environment for multiple sites on your local machine:

  1. In Sitecore Azure, on the map, click the deployment that is running. In the Farm menu select Properties.

  2. In the Properties dialog box, copy the value of your Windows Azure host name from the Webrole section.

  3. In the Windows host file, map your hostname (hostname and hostHeader attributes value) to your Windows Azure host name.

By default, Sitecore Azure extends the Microsoft.WindowsAzure.ServiceRuntime.RoleEntryPoint class to add functionality to configure the diagnostics. Sitecore Azure does this by using the Microsoft Azure Storage Account when the role instance is initialized (on start).

The RoleEntryPoint class is named Sitecore.Azure.WebRole, and  is located in the \bin\Sitecore.Azure.WebRole.dll assembly of the Sitecore website.

To implement a custom web role entry point:

  1. Implement a class that extends the default Sitecore.Azure.WebRole.WebRole class from the Sitecore.Azure.WebRole.dll assembly. You can find this assembly in the \Website\bin folder after the Sitecore Azure installation completes.

  2. Override the methods that execute when a role instance is initialized (OnStart), run (Run), and stopped (OnStop), in your class.

  3. Compile your code into a new assembly and put it in the \Website\bin folder of your solution.

  4. Update the assembly name in the Service Definition field of the deployment item:

    <NetFxEntryPoint assemblyName="bin\Sitecore.Azure.WebRole.dll" targetFrameworkVersion="4.5" />
  5. Create a new deployment, or upgrade an existing one, by using Sitecore Azure to apply the changes.

  • Restart ASP.NET.

  • Clear the browser cache.

  • Investigate the Sitecore logs in the Sitecore Deployment server environment for errors.

  • Remove the instances from the environment and deploy again.

  • After deploying, configure the $(dataFolder)\AzurePackages\(хх)Azure\SitecoreWebSite subfolder as the document root of an IIS web site, and diagnose that site.

  • Temporarily set the mode attribute of the /configuration/system.web/customErrors element in the web.config file to Off.


If you set the mode attribute to Off, it can expose detailed error information in the Microsoft Azure environment. Consider other techniques to protect the application while mode is Off. Remember to set mode to On or RemoteOnly after diagnosis, and remember to deploy that change.

Sitecore Azure only supports automatic deployment to SQL Azure databases. You can change the configuration settings to deploy to databases on Azure virtual machines (IaaS).

During a deployment, if you get a TooManyRequests error, you can increase the Get Operation Status interval. To change the Get Operation Status interval, open the Sitecore.Azure.config file in the Include folder (\website\AppConfig\) and then adjust the Azure.CheckAsyncOperationStatusIntervalInMS value.

To use your own domain name you must create a CNAME record with your internet provider. Using the tool provided by your internet provider, create an entry that maps the desired alias, such as www, for your domain to the host name that was assigned to it when your Microsoft Azure application was created, for example: Then use the tool supplied by your internet provider to forward the root domain to the subdomain that you have mapped to your Microsoft Azure host name.

You must always map CNAME records to a specific subdomain; you cannot map to the root domain itself or map a wildcard address.


Never map directly to a Virtual IP address (VIP), because in certain instances Microsoft Azure may change the underlying VIP.

Sitecore Azure stores configuration information in a number of locations, with basic configuration details stored in the /App_Config/Include/Sitecore.Azure.config file.

Sitecore manages configuration information using the Azure item (Sitecore/System/Modules/) and its descendants. The installed environments and the relevant deployment items contain configuration settings that are under the /Sitecore/System/Modules/Azure item. A few levels down is the Azure deployment item: Editing01, which contains configuration settings for deployment. You can access this through the Content Editor or by clicking More Options in the New Deployment dialog box.


You can manually customize several fields that contain configuration information for deployment.

Under each Azure deployment item, the Database References folder contains database projects for deployment to SQL Azure. By default, the delivery farm contains a core and web database, and the editing farm contains a core, master, and web database. If you need to deploy another database to SQL Azure, you can create another database item.

While Sitecore Azure is preparing the environment, the SQL Azure database servers and storage are also being created, (if they do not already exist). They will be used during the deployment process.