Enhance IBuildEngine3 Yield/Reacquire documentation with task requirements

[Copilot]

The documentation for IBuildEngine3.Yield() and IBuildEngine3.Reacquire() methods was too minimal and didn't explain the critical requirements and burdens that using these methods imposes on tasks.

Changes Made

Enhanced the XML documentation for both methods to include detailed <remarks> sections that explain:

1. Global process state changes: After calling Yield(), global process state like environment variables and current working directory can change arbitrarily until Reacquire() returns.

2. Task requirements: If tasks depend on any global state (e.g., opening files by relative path rather than calling ITaskItem.GetMetadata("FullPath")), they must complete that work before calling Yield().

3. Common pattern: The recommended approach is to figure out what all the long-running work is and start it before yielding.

Before

/// <summary>
/// Informs the system that this task has a long-running out-of-process component and other work can be done in the
/// build while that work completes.
/// </summary>
void Yield();

/// <summary>
/// Waits to reacquire control after yielding.
/// </summary>
void Reacquire();

After

/// <summary>
/// Informs the system that this task has a long-running out-of-process component and other work can be done in the
/// build while that work completes.
/// </summary>
/// <remarks>
/// After calling <see cref="Yield"/>, global process state like environment variables and current working directory 
/// can change arbitrarily until <see cref="Reacquire"/> returns. As a result, if you are going to depend on any of 
/// that state, for instance by opening files by relative path rather than calling 
/// <c>ITaskItem.GetMetadata("FullPath")</c>, you must do so before calling <see cref="Yield"/>. 
/// The common pattern is to figure out what all the long-running work is and start it before yielding.
/// </remarks>
void Yield();

/// <summary>
/// Waits to reacquire control after yielding.
/// </summary>
/// <remarks>
/// This method must be called to regain control after <see cref="Yield"/> has been called. 
/// After <see cref="Yield"/> is called, global process state like environment variables and current 
/// working directory can change arbitrarily until this method returns. Tasks should complete any work 
/// that depends on global process state before calling <see cref="Yield"/>.
/// </remarks>
void Reacquire();

This documentation enhancement will help task authors understand the proper usage patterns and avoid common pitfalls when implementing long-running tasks that need to yield control.

Fixes #12013.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

• dnceng.pkgs.visualstudio.com
  • Triggering command: dotnet build src/Framework/Microsoft.Build.Framework.csproj (dns block)
  • Triggering command: dotnet build src/Utilities.UnitTests/Microsoft.Build.Utilities.UnitTests.csproj (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to my firewall allow list

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[dotnet-policy-service]

Hello @@copilot, I noticed that you’re changing an .swr file or any file under src/Package/MSBuild.VSSetup.. Please make sure to validate this change by an experimental VS insertion. This is accomplished by pushing to an exp/* branch, which requires write permissions to this repo.

[rainersigwald]

I don't think this is interesting--just say it for Yield.

[Copilot]

Simplified the Reacquire() documentation to remove the redundant global state details, keeping only the essential requirement to call it after Yield(). The detailed explanation is now only in the Yield() method documentation. (72f4132)

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses

I tried to connect to the following addresses, but was blocked by firewall rules:

• dnceng.pkgs.visualstudio.com
  • Triggering command: dotnet build src/Framework/Microsoft.Build.Framework.csproj --no-restore (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to my firewall allow list

[rainersigwald]

@ghogen if you get a second could you look at this doc change?