Read ASPIRE_ENVIRONMENT in DistributedApplicationBuilder

Add ASPIRE_-prefixed environment variables as a configuration source
in DistributedApplicationBuilder, using the same AddEnvironmentVariables
pattern as the core framework uses for DOTNET_-prefixed variables.

ASPIRE_ENVIRONMENT is pre-seeded into the ConfigurationManager before
HostApplicationBuilder adds DOTNET_ env vars and command-line args,
giving the correct priority order:

1. --environment CLI flag (highest)
2. DOTNET_ENVIRONMENT
3. ASPIRE_ENVIRONMENT
4. Default (Production)

Tests use RemoteExecutor to run each test in a separate process,
avoiding concurrency issues from env var mutation.

Fixes #16096

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: davidfowl

src/Aspire.Hosting/DistributedApplicationBuilder.cs

@@ -185,6 +185,13 @@ public DistributedApplicationBuilder(DistributedApplicationOptions options)
         // so they're used to initialize some types created immediately, e.g. IHostEnvironment.
         innerBuilderOptions.Args = options.Args;
 
+        // Pre-seed the configuration with ASPIRE_-prefixed environment variables.
+        // HostApplicationBuilder will then add DOTNET_-prefixed env vars and command line args on top.
+        // This gives us the priority order: --environment > DOTNET_ENVIRONMENT > ASPIRE_ENVIRONMENT > default.
+        var configuration = new ConfigurationManager();
+        configuration.AddEnvironmentVariables(prefix: "ASPIRE_");
+        innerBuilderOptions.Configuration = configuration;
+
         LogBuilderConstructing(options, innerBuilderOptions);
         _innerBuilder = new HostApplicationBuilder(innerBuilderOptions);
 

src/Shared/KnownConfigNames.cs

@@ -54,6 +54,8 @@ internal static class KnownConfigNames
     public const string DeveloperCertificateDefaultHttpsTermination = "ASPIRE_DEVELOPER_CERTIFICATE_DEFAULT_HTTPS_TERMINATION";
     public const string DcpDeveloperCertificate = "ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE";
 
+    public const string AspireEnvironment = "ASPIRE_ENVIRONMENT";
+
     public const string DebugSessionInfo = "DEBUG_SESSION_INFO";
     public const string DebugSessionRunMode = "DEBUG_SESSION_RUN_MODE";
     public const string DebugSessionPort = "DEBUG_SESSION_PORT";

tests/Aspire.Hosting.Tests/AspireEnvironmentTests.cs

@@ -0,0 +1,93 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using Microsoft.DotNet.RemoteExecutor;
+using Microsoft.Extensions.Hosting;
+
+namespace Aspire.Hosting.Tests;
+
+[Trait("Partition", "5")]
+public class AspireEnvironmentTests
+{
+    [Fact]
+    public void AspireEnvironmentSetsBuilderEnvironment()
+    {
+        var options = new RemoteInvokeOptions();
+        options.StartInfo.Environment["ASPIRE_ENVIRONMENT"] = "Staging";
+        options.StartInfo.Environment.Remove("DOTNET_ENVIRONMENT");
+        options.StartInfo.Environment.Remove("ASPNETCORE_ENVIRONMENT");
+
+        RemoteExecutor.Invoke(static () =>
+        {
+            var builder = DistributedApplication.CreateBuilder(new DistributedApplicationOptions { DisableDashboard = true });
+            Assert.Equal("Staging", builder.Environment.EnvironmentName);
+        }, options).Dispose();
+    }
+
+    [Fact]
+    public void DotnetEnvironmentTakesPrecedenceOverAspireEnvironment()
+    {
+        var options = new RemoteInvokeOptions();
+        options.StartInfo.Environment["ASPIRE_ENVIRONMENT"] = "Staging";
+        options.StartInfo.Environment["DOTNET_ENVIRONMENT"] = "Production";
+        options.StartInfo.Environment.Remove("ASPNETCORE_ENVIRONMENT");
+
+        RemoteExecutor.Invoke(static () =>
+        {
+            var builder = DistributedApplication.CreateBuilder(new DistributedApplicationOptions { DisableDashboard = true });
+            Assert.Equal("Production", builder.Environment.EnvironmentName);
+        }, options).Dispose();
+    }
+
+    [Fact]
+    public void EnvironmentFlagTakesPrecedenceOverAspireEnvironment()
+    {
+        var options = new RemoteInvokeOptions();
+        options.StartInfo.Environment["ASPIRE_ENVIRONMENT"] = "Staging";
+        options.StartInfo.Environment.Remove("DOTNET_ENVIRONMENT");
+        options.StartInfo.Environment.Remove("ASPNETCORE_ENVIRONMENT");
+
+        RemoteExecutor.Invoke(static () =>
+        {
+            var builder = DistributedApplication.CreateBuilder(new DistributedApplicationOptions
+            {
+                DisableDashboard = true,
+                Args = ["--environment", "Production"]
+            });
+            Assert.Equal("Production", builder.Environment.EnvironmentName);
+        }, options).Dispose();
+    }
+
+    [Fact]
+    public void DefaultEnvironmentIsProductionWithNoEnvVars()
+    {
+        var options = new RemoteInvokeOptions();
+        options.StartInfo.Environment.Remove("ASPIRE_ENVIRONMENT");
+        options.StartInfo.Environment.Remove("DOTNET_ENVIRONMENT");
+        options.StartInfo.Environment.Remove("ASPNETCORE_ENVIRONMENT");
+
+        RemoteExecutor.Invoke(static () =>
+        {
+            var builder = DistributedApplication.CreateBuilder(new DistributedApplicationOptions { DisableDashboard = true });
+            Assert.Equal("Production", builder.Environment.EnvironmentName);
+        }, options).Dispose();
+    }
+
+    [Fact]
+    public void AspireEnvironmentSetsCustomEnvironmentName()
+    {
+        var options = new RemoteInvokeOptions();
+        options.StartInfo.Environment["ASPIRE_ENVIRONMENT"] = "Testing";
+        options.StartInfo.Environment.Remove("DOTNET_ENVIRONMENT");
+        options.StartInfo.Environment.Remove("ASPNETCORE_ENVIRONMENT");
+
+        RemoteExecutor.Invoke(static () =>
+        {
+            var builder = DistributedApplication.CreateBuilder(new DistributedApplicationOptions { DisableDashboard = true });
+            Assert.Equal("Testing", builder.Environment.EnvironmentName);
+            Assert.False(builder.Environment.IsDevelopment());
+            Assert.False(builder.Environment.IsProduction());
+            Assert.True(builder.Environment.IsEnvironment("Testing"));
+        }, options).Dispose();
+    }
+}