Updating Harmony Core

Updating a Harmony Core Development Solution

We have created a command-line tool that allows you to upgrade an existing Harmony Core development solution to the latest version of Harmony Core. This tool should only be used on development solutions that were originally created from the Harmony Core Project Templates, as it expects to find the project heirarchy defined by those templates.

Here's what the upgrade tool does:

• Updates NuGet package references:
  • To the latest version of the four Harmony Core packages.
  • To the latest version of the Synergy/DE runtime and build packages.
  • To the currently recommended versions of other dependent packages.
  • Removes references to packages that are no longer required.
• Provides the latest versions of the Harmony Core CodeGen templates.
• Provides the latest versions of the Traditional Bridge library code, if present.
• Adds any new Traditional Bridge source files to the project hosting the Traditional Bridge code.
• Removes project references to any Traditional Bridge source files that are no longer used.

Verify your .NET Core SDK Version

Before upgrading your Harmony Core environment we recommend verifying that you are running the latest released version of the .NET Core SDK. You can check your current version with the following command:

dotnet --version

You should compare this version to the latest released version of the .NET Core SDK from Microsoft. At the time of writing (late March 2020) the latest version is 3.1.201.

Obtaining the Upgrade Tool

The upgrade tool is distributed via a special NuGet package and can be downloaded and installed using the following command:

dotnet tool install -g Harmony.Core.CliTool 

Upgrading the Upgrade Tool

Once you have the upgrade tool installed, you can check for and download any new version that may be available by using this command:

dotnet tool update -g Harmony.Core.CliTool

We recommend checking for a new version of the upgrade tool each time you need to upgrade a development solution.

Upgrading a Harmony Core Solution

Before running the project upgrade tool we strongly recommend ensuring that the current state of your entire development environment has been checked in to your source control repository so that in the event of an unexpected failure you are easily able to restore the current state of the environment.

Once you are confident that you have secured a copy of your current environment you can execute the project upgrade tool. To do so, open a Windows Command Prompt and navigate to the main solution folder, then type the following command:

harmonycore upgrade-latest

If you prefer you can upgrade a project without having to be in the solution folder, by setting the environment variable SolutionDir to point to the main solution directory. If you do this, make sure that the path that you specify ends with a trailing \ character.

The upgrade tool always upgrades the solution to the latest available version of Harmony Core.

Post-Upgrade Steps

In addition to the automated upgrade of your development environment, you will need to complete the following manual steps:

Add new CodeGen templates to the Visual Studio Solution folders

If the version upgrade includes additional CodeGen templates, those templates will not be automatically added to the solution folders in Visual Studio. Doing so is not required for development, it is simply a convenience that allows you to easily view the templates. If you want to keep the solution folders up to date then look for any new files in the Templates folder hierarchy and manually add them to the Visual Studio solution folders.

Check for Traditional Bridge Code File Changes

If you are using Traditional Bridge then you should check to see if any new traditional bridge source files were provided that were not previously present. If so then you will need to add these new files into your TraditionalBridge project in Visual Studio or, if you perform your Traditional Bridge code on a different system, you will need to move the new code to that system and update your build environment accordingly.

Install the Latest Version of CodeGen

In some cases, the CodeGen templates that are distributed with the Harmony Core release may require an updated version of CodeGen to be installed on your system. Download and install the latest version of CodeGen.

Install the Latest Version of the Harmony Core Project Templates

Each Harmony Core release also includes updated project templates that go along with that release. You should download and install the latest version of the project templates by executing the following command:

dotnet new -i Harmony.Core.ProjectTemplates

Re-generate your code.

Most Harmony Core releases are likely to include changes to one or more CodeGen templates, so you should always re-generate all of your generated code before attempting to build the updates solution.

Re-Build and Test Your Environment

You should now be able to re-build all of your code. Bear in mind that the versions of various NuGet packages will have changed, so the initial build will need to perform a nugget package restore to download the new versions of packages from nuget.org. As a result, you will need to be on-line for this first build, which will take a little longer than usual.

Test Your Environment

As with any upgrade to your Harmony Core services, you should fully test your services before publishing the new version to your production systems.