Developing for Microsoft Azure - best practices

There are usually several different ways of how to set up the development environment for your Xperience projects running on Azure. This page provides our recommendations on the best options, explains several pitfalls you might encounter and offers solutions to certain problems.

Please note that some recommendations apply only to certain Azure environments, so proceed with the topics that apply to your environment.

Database

General rule: every deployment and every project must be connected to its one and only database.

Production and staging deployments have individual databases

Applies to: WEB APPS

When you use a staging environment to test your website before promoting it to production, always use different databases for each deployment (slot). This ensures that your staging deployment, does not damage your production database.

To set up your projects this way, modify the connection string in your local project to connect to a different database (you can create a copy of your production database through the Azure management portal) than your production project before you deploy the project to the staging slot.

If you need to switch the staging and production deployments but not the databases, you can set different connection strings in the Azure Management Portal.

1. Select your App service in the management portal.
2. Open the Application settings tab.
3. Configure the CMSConnectionString in the Connection strings section to connect either to the production or the copied database.

Database connections limit

Applies to: WEB APPS

If you need to adjust the database connections limit using the Max Pool Size attribute in the connection string, see Azure SQL Database resource limits.

<connectionStrings>
    <add name="CMSConnectionString" connectionString="Data Source=tcp:YourServerName.database.windows.net,1433;Initial Catalog=YourDatabaseName;User Id=YourUsername@YourServerName;Password=YourPassword;Max Pool Size=60" />
</connectionStrings>

There is no need to adjust this value if you do not have specific reasons to do so or encounter the error 10928. 

> Back to top

Web farms

The number of instances (web farm servers) being used is not higher than the number of web farm servers included in your license

Applies to: WEB APPS 

Do not increase the number of instances of your Azure project unless you have obtained a license with a corresponding number of web farm servers included. If you increase the number of instances beyond the number your license allows, the web farm server functionality will stop working completely.

Please contact your account manager to obtain a license for a higher number of web farm servers before increasing the number of instances in your Azure project.

> Back to top

Storage

Each project has its own blob storage or blob storage container

Applies to: WEB APPS BLOB STORAGE

If you have multiple projects connected to Azure Blob Storage, for example for testing and production, every project must have its own blob storage or at least a different blob storage container configured.

To configure your projects to use different containers, add the following key to the web.config file with the name of the new container as its value. Set a different value for each project.

• CMSAzureRootContainer – this key specifies the name of the blob container that will serve as the root of the application’s file system on the Azure Blob Storage account. The default value is cmsstorage.

<add key="CMSAzureRootContainer" value="CustomRoot"/>

The CMSHashStringSalt key is identical in all environments

Applies to: WEB APPS and all projects that use Content staging

The CMSHashStringSalt key defines the salt value that the system uses in hash functions, for example in macro signatures and media library links. For the content to be synchronized properly through Content staging, the value of this key must be identical in all environments you use. Otherwise, the hash values of objects will be different in different environments. Therefore, make sure that the value of this web.config key is set to a single static value, for example a random GUID, before you deploy your project to the Azure environment.

<appSettings>
    <add key="CMSHashStringSalt" value="eb2d6fac-8b9e-427c-b98b-3c562dffbb35" />
</appSettings>

Media files stored on blob storage are divided into folders

Applies to: WEB APPS BLOB STORAGE

Storing a large number of media files in a single folder can significantly affect the performance of your project when editing the files in the Media library application.

Instead of storing all files in one folder, create a structure and divide the files into multiple folders. The number of files in one folder directly affects the performance of the Media library user interface.

> Back to top

Temporary and cached files

Deleting files from the AzureCache and AzureTemp folders

Applies to: WEB APPS BLOB STORAGE

If Xperience is connected to the Azure Blob Storage, it creates two storage folders, AzureCache and AzureTemp, in its own file system. These folders store temporary files and their capacity is limited by default. If your project depletes the allocated space, local smart search indexes may stop working or media libraries may stop accepting files. This can result in the following error:

If this happens, you can temporarily solve these problems by cleaning the AzureCache and AzureTemp folders. In order to solve the problem permanently, see Preventing Azure cache folders from bloating.

To delete files in AzureCache and AzureTemp folders:

1. Connect to your project.
   • You can use FTP, Visual Studio, etc.
2. Locate the C:\Resources\Directory\<GUID>.CMSApp.AzureCache and C:\Resources\Directory\<GUID>.CMSApp.AzureTemp folders and clean the temporary files from them.

Preventing Azure cache folders from bloating

Applies to: WEB APPS BLOB STORAGE

See Preventing Azure cache folders from bloating for more recommendations on how to keep these folders from getting full.

> Back to top

Locally stored search indexes

For tips about using local search indexes when running on Azure, see: Troubleshooting local search indexes on Azure