[r8-obfuscation] Rewrite managed JNI metadata from R8 mappings (#12630)

Related to #12535

Depends on #12629

Layer 3 of 6 in the replacement stack for #12575.

This layer rewrites standard managed JNI metadata from R8 mappings. Trimmable typemap and FieldRVA handling follows in layer 4.

Author: simonrozsival

Documentation/docs-mobile/TOC.yml

@@ -364,6 +364,10 @@
         href: messages/xa4323.md
       - name: XA4324
         href: messages/xa4324.md
+      - name: XA4325
+        href: messages/xa4325.md
+      - name: XA4326
+        href: messages/xa4326.md
     - name: "XA5xxx: GCC and toolchain"
       items:
       - name: "XA5xxx: GCC and toolchain"

Documentation/docs-mobile/messages/index.md

@@ -254,6 +254,8 @@ Either change the value in the AndroidManifest.xml to match the $(SupportedOSPla
 + [XA4322](xa4322.md): Skipping library ProGuard configuration file '{file}' (from {source}) because it contains the unsupported global option '{option}'. Global ProGuard options are only allowed in application projects.
 + [XA4323](xa4323.md): Ignoring directory '{directory}' as it does not exist.
 + [XA4324](xa4324.md): [{arch}] Unable to delete source file '{file}'.
++ [XA4325](xa4325.md): Failed to rewrite managed JNI names for R8. {message}
++ [XA4326](xa4326.md): Unable to safely rewrite a JNI member lookup because its class handle does not have one structurally unambiguous `JNIEnv.FindClass` source.
 
 ## XA5xxx: GCC and toolchain
 

Documentation/docs-mobile/messages/xa4325.md

@@ -0,0 +1,56 @@
+---
+title: .NET for Android error XA4325
+description: XA4325 error code
+ms.date: 09/01/2026
+f1_keywords:
+  - "XA4325"
+---
+
+# .NET for Android error XA4325
+
+## Example messages
+
+```
+error XA4325: Failed to rewrite managed JNI names for R8. The 'SourceFiles' and 'DestinationFiles' item groups must contain the same number of items.
+```
+
+```
+error XA4325: Failed to rewrite managed JNI names for R8. Could not rewrite the JNI names in the assembly 'obj/Release/net11.0-android/android/Acme.App.dll': The file contains no managed metadata.
+```
+
+## Issue
+
+When R8 obfuscates Java type and member names, the JNI names embedded in your
+managed assemblies must be updated to match the obfuscated names. This error
+means that step failed, so the app would not have been able to find its Java
+types at run time.
+
+There are two causes:
+
+* **Mismatched item groups.** The `SourceFiles` and `DestinationFiles` item
+  groups passed to the `RewriteJniNamesForR8` task did not contain the same
+  number of items. This only happens if a custom target invokes the task
+  directly, or if a target that produces these item groups has been overridden.
+
+* **An assembly could not be rewritten.** A specific assembly could not be read
+  or reconstructed. The message names the assembly and includes the underlying
+  reason, such as the file not containing managed metadata or containing
+  malformed IL.
+
+## Solution
+
+For the mismatched item groups case, review any custom targets that call
+`RewriteJniNamesForR8` and make sure `SourceFiles` and `DestinationFiles` are
+populated in matching order, or set `DestinationDirectory` instead of
+`DestinationFiles`.
+
+For the assembly failure case, first confirm the named file is a managed
+assembly and is not corrupt. Deleting the `bin/` and `obj/` directories and
+rebuilding clears a partially written or stale file.
+
+If the named file is a valid managed assembly and the failure persists, this is
+unexpected. Please [report an issue][report-issue] and include the full error
+message, the name of the assembly, and, if possible, a project that reproduces
+the failure.
+
+[report-issue]: https://github.com/dotnet/android/issues/new/choose

Documentation/docs-mobile/messages/xa4326.md

@@ -0,0 +1,39 @@
+---
+title: .NET for Android warning XA4326
+description: XA4326 warning code
+ms.date: 09/01/2026
+f1_keywords:
+  - "XA4326"
+---
+
+# .NET for Android warning XA4326
+
+## Example message
+
+```
+warning XA4326: Unable to safely rewrite a JNI member lookup because its class handle does not have one structurally unambiguous JNIEnv.FindClass source.
+```
+
+## Issue
+
+R8 renamed a Java class referenced by a managed JNI member lookup. The class
+handle is assigned more than once, comes from an ambiguous control-flow path, or
+cannot be proven to come directly from `JNIEnv.FindClass`.
+
+The class name can be rewritten, but the corresponding member name cannot be
+safely associated with one original Java class. Guessing could make the managed
+assembly request a member from the wrong obfuscated class.
+
+## Solution
+
+This warning is unexpected for code generated by .NET for Android. Please
+[report an issue][report-issue] and include the full warning, the affected
+assembly, its R8 mapping file, and, if possible, a project that reproduces the
+warning.
+
+If the assembly contains custom JNI code, keep each `JNIEnv.FindClass` call and
+the member lookup that uses its result in an unambiguous sequence. Initialize
+each cached class-handle field from one direct `JNIEnv.FindClass` call and do
+not assign another class handle to the same field.
+
+[report-issue]: https://github.com/dotnet/android/issues/new/choose

src/Xamarin.Android.Build.Tasks/Properties/Resources.Designer.cs

@@ -884,6 +884,23 @@ Remove the '{0}' reference from your project and add the '{1}' NuGet package ins
     <comment>{0} - The target architecture, such as Arm, Arm64, or X86_64
 {1} - The path to the source file which could not be deleted.</comment>
   </data>
+  <data name="XA4325" xml:space="preserve">
+    <value>Failed to rewrite managed JNI names for R8. {0}</value>
+    <comment>{0} - A sentence describing the specific failure. It is supplied by one of the XA4325_* resources.</comment>
+  </data>
+  <data name="XA4325_AssemblyFailure" xml:space="preserve">
+    <value>Could not rewrite the JNI names in the assembly '{0}': {1}</value>
+    <comment>{0} - The path of the assembly which could not be rewritten.
+{1} - The underlying message describing why the assembly could not be rewritten. It is not localized.</comment>
+  </data>
+  <data name="XA4325_SourceDestinationCount" xml:space="preserve">
+    <value>The 'SourceFiles' and 'DestinationFiles' item groups must contain the same number of items.</value>
+    <comment>The following are literal MSBuild item group names and should not be translated: 'SourceFiles', 'DestinationFiles'.</comment>
+  </data>
+  <data name="XA4326" xml:space="preserve">
+    <value>Unable to safely rewrite a JNI member lookup because its class handle does not have one structurally unambiguous JNIEnv.FindClass source.</value>
+    <comment>The following are literal API names and should not be translated: JNI, JNIEnv.FindClass.</comment>
+  </data>
   <data name="XA5101" xml:space="preserve">
     <value>Missing Android NDK toolchains directory '{0}'. Please install the Android NDK.</value>
     <comment>{0} - The path of the missing directory</comment>

src/Xamarin.Android.Build.Tasks/Properties/Resources.resx

@@ -0,0 +1,136 @@
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Microsoft.Android.Build.Tasks;
+using Microsoft.Build.Framework;
+using Microsoft.Build.Utilities;
+using Xamarin.Android.Tasks.JniRemapping;
+
+namespace Xamarin.Android.Tasks
+{
+	/// <summary>
+	/// Rewrites JNI names embedded in compiled assemblies: Android.Runtime.RegisterAttribute,
+	/// the Java.Interop.Jni*SignatureAttribute family, and generated JniPeerMembers /
+	/// RegisterNatives <c>ldstr</c> strings. The R8 <c>mapping.txt</c> supplies the obfuscated
+	/// Java names that managed metadata must reference.
+	///
+	/// Each assembly is fully reconstructed with System.Reflection.Metadata: every metadata table
+	/// row is cloned in its original order, so every entity token keeps its value, while the
+	/// heaps, method bodies, managed resources, and mapped field data are re-emitted. Replacements
+	/// may therefore be of any length.
+	///
+	/// An adjacent PDB is copied unchanged: it stays valid because method tokens, IL offsets, and
+	/// the PE's CodeView identity (GUID, age, path) are all preserved.
+	/// </summary>
+	public class RewriteJniNamesForR8 : AndroidTask
+	{
+		static readonly StringComparison PathComparison = Path.DirectorySeparatorChar == '\\'
+			? StringComparison.OrdinalIgnoreCase
+			: StringComparison.Ordinal;
+
+		public override string TaskPrefix => "RJN";
+
+		[Required]
+		public ITaskItem [] SourceFiles { get; set; } = [];
+
+		public ITaskItem [] DestinationFiles { get; set; } = [];
+
+		public string? DestinationDirectory { get; set; }
+
+		[Required]
+		public string MappingFile { get; set; } = "";
+
+		public string? RewriteManifestFile { get; set; }
+
+		[Output]
+		public ITaskItem [] RewrittenFiles { get; set; } = [];
+
+		public override bool RunTask ()
+		{
+			RewrittenFiles = [];
+			if (DestinationDirectory.IsNullOrEmpty () && SourceFiles.Length != DestinationFiles.Length) {
+				Log.LogCodedError ("XA4325", Properties.Resources.XA4325, Properties.Resources.XA4325_SourceDestinationCount);
+				return !Log.HasLoggedErrors;
+			}
+
+			R8Mapping mapping = R8Mapping.Load (MappingFile);
+			var rewrittenFiles = new List<ITaskItem> (SourceFiles.Length);
+
+			for (int i = 0; i < SourceFiles.Length; i++) {
+				string source = SourceFiles [i].ItemSpec;
+				string destination = DestinationDirectory.IsNullOrEmpty ()
+					? DestinationFiles [i].ItemSpec
+					: Path.Combine (DestinationDirectory, Path.GetFileName (source));
+				try {
+					RewriteAssembly (source, destination, mapping);
+					var rewritten = new TaskItem (SourceFiles [i]) {
+						ItemSpec = destination,
+					};
+					rewritten.SetMetadata ("OriginalItemSpec", source);
+					rewrittenFiles.Add (rewritten);
+				} catch (JniRewriteException e) {
+					Log.LogCodedError ("XA4325", Properties.Resources.XA4325,
+						string.Format (Properties.Resources.XA4325_AssemblyFailure, source, e.Message));
+				}
+			}
+
+			if (!Log.HasLoggedErrors) {
+				RewrittenFiles = rewrittenFiles.ToArray ();
+				if (!RewriteManifestFile.IsNullOrEmpty ()) {
+					WriteRewriteManifest (RewriteManifestFile, mapping.AccessedEntries);
+				}
+			}
+			return !Log.HasLoggedErrors;
+		}
+
+		static void WriteRewriteManifest (string path, IEnumerable<string> entries)
+		{
+			string? directory = Path.GetDirectoryName (path);
+			if (!directory.IsNullOrEmpty ()) {
+				Directory.CreateDirectory (directory);
+			}
+			Files.CopyIfStringChanged (R8Mapping.CreateManifestContent (entries), path);
+		}
+
+		void RewriteAssembly (string sourcePath, string destinationPath, R8Mapping mapping)
+		{
+			string? destinationDirectory = Path.GetDirectoryName (destinationPath);
+			if (!destinationDirectory.IsNullOrEmpty ()) {
+				Directory.CreateDirectory (destinationDirectory);
+			}
+
+			JniRewriteResult result = JniAssemblyRewriter.Rewrite (File.ReadAllBytes (sourcePath), mapping, Log);
+
+			Log.LogDebugMessage ($"RewriteJniNamesForR8: rewrote {result.ReplacementCount} JNI name(s) in '{Path.GetFileName (sourcePath)}'.");
+			if (result.StrongNameSignatureCleared) {
+				Log.LogDebugMessage ($"RewriteJniNamesForR8: '{Path.GetFileName (sourcePath)}' is strong-named; preserved its public-key identity and emitted a delay-signed linker input.");
+			}
+
+			bool inPlace = AreSamePath (sourcePath, destinationPath);
+			if (!inPlace || result.ReplacementCount != 0) {
+				using var output = new MemoryStream (result.Image, writable: false);
+				Files.CopyIfStreamChanged (output, destinationPath);
+			}
+			if (!inPlace) {
+				CopyAdjacentPdbUnchanged (sourcePath, destinationPath);
+			}
+		}
+
+		internal static bool AreSamePath (string firstPath, string secondPath)
+			=> String.Equals (Path.GetFullPath (firstPath), Path.GetFullPath (secondPath), PathComparison);
+
+		static void CopyAdjacentPdbUnchanged (string sourcePath, string destinationPath)
+		{
+			string pdbSource = Path.ChangeExtension (sourcePath, "pdb");
+			string pdbDestination = Path.ChangeExtension (destinationPath, "pdb");
+			if (File.Exists (pdbSource)) {
+				Files.CopyIfChanged (pdbSource, pdbDestination);
+			} else if (File.Exists (pdbDestination)) {
+				Files.SetWriteable (pdbDestination);
+				File.Delete (pdbDestination);
+			}
+		}
+	}
+}