Class Harmony

Namespace

HarmonyLib

Assembly

0Harmony.dll

The Harmony instance is the main entry to Harmony. After creating one with an unique identifier, it is used to patch and query the current application domain

public class Harmony

Inheritance

object

Harmony

Constructors

Harmony(string)

Creates a new Harmony instance

public Harmony(string id)

Parameters

id string

A unique identifier (you choose your own)

Fields

DEBUG

Set to true before instantiating Harmony to debug Harmony or use an environment variable to set HARMONY_DEBUG to '1' like this: cmd /C "set HARMONY_DEBUG=1 && game.exe"

public static bool DEBUG

Field Value

bool

Remarks

This is for full debugging. To debug only specific patches, use the HarmonyDebug attribute

Properties

Id

The unique identifier

public string Id { get; }

Property Value

string

ValidateStack

Whether Harmony rejects a method body in which the paths that reach an instruction have different stack depths, or an instruction pops more than the stack holds

public static bool ValidateStack { get; set; }

Property Value

bool

True by default

Remarks

ECMA-335 forbids both, but some runtimes accept such IL. Mono accepts a depth difference at a leave, and other runtimes accept more. Set this to false to leave the decision to the runtime. Harmony then sizes the stack for the deepest path.

The environment variable HARMONY_VALIDATE_STACK overrides this property when it is set to 1, 0, true or false.

Only Harmony's own method body writer checks the stack. It runs on .NET Core and .NET 5 or later. On .NET Framework and Mono the runtime checks the IL.

A jump to a label that no instruction carries is always rejected, because that jump has no target.

Methods

ClearSwitch(string)

Clears a MonoMod switch value

public static void ClearSwitch(string name)

Parameters

name string

The switch name

CreateClassProcessor(Type)

Creates a patch class processor from a class

public PatchClassProcessor CreateClassProcessor(Type type)

Parameters

type Type

The class/type

Returns

PatchClassProcessor

A new PatchClassProcessor instance

CreateProcessor(MethodBase)

Creates a empty patch processor for an original method

public PatchProcessor CreateProcessor(MethodBase original)

Parameters

original MethodBase

The original method/constructor

Returns

PatchProcessor

A new PatchProcessor instance

CreateReversePatcher(MethodBase, HarmonyMethod)

Creates a reverse patcher for one of your stub methods

public ReversePatcher CreateReversePatcher(MethodBase original, HarmonyMethod standin)

Parameters

original MethodBase

The original method/constructor

standin HarmonyMethod

The stand-in stub method as HarmonyMethod

Returns

ReversePatcher

A new ReversePatcher instance

GetAllPatchedMethods()

Gets all patched original methods in the appdomain

public static IEnumerable<MethodBase> GetAllPatchedMethods()

Returns

IEnumerable<MethodBase>

An enumeration of patched original methods/constructors

GetMethodFromStackframe(StackFrame)

Tries to get the method from a stackframe including dynamic replacement methods

public static MethodBase GetMethodFromStackframe(StackFrame frame)

Parameters

frame StackFrame

The System.Diagnostics.StackFrame

Returns

MethodBase

For normal frames, frame.GetMethod() is returned. For frames containing patched methods, the replacement method is returned or null if no method can be found

GetOriginalMethod(MethodInfo)

Gets the original method from a given replacement method

public static MethodBase GetOriginalMethod(MethodInfo replacement)

Parameters

replacement MethodInfo

A replacement method (patched original method)

Returns

MethodBase

The original method/constructor or null if not found

GetOriginalMethodFromStackframe(StackFrame)

Gets the original method from the stackframe and uses original if method is a dynamic replacement

public static MethodBase GetOriginalMethodFromStackframe(StackFrame frame)

Parameters

frame StackFrame

The System.Diagnostics.StackFrame

Returns

MethodBase

The original method from that stackframe

GetPatchInfo(MethodBase)

Gets patch information for a given original method

public static Patches GetPatchInfo(MethodBase method)

Parameters

method MethodBase

The original method/constructor

Returns

Patches

The patch information as Patches

GetPatchedMethods()

Gets the methods this instance has patched

public IEnumerable<MethodBase> GetPatchedMethods()

Returns

IEnumerable<MethodBase>

An enumeration of original methods/constructors

HasAnyPatches(string)

Test for patches from a specific Harmony ID

public static bool HasAnyPatches(string harmonyID)

Parameters

harmonyID string

The Harmony ID

Returns

bool

True if patches for this ID exist

Patch(MethodBase, HarmonyMethod, HarmonyMethod, HarmonyMethod, HarmonyMethod)

Creates patches by manually specifying the methods

public MethodInfo Patch(MethodBase original, HarmonyMethod prefix = null, HarmonyMethod postfix = null, HarmonyMethod transpiler = null, HarmonyMethod finalizer = null)

Parameters

original MethodBase

The original method/constructor

prefix HarmonyMethod

An optional prefix method wrapped in a HarmonyMethod object

postfix HarmonyMethod

An optional postfix method wrapped in a HarmonyMethod object

transpiler HarmonyMethod

An optional transpiler method wrapped in a HarmonyMethod object

finalizer HarmonyMethod

An optional finalizer method wrapped in a HarmonyMethod object

Returns

MethodInfo

The replacement method that was created to patch the original method. An open generic definition installed by a registered MethodBodyPatching installer has no callable copy: the definition itself is returned, or null for a constructor.

PatchAll()

Infers the calling assembly and applies its annotated patches

[Obsolete("Automatic assembly detection can fail after inlining or tail calls. Use PatchAll(Assembly) with an explicit assembly.")]
public void PatchAll()

Remarks

Caller inlining or tail calls can select the wrong assembly. Use PatchAll(Assembly) with an explicit assembly.

PatchAll(Assembly)

Searches an assembly for HarmonyPatch-annotated classes/structs and uses them to create patches

public void PatchAll(Assembly assembly)

Parameters

assembly Assembly

The assembly

PatchAllUncategorized()

Infers the calling assembly and applies its annotated patches without categories

[Obsolete("Automatic assembly detection can fail after inlining or tail calls. Use PatchAllUncategorized(Assembly) with an explicit assembly.")]
public void PatchAllUncategorized()

Remarks

Caller inlining or tail calls can select the wrong assembly. Use PatchAllUncategorized(Assembly) with an explicit assembly.

PatchAllUncategorized(Assembly)

Searches an assembly for HarmonyPatch-annotated classes/structs without category annotations and uses them to create patches

public void PatchAllUncategorized(Assembly assembly)

Parameters

assembly Assembly

The assembly

PatchCategory(Assembly, string)

Searches an assembly for HarmonyPatch-annotated classes/structs with a specific category and uses them to create patches

public void PatchCategory(Assembly assembly, string category)

Parameters

assembly Assembly

The assembly

category string

Name of patch category

PatchCategory(string)

Infers the calling assembly and applies its annotated patches in a category

[Obsolete("Automatic assembly detection can fail after inlining or tail calls. Use PatchCategory(Assembly, string) with an explicit assembly.")]
public void PatchCategory(string category)

Parameters

category string

Name of patch category

Remarks

Caller inlining or tail calls can select the wrong assembly. Use PatchCategory(Assembly, string) with an explicit assembly.

ReversePatch(MethodBase, HarmonyMethod, MethodInfo)

Patches a foreign method onto a stub method of yours and optionally applies transpilers during the process

public static MethodInfo ReversePatch(MethodBase original, HarmonyMethod standin, MethodInfo transpiler = null)

Parameters

original MethodBase

The original method/constructor you want to duplicate

standin HarmonyMethod

Your stub method as HarmonyMethod that will become the original. Needs to have the correct signature (either original or whatever your transpilers generates)

transpiler MethodInfo

An optional transpiler as method that will be applied during the process

Returns

MethodInfo

The replacement method that was created to patch the stub method

SetSwitch(string, object)

Sets a MonoMod switch value (e.g., "DMDDebug", "DMDDumpTo")

public static void SetSwitch(string name, object value)

Parameters

name string

The switch name

value object

The value to set (bool, string, etc.)

TryGetSwitch(string, out object)

Tries to get a MonoMod switch value

public static bool TryGetSwitch(string name, out object value)

Parameters

name string

The switch name

value object

The switch value if found

Returns

bool

True if the switch was found, false otherwise

TryIsSwitchEnabled(string, out bool)

Tries to determine if a MonoMod switch is enabled

public static bool TryIsSwitchEnabled(string name, out bool isEnabled)

Parameters

name string

The switch name

isEnabled bool

True if the switch is enabled, false otherwise

Returns

bool

True if the switch enablement state could be determined, false otherwise

Unpatch(MethodBase, HarmonyPatchType, string)

Unpatches a method by patching it with zero patches. Fully unpatching is not supported. Be careful, unpatching is global

public void Unpatch(MethodBase original, HarmonyPatchType type, string harmonyID = "*")

Parameters

original MethodBase

The original method/constructor

type HarmonyPatchType

The HarmonyPatchType

harmonyID string

The optional Harmony ID to restrict unpatching to a specific Harmony instance

Unpatch(MethodBase, MethodInfo)

Unpatches a method by patching it with zero patches. Fully unpatching is not supported. Be careful, unpatching is global

public void Unpatch(MethodBase original, MethodInfo patch)

Parameters

original MethodBase

The original method/constructor

patch MethodInfo

The patch method as method to remove

UnpatchAll(string)

Unpatches methods by patching them with zero patches. Fully unpatching is not supported. Be careful, unpatching is global

public void UnpatchAll(string harmonyID = null)

Parameters

harmonyID string

The optional Harmony ID to restrict unpatching to a specific Harmony instance

Remarks

This method could be static if it wasn't for the fact that unpatching creates a new replacement method that contains your harmony ID

UnpatchCategory(Assembly, string)

Searches an assembly for HarmonyPatch-annotated classes/structs with a specific category annotation and uses them to unpatch existing patches. Fully unpatching is not supported. Be careful, unpatching is global

public void UnpatchCategory(Assembly assembly, string category)

Parameters

assembly Assembly

The assembly

category string

Name of patch category

UnpatchCategory(string)

Infers the calling assembly and unpatches its annotated types in a category. Fully unpatching is not supported. Be careful, unpatching is global

[Obsolete("Automatic assembly detection can fail after inlining or tail calls. Use UnpatchCategory(Assembly, string) with an explicit assembly.")]
public void UnpatchCategory(string category)

Parameters

category string

Name of patch category

Remarks

Caller inlining or tail calls can select the wrong assembly. Use UnpatchCategory(Assembly, string) with an explicit assembly.

VersionInfo(out Version)

Gets Harmony version for all active Harmony instances

public static Dictionary<string, Version> VersionInfo(out Version currentVersion)

Parameters

currentVersion Version

[out] The current Harmony version

Returns

Dictionary<string, Version>

A dictionary containing assembly versions keyed by Harmony IDs