Lib.Harmony
2.0.0.8
See the version list below for details.
dotnet add package Lib.Harmony --version 2.0.0.8
NuGet\Install-Package Lib.Harmony -Version 2.0.0.8
<PackageReference Include="Lib.Harmony" Version="2.0.0.8" />
paket add Lib.Harmony --version 2.0.0.8
#r "nuget: Lib.Harmony, 2.0.0.8"
// Install Lib.Harmony as a Cake Addin #addin nuget:?package=Lib.Harmony&version=2.0.0.8 // Install Lib.Harmony as a Cake Tool #tool nuget:?package=Lib.Harmony&version=2.0.0.8
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):
- Unity Doorstep
- BepInEx
- UnityAssemblyInjector
- MonoJunkie
- MInjector
- and more...
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:
- Alter dll files on disk
- 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
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]
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp3.0 is compatible. netcoreapp3.1 is compatible. |
.NET Framework | net35 is compatible. net40 was computed. net403 was computed. net45 is compatible. net451 was computed. net452 was computed. net46 was computed. net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 is compatible. net48 is compatible. net481 was computed. |
-
.NETCoreApp 3.0
- MonoMod.Common (>= 20.2.27.1)
-
.NETCoreApp 3.1
- MonoMod.Common (>= 20.2.27.1)
-
.NETFramework 3.5
- No dependencies.
-
.NETFramework 4.5
- No dependencies.
-
.NETFramework 4.7.2
- No dependencies.
-
.NETFramework 4.8
- No dependencies.
NuGet packages (78)
Showing the top 5 NuGet packages that depend on Lib.Harmony:
Package | Downloads |
---|---|
ClownFish.Nebula.net
简单易用的应用程序开发框架,支持多种架构模式(SaaS多租户/微服务/单体/模块化),内置强大的日志和监控能力。 |
|
Allure.Xunit
Create beautiful reports from your xUnit.net tests. |
|
Allure.SpecFlow
Create beautiful reports from your SpecFlow tests. |
|
WpfPilot
Next generation WPF automation testing. |
|
BrowserStack.TestAdapter
VS TestAdapter for integrating selenium tests with BrowserStack |
GitHub repositories (38)
Showing the top 5 popular GitHub repositories that depend on Lib.Harmony:
Repository | Stars |
---|---|
Sonarr/Sonarr
Smart PVR for newsgroup and bittorrent users.
|
|
Revolutionary-Games/Thrive
The main repository for the development of the evolution game Thrive.
|
|
JetBrains/resharper-unity
Unity support for both ReSharper and Rider
|
|
SychicBoy/NETReactorSlayer
An open source (GPLv3) deobfuscator and unpacker for Eziriz .NET Reactor
|
|
skyarkhangel/Hardcore-SK
Rimworld Hardcore SK project, our discord server:
|