[xabt] support @(RuntimeEnvironmentVariable) items (#10770)

Context: dotnet/sdk@bd5d3af

`dotnet run` now passes in `dotnet run -e FOO=BAR` as
`@(RuntimeEnvironmentVariable)` MSBuild items.

To opt in to this new feature, we need to add:

    <ProjectCapability Include="RuntimeEnvironmentVariableSupport" />

As well as update the `_GenerateEnvironmentFiles` MSBuild target:

    <!-- RuntimeEnvironmentVariable items come from 'dotnet run -e NAME=VALUE' -->
    <_GeneratedAndroidEnvironment Include="@(RuntimeEnvironmentVariable->'%(Identity)=%(Value)')" />

I added a new test to verify we have the env vars on-device at runtime.

Note that I tested this in combination with a local .NET SDK build:

* #10769

We won't be able to merge this until we have a .NET SDK here that
includes the above commit. Merging with nightly .NET 10.0.3xx SDK.

Author: jonathanpeppers

Documentation/docs-mobile/building-apps/build-items.md

@@ -581,3 +581,29 @@ this build action, see
 These files are ignored unless the
 [`$(EnableProguard)`](/xamarin/android/deploy-test/building-apps/build-properties#enableproguard)
 MSBuild property is `True`.
+
+## RuntimeEnvironmentVariable
+
+`@(RuntimeEnvironmentVariable)` items allow environment variables to be
+passed to the Android application at runtime via `dotnet run -e`. For example:
+
+```sh
+dotnet run -e DOTNET_RUN_FOO=TestValue123 -e DOTNET_RUN_BAR=AnotherValue456
+```
+
+These items are automatically populated by the .NET SDK when using
+`dotnet run -e NAME=VALUE` and are included in the generated
+environment file during the build. Each item's `%(Identity)` is the
+variable name and `%(Value)` is the variable value.
+
+```xml
+<ItemGroup>
+  <RuntimeEnvironmentVariable Include="DOTNET_RUN_FOO" Value="TestValue123" />
+</ItemGroup>
+```
+
+This feature is only available for Android application projects and
+requires a .NET SDK that supports the
+`RuntimeEnvironmentVariableSupport` project capability.
+
+This build item was introduced in .NET 10.0.300 SDK and .NET 11.

src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.ProjectCapabilities.targets

@@ -17,6 +17,7 @@ Docs about @(ProjectCapability):
     <ProjectCapability Include="Mobile" />
     <ProjectCapability Include="Android" />
     <ProjectCapability Include="AndroidApplication" Condition="$(AndroidApplication)" />
+    <ProjectCapability Include="RuntimeEnvironmentVariableSupport" Condition="$(AndroidApplication)" />
     <ProjectCapability Condition="'$(_KeepLaunchProfiles)' != 'true'" Remove="LaunchProfiles" />
   </ItemGroup>
 

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/DotNetCLI.cs

@@ -136,20 +136,20 @@ public bool Publish (string target = null, string runtimeIdentifier = null, stri
 			return Execute (arguments.ToArray ());
 		}
 
-		public bool Run (bool waitForExit = false, string [] parameters = null)
+		public bool Run (bool waitForExit = false, bool noBuild = true, string [] parameters = null)
 		{
 			string binlog = Path.Combine (Path.GetDirectoryName (projectOrSolution), "run.binlog");
 			var arguments = new List<string> {
 				"run",
 				"--project", $"\"{projectOrSolution}\"",
-				"--no-build",
-				$"/bl:\"{binlog}\"",
-				$"/p:WaitForExit={waitForExit.ToString (CultureInfo.InvariantCulture)}"
 			};
+			if (noBuild) {
+				arguments.Add ("--no-build");
+			}
+			arguments.Add ($"/bl:\"{binlog}\"");
+			arguments.Add ($"/p:WaitForExit={waitForExit.ToString (CultureInfo.InvariantCulture)}");
 			if (parameters != null) {
-				foreach (var parameter in parameters) {
-					arguments.Add ($"/p:{parameter}");
-				}
+				arguments.AddRange (parameters);
 			}
 			return Execute (arguments.ToArray ());
 		}
@@ -158,7 +158,7 @@ public bool Run (bool waitForExit = false, string [] parameters = null)
 		/// Starts `dotnet run` and returns a running Process that can be monitored and killed.
 		/// </summary>
 		/// <param name="waitForExit">Whether to use Microsoft.Android.Run tool which waits for app exit and streams logcat.</param>
-		/// <param name="parameters">Optional MSBuild properties to pass (e.g., "Device=emulator-5554").</param>
+		/// <param name="parameters">Additional arguments to pass to `dotnet run`.</param>
 		/// <returns>A running Process instance. Caller is responsible for disposing.</returns>
 		public Process StartRun (bool waitForExit = true, string [] parameters = null)
 		{
@@ -171,9 +171,7 @@ public Process StartRun (bool waitForExit = true, string [] parameters = null)
 				$"/p:WaitForExit={waitForExit.ToString (CultureInfo.InvariantCulture)}"
 			};
 			if (parameters != null) {
-				foreach (var parameter in parameters) {
-					arguments.Add ($"/p:{parameter}");
-				}
+				arguments.AddRange (parameters);
 			}
 
 			return ExecuteProcess (arguments.ToArray ());

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

@@ -1591,6 +1591,8 @@ because xbuild doesn't support framework reference assemblies.
     <_GeneratedAndroidEnvironment Include="mono.enable_assembly_preload=0" Condition=" '$(AndroidEnablePreloadAssemblies)' != 'True' " />
     <_GeneratedAndroidEnvironment Include="DOTNET_MODIFIABLE_ASSEMBLIES=Debug" Condition=" '$(AndroidIncludeDebugSymbols)' == 'true' and '$(AndroidUseInterpreter)' == 'true' " />
     <_GeneratedAndroidEnvironment Include="DOTNET_DiagnosticPorts=$(DiagnosticConfiguration)" Condition=" '$(DiagnosticConfiguration)' != '' " />
+    <!-- RuntimeEnvironmentVariable items come from 'dotnet run -e NAME=VALUE' -->
+    <_GeneratedAndroidEnvironment Include="@(RuntimeEnvironmentVariable->'%(Identity)=%(Value)')" />
   </ItemGroup>
   <WriteLinesToFile
       File="$(IntermediateOutputPath)__environment__.txt"

tests/MSBuildDeviceIntegration/Tests/InstallAndRunTests.cs

@@ -149,7 +149,7 @@ public void DotNetRunWithDeviceParameter ()
 			var serial = GetAttachedDeviceSerial ();
 
 			// Start dotnet run with Device parameter, which should set $(AdbTarget)
-			using var process = dotnet.StartRun (waitForExit: true, parameters: [$"Device={serial}"]);
+			using var process = dotnet.StartRun (waitForExit: true, parameters: [$"/p:Device={serial}"]);
 
 			var locker = new Lock ();
 			var output = new StringBuilder ();
@@ -1456,6 +1456,44 @@ public void FastDeployEnvironmentFiles (bool isRelease, bool embedAssembliesInto
 			}
 		}
 
+		[Test]
+		public void DotNetRunEnvironmentVariables ()
+		{
+			var proj = new XamarinAndroidApplicationProject {
+				ProjectName = nameof (DotNetRunEnvironmentVariables),
+				RootNamespace = nameof (DotNetRunEnvironmentVariables),
+				IsRelease = false,
+				EnableDefaultItems = true,
+			};
+			proj.MainActivity = proj.DefaultMainActivity.Replace ("//${AFTER_ONCREATE}", @"
+		Console.WriteLine (""DOTNET_RUN_FOO="" + Environment.GetEnvironmentVariable(""DOTNET_RUN_FOO""));
+		Console.WriteLine (""DOTNET_RUN_BAR="" + Environment.GetEnvironmentVariable(""DOTNET_RUN_BAR""));
+		");
+			using var builder = CreateApkBuilder ();
+			builder.Save (proj);
+
+			var dotnet = new DotNetCLI (Path.Combine (Root, builder.ProjectDirectory, proj.ProjectFilePath));
+			Assert.IsTrue (dotnet.Run (noBuild: false, parameters: new [] { "-e", "DOTNET_RUN_FOO=TestValue123", "-e", "DOTNET_RUN_BAR=AnotherValue456" }), "`dotnet run` should succeed");
+
+			WaitForPermissionActivity (Path.Combine (Root, builder.ProjectDirectory, "permission-logcat.log"));
+			bool didLaunch = WaitForActivityToStart (proj.PackageName, "MainActivity",
+				Path.Combine (Root, builder.ProjectDirectory, "logcat.log"), 30);
+			Assert.IsTrue (didLaunch, "Activity should have started.");
+			var appStartupLogcatFile = Path.Combine (Root, builder.ProjectDirectory, "logcat.log");
+			var logcatOutput = File.ReadAllText (appStartupLogcatFile);
+
+			StringAssert.Contains (
+					"DOTNET_RUN_FOO=TestValue123",
+					logcatOutput,
+					"The Environment variable \"DOTNET_RUN_FOO\" was not set to expected value \"TestValue123\"."
+			);
+			StringAssert.Contains (
+					"DOTNET_RUN_BAR=AnotherValue456",
+					logcatOutput,
+					"The Environment variable \"DOTNET_RUN_BAR\" was not set to expected value \"AnotherValue456\"."
+			);
+		}
+
 		[Test]
 		public void FixLegacyResourceDesignerStep ([Values (true, false)] bool isRelease)
 		{