multithreaded-task-migration

Migrating MSBuild Tasks to Multithreaded API

MSBuild's multithreaded execution model requires tasks to avoid global process state (working directory, environment variables). Thread-safe tasks declare this capability via MSBuildMultiThreadableTask and use TaskEnvironment from IMultiThreadableTask for safe alternatives.

Migration Steps

Step 1: Update Task Class Declaration

a. Ensure the task implementing class is decorated with the MSBuildMultiThreadableTask attribute. b. Implement IMultiThreadableTask only if the task needs TaskEnvironment APIs (path absolutization, env vars, process start). If the task has no file/environment operations (e.g., a stub class), the attribute alone is sufficient.

[MSBuildMultiThreadableTask]
public class MyTask : Task, IMultiThreadableTask
{
    public TaskEnvironment TaskEnvironment { get; set; } = TaskEnvironment.Fallback;
    ...
}

Note: [MSBuildMultiThreadableTask] has Inherited = false — it must be on each concrete class, not just the base.

Step 2: Absolutize Paths Before File Operations

All path strings must be absolutized with TaskEnvironment.GetAbsolutePath() before use in file system APIs. This resolves paths relative to the project directory, not the process working directory.

AbsolutePath absolutePath = TaskEnvironment.GetAbsolutePath(inputPath);
if (File.Exists(absolutePath))
{
    string content = File.ReadAllText(absolutePath);
}

The AbsolutePath struct:

• Value — the absolute path string
• OriginalValue — preserves the input path (use for error messages and [Output] properties)
• Implicitly convertible to string for File/Directory API compatibility
• GetCanonicalForm() — resolves .. segments and normalizes separators (see Sin 5)

CAUTION: GetAbsolutePath() throws ArgumentException for null/empty inputs. See Sin 3 and Sin 6 for compatibility implications.

Step 3: Replace Environment Variable APIs

BEFORE (UNSAFE)	AFTER (SAFE)
Environment.GetEnvironmentVariable("VAR");	TaskEnvironment.GetEnvironmentVariable("VAR");
Environment.SetEnvironmentVariable("VAR", "v");	TaskEnvironment.SetEnvironmentVariable("VAR", "v");

Step 4: Replace Process Start APIs

BEFORE (UNSAFE - inherits process state)	AFTER (SAFE - uses task's isolated environment)
var psi = new ProcessStartInfo("tool.exe");	var psi = TaskEnvironment.GetProcessStartInfo();
	psi.FileName = "tool.exe";

Updating Unit Tests

Built-in MSBuild tasks now initialize TaskEnvironment with a MultiProcessTaskEnvironmentDriver-backed default. Tests creating instances of built-in tasks no longer need manual TaskEnvironment setup. For custom or third-party tasks that implement IMultiThreadableTask without a default initializer, set TaskEnvironment = TaskEnvironmentHelper.CreateForTest().

APIs to Avoid

Category	APIs	Alternative
Forbidden	Environment.Exit, FailFast, Process.Kill, ThreadPool.SetMin/MaxThreads, Console.*	Return false, throw, or use Log
Use TaskEnvironment	Environment.CurrentDirectory, Get/SetEnvironmentVariable, Path.GetFullPath, ProcessStartInfo	See Steps 2-4
Need absolute paths	File.*, Directory.*, FileInfo, DirectoryInfo, FileStream, StreamReader/Writer	Absolutize first (File System APIs)
Review required	Assembly.Load*, Activator.CreateInstance*	Check for version conflicts

Practical Notes

CRITICAL: Trace All Path String Usage

Trace every path string through all method calls and assignments to find all places it flows into file system operations — including helper methods that may internally use File System APIs.

1. Find every path string (e.g., item.ItemSpec, function parameters)
2. Trace downstream through all method calls
3. Absolutize BEFORE any code path that touches the file system
4. Use OriginalValue for user-facing output (logs, errors) — see Sin 2

Exception Handling in Batch Operations

In batch processing (iterating over files), GetAbsolutePath() throwing on one bad path aborts the entire batch. Match the original task's error semantics:

bool success = true;
foreach (ITaskItem item in SourceFiles)
{
    try
    {
        AbsolutePath path = TaskEnvironment.GetAbsolutePath(item.ItemSpec);
        ProcessFile(path);
    }
    catch (ArgumentException ex)
    {
        Log.LogError("Invalid path '{0}': {1}", item.ItemSpec, ex.Message);
        success = false;
    }
}
return success;

Prefer AbsolutePath Over String

Stay in the AbsolutePath world — it's implicitly convertible to string where needed. Avoid round-tripping through string and back.

TaskEnvironment is Not Thread-Safe

If your task spawns multiple threads internally, synchronize access to TaskEnvironment. Each task instance gets its own environment, so no synchronization between tasks is needed.

References

• Thread-Safe Tasks Spec
• AbsolutePath
• TaskEnvironment
• IMultiThreadableTask

---

Compatibility Red-Team Playbook

After migration, review for behavioral compatibility. Every observable difference is a bug until proven otherwise.

Observable behavior = Execute() return value, [Output] property values, error/warning message content, exception types, files written, and which code path runs.

The 6 Deadly Compatibility Sins

Real bugs found during MSBuild task migrations. Every one shipped in initial "passing" code with green tests.

Sin 1: Output Property Contamination

Absolutized values leak into [Output] properties that users/other tasks consume.

// BROKEN: ManifestPath was "bin\Release\app.manifest", now "C:\repo\bin\Release\app.manifest"
AbsolutePath abs = TaskEnvironment.GetAbsolutePath(Path.Combine(OutputDirectory, name));
ManifestPath = abs; // implicit string conversion!

// CORRECT: separate original form from absolutized path
string originalPath = Path.Combine(OutputDirectory, name);
AbsolutePath outputPath = TaskEnvironment.GetAbsolutePath(originalPath);
ManifestPath = originalPath;          // [Output]: original form
document.Save((string)outputPath);    // file I/O: absolute path

Detect: For every [Output] property, trace backward — is it ever assigned from an AbsolutePath?

Sin 2: Error Message Path Inflation

Error messages show absolutized paths instead of the user's original input.

// BROKEN: "Cannot find 'C:\repo\app.manifest'" instead of "Cannot find 'app.manifest'"
AbsolutePath abs = TaskEnvironment.GetAbsolutePath(path);
Log.LogError("Cannot find '{0}'", abs); // implicit conversion!

// CORRECT: use OriginalValue
Log.LogError("Cannot find '{0}'", abs.OriginalValue);

Detect: Search every Log.LogError/LogWarning/LogMessage — is any argument an AbsolutePath?

Sin 3: Null Coalescing That Changes Control Flow

Adding ?? "" silently swallows an exception the old code relied on for error handling.

// BEFORE: Path.GetDirectoryName("C:\") → null → Path.Combine(null, x) → ArgumentNullException
//   → task fails with an exception / error logged → Execute() returns false

// BROKEN: ?? "" added "for safety"
string dir = Path.GetDirectoryName(fileName) ?? string.Empty;
// Path.Combine("", x) succeeds silently → no error → Execute() returns TRUE!

Detect: For every ?? you added, ask: "What happened when this was null before?" If it threw and was caught → your ?? is a bug.

Sin 4: Try-Catch Scope Mismatch

GetAbsolutePath() inside a try block leaves the absolutized value out of scope in the catch block. Helper methods in the catch (like LockCheck) then use the original non-absolute path.

// CORRECT: hoist above try so catch can use it too
AbsolutePath abs = TaskEnvironment.GetAbsolutePath(OutputManifest.ItemSpec);
try {
    WriteFile(abs);
} catch (Exception ex) {
    string lockMsg = LockCheck.GetLockedFileMessage(abs);        // absolute → correct file
    Log.LogError("Failed: {0}", OutputManifest.ItemSpec, ...);   // original → user-friendly
}

Detect: For every GetAbsolutePath inside a try, check if the catch block needs the absolutized value.

Sin 5: Canonicalization Mismatch

GetAbsolutePath does NOT canonicalize. Path.GetFullPath does TWO things: absolutize AND canonicalize (.. resolution, separator normalization). If the old code used Path.GetFullPath for dictionary keys, comparisons, or display, you must add .GetCanonicalForm():

// GetAbsolutePath("foo/../bar")  → "C:\repo\foo/../bar"  (NOT canonical)
// Path.GetFullPath("foo/../bar") → "C:\repo\bar"         (canonical)

// BROKEN for dictionary keys — "C:\repo\foo\..\bar" ≠ "C:\repo\bar"
var map = items.ToDictionary(p => (string)TaskEnvironment.GetAbsolutePath(p.ItemSpec), ...);

// CORRECT
var map = items.ToDictionary(
    p => (string)TaskEnvironment.GetAbsolutePath(p.ItemSpec).GetCanonicalFor

---

*Content truncated.*