Updating Harmony Core

Updating a Harmony Core Solution

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

Here's what the upgrade tool does:

• Updates NuGet package references to:
  • The latest version of the Harmony Core packages.
  • The latest version of the Synergy/DE runtime and build packages.
  • The recommended versions of dependent packages.
• Removes references to NuGet 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 source code, if Traditional Bridge is present in the solution.

Obtaining the Upgrade Tool

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

dotnet tool install -g Harmony.Core.CliTool 

Once you have the upgrade tool installed, you can check for and download a new version of the tool 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 solution.

Pre-Upgrade Tasks

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 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 (May 2023) the latest supported version is 6.0.408.

Backup Your Code

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.

If you don't use a formal version control product then use some other method to preserve the current state of your development environment.

If You Have Customized Templates

We recommend that you avoid customizing the Harmony Core CodeGen templates; we have specific extensibility points throughout the environment that are designed to allow you to customize the environment. If these extensibility points do not meet your requirements then we encourage you to contact us so that we can understand your needs and implement a solution to address those needs without editing either CodeGen templates or generated code.

However, if you did find it necessary to customize templates then, with each release, you will need to diff and merge any changes that we may have made to the standard templates into your own custom templates.

By default the upgrade tool will download and overwrite the CodeGen templates (and Traditional Bridge library code). Ideally, you will have your code in version control and will be able to easily visualize and reconcile any changes that we make, but if not then you will need to use whatever tools you have at your disposal to ensure that both our changes and your customizations make it into your new codebase.

If absolutely necessary then you can suppress the overwriting of updated CodeGen templates and Traditional Bridge code by adding a -p option to the command line when updating your solution. If you do so you should then go to GitHub to download the templates that are distributed with the latest version and propagate any changes forward.

Upgrading a Solution

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

Here is an example of upgrading a solution"

D:\DEV\HarmonyCoreDemoIIS>harmonycore update-latest
Scanning 'D:\DEV\HarmonyCoreDemoIIS' for HarmonyCore project files
Updating template files in D:\DEV\HarmonyCoreDemoIIS\Templates
Found template files in D:\DEV\HarmonyCoreDemoIIS\Templates\SignalR
Found template files in D:\DEV\HarmonyCoreDemoIIS\Templates\xfServerPlus
Found template files in D:\DEV\HarmonyCoreDemoIIS\Templates\TraditionalBridge
Updating traditional bridge files in D:\DEV\HarmonyCoreDemoIIS\TraditionalBridge\Bridge

D:\HarmonyCoreDemoIIS>

You can also upgrade a project without being in the solution folder. To do this you must set the environment variable SolutionDir to point to the main solution directory, ensuring that the path specified ends with a trailing \.

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

Post-Upgrade Tasks

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

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.

If new CodeGen templates were provided, make sure you check the new files into your version control environment.

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.

If new Traditional Bridge code was provided, make sure you check the new files into your version control environment.

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