Lib.Harmony 2.0.1

A general non-destructive patch library for .NET and Mono modules

Install-Package Lib.Harmony -Version 2.0.1
dotnet add package Lib.Harmony --version 2.0.1
<PackageReference Include="Lib.Harmony" Version="2.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Lib.Harmony --version 2.0.1
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Introduction

Harmony - a library for patching, replacing and decorating .NET methods during runtime.

Prerequisites

Harmony works with all languages that compile to CIL, Microsofts intermediate byte code language. This is foremost the .NET Framework and of course Mono - used by the game engine Unity.

The exception is probably Unity .NET Standard profile, which does not provide the functionality to fully create methods on the fly at runtime.

Bootstrapping and Injection

Harmony does not provide you with a way to run your own code within an application that is not designed to execute foreign code. You need a way to inject at least the few lines that start the Harmony patching and this is usually done with a loader. Here are some common examples of loaders (incomplete):

You need to find your own injection method or choose a game that supports user dll loading (usually called Mods) like for example RimWorld (Wiki).

Dependencies

It has no other dependencies and will most likely work in other environments too. Harmony was tested on PC, Mac and Linux and support 32- and 64-bit. For a typical Unity target, simply set your project to .Net 3.5 or Mono 2.x and include the Harmony dll.

Altering functionality (Patching)

If you want to change how an exising C# application like a game works and you don't have the source code for that application, you have basically two options to do that:

  1. Alter dll files on disk
  2. Re-point method implementations (hooking)

Depending on the needs and situation, altering dll files is not always a desirable solution. For example

  • it has legal implications
  • it might be blocked by an anti-cheat system
  • it does not coordinate nicely with multiple concurrent changes
  • it has to be done before and outside the original application

Harmony focuces only on runtime changes that don't affect files on disk:

  • less conflicts with multiple mods
  • supports existing mod loaders
  • changes can be made dynamically/conditionally
  • the patch order can be flexible
  • other mods can be patched too
  • less legal issues

How Harmony works

Where other patch libraries simply allow you to replace the original method, Harmony goes one step further and gives you:

  • A way to keep the original method intact
  • Execute your code before and/or after the original method
  • Modify the original with IL code processors
  • Multiple Harmony patches co-exist and don't conflict with each other

Limits of runtime patching

note Harmony can't do everything. Make sure you understand the following:

  • With Harmony, you only manipulate methods. This includes constructors and getters/setters.

  • You can only work with methods that have an actual IL code body, which means that they appear in a dissassembler like dnSpy.

  • Methods that are too small might get inlined and your patches will not run.

  • You cannot add fields to classes and you cannot extend enums (they get compiled into ints).

  • Patching generic methods or methods in generic classes is difficult and might not work as you expect it to.

Hello World Example

Original game code:

[!code-csharpexample]

Patching with Harmony annotations:

[!code-csharpexample]

Alternatively, manual patching with reflection:

[!code-csharpexample]

Introduction

Harmony - a library for patching, replacing and decorating .NET methods during runtime.

Prerequisites

Harmony works with all languages that compile to CIL, Microsofts intermediate byte code language. This is foremost the .NET Framework and of course Mono - used by the game engine Unity.

The exception is probably Unity .NET Standard profile, which does not provide the functionality to fully create methods on the fly at runtime.

Bootstrapping and Injection

Harmony does not provide you with a way to run your own code within an application that is not designed to execute foreign code. You need a way to inject at least the few lines that start the Harmony patching and this is usually done with a loader. Here are some common examples of loaders (incomplete):

You need to find your own injection method or choose a game that supports user dll loading (usually called Mods) like for example RimWorld (Wiki).

Dependencies

It has no other dependencies and will most likely work in other environments too. Harmony was tested on PC, Mac and Linux and support 32- and 64-bit. For a typical Unity target, simply set your project to .Net 3.5 or Mono 2.x and include the Harmony dll.

Altering functionality (Patching)

If you want to change how an exising C# application like a game works and you don't have the source code for that application, you have basically two options to do that:

  1. Alter dll files on disk
  2. Re-point method implementations (hooking)

Depending on the needs and situation, altering dll files is not always a desirable solution. For example

  • it has legal implications
  • it might be blocked by an anti-cheat system
  • it does not coordinate nicely with multiple concurrent changes
  • it has to be done before and outside the original application

Harmony focuces only on runtime changes that don't affect files on disk:

  • less conflicts with multiple mods
  • supports existing mod loaders
  • changes can be made dynamically/conditionally
  • the patch order can be flexible
  • other mods can be patched too
  • less legal issues

How Harmony works

Where other patch libraries simply allow you to replace the original method, Harmony goes one step further and gives you:

  • A way to keep the original method intact
  • Execute your code before and/or after the original method
  • Modify the original with IL code processors
  • Multiple Harmony patches co-exist and don't conflict with each other

Limits of runtime patching

note Harmony can't do everything. Make sure you understand the following:

  • With Harmony, you only manipulate methods. This includes constructors and getters/setters.

  • You can only work with methods that have an actual IL code body, which means that they appear in a dissassembler like dnSpy.

  • Methods that are too small might get inlined and your patches will not run.

  • You cannot add fields to classes and you cannot extend enums (they get compiled into ints).

  • Patching generic methods or methods in generic classes is difficult and might not work as you expect it to.

Hello World Example

Original game code:

[!code-csharpexample]

Patching with Harmony annotations:

[!code-csharpexample]

Alternatively, manual patching with reflection:

[!code-csharpexample]

  • .NETCoreApp 3.0

  • .NETCoreApp 3.1

  • .NETFramework 3.5

    • No dependencies.
  • .NETFramework 4.5

    • No dependencies.
  • .NETFramework 4.7.2

    • No dependencies.
  • .NETFramework 4.8

    • No dependencies.

GitHub repositories (11+)

Showing the top 5 GitHub repositories that depend on Lib.Harmony:

Repository Stars
Sonarr/Sonarr
Smart PVR for newsgroup and bittorrent users.
SubnauticaNitrox/Nitrox
An open-source, multiplayer modification for the game Subnautica.
JetBrains/resharper-unity
Unity support for both ReSharper and Rider
CitiesSkylinesMultiplayer/CSM
Source code for the Cities: Skylines Multiplayer mod (CSM)
FailedShack/USBHelperLauncher
USBHelperLauncher restores and enhances Wii U USB Helper functionality by patching it at runtime and intercepting its network requests.

Version History

Version Downloads Last updated
2.0.1 2,818 5/10/2020
1.2.0.1 61,856 8/8/2018