---
title: Upgrading Microsoft Azure projects
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

For projects hosted on Microsoft Azure, you need to **perform the entire upgrade on a local machine** and then redeploy the project after the upgrade is successfully completed.

Completing the upgrade procedure may take a significant amount of time, particularly for heavily customized projects. We recommend that you keep your production site running and first perform a local upgrade of your project to upgrade your code files and try out the database upgrade in advance. Then you need to take your website offline and repeat the process for a copy of the production database.

> **Note:** We do NOT recommend upgrading your database on an Azure SQL server directly, as this may prevent the upgrade script from performing certain changes in the database.

**See also:** [Running Kentico on Microsoft Azure](https://docs.kentico.com/k82/running-kentico-on-microsoft-azure.md)

## Upgrading Azure projects through the local emulator

We recommend that you perform the first site request and testing after the upgrade of an Azure project through the local emulator.

### Project upgrade

First upgrade your project code files in a local environment and try out the upgrade of your database.

1. Copy your Azure database to the same Azure SQL server. Creating a copy of a running database ensures that the copied database stays consistent, unlike database export performed in the next step, which may result in a faulty export.

   1. Open [Microsoft Azure management portal](https://manage.windowsazure.com) and select your database.
   2. Click **Copy** in the bottom panel.
   3. Copy the database to the same Azure SQL server.
2. Export the copied Azure database and import it to your on premise server:
   1. Open **Microsoft SQL Server Management Studio** and connect to your Azure SQL server (supported versions of Microsoft SQL Server are 2012 SP1 and newer).

      - You can find the name of your database server when you edit your database on the Azure management portal and display the **Dashboard** tab. Enter the username and password that you used for creating the Azure SQL server.
      - To connect to the Azure SQL server, you need to configure the firewall rules for the server in the [Microsoft Azure management portal](https://manage.windowsazure.com) – select your database server and add the firewall rules for your machine on the **Configure** tab.
   2. Right-click the copied database and select **Tasks -> Export Data-tier Application**.
   3. Save the database export to the disk.
   4. Connect to your own SQL server.
   5. Right-click the **Databases** node and select **Import Data-tier Application**.
   6. Import the exported database to your server.
3. Set up your project in a local development environment (emulated) and set the connection strings for the **CMSApp** and **SmartSearchWorker** roles to connect to the imported database on your server.

   - You need to set the connection string for all configurations (both Local and Cloud). The upgrade procedure upgrades the database specified in the connection string of the Cloud configuration.
   - See [Developing Azure projects locally](https://docs.kentico.com/k82/running-kentico-on-microsoft-azure/developing-azure-projects-locally.md) for details.
   - You do not need to start the emulator right now.
4. Increase the _Connection Timeout_ value in the connection strings of the CMSApp and SmartSearchWorker roles. We recommend at least 600 seconds.
5. Perform the required [Steps before the upgrade](https://docs.kentico.com/k82/installation/upgrading-to-kentico-8-2.md#steps-before-you-start-the-upgrade).
6. Install [Microsoft Azure SDK version **2.5**](http://azure.microsoft.com/en-us/downloads/archive-net-downloads/). We recommend using the WebPI all-in-one feed for your version of Visual Studio. You may also need to uninstall your previous version of Microsoft Azure Emulator and Tools for Visual Studio.
7. Run the upgrade utility for your local project (see [Applying the upgrade](https://docs.kentico.com/k82/installation/upgrading-to-kentico-8-2.md#applying-the-upgrade)).
8. The upgrade creates new versions of the project’s Microsoft Azure configuration files (_ServiceConfiguration.cscfg_, _ServiceDefinition.csdef_, _app.config_ of the SmartSearchWorker) with the _.new_ extension. You need to manually transfer your configuration to the new files and then replace the original ones.
9. If your CMSAzure project is customized, the upgrade creates a new version of _CMSAzure.ccproj_ in the _CMSAzure_ folder (with the ._new_ extension). Transfer any customizations from your original CMSAzure.ccproj file and remove the .new extension from the new one.
10. Open the project in Visual Studio (using CMSAzure.sln) and start the site in the emulator. Wait for the upgrade procedure to finish.

    > **Note:** **Important**: You always need to perform the first request on the upgraded site in a local development environment. Processing of the first request may take a longer than usual (up to an hour).
11. Perform the required [Steps after the upgrade](https://docs.kentico.com/k82/installation/upgrading-to-kentico-8-2.md#steps-after-performing-the-upgrade) and test your site.
12. Remove the connection string from the Cloud configurations of both the CMSApp and SmartSearchWorker roles and deploy the project to your Microsoft Azure staging environment. See [Deploying an Azure project](https://docs.kentico.com/k82/running-kentico-on-microsoft-azure/deploying-an-azure-project.md) for more information.

    - It is essential NOT to include the connection string to ensure that the application does not start after the deployment, which could cause problems with the web farm server settings.

### Production database upgrade

When you have upgraded your code files and uploaded your project to the staging environment, you can now shut down your production website and upgrade the production database.

1. Take your website offline. We recommend uploading the file to your site using remote desktop:

   1. Open the [Microsoft Azure management portal](https://manage.windowsazure.com) and select your cloud service.
   2. Switch to the **Configure** tab and click **Remote** in the bottom panel.
   3. Configure the remote desktop access for all roles.
   4. Switch to the **Instances** tab.
   5. Select an instance and click **Connect** in the bottom panel. The system downloads a file for remote connection.
   6. Run the file and connect to the cloud server.
   7. Locate your application and upload the **App\_offline.htm** file (available in the upgrade installation folder) to its root. You can simply use copy & paste.
   8. Repeat the steps _e_ - _g_ for all instances.
2. Export your production database from the Azure SQL server and import it to your on premise server.
3. Run the SQL upgrade script on the imported database on your server:
   - If you have a standard Kentico database, run the _**upgrade.sql**_ script located in the **SQL** folder of your upgrade installation directory.
   - If your project uses a [separated on-line marketing database](https://docs.kentico.com/k82/on-line-marketing-features/contact-management/separating-the-contact-management-database.md), expand the **SQL\Separation** folder in your upgrade installation directory and run the scripts _in the following order:_
     1. _**separated.sql**_ (against the separated on-line marketing database)
     2. _**default.sql**_ (against the main Kentico database)
4. Open the Azure project in Visual Studio (using CMSAzure.sln) and start the site in the emulator. Wait for the upgrade procedure to finish.
5. Open the administration interface of the upgraded local project and open the **Web farms** application. Delete all web farm servers.
   - This step is necessary to prevent more than the required number of web farm servers from being generated.
6. Export your upgraded database from your on premise SQL server and import it to the Azure SQL server into a new database:
   1. Open **Microsoft SQL Server Management Studio** and connect to your on premise server.
   2. Right-click your upgraded database and select **Tasks -> Export Data-tier Application**.
   3. Save the database export to the disk.
   4. Connect to the Azure SQL server.
   5. Right-click the **Databases** node and select **Import Data-tier Application**.
   6. Import the exported database to the Azure SQL server. We recommend that you do not delete the original database at the moment and wait after you have tested the upgraded database.
7. Set the connection string of your previously deployed project in the staging environment to connect to the new upgraded database. Set the connection string for both the CMSApp and SmartSearchWorker roles.

   1. Open the [Microsoft Azure management portal](https://manage.windowsazure.com) and select your cloud service.
   2. Switch to the **Staging** deployment and the **Configure** tab.
   3. Set the connection string to connect to the upgraded database.
8. Swap the staging deployment with your production deployment.
9. Open your website in the administration interface and open the **Event log** application and check if any errors occurred.

Your project files and database are now upgraded. When you have adequately tested your website and you are sure it is running as expected, you can delete your original Azure SQL database, the copied database and the staging deployment. You can also add the connection string to the Cloud configuration file of your local project to have it prepared for future deployments.

> **Tip:** **Upgrading Azure projects through a web application**
>
> If you are [developing Azure projects locally as web applications](https://docs.kentico.com/k82/running-kentico-on-microsoft-azure/developing-azure-projects-locally.md#developing-azure-projects-locally-as-web-applications), you can also upgrade your projects this way, without setting up the local emulator. The differences are that:
>
> - You set the connection string in the web.config file instead of the configuration files.
> - When you run the website locally as a web application, you need to open the solution using the **WebApp.sln** file and exclude the **CMSApp\_AppCode\Old\_App\_Code\CMSModules\WindowsAzure** folder from the project. Before the upgrade or deployment, you need to include the folder back in the project. See [Developing Azure projects locally as web applications](https://docs.kentico.com/k82/running-kentico-on-microsoft-azure/developing-azure-projects-locally.md#developing-azure-projects-locally-as-web-applications) for details.