Add guidance for choosing ToList() vs ToArray() in async LINQ scenarios

[Copilot]

Enhanced the async scenarios documentation to explain when to use ToList() versus ToArray() when forcing eager evaluation of LINQ expressions with async operations.

Changes Made

Updated documentation text to provide clear guidance on choosing between the two methods:

• Use ToArray() for Task.WhenAll scenarios where you process all tasks together and the collection size is fixed
• Use ToList() for Task.WhenAny scenarios where you need to dynamically manage tasks, such as removing completed tasks from the collection

Added practical code example demonstrating the ToList() approach:

private static async Task ProcessTasksAsTheyCompleteAsync(IEnumerable<int> userIds)
{
    var getUserTasks = userIds.Select(id => GetUserAsync(id)).ToList();
    
    while (getUserTasks.Count > 0)
    {
        Task<User> completedTask = await Task.WhenAny(getUserTasks);
        getUserTasks.Remove(completedTask);
        
        User user = await completedTask;
        Console.WriteLine($"Processed user {user.id}");
    }
}

This example shows how ToList() creates a modifiable collection that supports the Remove() operation, making it ideal for WhenAny patterns where you handle completions as they arise.

The existing ToArray() example and explanation remain unchanged to maintain backwards compatibility while providing developers with a complete understanding of both approaches.

Fixes #34606.

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:

• learn.microsoft.com
  • Triggering command: /home/REDACTED/work/docs/docs/docs/csharp/asynchronous-programming/snippets/async-scenarios/bin/Debug/net8.0/async-scenarios (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 the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

---

Internal previews

📄 File	🔗 Preview link
docs/csharp/asynchronous-programming/async-scenarios.md	docs/csharp/asynchronous-programming/async-scenarios

[BillWagner]

This is ready for final review.

[learn-build-service-prod]

PoliCheck Scan Report

The following reports lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a comment that you post to the PR. The feedback helps reduce false positive instances in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[BillWagner]

@gewarren This is now updated with all your feedback. Can you approve?

[adegeo]

@copilot the full Program.cs reference at the end of the article includes the snippet system code comments because it's referencing the file with out a snippet id. Place a starting and ending snippet id (named complete) at the top and bottom of the Program.cs file, then reference it. The build system will solve the problem of showing other snippet identifiers in the published article.

[Copilot]

@copilot the full Program.cs reference at the end of the article includes the snippet system code comments because it's referencing the file with out a snippet id. Place a starting and ending snippet ...

Fixed this issue by adding "complete" snippet markers to wrap the entire Program.cs file and updating the markdown reference to use ID="complete". This prevents the internal snippet system code comments from appearing in the published article. The change was validated by successfully building the project. (commit e26e9a4)

[learn-build-service-prod]

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.