Add exact argument name binding

Author: pardeike

Documentation/articles/patching-injections.md

@@ -39,6 +39,12 @@ To access or change one or several of the original methods arguments, simply rep
 - The type of an injected argument must be assignable from the original argument (or just use `object`)
 - The name of a given argument (that is to be matched to the argument of the original method) must either be the same name or of the form **`__n`**, where `n` is the zero-based index of the argument in the orignal method (you can also use argument annotations to map to custom names).
 
+If an original argument name conflicts with a Harmony injection name or naming convention, use `ArgumentMode.Original` to match its exact, case-sensitive name without interpreting it:
+
+```csharp
+static void Prefix([HarmonyArgument("__result", ArgumentMode.Original)] ref bool result)
+```
+
 ### __originalMethod
 
 To allow patches to identify on which method they are attached to, you can inject the original methods MethodBase by using an argument called **`__originalMethod`**.

Harmony/Internal/InjectedParameter.cs

@@ -22,6 +22,7 @@ internal class InjectedParameter
 		internal ParameterInfo parameterInfo;
 		internal string realName;
 		internal InjectionType injectionType;
+		internal ArgumentMode argumentMode;
 
 		internal const string INSTANCE_PARAM = "__instance";
 		internal const string ORIGINAL_METHOD_PARAM = "__originalMethod";
@@ -35,16 +36,25 @@ internal class InjectedParameter
 		internal InjectedParameter(MethodInfo method, ParameterInfo parameterInfo)
 		{
 			this.parameterInfo = parameterInfo;
-			realName = CalculateRealName(method);
-			injectionType = Type(realName);
+			var arg = parameterInfo.GetArgumentAttribute();
+			argumentMode = arg?.Mode ?? ArgumentMode.Default;
+			if (argumentMode == ArgumentMode.Original)
+			{
+				realName = arg.NewName;
+				injectionType = InjectionType.Unknown;
+			}
+			else
+			{
+				realName = CalculateRealName(method, arg);
+				injectionType = Type(realName);
+			}
 		}
 
-		string CalculateRealName(MethodInfo method)
+		string CalculateRealName(MethodInfo method, HarmonyArgument arg)
 		{
 			var baseArgs = method.GetArgumentAttributes();
 			if (method.DeclaringType is not null)
 				baseArgs = baseArgs.Union(method.DeclaringType.GetArgumentAttributes());
-			var arg = parameterInfo.GetArgumentAttribute();
 			if (arg != null)
 				return arg.OriginalName ?? parameterInfo.Name;
 			return baseArgs.GetRealName(parameterInfo.Name, null) ?? parameterInfo.Name;

Harmony/Internal/MethodCreatorTools.cs

@@ -280,7 +280,7 @@ List<KeyValuePair<LocalBuilder, Type>> tmpBoxVars
 					continue;
 				}
 
-				if (paramRealName.StartsWith(INSTANCE_FIELD_PREFIX, StringComparison.Ordinal))
+				if (injection.argumentMode != ArgumentMode.Original && paramRealName.StartsWith(INSTANCE_FIELD_PREFIX, StringComparison.Ordinal))
 				{
 					var fieldName = paramRealName.Substring(INSTANCE_FIELD_PREFIX.Length);
 					FieldInfo fieldInfo;
@@ -363,15 +363,21 @@ List<KeyValuePair<LocalBuilder, Type>> tmpBoxVars
 					continue;
 				}
 
-				if (config.localVariables.TryGetValue(paramRealName, out var localBuilder))
+				if (injection.argumentMode != ArgumentMode.Original && config.localVariables.TryGetValue(paramRealName, out var localBuilder))
 				{
 					var ldlocCode = paramType.IsByRef ? OpCodes.Ldloca : OpCodes.Ldloc;
 					codes.Add(new CodeInstruction(ldlocCode, localBuilder));
 					continue;
 				}
 
 				int argumentIdx;
-				if (paramRealName.StartsWith(PARAM_INDEX_PREFIX, StringComparison.Ordinal))
+				if (injection.argumentMode == ArgumentMode.Original)
+				{
+					argumentIdx = Array.IndexOf(originalParameterNames, paramRealName);
+					if (argumentIdx == -1)
+						throw new Exception($"Parameter \"{paramRealName}\" not found in method {original.FullDescription()}");
+				}
+				else if (paramRealName.StartsWith(PARAM_INDEX_PREFIX, StringComparison.Ordinal))
 				{
 					var val = paramRealName.Substring(PARAM_INDEX_PREFIX.Length);
 					if (!int.TryParse(val, out argumentIdx))

Harmony/Public/Attributes.cs

@@ -99,6 +99,16 @@ public enum ArgumentType
 		Pointer
 	}
 
+	/// <summary>Specifies how Harmony resolves an argument name</summary>
+	///
+	public enum ArgumentMode
+	{
+		/// <summary>Use Harmony's default argument name handling</summary>
+		Default = 0,
+		/// <summary>Match an original method argument by its exact name</summary>
+		Original = 1
+	}
+
 	/// <summary>Specifies the type of patch</summary>
 	///
 	public enum HarmonyPatchType
@@ -667,6 +677,9 @@ public class HarmonyFinalizer : Attribute
 	[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Method | AttributeTargets.Class | AttributeTargets.Struct, AllowMultiple = true)]
 	public class HarmonyArgument : Attribute
 	{
+		// Older Harmony versions copy the existing fields and reject this name instead of silently treating the argument as a special injection
+		const string LEGACY_REJECTION_NAME = "__HarmonyArgumentOriginal";
+
 		/// <summary>The name of the original argument</summary>
 		///
 		public string OriginalName { get; private set; }
@@ -679,12 +692,31 @@ public class HarmonyArgument : Attribute
 		///
 		public string NewName { get; private set; }
 
+		internal ArgumentMode Mode { get; private set; }
+
 		/// <summary>An annotation to declare injected arguments by name</summary>
 		///
 		public HarmonyArgument(string originalName) : this(originalName, null)
 		{
 		}
 
+		/// <summary>An annotation to declare an injected argument using the selected name handling</summary>
+		/// <param name="originalName">Name of the original argument</param>
+		/// <param name="mode">How Harmony resolves the argument name</param>
+		///
+		public HarmonyArgument(string originalName, ArgumentMode mode) : this(originalName)
+		{
+			Mode = mode;
+			if (mode == ArgumentMode.Original)
+			{
+				OriginalName = LEGACY_REJECTION_NAME;
+				Index = int.MinValue;
+				NewName = originalName;
+			}
+			else if (mode != ArgumentMode.Default)
+				throw new ArgumentOutOfRangeException(nameof(mode));
+		}
+
 		/// <summary>An annotation to declare injected arguments by index</summary>
 		/// <param name="index">Zero-based index</param>
 		///

HarmonyTests/Patching/Arguments.cs

@@ -488,6 +488,28 @@ public void Test_RenamedArguments()
 			Assert.AreEqual("val1, patched, val2, hello", log);
 		}
 
+		[Test]
+		public void Test_OriginalArgumentNames()
+		{
+			var harmony = new Harmony("test");
+			var processor = new PatchClassProcessor(harmony, typeof(OriginalArgumentNamesPatch));
+			var patches = processor.Patch();
+			Assert.NotNull(patches, "patches");
+			Assert.AreEqual(1, patches.Count);
+
+			var state = new object[] { "original state" };
+			var result = false;
+			var index = 0;
+			OriginalArgumentNames.log = null;
+			OriginalArgumentNamesPatch.gotInstance = false;
+			new OriginalArgumentNames().Method(state, ref result, "original field", ref index);
+
+			Assert.AreEqual("patched state, True, patched field, 42", OriginalArgumentNames.log);
+			Assert.IsTrue(result);
+			Assert.AreEqual(42, index);
+			Assert.IsTrue(OriginalArgumentNamesPatch.gotInstance);
+		}
+
 		[Test]
 		public void Test_CompatibleStateTypes()
 		{

HarmonyTests/Patching/Assets/ArgumentCases.cs

@@ -145,6 +145,37 @@ public static void Postfix([HarmonyArgument("__instance")] RenamedArguments foo2
 		}
 	}
 
+	public class OriginalArgumentNames
+	{
+		public static string log;
+
+		[MethodImpl(MethodImplOptions.NoInlining)]
+		public void Method(object[] __state, ref bool __result, string ___field, ref int __0)
+		{
+			log = $"{__state[0]}, {__result}, {___field}, {__0}";
+		}
+	}
+
+	[HarmonyPatch(typeof(OriginalArgumentNames), nameof(OriginalArgumentNames.Method))]
+	public static class OriginalArgumentNamesPatch
+	{
+		public static bool gotInstance;
+
+		public static void Prefix(
+			[HarmonyArgument("__state", ArgumentMode.Original)] object[] state,
+			[HarmonyArgument("__result", ArgumentMode.Original)] ref bool result,
+			[HarmonyArgument("___field", ArgumentMode.Original)] ref string field,
+			[HarmonyArgument("__0", ArgumentMode.Original)] ref int index,
+			[HarmonyArgument("__instance", ArgumentMode.Default)] OriginalArgumentNames instance)
+		{
+			state[0] = "patched state";
+			result = true;
+			field = "patched field";
+			index = 42;
+			gotInstance = instance is not null;
+		}
+	}
+
 	public class DifferingStateTypes
 	{
 		[MethodImpl(MethodImplOptions.NoInlining)]