Upgrading Microsoft Azure projects

✖
Copy to clipboard

For projects hosted in Microsoft Azure, we strongly recommend performing the entire upgrade on a local machine and then redeploying the project.

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 and try out the database upgrade in advance.

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 Xperience on Microsoft Azure

Upgrading Azure projects

Upgrading projects running as Microsoft Azure App Services Web Apps is similar to upgrading a standard project, with the difference that you must export the database from the Azure SQL server and import it to your on premise server.

Part 1 - Project upgrade with a test database upgrade

Database export

  1. Create a copy of your Azure database on 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 the Azure management portal and select your SQL database.
    2. Click Copy on the Overview tab.
    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 (it is recommended to always use the latest version of Management Studio to remain compatible with Azure SQL Database updates).

      • You can find the name of your database server in the Azure management portal on the Overview tab. Enter the username and password that you used to create the Azure SQL server.
      • To connect to the Azure SQL server, you need to configure the firewall rules for the server in the Azure management portal – select your SQL database, click Set server firewall on the Overview tab, and add firewall rules for your local machine.

    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.

Project upgrade

  1. Set the connection string in the web.config files of your projects to the imported database on your server.

  2. Perform the required Steps before the upgrade.

  3. Run the upgrade utility for your local project (see Applying the upgrade).

  4. Be sure to open the upgraded administration site in a browser and wait for the upgrade procedure to finish.

    • When handling the first request, the system performs certain tasks required to finalize the upgrade. Processing of the first request may take longer than usual.

  5. Perform the required Steps after the upgrade and test your site.

    • If you need to make any database changes, track these changes so that you can replicate them again later on the production database.

  6. Remove the connection string from the web.config files and deploy the projects to your Azure Web Apps. You can use a staging environment.

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

Part 2 - Production database upgrade

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

Database export

  1. Export your production database from the Azure SQL server and import it to your on premise server.

Database upgrade

  1. Run the SQL upgrade script on the newly imported database on your server:

    • If you have a standard Xperience 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, 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 Xperience database)

  2. Set the connection string in the web.config files of your projects to the new database on your server.

  3. Open the project in a browser and wait for the upgrade procedure to finish.

  4. Perform any database changes that you tracked previously during the test database upgrade.

  5. Export your upgraded database from your on premise SQL server and import it to the Azure SQL server into a new database:

    1. Export the upgraded database to a BACPAC file.

    2. Import the BACPAC file to your Azure SQL Database.

      We recommend that you do not delete the original database immediately and wait after you have tested the upgraded database.

  6. Set the connection string of your previously deployed projects (in the staging environment) to connect to the newly upgraded database.

  7. Swap the staging deployment with your production deployment.

  8. 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 in the web.config file of your local project to have it prepared for future deployments.