Skip to content

.NET: feat: add pipeline behavior extension points for workflow and executor execution#3982

Open
gijswalraven wants to merge 23 commits intomicrosoft:mainfrom
gijswalraven:feat/issue_3960_Workflow_Pipeline_Behavior
Open

.NET: feat: add pipeline behavior extension points for workflow and executor execution#3982
gijswalraven wants to merge 23 commits intomicrosoft:mainfrom
gijswalraven:feat/issue_3960_Workflow_Pipeline_Behavior

Conversation

@gijswalraven
Copy link

@gijswalraven gijswalraven commented Feb 17, 2026

Summary

  • Introduces IWorkflowBehavior and IExecutorBehavior interfaces for injecting custom logic before/after workflow start/end and executor step start/end
  • Implements a chain-of-responsibility BehaviorPipeline (internal) with zero-overhead fast path when no behaviors are registered
  • Wires behaviors into Workflow, WorkflowBuilder, Executor, and InProcessRunner via an opt-in fluent API (WithBehaviors)
  • Adds BehaviorExecutionException for wrapping behavior failures with stage/type context

Test plan

  • Unit tests for BehaviorExecutionException constructors and properties
  • Unit tests for BehaviorPipeline execution order and error handling
  • Unit tests for WorkflowBehaviorOptions registration (instance and factory)
  • Integration tests for full pipeline: logging, validation, short-circuiting, and context enrichment scenarios
  • Build passes with 0 errors and 0 warnings

References

Closes #3960

🤖 Generated with Claude Code

Gijs Walraven and others added 3 commits February 17, 2026 09:33
@claude
feat: add pipeline behavior interfaces and contracts
0a95746 
Introduces IWorkflowBehavior, IExecutorBehavior, WorkflowBehaviorOptions,
and BehaviorExecutionException as the public API surface for pipeline
behaviors on workflow and executor execution.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
feat: wire pipeline behaviors into workflow execution
0db8c19 
Adds BehaviorPipeline (internal chain-of-responsibility engine) and
integrates it into Workflow, WorkflowBuilder, Executor, and
InProcessRunner. Includes a zero-overhead fast path when no behaviors
are registered.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
test: add unit tests and docs for pipeline behaviors
74c9689 
Adds XUnit tests for BehaviorExecutionException, BehaviorPipeline,
WorkflowBehaviorOptions, and integration tests for the full behavior
pipeline. Includes developer documentation (README.md) covering
usage, examples, and API reference.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@markwallace-microsoft markwallace-microsoft added documentation Improvements or additions to documentation .NET workflows Related to Workflows in agent-framework labels Feb 17, 2026
@github-actions github-actions bot changed the title feat: add pipeline behavior extension points for workflow and executor execution .NET: feat: add pipeline behavior extension points for workflow and executor execution Feb 17, 2026
@gijswalraven gijswalraven mentioned this pull request Feb 17, 2026
Open
Gijs Walraven and others added 5 commits February 17, 2026 10:05
@claude
.NET Workflows: Remove unused ExecutorStage.PostExecution enum value
9bfcb22 
PostExecution was never set in ExecutorBehaviorContext. Behaviors already
support post-execution logic naturally by placing code after the
`await continuation()` call. Clarify this in docs and remove the dead value.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
.NET Workflows: Fix null configure silently ignored in WithBehaviors
560f9d4 
Passing null to WithBehaviors previously created an empty
WorkflowBehaviorOptions and returned without error. Use Throw.IfNull
to match the validation pattern used by all other WorkflowBuilder methods.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
.NET Workflows: Avoid async state machine allocation in BeginStreamAsync
2408c8f 
The async keyword on BeginStreamAsync caused a state machine to be allocated
on every call, even when no behaviors are configured. Split into a sync fast
path returning ValueTask directly, and a private async method used only when
behaviors are present.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
.NET Workflows: Fix RunId correlation in ExecutorBehaviorContext
91fc271 
A new GUID was generated per executor invocation, making it impossible
for behaviors to correlate calls within the same workflow run. Pass the
run ID alongside BehaviorPipeline through the internal ExecuteAsync
overload so behaviors always see the correct run identifier.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
.NET Workflows: Wire ExecuteWorkflowEndBehaviorsAsync into workflow t…
dde1d04 
…eardown

WorkflowStage.Ending was unreachable because ExecuteWorkflowEndBehaviorsAsync
was defined but never called. Register it as a callback on InProcessRunnerContext
so it fires during EndRunAsync, before executor disposal, symmetrically
with the Starting behaviors fired in BeginStreamAsync.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@gijswalraven
Copy link
Author

gijswalraven commented Feb 17, 2026

@microsoft-github-policy-service agree company="delaware Consulting B.V."

Gijs Walraven and others added 15 commits February 17, 2026 10:18
@claude
Bug 6: Use required keyword on ExecutorBehaviorContext properties
6b8589c 
Replace null! initializer workarounds with the required keyword on
ExecutorType, Message, MessageType, and WorkflowContext properties so
the compiler enforces initialization at the call site.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 7: Add non-generic ExecuteWorkflowPipelineAsync overload
866f6ab 
Add a ValueTask (void) overload of ExecuteWorkflowPipelineAsync to
BehaviorPipeline so callers that don't need a return value can avoid
the dummy (ct) => new ValueTask<int>(0) continuation pattern.
Update both call sites in InProcessRunner to use ValueTask.CompletedTask.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 8: Add tests for Ending stage and RunId consistency
288e19b 
Add WorkflowBehavior_BehaviorExecutesAtEndAsync to verify that
WorkflowStage.Ending fires during run disposal, and
Workflow_WithBehaviors_RunIdIsConsistentAcrossContextsAsync to verify
that workflow, executor, and Run all share the same RunId.

Also fix net472 build issues introduced by Bugs 6 and 7:
- Add InjectRequiredMemberOnLegacy/InjectCompilerFeatureRequiredOnLegacy
  polyfills to the csproj for the required keyword (Bug 6)
- Replace ValueTask.CompletedTask (net5+ only) with default (Bug 7)
- Add NullWorkflowContext stub and WorkflowContext initializer to
  BehaviorPipelineTests to satisfy the now-required property (Bug 6)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 9: Use Throw.IfNull in BehaviorExecutionException
a911137 
Replace manual if-null-throw pattern in the 3-parameter constructor
with Throw.IfNull from Microsoft.Shared.Diagnostics, consistent with
the rest of the project.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Rename WorkflowBehaviorIntegrationTests to WorkflowBehaviorEndToEndTests
651f4a8 
The tests exercise an in-process pipeline with no external dependencies,
making "end-to-end" a more accurate description than "integration".

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Add comment explaining CancellationToken.None for end behaviors
8474c89 
Document the known limitation that WorkflowStage.Ending behaviors
receive CancellationToken.None, explaining why and what a fix would
require.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 11: Use Throw.IfNull in WorkflowBehaviorOptions
31a3031 
Replace the ?? throw new ArgumentNullException(...) pattern with
Throw.IfNull() from Microsoft.Shared.Diagnostics, consistent with the
rest of the project.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 12: Guard against double-registration in SetRunEndingCallback
9e88049 
Throw InvalidOperationException if a run-ending callback is registered
more than once, preventing silent overwrites of the first registration.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 13: Add combined workflow + executor behavior end-to-end test
0497bc7 
Add Workflow_WithBothBehaviorTypes_ExecutesInCorrectOrderAsync to verify
that workflow and executor behaviors interleave correctly:
Starting → PreExecution → executor → Ending.

Also fix spurious XML doc warning in WorkflowBehaviorOptions introduced
by Bug 11 (use fully-qualified System.ArgumentNullException in cref).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 14: Document continuation call semantics in IExecutorBehavior
dac3985 
Clarify that continuation should be called exactly once, and explain
what happens if it is called multiple times or not at all.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 15: Use Throw.IfNullOrEmpty for behaviorType and stage
046a794 
Replace Throw.IfNull with Throw.IfNullOrEmpty so that empty strings
produce a clear ArgumentException rather than silently creating a
confusing error message like "Error executing behavior '' at stage ''".

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 16: Test that finalHandler exception is not wrapped without behav…
9018cbf 
…iors

Add ExecutorPipeline_WithNoBehaviors_FinalHandlerExceptionNotWrappedAsync
to document and enforce that when no behaviors are registered, exceptions
from the core finalHandler propagate as-is, without being wrapped in
BehaviorExecutionException.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 17: Validate BehaviorType and Stage in exception test
e26411e 
Enhance Workflow_BehaviorThrowsException_EmitsErrorEventAsync to also
assert that BehaviorExecutionException.BehaviorType and Stage are
populated correctly, catching regressions in error context propagation.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 18: Clarify TResult contract and continuation semantics in IWorkf…
42c48e9 
…lowBehavior.HandleAsync

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@claude
Bug 19: Distinguish ExecutorId from ExecutorType in ExecutorBehaviorC…
8a61c4c 
…ontext doc

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation .NET workflows Related to Workflows in agent-framework

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

.NET Workflows: Feature Request: Pipeline Behavior Extension Points for Cross-Cutting Concerns

2 participants

@gijswalraven @markwallace-microsoft

Comments