[Xamarin.Android.Build.Tasks] introduce XA1038

Fixes: dotnet#8331

Building a `net8.0-android33` project, currently fails with:

    error NETSDK1181: Error getting pack version: Pack 'Microsoft.Android.Ref.33' was not present in workload manifests.
    C:\Program Files\dotnet\sdk\8.0.100-preview.7.23376.3\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Sdk.FrameworkReferenceResolution.targets

To solve this, you would either change 33 to 34, or just remove the
number to rely on the default value.

To make this easier:

* Automatically switch to 34 if the user specifies 33 or less.

* Emit the new `XA1038` error message.

This allows these projects to build with a reasonable error message.

The only concern down the road: if we ever support `net8.0-android35`
alongside `net8.0-android34`, then we'd need to slightly adjust the
logic here.

Documentation/guides/messages/xa1038.md

@@ -0,0 +1,49 @@
+---
+title: Xamarin.Android error XA1038
+description: XA1038 error code
+ms.date: 12/6/2023
+---
+# Xamarin.Android error XA1038
+
+## Example messages
+
+```
+error XA1038: $(TargetPlatformVersion) 33 is not a valid target for `net8.0-android` projects. Please update your $(TargetPlatformVersion) to a supported version (e.g. 34).
+```
+
+## Issue
+
+This error indicates that you have a mismatch between the
+`$(TargetPlatformVersion)` set and what .NET Android supports.
+
+For example:
+
+```xml
+<PropertyGroup>
+  <TargetFramework>net8.0-android33</TargetFramework>
+</PropertyGroup>
+```
+
+In this case, .NET 8 targets Android 34, which is the default and valid
+`$(TargetPlatformVersion)`, but the `$(TargetPlatformVersion)` is set to 33.
+`TargetFramework=net8.0-android33` above is shorthand for:
+
+```xml
+<PropertyGroup>
+  <TargetFramework>net8.0</TargetFramework>
+  <TargetPlatformIdentifier>android</TargetPlatformIdentifier>
+  <TargetPlatformVersion>33.0</TargetPlatformVersion>
+</PropertyGroup>
+```
+
+## Solution
+
+Change the value of the `$(TargetPlatformVersion)` property to match a supported
+version for the `$(TargetFramework)`, or remove the value entirely to rely on
+the default:
+
+```xml
+<PropertyGroup>
+  <TargetFramework>net8.0-android</TargetFramework>
+</PropertyGroup>
+```

src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/in/Microsoft.Android.Sdk.BundledVersions.in.targets

@@ -10,12 +10,16 @@ WARNING:  DO NOT MODIFY this file unless you are knowledgeable about MSBuild and
   <PropertyGroup>
     <AndroidNETSdkVersion>@ANDROID_PACK_VERSION_LONG@</AndroidNETSdkVersion>
     <XamarinAndroidVersion>@ANDROID_PACK_VERSION_LONG@</XamarinAndroidVersion>
+    <_AndroidLatestStableApiLevel>@ANDROID_LATEST_STABLE_API_LEVEL@</_AndroidLatestStableApiLevel>
   </PropertyGroup>
   <PropertyGroup>
     <_AndroidTargetingPackId Condition="$(TargetPlatformVersion.EndsWith('.0'))">$(TargetPlatformVersion.Substring(0, $(TargetPlatformVersion.LastIndexOf('.0'))))</_AndroidTargetingPackId>
     <_AndroidTargetingPackId Condition="'$(_AndroidTargetingPackId)' == ''">$(TargetPlatformVersion)</_AndroidTargetingPackId>
-    <_AndroidRuntimePackId Condition=" '$(_AndroidTargetingPackId)' &lt; '@ANDROID_LATEST_STABLE_API_LEVEL@' ">@ANDROID_LATEST_STABLE_API_LEVEL@</_AndroidRuntimePackId>
+    <!-- NOTE: adjust if a TargetFramework supports multiple API levels -->
+    <_AndroidErrorOnTargetPlatformVersion Condition=" '$(_AndroidTargetingPackId)' != '$(_AndroidLatestStableApiLevel)' ">$(_AndroidTargetingPackId)</_AndroidErrorOnTargetPlatformVersion>
+    <_AndroidTargetingPackId Condition=" '$(_AndroidTargetingPackId)' != '$(_AndroidLatestStableApiLevel)' ">$(_AndroidLatestStableApiLevel)</_AndroidTargetingPackId>
     <_AndroidRuntimePackId Condition=" '$(_AndroidRuntimePackId)' == '' ">$(_AndroidTargetingPackId)</_AndroidRuntimePackId>
+    <_AndroidRuntimePackId Condition=" '$(_AndroidRuntimePackId)' != '$(_AndroidLatestStableApiLevel)' ">$(_AndroidLatestStableApiLevel)</_AndroidRuntimePackId>
   </PropertyGroup>
   <ItemGroup>
     <KnownFrameworkReference

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

@@ -1006,4 +1006,11 @@ To use a custom JDK path for a command line build, set the 'JavaSdkDirectory' MS
 {0} - The deprecated MSBuild property name
 {1} - The numeric version of .NET</comment>
   </data>
+  <data name="XA1038" xml:space="preserve">
+    <value>$(TargetPlatformVersion) {0} is not a valid target for '{1}' projects. Please update your $(TargetPlatformVersion) to a supported version (e.g. {2}).</value>
+    <comment>The following are literal names and should not be translated: $(TargetPlatformVersion).
+{0} - the invalid $(TargetPlatformVersion) such as 33
+{1} - the $(TargetFramework) such as net8.0-android
+{2} - the valid $(TargetPlatformVersion) such as 34</comment>
+  </data>
 </root>

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BuildTest.cs

@@ -806,6 +806,22 @@ public void IfAndroidJarDoesNotExistThrowXA5207 ([Values(true, false)] bool buil
 			Directory.Delete (AndroidSdkDirectory, recursive: true);
 		}
 
+		[Test]
+		public void InvalidTargetPlatformVersion ([Values ("android33", "android35.0")] string platformVersion)
+		{
+			const string targetFramework = "net9.0";
+			var project = new XamarinAndroidApplicationProject {
+				TargetFramework = $"{targetFramework}-{platformVersion}",
+			};
+			using var builder = CreateApkBuilder ();
+			builder.ThrowOnBuildFailure = false;
+			Assert.IsFalse (builder.Build (project), "build should fail");
+
+			Assert.IsTrue (int.TryParse (platformVersion.Replace ("android", "").Replace (".0", ""), out var apiLevel), "failed to parse API level!");
+			var message = $"error XA1038: $(TargetPlatformVersion) {apiLevel} is not a valid target for '{targetFramework}' projects.";
+			Assert.IsTrue (builder.LastBuildOutput.ContainsText (message), "XA1038 should have been raised.");
+		}
+
 		[Test]
 		public void XA4212 ()
 		{

src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets

@@ -545,6 +545,11 @@ Copyright (C) 2011-2012 Xamarin. All rights reserved.
       ResourceName="XA1035"
       Condition=" '$(BundleAssemblies)' == 'true' and '$(UsingAndroidNETSdk)' == 'true' "
   />
+  <AndroidError Code="XA1038"
+      ResourceName="XA1038"
+      Condition=" '$(_AndroidErrorOnTargetPlatformVersion)' != '' "
+      FormatArguments="$(_AndroidErrorOnTargetPlatformVersion);net$(TargetFrameworkVersion.TrimStart('vV'));$(_AndroidLatestStableApiLevel)"
+  />
 </Target>
 
 <!--