Changes

[https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0] and [https://github.com/pardeike/Harmony/releases/tag/v2.1.0.0 2.1] have many changes that benefit SMAPI and mods. Some notable changes:

[https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0] and [https://github.com/pardeike/Harmony/releases/tag/v2.1.0.0 2.1] have many changes that benefit SMAPI and mods. Some notable changes:

* Added [https://harmony.pardeike.net/articles/patching-finalizer.html finalizers] and [https://harmony.pardeike.net/articles/reverse-patching.html reverse patches].

* Added [https://harmony.pardeike.net/articles/patching-finalizer.html finalizers] and [https://harmony.pardeike.net/articles/reverse-patching.html reverse patches].

* Added [https://harmony.pardeike.net/api/HarmonyLib.Transpilers.html <tt>Manipulator</tt>] utility, <tt>CodeInstruction</tt> extensions, and other improvements for transpilers.

* Added more <tt>AccessTools.Is*</tt> methods.

* Added [https://harmony.pardeike.net/api/HarmonyLib.Transpilers.html <samp>Manipulator</samp>] utility, <samp>CodeInstruction</samp> extensions, and other improvements for transpilers.

* Added more <samp>AccessTools.Is*</samp> methods.

* Added support for .NET 5.

* Added support for .NET 5.

* Transpilers can now default to the original input by returning <tt>null</tt>.

* Transpilers can now default to the original input by returning <samp>null</samp>.

* Improved compatibility with Android modding.

* Improved compatibility with Android modding.

* Improved exception messages.

* Improved exception messages.

Nope. Although this is a major change, significant efforts were undertaken to minimise the impact:

Nope. Although this is a major change, significant efforts were undertaken to minimise the impact:

* mods which don't use Harmony directly aren't affected;

* mods which don't use Harmony directly aren't affected;

* most mods will be rewritten automatically for compatibility, so many mods will work without an update;

* most mods are rewritten automatically for compatibility, so they'll work without an update;

* pull requests will be submitted to update affected open-source mods;

* pull requests were submitted to update affected open-source mods;

* unofficial updates will be created if needed for mods which haven't updated officially;

* unofficial updates were created as needed for mods which hadn't updated officially;

* the changes will be actively communicated and documented to modders.

* the changes were actively communicated and documented to modders.

In addition, the current target is ''at least'' 90% compatibility for open-source mods before SMAPI migrates. All of this means that the release should have minimal impact on mod compatibility, despite the scope of the changes.

In addition, the target was ''at least'' 90% compatibility for open-source mods before SMAPI migrates. All of this means that the release should have minimal impact on mod compatibility, despite the scope of the changes.

===How to update your mod===

===How to update your mod===

===Stricter validation===

===Stricter validation===

Harmony 2.x has stricter validation in general, so invalid patches that would previously somewhat work (e.g. setting <tt>__result</tt> to the wrong type) will now cause errors. See the exception messages for help fixing these.

Harmony 2.x has stricter validation in general, so invalid patches that would previously somewhat work (''e.g.,'' setting <samp>__result</samp> to the wrong type) will now cause errors. See the exception messages for help fixing these.

===Patching static constructors===

===Patching static constructors===

The <tt>AccessTools</tt> methods for constructors (<tt>Constructor</tt>, <tt>DeclaredConstructor</tt>, and <tt>GetDeclaredConstructors</tt>) no longer match static constructors by default. Use the new <tt>searchForStatic</tt> argument if you need to match them:

The <samp>AccessTools</samp> methods for constructors (<samp>Constructor</samp>, <samp>DeclaredConstructor</samp>, and <samp>GetDeclaredConstructors</samp>) no longer match static constructors by default. Use the new <samp>searchForStatic</samp> argument if you need to match them:

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">

</syntaxhighlight>

</syntaxhighlight>

<tt>Farm.cleanupBeforePlayerExit</tt> doesn't exist, so it's inherited from <tt>GameLocation</tt>. Harmony 1.x would let you patch <tt>Farm.cleanupBeforePlayerExit</tt>, but in Harmony 2.x you must target the actual method (<tt>GameLocation.cleanupBeforePlayerExit</tt> in this example).

<samp>Farm.cleanupBeforePlayerExit</samp> doesn't exist, so it's inherited from <samp>GameLocation</samp>. Harmony 1.x would let you patch <samp>Farm.cleanupBeforePlayerExit</samp>, but in Harmony 2.x you must target the actual method (<samp>GameLocation.cleanupBeforePlayerExit</samp> in this example).

===<tt>HarmonyMethod</tt> no longer allows null===

===<samp>HarmonyMethod</samp> no longer allows null===

Harmony 1.x allowed <code>new HarmonyMethod(null)</code>, so you could safely use it with methods that might not exist. Harmony 2.x now throws an exception in that case, so you should check if you're not sure it exists:

Harmony 1.x allowed <code>new HarmonyMethod(null)</code>, so you could safely use it with methods that might not exist. Harmony 2.x now throws an exception in that case, so you should check if you're not sure it exists:

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">