[Xamarin.Android.Build.Tasks] Update XA5207 for VSCode (#8494)

Context: #8413
Context: #8522

The [XA5207][0] error message contained IDE-specific instructions:

	# Visual Studio
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed.
	  Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change your Xamarin.Android project
	  to target an API version that is installed.

	# Visual Studio for Mac
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed.
	  Either install it in the Android SDK Manager (Tools > Open Android SDK Manager...), or change your Xamarin.Android project
	  to target an API version that is installed.

[Visual Studio for Mac is now deprecated][1]:

> Visual Studio for Mac is scheduled for retirement by August 31, 2024

Visual Studio Code is now supported, via [C# Dev Kit][2] and the
[.NET MAUI][3] extensions.  ([Announcement][4].)

These changes mean that our error messages are obsolete (building on
macOS) or misleading (building within VSCode on Windows).

Update the XA5207 error generation logic to take these changes into
consideration.  Visual Studio (Windows) will retain the existing
error message text.  The Visual Studio for Mac instructions are
replaced with instructions for command-line builds, for use from
Visual Studio Code:

	# Visual Studio
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed;
	  it was expected to be in `…`.
	  Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change the .NET Android project
	  to target an API version that is installed.
	  See https://aka.ms/xa5207 for more details.

	# Visual Studio Code
	error XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed;
	  it was expected to be in `…`.
	  You can install the missing API level by running
	  `dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=…"`,
	  or change the project to target an API version that is installed.
	  See https://aka.ms/xa5207 for more details.


Update some of the documentation around the
`InstallAndroidDependencies` target to mention `dotnet build` options
which are required in order for the target to function correctly.

Finally, update various error messages, replacing "Xamarin.Android"
with ".NET Android".

[0]: https://github.com/xamarin/xamarin-android/blob/40cc8eaf78eb9f95abcc0e966ab274cef1692acc/Documentation/guides/messages/xa5207.md
[1]: https://learn.microsoft.com/en-us/visualstudio/mac/what-happened-to-vs-for-mac?view=vsmac-2022
[2]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit
[3]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui
[4]: https://devblogs.microsoft.com/visualstudio/announcing-the-dotnet-maui-extension-for-visual-studio-code/

Documentation/guides/building-apps/build-targets.md

@@ -91,6 +91,20 @@ MSBuild /t:Install ProjectName.csproj /p:AdbTarget=-e
 Calls the [`GetAndroidDependencies`](#getandroiddependencies) target, then installs
 the Android SDK packages specified in the `@(AndroidDependency)` item group.
 
+```dotnetcli
+dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=<path to sdk>" "-p:JavaSdkDirectory=<path to java sdk>"
+```
+
+The `-f net8.0-android` is required as this target is a .NET Android specific target. If you omit this argument
+you will get the following error:
+
+```
+error MSB4057: The target "InstallAndroidDependencies" does not exist in the project.
+```
+
+The `AndroidSdkDirectory` and `JavaSdkDirectory` properties are required as we need to know where to install the required components. These directories can be empty or existing. Sdk components
+will be installed on top on an existing sdk installation.
+
 The [`$(AndroidManifestType)`](~/android/deploy-test/building-apps/build-properties.md#androidmanifesttype)
 MSBuild property controls which
 [Visual Studio SDK Manager repository](~/android/get-started/installation/android-sdk.md?tabs=windows#repository-selection)

Documentation/guides/messages/xa5207.md

@@ -7,14 +7,35 @@ ms.date: 06/26/2019
 
 ## Example messages
 
-```
+```dotnetcli
 XA5207: Could not find android.jar for API Level 28. This means the Android SDK platform for API Level 28 is not installed. Either install it in the Android SDK Manager (Tools > Android > Android SDK Manager...), or change your Xamarin.Android project to target an API version that is installed.
 ```
 
 ## Issue
 
-In order to build a project, the Android SDK Platform matching the target API level must be installed. 
+In order to build a project, the Android SDK Platform matching the target API level must be installed.
 
 ## Solution
 
-Use the Android SDK Manager to install the Android SDK Platform for the desired API level.
+Use the Android SDK Manager (Tools > Android > Android SDK Manager...) to install the Android SDK Platform for the desired API level. Alternatively you can install the missing API level by running the following command from a terminal or command prompt:
+
+```dotnetcli
+dotnet build -t:InstallAndroidDependencies -f net8.0-android "-p:AndroidSdkDirectory=<path to sdk directory>"
+```
+
+Part of the new .net android system is when upgrading projects you will automatically be
+upgraded to the latest API level. For example net7.0-android allowed you to target API 33,
+but net8.0-android will automatically target API 34. If you want to keep your current
+target API level you will need to add the 'uses-sdk' `android:targetSdkVersion` to your `AndroidManifest.xml` file.
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    android:versionCode="1"
+    android:versionName="1.0"
+    package="com.companyname.myapp">
+  <uses-sdk android:targetSdkVersion="33">
+  <application android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme" />
+</manifest>
+```
+
+You might then need to run the `InstallAndroidDependencies` target as mentioned above to ensure that the required API level is installed.

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

@@ -416,7 +416,7 @@ The capitalized word "Portable" that appears earlier in the message is plain tex
   <data name="XA1019" xml:space="preserve">
     <value>`LibraryProjectProperties` file `{0}` is located in a parent directory of the bindings project's intermediate output directory. Please adjust the path to use the original `project.properties` file directly from the Android library project directory.</value>
     <comment>The following are literal names and should not be translated: LibraryProjectProperties, project.properties, Android
-In this message, the term "binding" means a piece of generated code that makes it easy to access an Android API written in Java from a Xamarin.Android project written in C# or F#.
+In this message, the term "binding" means a piece of generated code that makes it easy to access an Android API written in Java from a .NET Android project written in C# or F#.
 {0} - The path of the LibraryProjectProperties file</comment>
   </data>
   <data name="XA1020" xml:space="preserve">
@@ -438,8 +438,8 @@ In this message, the term "binding" means a piece of generated code that makes i
     <comment>The following are literal names and should not be translated: DX, DEX, d8, AndroidDexTool.</comment>
   </data>
   <data name="XA1024" xml:space="preserve">
-    <value>Ignoring configuration file '{0}'. .NET configuration files are not supported in Xamarin.Android projects that target .NET 6 or higher.</value>
-    <comment>The following are literal names and should not be translated: .NET, Xamarin.Android.
+    <value>Ignoring configuration file '{0}'. .NET configuration files are not supported in .NET Android projects that target .NET 6 or higher.</value>
+    <comment>The following are literal names and should not be translated: .NET, .NET Android.
 {0} - The file name such as 'Foo.dll.config'</comment>
   </data>
   <data name="XA1025" xml:space="preserve">
@@ -451,7 +451,7 @@ In this message, the term "binding" means a piece of generated code that makes i
     <comment>The following are literal names and should not be translated: AAPT, AAPT2, Android, AndroidUseAapt2, true.</comment>
   </data>
   <data name="XA1026_dotnet" xml:space="preserve">
-    <value>Using AAPT is not supported in Xamarin.Android projects that target .NET 6 or higher. Please enable 'Use incremental Android packaging system (aapt2)' in the Visual Studio project property pages or edit the project file in a text editor and set the 'AndroidUseAapt2' MSBuild property to 'true'.</value>
+    <value>Using AAPT is not supported in .NET Android projects that target .NET 6 or higher. Please enable 'Use incremental Android packaging system (aapt2)' in the Visual Studio project property pages or edit the project file in a text editor and set the 'AndroidUseAapt2' MSBuild property to 'true'.</value>
     <comment>The following are literal names and should not be translated: AAPT, Android, AndroidUseAapt2, true.</comment>
   </data>
   <data name="XA1027" xml:space="preserve">
@@ -505,7 +505,7 @@ Either change the value in the AndroidManifest.xml to match the $(SupportedOSPla
 {1} - The SupportedOSPlatformVersion property value</comment>
   </data>
   <data name="XA2000" xml:space="preserve">
-    <value>Use of AppDomain.CreateDomain() detected in assembly: {0}. .NET 6 and higher will only support a single AppDomain, so this API will no longer be available in Xamarin.Android once .NET 6 is released.</value>
+    <value>Use of AppDomain.CreateDomain() detected in assembly: {0}. .NET 6 and higher will only support a single AppDomain, so this API will no longer be available in .NET Android once .NET 6 is released.</value>
     <comment>The following are literal names and should not be translated: AppDomain.CreateDomain(), AppDomain
 {0} - The name of the assembly</comment>
   </data>
@@ -704,12 +704,12 @@ In this message, "root element" refers to the root element of an XML file.
     <comment>{0} - The exception message and stack trace of the associated exception</comment>
   </data>
   <data name="XA4231" xml:space="preserve">
-    <value>The Android class parser value '{0}' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'class-parse'.</value>
+    <value>The Android class parser value '{0}' is deprecated and will be removed in a future version of .NET Android. Update the project properties to use 'class-parse'.</value>
     <comment>The following are literal names and should not be translated: class-parse
 {0} - The name of the current class parser value</comment>
   </data>
   <data name="XA4232" xml:space="preserve">
-    <value>The Android code generation target '{0}' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'XAJavaInterop1'.</value>
+    <value>The Android code generation target '{0}' is deprecated and will be removed in a future version of .NET Android. Update the project properties to use 'XAJavaInterop1'.</value>
     <comment>The following are literal names and should not be translated: XAJavaInterop1
 {0} - The name of the current code generation target</comment>
   </data>
@@ -790,7 +790,7 @@ The following are literal names and should not be translated: ABI, 'libs/armeabi
 "Wear" is a short version of the full product name "Wear OS" and so should not be translated.</comment>
   </data>
   <data name="XA4312" xml:space="preserve">
-    <value>Referencing the Android Wear application project '{0}' from an Android application project is deprecated and will no longer be supported in a future version of Xamarin.Android. Remove the Android Wear application project reference from the Android application project and distribute the Wear application as a standalone application instead.</value>
+    <value>Referencing the Android Wear application project '{0}' from an Android application project is deprecated and will no longer be supported in a future version of .NET Android. Remove the Android Wear application project reference from the Android application project and distribute the Wear application as a standalone application instead.</value>
     <comment>The following are literal names and should not be translated: Android Wear, Android, Wear.
 {0} - The referenced Android Wear project.</comment>
   </data>
@@ -861,19 +861,23 @@ Remove the '{0}' reference from your project and add the '{1}' NuGet package ins
 {0} - The missing tool name</comment>
   </data>
   <data name="XA5207" xml:space="preserve">
-    <value>Could not find android.jar for API level {0}. This means the Android SDK platform for API level {0} is not installed. Either install it in the Android SDK Manager ({2}), or change the Xamarin.Android project to target an API version that is installed. ({1} missing.)</value>
+    <value>Could not find android.jar for API level {0}. This means the Android SDK platform for API level {0} is not installed; it was expected to be in `{1}`.
+{2}
+See https://aka.ms/xa5207 for more details.</value>
     <comment>The following are literal names and should not be translated: android.jar
 {0} - The API level name
 {1} - The expected path of the android.jar file
-{2} - The menu location in Visual Studio that can be used to launch the Android SDK Manager</comment>
-  </data>
-  <data name="XA5207_SDK_Manager_macOS" xml:space="preserve">
-    <value>Tools &gt; Open Android SDK Manager...</value>
-    <comment>This string is the location of a menu command in Visual Studio for Mac.</comment>
+{2} - The instructions to install the missing component</comment>
   </data>
   <data name="XA5207_SDK_Manager_Windows" xml:space="preserve">
-    <value>Tools &gt; Android &gt; Android SDK Manager...</value>
-    <comment>This string is the location of a menu command in Visual Studio.</comment>
+    <value>Either install it in the Android SDK Manager (Tools &gt; Android &gt; Android SDK Manager...), or change the .NET Android project to target an API version that is installed.</value>
+    <comment>This string is the instrucitons to install the component</comment>
+  </data>
+  <data name="XA5207_SDK_Manager_CLI" xml:space="preserve">
+    <value>You can install the missing API level by running `dotnet build -t:InstallAndroidDependencies -f {0} "-p:AndroidSdkDirectory={1}"`, or change the project to target an API version that is installed.</value>
+    <comment>This string is the instrucitons to install the component
+{0} - The TargetFramework the app is targeting.
+{1} - The current AndroidSdkDirectory path.</comment>
   </data>
   <data name="XA5211" xml:space="preserve">
     <value>Embedded Wear app package name differs from handheld app package name ({0} != {1}).</value>

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

@@ -25,8 +25,14 @@ public class GetJavaPlatformJar : AndroidTask
 
 		public bool DesignTimeBuild { get; set; }
 
+		public bool BuildingInsideVisualStudio { get; set; }
+
 		public string SupportedOSPlatformVersion { get; set; }
 
+		public string TargetFramework { get; set; }
+
+		public string AndroidSdkDirectory { get; set; }
+
 		[Output]
 		public string JavaPlatformJarPath { get; set; }
 
@@ -95,7 +101,9 @@ public override bool RunTask ()
 			}
 
 			platform            = GetTargetSdkVersion (platform, target_sdk);
-			JavaPlatformJarPath =  MonoAndroidHelper.TryGetAndroidJarPath (Log, platform, designTimeBuild: DesignTimeBuild);
+			JavaPlatformJarPath =  MonoAndroidHelper.TryGetAndroidJarPath (Log, platform,
+				designTimeBuild: DesignTimeBuild, buildingInsideVisualStudio: BuildingInsideVisualStudio,
+				targetFramework: TargetFramework, androidSdkDirectory: AndroidSdkDirectory);
 			TargetSdkVersion = MonoAndroidHelper.SupportedVersions.GetApiLevelFromId (platform).ToString ();
 			if (JavaPlatformJarPath == null)
 				return !Log.HasLoggedErrors;

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

@@ -801,7 +801,7 @@ public void BuildInDesignTimeMode ([Values(false, true)] bool useManagedParser)
 		}
 
 		[Test]
-		public void IfAndroidJarDoesNotExistThrowXA5207 ()
+		public void IfAndroidJarDoesNotExistThrowXA5207 ([Values(true, false)] bool buildingInsideVisualStudio)
 		{
 			var path = Path.Combine ("temp", TestName);
 			var AndroidSdkDirectory = CreateFauxAndroidSdkDirectory (Path.Combine (path, "android-sdk"), "24.0.1", new ApiInfo [] { new ApiInfo { Id = "30" } });
@@ -814,6 +814,7 @@ public void IfAndroidJarDoesNotExistThrowXA5207 ()
 				if (!Builder.UseDotNet)
 					proj.TargetFrameworkVersion = builder.LatestTargetFrameworkVersion ();
 				builder.ThrowOnBuildFailure = false;
+				builder.BuildingInsideVisualStudio = buildingInsideVisualStudio;
 				Assert.IsTrue (builder.DesignTimeBuild (proj), "DesignTime build should succeed.");
 				Assert.IsFalse (builder.LastBuildOutput.ContainsText ("error XA5207:"), "XA5207 should not have been raised.");
 				builder.Target = "AndroidPrepareForBuild";
@@ -823,6 +824,10 @@ public void IfAndroidJarDoesNotExistThrowXA5207 ()
 				}), "Build should have failed");
 				Assert.IsTrue (builder.LastBuildOutput.ContainsText ("error XA5207:"), "XA5207 should have been raised.");
 				Assert.IsTrue (builder.LastBuildOutput.ContainsText ($"Could not find android.jar for API level {proj.TargetSdkVersion}"), "XA5207 should have had a good error message.");
+				if (buildingInsideVisualStudio)
+					Assert.IsTrue (builder.LastBuildOutput.ContainsText ($"Either install it in the Android SDK Manager"), "XA5207 should have an error message for Visual Studio.");
+				else 
+				    Assert.IsTrue (builder.LastBuildOutput.ContainsText ($"You can install the missing API level by running"), "XA5207 should have an error message for the command line.");
 			}
 			Directory.Delete (AndroidSdkDirectory, recursive: true);
 		}

src/Xamarin.Android.Build.Tasks/Utilities/MonoAndroidHelper.cs

@@ -482,14 +482,14 @@ public static IEnumerable<string> Executables (string executable)
 			yield return executable;
 		}
 
-		public static string TryGetAndroidJarPath (TaskLoggingHelper log, string platform, bool designTimeBuild = false)
+		public static string TryGetAndroidJarPath (TaskLoggingHelper log, string platform, bool designTimeBuild = false, bool buildingInsideVisualStudio = false, string targetFramework = "", string androidSdkDirectory = "")
 		{
 			var platformPath = MonoAndroidHelper.AndroidSdk.TryGetPlatformDirectoryFromApiLevel (platform, MonoAndroidHelper.SupportedVersions);
 			if (platformPath == null) {
 				if (!designTimeBuild) {
 					var expectedPath = MonoAndroidHelper.AndroidSdk.GetPlatformDirectoryFromId (platform);
-					var sdkManagerMenuPath = OS.IsWindows ? Properties.Resources.XA5207_SDK_Manager_Windows : Properties.Resources.XA5207_SDK_Manager_macOS;
-					log.LogCodedError ("XA5207", Properties.Resources.XA5207, platform, Path.Combine (expectedPath, "android.jar"), sdkManagerMenuPath);
+					var sdkManagerMenuPath = buildingInsideVisualStudio ? Properties.Resources.XA5207_SDK_Manager_Windows : Properties.Resources.XA5207_SDK_Manager_CLI;
+					log.LogCodedError ("XA5207", Properties.Resources.XA5207, platform, Path.Combine (expectedPath, "android.jar"), string.Format (sdkManagerMenuPath, targetFramework, androidSdkDirectory));
 				}
 				return null;
 			}

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

@@ -99,9 +99,12 @@ projects.
   <Target Name="_GetJavaPlatformJar">
     <GetJavaPlatformJar
         AndroidSdkPlatform="$(_AndroidApiLevel)"
+        AndroidSdkDirectory="$(AndroidSdkDirectory)"
         AndroidManifest="$(_AndroidManifestAbs)"
         DesignTimeBuild="$(DesignTimeBuild)"
+        BuildingInsideVisualStudio="$(BuildingInsideVisualStudio)"
         SupportedOSPlatformVersion="$(SupportedOSPlatformVersion)"
+        TargetFramework="$(TargetFramework)"
     >
       <Output TaskParameter="JavaPlatformJarPath" PropertyName="JavaPlatformJarPath" />
       <Output TaskParameter="TargetSdkVersion"    PropertyName="_AndroidTargetSdkVersion" />