.NET: Add parallel declarative Foreach execution

[KirschQAQ (KirschBluteX)]

Motivation & Context

Declarative Foreach workflows currently execute each iteration serially, even when iterations are independent. This adds bounded, opt-in parallel fan-out while preserving the existing sequential behavior by default.

Description & Review Guide

• What are the major changes? Add mode: Parallel, maxParallelism, and per-iteration timeoutInMilliseconds through the ObjectModel extension-data contract. Parallel iterations run as isolated in-process sub-workflows, buffer state and events, and commit them in source-index order. External-input checkpoints and loop control targeting the parallel loop are rejected explicitly. Configuration validation also rejects numeric strings such as mode: "1", combined enum values, non-positive parallelism, and invalid timeouts.
• What is the impact of these changes? Existing workflows are unchanged. Parallel workflows get deterministic last-index-wins state commits, bounded concurrency, peer cancellation on failure or timeout, and no buffered state/event commit on failure. The declarative library builds for all five target frameworks; 915 unit tests pass on both net10.0 and net472, including 40 focused parallel-Foreach tests on each framework.
• What do you want reviewers to focus on?

Related Issue

Fixes #2793

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds opt-in parallel execution for declarative Foreach, including isolated per-iteration formula state, deterministic commit ordering, timeout/cancellation behavior, and documentation + end-to-end tests validating concurrency and failure semantics.

Changes:

• Introduces ForeachExecutionOptions and ParallelForeachIterationRunner to execute Foreach bodies concurrently with bounded parallelism and per-iteration timeouts.
• Extends WorkflowFormulaState to snapshot/branch state and track variable writes for deterministic, ordered commits.
• Adds unit tests and README documentation describing parallel Foreach behavior and limitations.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ParallelForeachWorkflowTests.cs	New E2E behavioral tests covering concurrency, ordering, failures, cancellation, and timeouts.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/README.md	Documents how to opt into parallel Foreach, limits/timeouts, and checkpointing constraints.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/PowerFx/WorkflowFormulaState.cs	Adds state snapshotting, branch creation, and change tracking for parallel iteration isolation/commit.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ParallelForeachIterationRunner.cs	Executes a single iteration in an isolated runtime and returns buffered state changes/events.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutor.cs	Adds parallel execution path, bounded worker pool, and ordered commit replay into parent context.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/ForeachExecutionOptions.cs	Parses/validates Foreach execution options from extension data (mode, maxParallelism, timeoutInMilliseconds).
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowElementWalker.cs	Prevents walking into parallel Foreach descendants to avoid double-compiling its body.
dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs	Passes workflow options into ForeachExecutor and short-circuits visitor logic for parallel loops.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[KirschQAQ (KirschBluteX)]

@microsoft-github-policy-service agree