[Xamarin.Android.Build.Tasks] Improve aapt2+file not found handling (#7644)

Context: #7639

If a project has a long path name, this can cause `aapt2` to fail:

	error APT2000: The system cannot find the file specified. (2).
	
This is not very helpful since there is no obvious reason to the user
as to *why* the build is failing.

We should do better.  We *can* do better.

Catch this specific error message and report a helpful, actionable
message instead.

	error APT2264: This is probably caused by the project exceeding the Windows maximum path length limitation.
	  See https://learn.microsoft.com/xamarin/android/errors-and-warnings/apt2264 for details.


In this case we will advise the user that the path is probably too
long and they should consult the documentation on how to resolve it.

The documentation includes a number of options for resolutions, so it
should cover all use cases.  Generally these are:

 1. Move the project closer to the root of the drive.
 2. Enable long path support in windows.
 3. Make changes to the `$(BaseIntermediateOutputPath)` MSBuild
    property to move only the `obj` folder closer to the drive root.

Most users can get away with (1), though with Maui and Blazor based
apps this might not solve the problem as the project itself might
have a deep folder structure.  Options (2) and (3) are available to
cover those scenarios.

Author: dellis1972

Documentation/guides/messages/README.md

@@ -30,6 +30,7 @@ ms.date: 01/24/2020
 + APT0002: Invalid file name: It must contain only \[^a-zA-Z0-9_.-\]+.
 + APT0003: Invalid file name: It must contain only \[^a-zA-Z0-9_.\]+.
 + APT0004: Invalid file name: It must start with either A-Z or a-z or an underscore.
++ [APT2264](apt2264.md): The system cannot find the file specified. (2).
 
 ## JAVAxxxx: Java Tool
 

Documentation/guides/messages/apt2264.md

@@ -0,0 +1,58 @@
+---
+title: Xamarin.Android error APT2264
+description: APT2264 error code
+ms.date: 12/16/2022
+---
+# Xamarin.Android error APT2264
+
+## Issue
+
+The tool `aapt2` is unable to resolve one of the files it was passed.
+This is generally caused by the path being longer than the Maximum Path
+length allowed on windows.
+
+## Solution
+
+The best way to avoid this is to ensure that your project is not located
+deep in the folder structure. For example if you create all of your
+projects in folders such as
+
+`C:\Users\shelly\Visual Studio\Android\MyProjects\Com.SomeReallyLongCompanyName.MyBrillantApplication\MyBrilliantApplicaiton.Android\`
+
+you may well encounter problems with not only `aapt2` but also Ahead of Time
+compilation. Keeping your project names and folder structures short and
+concise will help work around these issues. For example instead of the above
+you could use
+
+`C:\Work\Android\MyBrilliantApp`
+
+Which is much shorter and much less likely to encounter path issues.
+
+However this is no always possible. Sometimes a project or a environment requires
+deep folder structures. In this case enabling long path support in Windows *might*
+be enough to get your project working. Details on how to do this can be found
+[here](https://learn.microsoft.com/windows/win32/fileio/maximum-file-path-limitation?tabs=registry#enable-long-paths-in-windows-10-version-1607-and-later).
+
+
+If long path support does not work changing the location of the
+`$(BaseIntermediateOutputPath)` can help solve these problems. In order for this
+to work the setting MUST be changed before ANY build or restore occurs. To do this
+you can make use of the MSBuild `Directory.Build.props` support.
+
+Creating a `Directory.Build.props` file in your solution or project directory which
+redefines the `$(BaseIntermediateOutputPath)` to somewhere nearer the root of the drive
+with solve these issues. Adding a file with the following contents will create the `obj`
+directory in a different location of your choosing.
+
+```
+<Project>
+  <PropertyGroup>
+      <BaseIntermediateOutputPath Condition=" '$(OS)' == 'Windows_NT' ">C:\Intermediate\$(ProjectName)</BaseIntermediateOutputPath>
+      <BaseIntermediateOutputPath Condition=" '$(OS)' != 'Windows_NT' ">/tmp/Intermediate/$(ProjectName)</BaseIntermediateOutputPath>
+  </PropertyGroup>
+</Project
+```
+
+Using this technique will reduce the lengths of the paths sent to the various tools like `aapt2`.
+Note this is generally only a Windows issue. So there is no need to override the `$(BaseIntermediateOutputPath)`
+on Mac or Linux based environments. However you might want to override everywhere to be consistent.

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

@@ -530,6 +530,10 @@ Please change the value to an assembly-qualifed type name which inherits from '{
     <comment>The following are literal names and should not be translated: Java.Interop.DoNotPackageAttribute
 {0} - The assembly name</comment>
   </data>
+  <data name="APT2264" xml:space="preserve">
+    <value>This is probably caused by the project exceeding the Windows maximum path length limitation. See https://learn.microsoft.com/xamarin/android/errors-and-warnings/apt2264 for details.</value>
+    <comment>The following are literal names and should not be translated:</comment>
+  </data>
   <data name="XA3001" xml:space="preserve">
     <value>Could not AOT the assembly: {0}</value>
     <comment>The abbreviation "AOT" should not be translated.</comment>

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

@@ -188,23 +188,38 @@ protected bool LogAapt2EventsFromOutput (string singleLine, MessageImportance me
 					message = message.Substring ("error: ".Length);
 
 				if (level.Contains ("error") || (line != 0 && !string.IsNullOrEmpty (file))) {
+					var errorCode = GetErrorCode (message);
 					if (manifestError)
-						LogCodedError (GetErrorCode (message), string.Format (Xamarin.Android.Tasks.Properties.Resources.AAPTManifestError, message.TrimEnd('.')), AndroidManifestFile.ItemSpec, 0);
+						LogCodedError (errorCode, string.Format (Xamarin.Android.Tasks.Properties.Resources.AAPTManifestError, message.TrimEnd('.')), AndroidManifestFile.ItemSpec, 0);
 					else
-						LogCodedError (GetErrorCode (message), message, file, line);
+						LogCodedError (errorCode, AddAdditionalErrorText (errorCode, message), file, line);
 					return true;
 				}
 			}
 
 			if (!apptResult) {
 				var message = string.Format ("{0} \"{1}\".", singleLine.Trim (), singleLine.Substring (singleLine.LastIndexOfAny (new char [] { '\\', '/' }) + 1));
-				LogCodedError (GetErrorCode (message), message, ToolName);
+				var errorCode = GetErrorCode (message);
+				LogCodedError (errorCode, AddAdditionalErrorText (errorCode, message), ToolName);
 			} else {
 				LogCodedWarning (GetErrorCode (singleLine), singleLine);
 			}
 			return true;
 		}
 
+		static string AddAdditionalErrorText (string errorCode, string message)
+		{
+			var sb = new StringBuilder ();
+			sb.AppendLine (message);
+			switch (errorCode)
+			{
+				case "APT2264":
+					sb.AppendLine (Xamarin.Android.Tasks.Properties.Resources.APT2264);
+				break;
+			}
+			return sb.ToString ();
+		}
+
 		static string GetErrorCode (string message)
 		{
 			foreach (var tuple in error_codes)
@@ -478,6 +493,7 @@ static string GetErrorCode (string message)
 			Tuple.Create ("APT2261", "file failed to compile"),
 			Tuple.Create ("APT2262", "unexpected element <activity> found in <manifest>"),
 			Tuple.Create ("APT2263", "found in <manifest>"),  // unexpected element <xxxxx> found in <manifest>
+			Tuple.Create ("APT2264", "The system cannot find the file specified. (2).") // Windows Long Path error from aapt2
 		};
 	}
 }