Table of Contents

DW9-10 Upgrade Path

How to upgrade from Dynamicweb 9 to DynamicWeb 10

The Upgrade Path is a high-level path, that cuts a DynamicWeb upgrade in to smaller steps, while focusing on making as few changes to the solution as possible. While there are many potential ways from DW9.18 to DW10, the Upgrade Path, which we outline below, has a few benefits in consideration:

  • It minimizes big bang deployments
  • It provides a process where the individual steps can be more easily estimated
  • It provides a modular process where the individual steps can be rehearsed and improved from upgrade to upgrade

In general terms, the Upgrade Path follows a simple process:

  1. Upgrade Preparations: Upgrading DW9 and Swift to latest versions
  2. The Platform Upgrade: Moving the core to DW10
Note

The Upgrade Path is considered a general guideline more than a precise path to DW10. Solutions are often very different in their implementations and will often require tailored efforts on specific areas of the upgrade. The modular approach of the Upgrade Path enables you to more easily narrow the areas you need to tailor.

Upgrade Preparations

When planning an upgrade to DW10, it will often be helpful (and in some cases required) to upgrade the existing solution to the latest versions. While upgrading from DW9.15, for instance, is theoretically possible it will open a field of potential challenges, that will simply not be opened if you upgrade from DW9.18 instead.

flowchart LR
    A[Upgrade Preparations]
    A --> B{DynamicWeb 9.x version?}
    B --> |9.x-16| C[Upgrade to 9.18]
    B --> |9.17+| D{Swift Version?}
    C --> D
    D --> |1.25+| E[Ready for upgrade]
    D --> |1.x-24| F[Upgrade Swift to 1.26]
    F --> E

DW9.18 and DW10 shares much of the same core codebase, therefore there will simply be less differences when upgrading from 9.18. Additionally, the latest versions of Swift are built on top of DW10 but also tested on later 9.x versions, so you can expect a much better fit when upgrading from the latest versions.

Tip

It is entirely possible to upgrade to the latest DW9.x and Swift 1.x version before upgrading to DW10. In many cases it is also a prerequisite, but in all cases we recommend it, to minimize the size of individual deployments, so that any potential problems in the process can also be easily identified and fixed.

For upgrading DW9 and Swift, please refer to the specific documentation on those subjects:

Platform Upgrade

The actual upgrade to DW10 can also be broken down in to multiple, smaller steps. It is theoretically possible to multi-target the same database (from both DW9.18 and DW10) simultaneously, but for several reasons we recommend copying to an independent database.

For one thing, new versions of DW10.x will have the potential to contain database migrations, which differ from DW9.18. For another, working in an isolated environment during upgrades enables for much easier identification and solution of the challanges that show in the process.

We splitting the process into three separate areas:

  • Setup: Setting up the new DW10 instance
  • Migration: Migrating all custom code
  • Finalize: Configuring and testing the running DW10 instance
Tip

You can do the full upgrade on your local machine. Doing this will give you a much better sense of the new solution, and will also provide for easier, more specific debugging.

Platform Upgrade Overview

flowchart TD
    subgraph Setup
        direction LR
        A["Copy DW9.18 Database"] 
        A --> B["Create new DW10 Dotnet project"] 
        B --> C["Copy /Files to new project"]
    end
    Setup --> Migration

    subgraph Migration
        direction LR
        D["Migrate backend code to new project"] 
        D --> E["Run DW10 project"]
    end
    Migration --> Finalize

    subgraph Finalize
        direction LR
        F["Build Indices"] 
        F --> G["Setup Permissions"] 
        G --> H["Regression Testing"]
    end

Setup

During the setup phase, you will copy and prepare the content and files that need to be migrated from the existing/old solution. We recommend doing the upgrade on a local machine, where you check in the migrated code to source and afterwards deploying it to a cloud DW10 instance with the pipeline + CLI for setting up CI/CD.

In the following section, we assume working on a local machine.

Copy DW9.18 database

First, copy the DW9.18 database by exporting to a .bacpac file. Depending on your solution, you can leave out several tables in the export. For instance, log files and the recycle bin are not tables necessary for migrating the actual content. These tables can grow fairly large with time, so exporting and importing them make take a long time. If you're preparing the setup for doing a migration on your local machine, for instance, you will not need to import these tables.

Among the tables you can typically leave out for speed are:

  • dbo.ActionLog
  • dbo.CommandLog
  • dbo.EmailMessage
  • dbo.EmailRecipient
  • dbo.GeneralLog
  • dbo.RecycleBin
  • dbo.SmsMessage
  • dbo.TrackingSession
  • dbo.TrashBin

When you have a .bacpac file ready for import, import it to a local SqlExpress instance, or a container SQL Server on your machine. You can use a network SQL server if you need to, but we recommend working locally at this stage.

Tip

After the import, consider disabling all scheduled tasks to avoid any side effects at this point. When you have finished the later migration, you should enable them again, one by one, to test them. You can disable them easily by setting dbo.ScheduledTask.TaskEnabled = 0 in the imported database.

Create new DW10 project

DynamicWeb projects are often structured very differently, but for a DW10 application, there's typically three main areas we need to create for our local project:

  1. The local DW10 host
  2. A NET8 library for custom backend code
  3. A directory / project for Swift

We will create the above structure in source as a example. You can create all the NET8 libraries as you need to. For larger projects, we recommend separating the backend customizations into functional components to avoid coupling.

Prepare the repository

First, create a new source repo for you preferred provider (Github, DevOps, etc.) and enter the folder in a terminal (you can also branch out of the old solution, if you wish to keep it in the same source).

Create the projects

Install DW10 by following the steps below (or take a look at the setup documentation). We will assume your project name is Dw10Upgrade and the root folder is named the same. In the below, we will add the projects needed to do the upgrade.


    dotnet new install Dynamicweb.ProjectTemplates
    cd Dw10Upgrade
    dotnet new dw10-suite --name Dw10Upgrade.Host
    dotnet new classlib --name Dw10Upgrade.CustomCode --framework net8.0
    dotnet new classlib --name Dw10Upgrade.Swift --framework net8.0

Open the Dw10Upgrade.CustomCode.csproj file and add references to DynamicWeb:


    <ItemGroup>
        <PackageReference Include="Dynamicweb.Suite" Version="10.*" />
    </ItemGroup>

Open the Dw10Upgrade.Swift.csproj file and add references to DynamicWeb: The reference to the CustomCode project is optional, but often it will be needed.


    <ItemGroup>
        <ProjectReference Include="..\Dw10Upgrade.CustomCode\Dw10Upgrade.CustomCode.csproj" />
    </ItemGroup>
    <ItemGroup>
        <PackageReference Include="Dynamicweb.Suite" Version="10.*" />
    </ItemGroup>

Open the Dw10Upgrade.Host.csproj file and add references to the CustomCode project:


    <ItemGroup>
        <ProjectReference Include="..\Dw10Upgrade.CustomCode\Dw10Upgrade.CustomCode.csproj" />
    </ItemGroup>

Open the appsettings.json file in Dw10Upgrade.Host/ and add the following in the root path:


    "FilesPath":  "..\\Dw10Upgrade.Swift\\Files\\",

Copy /Files to new project

Note

At this stage, we assume you already upgraded an eventual Swift installation to the latest version. Older Swift versions are not compatible with DynamicWeb 10.

Make a Zip-file of the /Files directory in the existing DynamicWeb 9.18 solution and copy it to Dw10Upgrade.Swift/Files. In the same manner as the database export, there are several folders you can leave out. Among the considerations are:

  • Images, mediafiles, similar assets: You technically only need this for verifying display. If you have many assets in production, you might consider leaving some for faster copy.
  • Indexes: All indices need to be rebuilt, so you don't need to copy these (but remember to copy the repositories)

Migration

Note

The below sections remain unfinished. Content will be coming soon

Migrate Backend Code

Run the project

Finalize

Build Indices

Setup Permissions

Regression Testing

Improve this doc
To top