From d282ddc3e8d90985e7e92fcf89ece7d3bd517639 Mon Sep 17 00:00:00 2001
From: Jonathan Peppers <jonathan.peppers@microsoft.com>
Date: Wed, 4 Feb 2026 14:14:10 -0600
Subject: [PATCH 1/2] [xabt] support `@(RuntimeEnvironmentVariable)` items

Context: https://github.com/dotnet/sdk/commit/bd5d3af9804ba358bf3f2e1be209418bcc949d16

`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:

* https://github.com/dotnet/android/pull/10769

We won't be able to merge this until we have a .NET SDK here that
includes the above commit.
---
 ...ft.Android.Sdk.ProjectCapabilities.targets |  1 +
 .../Xamarin.ProjectTools/Common/DotNetCLI.cs  | 20 +++++-----
 .../Xamarin.Android.Common.targets            |  2 +
 .../Tests/InstallAndRunTests.cs               | 40 ++++++++++++++++++-
 4 files changed, 51 insertions(+), 12 deletions(-)

diff --git a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.ProjectCapabilities.targets b/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.ProjectCapabilities.targets
index a8b04059e23..fef1c290dfb 100644
--- a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.ProjectCapabilities.targets
+++ b/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>
 
diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/DotNetCLI.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/DotNetCLI.cs
index d5def237a9a..46fbc3ecae4 100644
--- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/DotNetCLI.cs
+++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/DotNetCLI.cs
@@ -131,20 +131,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 ());
 		}
@@ -153,7 +153,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)
 		{
@@ -166,9 +166,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 ());
diff --git a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets
index ae344755a58..f01393f6565 100644
--- a/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets
+++ b/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Common.targets
@@ -1778,6 +1778,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"
diff --git a/tests/MSBuildDeviceIntegration/Tests/InstallAndRunTests.cs b/tests/MSBuildDeviceIntegration/Tests/InstallAndRunTests.cs
index 5e02d029904..11be3075d1c 100644
--- a/tests/MSBuildDeviceIntegration/Tests/InstallAndRunTests.cs
+++ b/tests/MSBuildDeviceIntegration/Tests/InstallAndRunTests.cs
@@ -146,7 +146,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 ();
@@ -1352,6 +1352,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)
 		{

From fea1769ff950f99cc0610ed5d6159f32ae97d98e Mon Sep 17 00:00:00 2001
From: Jonathan Peppers <jonathan.peppers@microsoft.com>
Date: Wed, 25 Feb 2026 09:21:04 -0600
Subject: [PATCH 2/2] Update build-items.md

---
 .../docs-mobile/building-apps/build-items.md  | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/Documentation/docs-mobile/building-apps/build-items.md b/Documentation/docs-mobile/building-apps/build-items.md
index 57cc85ce9af..73c3d3a51c6 100644
--- a/Documentation/docs-mobile/building-apps/build-items.md
+++ b/Documentation/docs-mobile/building-apps/build-items.md
@@ -567,3 +567,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.