Updating Harmony Core

---- EXPERIMENTAL ----

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.

Obtaining the Upgrade Tool

The upgrade tool is available from NuGet and can be downloaded and installed by using a DOTNET command, like this:

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 a DOTNET command, like this:

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

Additional 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 happens to include any NEW CodeGen templates then those templates will not be automatically added to the solution folders in Visual Studio. Doing so is simply a convenience as it allows you to easily ver the template files, but is not required for code generation. 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.

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.

Re-Build and Test Your Environment

The final step of the upgrade process is to re-build all of your code and verify that it still operates correctly. Bear in mind that the versions of various NuGet packages will have changed, so the build will need to download those packages from nuget.org. As a result, you will need to be on-line for this first build of the new version, and the first build will take a little longer than normal.