Use documented XA4325 error code for JNI name rewriting failures

Replace the ad-hoc RJN0000/RJN0001 error codes and their hard-coded
English strings with a single documented, localizable XA4325 product
code.

The task prefix stays "RJN" so unexpected exceptions keep reporting as
XARJN7xxx, consistent with other task-specific prefixes; only the two
explicit errors change.

The user-visible detail is resource-backed as well: XA4325 is a general
wrapper and the two specific failures live in XA4325_SourceDestinationCount
and XA4325_AssemblyFailure, so no new English fragments are formatted into
the message from code.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: simonrozsival

Documentation/docs-mobile/TOC.yml

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

Documentation/docs-mobile/messages/index.md

@@ -254,6 +254,7 @@ 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}
 
 ## 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

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

@@ -884,6 +884,19 @@ 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="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

@@ -46,7 +46,7 @@ public class RewriteJniNamesForR8 : AndroidTask
 		public override bool RunTask ()
 		{
 			if (DestinationDirectory.IsNullOrEmpty () && SourceFiles.Length != DestinationFiles.Length) {
-				Log.LogCodedError ("RJN0000", "SourceFiles and DestinationFiles must contain the same number of items.");
+				Log.LogCodedError ("XA4325", Properties.Resources.XA4325, Properties.Resources.XA4325_SourceDestinationCount);
 				return !Log.HasLoggedErrors;
 			}
 
@@ -66,7 +66,8 @@ public override bool RunTask ()
 					rewritten.SetMetadata ("OriginalItemSpec", source);
 					rewrittenFiles [i] = rewritten;
 				} catch (JniRewriteException e) {
-					Log.LogCodedError ("RJN0001", $"Could not rewrite the JNI names in '{source}': {e.Message}");
+					Log.LogCodedError ("XA4325", Properties.Resources.XA4325,
+						string.Format (Properties.Resources.XA4325_AssemblyFailure, source, e.Message));
 				}
 			}
 

src/Xamarin.Android.Build.Tasks/Tasks/RewriteJniNamesForR8.cs

@@ -1,10 +1,12 @@
 using System;
+using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.IO;
 using System.Reflection;
 using System.Reflection.Metadata;
 using System.Reflection.Metadata.Ecma335;
 using System.Reflection.PortableExecutable;
+using Microsoft.Build.Framework;
 using NUnit.Framework;
 using Xamarin.Android.Tasks;
 
@@ -116,14 +118,18 @@ public void FailsWithACodedErrorWhenSourceAndDestinationCountsDiffer ()
 			string mappingFile = Path.Combine (path, "mapping.txt");
 			File.WriteAllText (mappingFile, "");
 
+			var errors = new List<BuildErrorEventArgs> ();
 			var task = new RewriteJniNamesForR8 {
-				BuildEngine = new MockBuildEngine (TestContext.Out),
+				BuildEngine = new MockBuildEngine (TestContext.Out, errors),
 				SourceFiles = new [] { new Microsoft.Build.Utilities.TaskItem ("a.dll"), new Microsoft.Build.Utilities.TaskItem ("b.dll") },
 				DestinationFiles = new [] { new Microsoft.Build.Utilities.TaskItem ("a.dll") },
 				MappingFile = mappingFile,
 			};
 
 			Assert.IsFalse (task.Execute (), "Task should fail when SourceFiles/DestinationFiles counts differ.");
+			Assert.AreEqual (1, errors.Count, "Exactly one error should have been logged.");
+			Assert.AreEqual ("XA4325", errors [0].Code, "The error should use the documented XA4325 code.");
+			StringAssert.Contains ("SourceFiles", errors [0].Message, "The error should name the mismatched item groups.");
 		}
 
 		[Test]