Expose public API for TaskEnvironment construction

src/Build.UnitTests/BackEnd/TaskEnvironment_Tests.cs

@@ -360,6 +360,111 @@ public void TaskEnvironment_MultithreadedEnvironment_ShouldBeIsolatedFromSystem(
             }
         }
 
+        [Fact]
+        public void TaskEnvironment_Fallback_ReadsProcessEnvironment()
+        {
+            string testVarName = $"MSBUILD_DEFAULT_ENV_TEST_{Guid.NewGuid():N}";
+            string testVarValue = "default_env_test_value";
+
+            try
+            {
+                Environment.SetEnvironmentVariable(testVarName, testVarValue);
+
+                TaskEnvironment.Fallback.GetEnvironmentVariable(testVarName).ShouldBe(testVarValue);
+            }
+            finally
+            {
+                Environment.SetEnvironmentVariable(testVarName, null);
+            }
+        }
+
+        [Fact]
+        public void TaskEnvironment_CreateWithProjectDirectoryAndEnvironment_SnapshotsCurrentEnvironment()
+        {
+            string testVarName = $"MSBUILD_CREATE_MT_TEST_{Guid.NewGuid():N}";
+            string testVarValue = "snapshot_test_value";
+            string projectDir = GetResolvedTempPath();
+
+            try
+            {
+                Environment.SetEnvironmentVariable(testVarName, testVarValue);
+
+                TaskEnvironment env = TaskEnvironment.CreateWithProjectDirectoryAndEnvironment(projectDir);
+
+                env.ShouldNotBeNull();
+                env.GetEnvironmentVariable(testVarName).ShouldBe(testVarValue);
+                env.ProjectDirectory.Value.ShouldBe(projectDir);
+
+                // Changing the process env var after snapshot should not affect the isolated environment.
+                Environment.SetEnvironmentVariable(testVarName, "changed_after_snapshot");
+                env.GetEnvironmentVariable(testVarName).ShouldBe(testVarValue);
+            }
+            finally
+            {
+                Environment.SetEnvironmentVariable(testVarName, null);
+            }
+        }
+
+        [Fact]
+        public void TaskEnvironment_CreateWithProjectDirectoryAndEnvironment_WithCustomEnvironment_UsesProvidedDictionary()
+        {
+            string excludedVarName = $"MSBUILD_EXCLUDED_VAR_{Guid.NewGuid():N}";
+            string projectDir = GetResolvedTempPath();
+
+            try
+            {
+                // Set a process-level env var that should NOT appear in the custom environment.
+                Environment.SetEnvironmentVariable(excludedVarName, "process_level_value");
+
+                var customEnv = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+                {
+                    ["MY_CUSTOM_VAR"] = "custom_value",
+                    ["ANOTHER_VAR"] = "another_value"
+                };
+
+                TaskEnvironment env = TaskEnvironment.CreateWithProjectDirectoryAndEnvironment(projectDir, customEnv);
+
+                env.ShouldNotBeNull();
+                env.GetEnvironmentVariable("MY_CUSTOM_VAR").ShouldBe("custom_value");
+                env.GetEnvironmentVariable("ANOTHER_VAR").ShouldBe("another_value");
+                env.GetEnvironmentVariable(excludedVarName).ShouldBeNull();
+                env.ProjectDirectory.Value.ShouldBe(projectDir);
+            }
+            finally
+            {
+                Environment.SetEnvironmentVariable(excludedVarName, null);
+            }
+        }
+
+        [Fact]
+        public void TaskEnvironment_CreateWithProjectDirectoryAndEnvironment_ReturnsIsolatedInstances()
+        {
+            string projectDir = GetResolvedTempPath();
+
+            TaskEnvironment env1 = TaskEnvironment.CreateWithProjectDirectoryAndEnvironment(projectDir);
+            TaskEnvironment env2 = TaskEnvironment.CreateWithProjectDirectoryAndEnvironment(projectDir);
+
+            env1.ShouldNotBeSameAs(env2);
+
+            string testVarName = $"MSBUILD_ISOLATION_TEST_{Guid.NewGuid():N}";
+            env1.SetEnvironmentVariable(testVarName, "only_in_env1");
+
+            env1.GetEnvironmentVariable(testVarName).ShouldBe("only_in_env1");
+            env2.GetEnvironmentVariable(testVarName).ShouldNotBe("only_in_env1");
+        }
+
+        [Fact]
+        public void TaskEnvironment_CreateWithProjectDirectoryAndEnvironment_NullProjectDirectory_Throws()
+        {
+            Should.Throw<ArgumentNullException>(() => TaskEnvironment.CreateWithProjectDirectoryAndEnvironment(null!));
+        }
+
+        [Fact]
+        public void TaskEnvironment_CreateWithProjectDirectoryAndEnvironment_EmptyProjectDirectory_Throws()
+        {
+            Should.Throw<ArgumentException>(() => TaskEnvironment.CreateWithProjectDirectoryAndEnvironment(string.Empty));
+        }
+
         [Theory]
         [MemberData(nameof(EnvironmentTypes))]
         public void TaskEnvironment_GetAbsolutePath_WithInvalidPathChars_ShouldNotThrow(string environmentType)

src/Framework/TaskEnvironment.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System;
 using System.Collections.Generic;
 using System.Diagnostics;
 
@@ -22,6 +23,38 @@ internal TaskEnvironment(ITaskEnvironmentDriver driver)
             _driver = driver;
         }
 
+        /// <summary>
+        /// Gets the fallback task environment that directly accesses the system environment variables
+        /// and working directory of the current process.
+        /// </summary>
+        /// <remarks>
+        /// This is the environment provided to tasks by the MSBuild engine in multi-process execution mode,
+        /// where each task runs in its own process and process-level state is inherently isolated.
+        /// </remarks>
+        public static TaskEnvironment Fallback { get; } = new(MultiProcessTaskEnvironmentDriver.Instance);
+
+        /// <summary>
+        /// Creates a new <see cref="TaskEnvironment"/> with isolated working directory and environment variables.
+        /// </summary>
+        /// <remarks>
+        /// This method is primarily intended for testing scenarios. In normal MSBuild operation, the correct task environment is provided by the MSBuild engine.
+        /// The created TaskEnvironment provides isolated environment state similar to what tasks receive in multithreaded execution mode, enabling testing of task isolation behavior.
+        /// </remarks>
+        /// <param name="projectDirectory">The initial working directory for the task.</param>
+        /// <param name="environmentVariables">A dictionary of environment variables to use, or <see langword="null"/> to use the current process environment variables.</param>
+        /// <returns>A new <see cref="TaskEnvironment"/> with isolated environment state.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="projectDirectory"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException"><paramref name="projectDirectory"/> is empty.</exception>
+        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
+        public static TaskEnvironment CreateWithProjectDirectoryAndEnvironment(string projectDirectory, IDictionary<string, string>? environmentVariables = null)
+        {
+            ArgumentException.ThrowIfNullOrEmpty(projectDirectory);
+
+            return environmentVariables is null
+                ? new TaskEnvironment(new MultiThreadedTaskEnvironmentDriver(projectDirectory))
+                : new TaskEnvironment(new MultiThreadedTaskEnvironmentDriver(projectDirectory, environmentVariables));
+        }
+
         /// <summary>
         /// Gets or sets the project directory for the task execution.
         /// </summary>