Add new multithreaded APIs

documentation/specs/multithreading/thread-safe-tasks.md

@@ -88,16 +88,16 @@ public interface IMultiThreadableTask : ITask
 
 public class TaskEnvironment
 { 
-    public virtual AbsolutePath ProjectDirectory { get; internal set; }
+    public AbsolutePath ProjectDirectory { get; internal set; }
 
     // This function resolves paths relative to ProjectDirectory.
-    public virtual AbsolutePath GetAbsolutePath(string path);
+    public AbsolutePath GetAbsolutePath(string path);
 
-    public virtual string? GetEnvironmentVariable(string name);
-    public virtual IReadOnlyDictionary<string, string> GetEnvironmentVariables();
-    public virtual void SetEnvironmentVariable(string name, string? value);
+    public string? GetEnvironmentVariable(string name);
+    public IReadOnlyDictionary<string, string> GetEnvironmentVariables();
+    public void SetEnvironmentVariable(string name, string? value);
 
-    public virtual ProcessStartInfo GetProcessStartInfo();
+    public ProcessStartInfo GetProcessStartInfo();
 }
 ```
 
@@ -152,4 +152,4 @@ The main advantages of API hooking include requiring no action from task authors
 
 ### Alternative to Attribute-Based Thread-Safe Capability Declaration
 
-We considered making the thread-safety signal using the task declaration (for example, a `ThreadSafe="true"` attribute on `UsingTask`) so that project authors could declare compatibility without changing task assemblies. However, because older MSBuild versions treat unknown attributes in task declarations as errors, this approach would require updating older MSBuild versions or servicing them to ignore the attribute. 
+We considered making the thread-safety signal using the task declaration (for example, a `ThreadSafe="true"` attribute on `UsingTask`) so that project authors could declare compatibility without changing task assemblies. However, because older MSBuild versions treat unknown attributes in task declarations as errors, this approach would require updating older MSBuild versions or servicing them to ignore the attribute. 

src/Framework/IMultiThreadableTask.cs

@@ -0,0 +1,37 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.Build.Framework
+{
+    /// <summary>
+    /// Interface for tasks that can execute in a thread-safe manner within MSBuild's multithreaded execution model. 
+    /// Tasks that implement this interface declare their capability to run in multiple threads within one process.
+    /// </summary>
+    /// <remarks>
+    /// The task <strong>must</strong>:
+    /// <list type="bullet">
+    /// <item>Use the provided <see cref="TaskEnvironment"/> for all modifications to process state such as environment variables,
+    ///   working directory, or process spawning instead of directly modifying global process state</item>
+    /// <item>Not depend on global process state for correct operation, including avoiding relative path
+    ///   resolution that relies on the current working directory</item>
+    /// <item>Use <see cref="TaskEnvironment.GetAbsolutePath(string)"/> instead of <see cref="System.IO.Path.GetFullPath(string)"/> for path resolution</item>
+    /// <item>Handle any internal synchronization if the task spawns multiple threads internally</item>
+    /// </list>
+    /// Tasks implementing this interface can be safely executed in parallel with other tasks or
+    /// instances of the same task within a single MSBuild process, enabling better performance
+    /// in multithreaded build scenarios.
+    /// 
+    /// See the <see href="https://github.com/dotnet/msbuild/blob/main/documentation/specs/multithreading/thread-safe-tasks.md">Thread-Safe Tasks specification</see> for detailed guidelines on thread-safe task development.
+    /// </remarks>
+    public interface IMultiThreadableTask : ITask
+    {
+        /// <summary>
+        /// Gets or sets the task execution environment, which provides access to project current directory and environment variables in a thread-safe manner.
+        /// </summary>
+        /// <remarks>
+        /// This property is set on behalf of the Task by the MSBuild engine before the Task is executed. It should <strong>never</strong> be set by a Task itself.
+        /// </remarks>
+        /// <value>Task environment which provides access to project current directory and environment variables.</value>
+        TaskEnvironment TaskEnvironment { get; internal set; }
+    }
+}

src/Framework/MSBuildMultiThreadableTaskAttribute.cs

@@ -0,0 +1,39 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+#nullable enable
+
+using System;
+
+namespace Microsoft.Build.Framework
+{
+    /// <summary>
+    /// Attribute that marks a task class as thread-safe for multithreaded execution.
+    /// </summary>
+    /// <remarks>
+    /// Task classes marked with this attribute indicate they can be safely executed in parallel 
+    /// in the same process with other tasks. This is a compatibility bridge option for existing tasks
+    /// that do not have access to TaskEnvironment APIs.
+    /// 
+    /// Tasks using this attribute must satisfy strict requirements:
+    /// - Must not modify global process state (environment variables, working directory, etc.)
+    /// - Must not depend on global process state, including relative path resolution
+    /// 
+    /// MSBuild detects this attribute by its namespace and name only, ignoring the defining assembly.
+    /// This allows customers to define the attribute in their own assemblies alongside their tasks.
+    /// Since MSBuild does not ship this attribute, task authors can copy this definition into their
+    /// own projects and mark their task classes with it. Customers using newer MSBuild versions
+    /// should prefer implementing IMultiThreadableTask which provides access to TaskEnvironment
+    /// for safe process state operations.
+    /// </remarks>
+    [AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
+    internal class MSBuildMultiThreadableTaskAttribute : Attribute
+    {
+        /// <summary>
+        /// Initializes a new instance of the MSBuildMultiThreadableTaskAttribute class.
+        /// </summary>
+        public MSBuildMultiThreadableTaskAttribute()
+        {
+        }
+    }
+}

src/Framework/PathHelpers/AbsolutePath.cs

@@ -0,0 +1,62 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+
+namespace Microsoft.Build.Framework
+{
+    /// <summary>
+    /// Represents an absolute file system path.
+    /// </summary>
+    /// <remarks>
+    /// This struct ensures that paths are always in absolute form and properly formatted.
+    /// </remarks>
+    public readonly struct AbsolutePath
+    {
+        /// <summary>
+        /// Gets the string representation of this path.
+        /// </summary>
+        public string Path { get; }
+
+        /// <summary>
+        /// Creates a new instance of AbsolutePath.
+        /// </summary>
+        /// <param name="path">The absolute path string.</param>
+        public AbsolutePath(string path)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        /// Creates a new instance of AbsolutePath.
+        /// </summary>
+        /// <param name="path">The absolute path string.</param>
+        /// <param name="ignoreRootedCheck">If true, skips checking whether the path is rooted.</param>
+        internal AbsolutePath(string path, bool ignoreRootedCheck)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        /// Creates a new absolute path by combining a absolute path with a relative path.
+        /// </summary>
+        /// <param name="path">The path to combine with the base path.</param>
+        /// <param name="basePath">The base path to combine with.</param>
+        public AbsolutePath(string path, AbsolutePath basePath)
+        {
+            throw new NotImplementedException();
+        }
+
+        /// <summary>
+        /// Implicitly converts an AbsolutePath to a string.
+        /// </summary>
+        /// <param name="path">The path to convert.</param>
+        public static implicit operator string(AbsolutePath path) => throw new NotImplementedException();
+
+        /// <summary>
+        /// Returns the string representation of this path.
+        /// </summary>
+        /// <returns>The path as a string.</returns>
+        public override string ToString() => throw new NotImplementedException();
+    }
+}

src/Framework/TaskEnvironment.cs

@@ -0,0 +1,59 @@
+// 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;
+
+namespace Microsoft.Build.Framework
+{
+    /// <summary>
+    /// Provides an <see cref="IMultiThreadableTask"/> with access to a run-time execution environment including
+    /// environment variables, file paths, and process management capabilities.
+    /// </summary>
+    public sealed class TaskEnvironment
+    {
+        /// <summary>
+        /// Gets or sets the project directory for the task execution.
+        /// </summary>
+        public AbsolutePath ProjectDirectory
+        {
+            get => throw new NotImplementedException();
+            internal set => throw new NotImplementedException();
+        }
+
+        /// <summary>
+        /// Converts a relative or absolute path string to an absolute path.
+        /// This function resolves paths relative to ProjectDirectory.
+        /// </summary>
+        /// <param name="path">The path to convert.</param>
+        /// <returns>An absolute path representation.</returns>
+        public AbsolutePath GetAbsolutePath(string path) => throw new NotImplementedException();
+
+        /// <summary>
+        /// Gets the value of an environment variable.
+        /// </summary>
+        /// <param name="name">The name of the environment variable.</param>
+        /// <returns>The value of the environment variable, or null if it does not exist.</returns>
+        public string? GetEnvironmentVariable(string name) => throw new NotImplementedException();
+
+        /// <summary>
+        /// Gets a dictionary containing all environment variables.
+        /// </summary>
+        /// <returns>A read-only dictionary of environment variables.</returns>
+        public IReadOnlyDictionary<string, string> GetEnvironmentVariables() => throw new NotImplementedException();
+
+        /// <summary>
+        /// Sets the value of an environment variable.
+        /// </summary>
+        /// <param name="name">The name of the environment variable.</param>
+        /// <param name="value">The value to set, or null to remove the environment variable.</param>
+        public void SetEnvironmentVariable(string name, string? value) => throw new NotImplementedException();
+
+        /// <summary>
+        /// Creates a new ProcessStartInfo configured for the current task execution environment.
+        /// </summary>
+        /// <returns>A ProcessStartInfo object configured for the current task execution environment.</returns>
+        public ProcessStartInfo GetProcessStartInfo() => throw new NotImplementedException();
+    }
+}