Upgrading Microsoft Azure projects

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.

See also: Running Kentico on Microsoft Azure

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 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 — 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 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.

6. Install Microsoft Azure SDK version 2.3. 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).

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.

    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 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 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 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 (upgrade.sql included in the SQL folder of the upgrade package) on the imported database on your server.

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 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.