Table of Contents

Setting up CI/CD

How to build deployable artifacts from a Dynamicweb 10 solution and deploy them to each environment

Continuous integration means every developer's work is merged and validated constantly, so the main branch stays releasable. Continuous delivery means that releasable branch actually gets released, at minimum to a test environment where the whole solution can be checked.

For a Dynamicweb 10 solution this comes down to two concrete problems: producing artifacts from a solution whose parts deploy differently, and getting those artifacts onto environments that may or may not host the application for you.

This article solves both using Azure DevOps. The principles carry to any build system.

Note

This continues from working in teams. Read that first, particularly the sections on databases and source control.

What gets deployed

A Dynamicweb solution deploys as two or three separate things, and keeping them separate is the whole reason for the project structure in Project structure:

Artifact Built from Deployed to
Files The .Files project The solution's Files folder
Custom code Custom code projects Installed as add-ins
Clean host A dedicated host project Only when you host the application

The database is not in this list. No pipeline step updates it, and content created on one environment does not travel to another. This surprises people regularly: a feature that works on test because someone created a page there will not work on production until someone creates that page on production.

Before you start

A build system

You need something that builds .NET applications and can reach your deploy targets. Azure DevOps, Jenkins, or any comparable system works. The examples here are Azure DevOps YAML.

Environments to deploy to

Developers working locally are working independently, which is good for them and useless for validating the solution as a whole. You need somewhere the complete solution runs with everyone's changes.

The recommended progression is:

Local development -> Shared test -> Staging -> Production
  • Shared test tracks the main branch and is always current. This is where features meet each other
  • Staging is for user acceptance testing
  • Production is the live site

Host these however you like, as long as the requirements are met.

A clean host, if you host the application

In DynamicWeb Cloud the application is version-less and managed for you. You deploy Files and custom code, and nothing else.

Anywhere else — Azure, AWS, on-premises — you bring your own application, so you need a host project to deploy. That is a different project from the one you run locally, because the local host references your custom code projects directly for a good F5 experience, and the deployed host must not.

Extending the structure from Project structure:

  1. Keep MyCustomerProject.Host as the local startup project, referencing your custom code projects
  2. Add a second host project, MyCustomerProject.DeployHost, with no references to custom code
  3. Deploy DeployHost; custom code reaches the solution as add-ins through the Files folder
Tip

Keep every project on the same Dynamicweb version by removing the package references from the individual projects and declaring one at the solution root in Directory.Build.props:

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

Change the package to match the release ring you want. If you host in DynamicWeb Cloud, align the ring with the one the host runs. Each cloud ring comes in a .NET 8 and a .NET 10 variant, such as R1 and R1-NET10, and current packages target net10.0, so the package and the host's ring must be on the same .NET version. See Cloud hosting and release rings.

New and updated projects should target net10.0. See DynamicWeb 10 on .NET 10 if the solution is still on net8.0.

Building the artifact

The build pipeline produces one artifact containing three zip files: MyCustomerProject.DeployHost.zip, Custom.zip, and Files.zip.

Build the clean host

The host is published rather than built, so the output is runnable:

Screenshot

- task: DotNetCoreCLI@2
  displayName: 'Build DeployHost'
  inputs:
    command: publish
    publishWebProjects: false
    projects: |
     **/*.DeployHost.csproj

    arguments: '-c Release --output $(Build.ArtifactStagingDirectory)'

The publish task zips its output by default and names the zip after the project folder, so this produces MyCustomerProject.DeployHost.zip.

Skip this step entirely if every target is in DynamicWeb Cloud.

Build the custom code

Custom code is built, not published, and the three project types that must be excluded are the reason the naming convention matters:

  • Files is deployed as-is and never built
  • Host is local development only
  • DeployHost was handled above
  • Swift-v2 is Swift's own project file, present if you installed Swift with the DynamicWeb CLI as described in Adding Swift to the Files project, and is not part of your custom code

Screenshot

- task: DotNetCoreCLI@2
  displayName: 'Build custom projects'
  inputs:
    projects: |
     **/*.csproj
     !**/*.Files.csproj
     !**/*.DeployHost.csproj
     !**/*.Host.csproj
     !**/Swift-v2.csproj
    arguments: '-c Release --artifacts-path $(Build.BinariesDirectory)/output'

Package the custom code

The archive task cannot glob, so copy the assemblies to one flat folder first:

Screenshot

- task: CopyFiles@2
  displayName: 'Copy Files to: $(Build.BinariesDirectory)/custom'
  inputs:
    SourceFolder: '$(Build.BinariesDirectory)'
    Contents: 'output/**/release/*.dll'
    TargetFolder: '$(Build.BinariesDirectory)/custom'
    CleanTargetFolder: true
    flattenFolders: true

Then archive them:

Screenshot

- task: ArchiveFiles@2
  displayName: 'Archive $(Build.BinariesDirectory)/custom'
  inputs:
    rootFolderOrFile: '$(Build.BinariesDirectory)/custom'
    includeRootFolder: false
    archiveFile: '$(Build.ArtifactStagingDirectory)/Custom.zip'

Build Swift's client-side assets

Skip this step if your Files folder is not based on Swift, or if your repository has no Swift package.json because you copied an already built Files folder into the Files project.

Swift's compiled CSS and JavaScript in Files/Templates/Designs/Swift-v2/Assets/ are excluded by Swift's .gitignore, so they are not in the repository the pipeline checks out. Without this step, Files.zip ships a Swift that renders with no styling and no interactivity. These steps match Swift's own build pipeline, and run in the folder containing Swift's package.json, which is MyCustomerProject.Files/Swift if you installed Swift with the DynamicWeb CLI:

- task: NodeTool@0
  displayName: 'Install Node.js'
  inputs:
    versionSpec: '20.x'

- script: npm install
  workingDirectory: MyCustomerProject.Files/Swift
  displayName: 'npm install'

- script: npm run build
  workingDirectory: MyCustomerProject.Files/Swift
  displayName: 'npm run build'

Package the Files folder

The Files folder is a plain folder inside the Files project, so apart from Swift's assets it needs no build step and archives directly. Point rootFolderOrFile at the Files folder inside your Files project, which is MyCustomerProject.Files/Swift/Files if you installed Swift with the DynamicWeb CLI:

Screenshot

- task: ArchiveFiles@2
  displayName: 'Archive MyCustomerProject.Files/Files'
  inputs:
    rootFolderOrFile: MyCustomerProject.Files/Files
    includeRootFolder: false
    archiveFile: '$(Build.ArtifactStagingDirectory)/Files.zip'

Publish the artifact

Screenshot

- task: PublishBuildArtifacts@1
  displayName: 'Publish Artifact: drop'

Deploying

Create a release pipeline containing every environment except local, connected to the build pipeline and triggered when a new artifact appears.

How automatic each stage should be differs by environment:

  • Shared test deploys automatically on every artifact
  • Staging and production should require approval

These examples use the DynamicWeb CLI, which talks to a running solution. That means the target must already be up, and you need an API key for it. Store the host URL and API key as pipeline variables per environment, so the same steps work for every target.

Install the CLI

Screenshot

- task: Npm@1
  displayName: 'npm install -g @dynamicweb/cli'
  inputs:
    command: custom
    verbose: false
    customCommand: 'install -g @dynamicweb/cli'

Deploy the custom code

Extract the assemblies:

Screenshot

- task: ExtractFiles@1
  displayName: 'Extract files'
  inputs:
    archiveFilePatterns: '**/Custom.zip'
    destinationFolder: '$(System.DefaultWorkingDirectory)/Custom'

Then install them. The CLI installs one assembly per call, so loop:

Screenshot

- powershell: |
   $dlls = Get-ChildItem -Filter *.dll

   foreach ($dll in $dlls) {
       dw install "$dll" --host $(host) --apiKey $(apiKey)
   }
  workingDirectory: '$(System.DefaultWorkingDirectory)/Custom'
  displayName: 'Assembly loop to install'
Note

Assemblies that are in use cannot always be replaced on a running solution, and assemblies with dependencies can fail to load cleanly. If you hit either, queue the installation for the next recycle with --queue or -q:

dw install "$dll" --queue --host $(host) --apiKey $(apiKey)

If you queue installations, recycling the solution afterwards is no longer optional.

Deploy the Files folder

Extract:

Screenshot

- task: ExtractFiles@1
  displayName: 'Extract files '
  inputs:
    archiveFilePatterns: '**/Files.zip'
    destinationFolder: '$(System.DefaultWorkingDirectory)/Files'

Then upload. The combined -iro flags mean import, recursively, overwriting existing files, sending the working directory (.) to the root (/) of the target's Files folder:

Screenshot

- script: 'dw files -iro . / --host $(host) --apiKey $(apikey)'
  workingDirectory: '$(System.DefaultWorkingDirectory)/Files'
  displayName: 'dw files'

Because of -o, the configuration files at the root of the Files folder in the artifact, such as GlobalSettings.config, replace the ones on the target. Keep each environment's database connection in a GlobalSettings.Database.config that is excluded from source control, as described in working in teams. It is then never in the artifact, and the deployment leaves it alone.

Important

The CLI adds and overwrites files; it does not delete files that are no longer in the artifact. A template you deleted in git stays on the target until someone removes it by hand, which matters when a file is deleted because it was wrong or superseded.

Finish the deployment

The final step depends on where you are deploying.

With a version-less cloud host there is nothing to deploy beyond Files and custom code. Recycle the solution so the changes take effect, which you do by uploading a recycle.txt file to /Files/System/CloudHosting:

Screenshot

- powershell: |
   ni recycle.txt
   dw files -io --createEmpty recycle.txt System/CloudHosting --host $(host) --apiKey $(apikey)
  displayName: 'Recycle application'

The file is empty, and the CLI skips empty files unless you pass --createEmpty. Without -o, the CLI also does not replace a recycle.txt that is already on the target, so the upload has no effect. Recycling is strongly recommended in all cases and required if you queued any add-in installations. See cloud hosting.

Verifying a deployment

A pipeline that reports success has only proved the files moved. Check that the solution actually works:

  1. Load the front page and an ecommerce page, since template errors often surface only on specific page types
  2. Confirm your custom add-ins are registered, visible in the App store if you installed with the CLI
  3. Check the error log for load failures, which is where a queued or failed assembly installation shows up
  4. Confirm the changes you expected are live, remembering that anything needing new content or settings will not be there until someone creates it

That last point is the most common cause of a successful deployment that appears to have changed nothing.

To top