bool ValidateContextSerialization { get; set; }
Source
Gets or sets whether the adapter validates flow context serialization before evaluating durable decisions.
DurableTask
FlowContextSerializationValidator
SourceValidates that a flow context can survive a serializer round trip before durable execution starts.
Validate
FlowContextSerializationResult Validate<TContext>(TContext context)
Source
Validates a context by serializing and deserializing it.
Type Parameters
TContextContext type.
Parameters
contextContext instance.
Returns
A success or failure result.
FlowContextSerializationResult
SourceResult produced by FlowContextSerializationValidator.
Parameters
SucceededWhether validation succeeded.MessageValidation message.ExceptionException captured from the serializer, if any.
Success
FlowContextSerializationResult Success()
Source
Creates a successful validation result.
Failure
FlowContextSerializationResult Failure(string message, Exception exception)
Source
Creates a failed validation result.
SystemTextJsonFlowContextSerializer
SourceSystem.Text.Json implementation of IFlowContextSerializer.
IDurableTaskFlowRunner<TContext>
SourceEvaluates AppSurface Flow nodes as Durable Task orchestration decisions.
Type Parameters
TContextSerializable context type carried by the flow.
Remarks
This service is the AppSurface mapping layer between durable orchestration code and Flow definitions. Hosts still own Durable Task worker/client setup, instance scheduling, persisted state, timers, replay, and external event delivery.
StartAsync
ValueTask<DurableTaskFlowDecision<TContext>> StartAsync(string flowId, string version, string instanceId, TContext context, CancellationToken cancellationToken = default)
Source
Starts a durable flow by evaluating the definition's start node.
Parameters
flowIdFlow id to start.versionFlow version to start.instanceIdDurable Task instance id associated with the flow.contextInitial flow context.cancellationTokenToken that cancels node execution.
Returns
A durable decision. Missing definitions, missing nodes, non-durable contexts, invalid next targets, and unsupported outcomes are returned as DurableTaskFlowDecisionKind.Fault decisions.
Exceptions
ArgumentExceptionThrown whenflowId,version, orinstanceIdis empty.ArgumentNullExceptionThrown whencontextis null.
Remarks
Caller code should inspect the returned DurableTaskFlowDecision{TContext}.Kind instead of relying on exceptions for process-level failures. Exceptions are reserved for invalid caller arguments and cancellation.
RunNodeAsync
ValueTask<DurableTaskFlowDecision<TContext>> RunNodeAsync(DurableTaskFlowStep<TContext> step, CancellationToken cancellationToken = default)
Source
Evaluates one node and maps its outcome to a durable orchestration decision.
Parameters
stepCurrent durable flow step.cancellationTokenToken that cancels node execution.
Returns
A durable decision. Missing definitions or nodes, serialization failures, invalid next targets, node faults, and unsupported outcomes are returned as DurableTaskFlowDecisionKind.Fault decisions.
Exceptions
ArgumentNullExceptionThrown whenstepis null.
Remarks
When AppSurfaceFlowDurableTaskOptions.ValidateContextSerialization is enabled, this method validates the input context before executing the node and validates returned contexts before scheduling, waiting, timing out, or completing. Disabling that option skips the serialization round-trip check. Callers must branch on the returned decision kind.
ResumeAsync
ValueTask<DurableTaskFlowDecision<TContext>> ResumeAsync(DurableTaskFlowStep<TContext> step, string expectedEventName, CancellationToken cancellationToken = default)
Source
Resumes a waiting node if the delivered event matches the event the orchestration was waiting for.
Parameters
stepCurrent durable flow step carrying a resume event.expectedEventNameEvent name the orchestration is waiting for.cancellationTokenToken that cancels resumed node execution.
Returns
A durable decision. Missing resume events return a fault decision. Mismatched events return DurableTaskFlowDecisionKind.IgnoreLateEvent when AppSurfaceFlowDurableTaskOptions.IgnoreLateResumeEvents is enabled, otherwise they return a fault decision.
Exceptions
ArgumentExceptionThrown whenexpectedEventNameis empty.ArgumentNullExceptionThrown whenstepis null.
Remarks
The expectedEventName comparison uses StringComparison.Ordinal, so matching is case-sensitive. Deliver only the exact event the orchestration is currently waiting for, or normalize event names before calling this method. Mismatches are represented as late-event or fault decisions, so callers should inspect the returned kind before scheduling more work.
DurableTaskFlowRunner<TContext>
SourceDefault implementation of IDurableTaskFlowRunner{TContext}.
Type Parameters
TContextSerializable context type carried by the flow.
AppSurfaceFlowDurableTaskOptions
SourceConfigures the Durable Task adapter boundary for AppSurface Flow.
Remarks
The default configuration is intentionally conservative: resume events are denied until a host registers an IFlowResumeAuthorizer implementation, and context serialization is validated before durable execution.
ValidateContextSerialization
IgnoreLateResumeEvents
bool IgnoreLateResumeEvents { get; set; }
Source
Gets or sets whether a host should ignore late or mismatched resume events instead of faulting the durable flow.
Remarks
The default value is true because durable orchestrations can receive delayed external events after a timer has won the race. Ignoring the stale signal is usually safer than failing a completed timeout path.
NodeRetryPolicy
FlowRetryPolicy? NodeRetryPolicy { get; set; }
Source
Gets or sets the retry policy a Durable Task host should apply when scheduling flow node work.
Remarks
The default value is null, which means the adapter does not request retries and the host's normal scheduling behavior applies. Set this when every node in a flow should share one durable retry policy.
IDurableTaskFlowClient<TContext>
SourceAuthorizes external resume requests before a host raises a Durable Task external event.
Type Parameters
TContextSerializable context type carried by the flow.
AuthorizeResumeAsync
ValueTask<FlowResumeAuthorizationResult> AuthorizeResumeAsync(FlowResumeAuthorizationRequest request, CancellationToken cancellationToken = default)
Source
Authorizes a resume event.
Parameters
requestResume authorization request.cancellationTokenCancellation token.
Returns
The authorization result.
DurableTaskFlowClient<TContext>
SourceDefault implementation of IDurableTaskFlowClient{TContext}.
Type Parameters
TContextSerializable context type carried by the flow.
DurableTaskFlowStep<TContext>
SourceInput used by the Durable Task adapter to evaluate one flow node.
Type Parameters
TContextSerializable context type carried by the flow.
FlowId
string FlowId { get; }
Source
Gets the flow id.
Version
string Version { get; }
Source
Gets the flow version.
InstanceId
string InstanceId { get; }
Source
Gets the durable instance id.
NodeId
string NodeId { get; }
Source
Gets the current node id.
Context
TContext Context { get; }
Source
Gets the current flow context.
ResumeEvent
FlowResumeEvent? ResumeEvent { get; }
Source
Gets the optional external event or timeout used to resume the node.
DenyAllFlowResumeAuthorizer
SourceDefault resume authorizer that denies every external resume event.
Remarks
Hosts must replace this service with an application-specific implementation before exposing resume endpoints or queue consumers. Durable instance ids and event names are not sufficient authorization by themselves.
DurableTaskFlowDecision<TContext>
SourceDurable Task adapter decision created from one flow node evaluation.
Type Parameters
TContextSerializable context type carried by the flow.
ScheduleNode
DurableTaskFlowDecision<TContext> ScheduleNode(string nodeId, TContext context, FlowRetryPolicy? retryPolicy = null)
Source
Creates a schedule-node decision.
Parameters
nodeIdNode id to schedule next.contextContext to pass to the scheduled node.retryPolicyOptional retry policy requested for the scheduled node work.
Exceptions
ArgumentExceptionThrown whennodeIdis null, empty, or white space.ArgumentNullExceptionThrown whencontextis null.
Remarks
Schedule decisions carry the next node id, the context to persist, and optional retry metadata. They do not carry event, timeout, fault, or diagnostic details. Inspect Kind before reading kind-specific properties.
WaitForExternalEvent
DurableTaskFlowDecision<TContext> WaitForExternalEvent(string nodeId, string eventName, TContext context, FlowTimeout? timeout)
Source
Creates a wait-for-external-event decision.
Parameters
nodeIdNode id where the durable flow is waiting.eventNameExternal event name the orchestration should wait for.contextContext to persist while waiting.timeoutOptional timeout associated with the external event wait.
Exceptions
ArgumentExceptionThrown whennodeIdoreventNameis null, empty, or white space.ArgumentNullExceptionThrown whencontextis null.
Remarks
Wait decisions pause durable execution until the named event arrives or the optional timeout expires. The timeout may be null for waits without a durable timer. Inspect Kind before reading wait-specific properties.
Complete
DurableTaskFlowDecision<TContext> Complete(string nodeId, TContext context)
Source
Creates a complete decision.
Parameters
nodeIdNode id that completed the durable flow.contextFinal flow context.
Exceptions
ArgumentExceptionThrown whennodeIdis null, empty, or white space.ArgumentNullExceptionThrown whencontextis null.
Remarks
Complete decisions are terminal and do not carry wait, timeout, retry, fault, or diagnostic details. Inspect Kind before reading kind-specific properties.
TimedOut
DurableTaskFlowDecision<TContext> TimedOut(string nodeId, string eventName, TContext context)
Source
Creates a timeout decision.
Parameters
nodeIdNode id that handled the timeout branch.eventNameEvent whose wait timed out.contextContext after timeout handling.
Exceptions
ArgumentExceptionThrown whennodeIdoreventNameis null, empty, or white space.ArgumentNullExceptionThrown whencontextis null.
Remarks
Timed-out decisions mean timeout handling has already run; they are distinct from wait decisions that carry a future timeout. Inspect Kind before reading timeout-specific properties.
Faulted
DurableTaskFlowDecision<TContext> Faulted(string nodeId, FlowFault fault, string? diagnostic = null)
Source
Creates a fault decision.
Parameters
nodeIdNode id associated with the fault.faultFlow fault details.diagnosticOptional human-readable diagnostic detail.
Exceptions
ArgumentExceptionThrown whennodeIdis null, empty, or white space.ArgumentNullExceptionThrown whenfaultis null.
Remarks
Fault decisions do not carry a context. Use fault for stable machine-readable failure details and diagnostic only for explanatory text. Inspect Kind before reading fault-specific properties.
IgnoreLateEvent
DurableTaskFlowDecision<TContext> IgnoreLateEvent(string nodeId, string eventName, string diagnostic)
Source
Creates an ignored-late-event decision.
Parameters
nodeIdNode id that received the late or mismatched event.eventNameLate or mismatched event name.diagnosticHuman-readable reason the event was ignored.
Exceptions
ArgumentExceptionThrown whennodeId,eventName, ordiagnosticis null, empty, or white space.
Remarks
Ignored-late-event decisions are non-scheduling decisions used when stale external events should not fault the durable instance. They do not carry context, timeout, retry, or fault details. Inspect Kind before reading late-event-specific properties.
Kind
DurableTaskFlowDecisionKind Kind { get; }
Source
Gets the decision kind.
Context
TContext? Context { get; }
Source
Gets the context carried by the decision, when present.
NodeId
string? NodeId { get; }
Source
Gets the node id associated with the decision.
EventName
string? EventName { get; }
Source
Gets the external event associated with the decision.
Timeout
FlowTimeout? Timeout { get; }
Source
Gets the optional timeout for a wait decision.
RetryPolicy
FlowRetryPolicy? RetryPolicy { get; }
Source
Gets the retry policy requested for scheduled node work, when present.
Fault
FlowFault? Fault { get; }
Source
Gets fault details for a fault decision.
Diagnostic
string? Diagnostic { get; }
Source
Gets a human-readable diagnostic message.
DurableTaskFlowDecisionKind
SourceIdentifies the durable orchestration decision produced from a flow node outcome.
Remarks
The numeric values are part of the Durable Task adapter compatibility contract and may appear in durable persistence, telemetry, or wire payloads. Do not reorder, renumber, remove, or reuse values. Add new decisions only at the end with explicit numeric values and migration/versioning considerations.
IFlowContextSerializer
SourceSerializes flow contexts for Durable Task persistence validation.
Serialize
string Serialize<TContext>(TContext context)
Source
Serializes a context to a string payload.
Type Parameters
TContextContext type.
Parameters
contextContext instance.
Returns
Serialized payload.
Deserialize
TContext Deserialize<TContext>(string payload)
Source
Deserializes a context from a string payload.
Type Parameters
TContextContext type.
Parameters
payloadSerialized payload.
Returns
Deserialized context.
FlowRetryPolicy
SourceDescribes retry settings that a Durable Task host can apply when scheduling flow node work.
Remarks
The adapter only carries retry intent. Durable Task worker/client code remains responsible for translating this value into the provider-specific retry options used by the host.
MaxAttempts
int MaxAttempts { get; }
Source
Gets the maximum number of attempts, including the first attempt.
FirstRetryInterval
TimeSpan FirstRetryInterval { get; }
Source
Gets the delay before the first retry.
BackoffCoefficient
double BackoffCoefficient { get; }
Source
Gets the backoff coefficient applied by the durable host.
AppSurfaceFlowDurableTaskModule
SourceRegisters the AppSurface Flow Durable Task adapter boundary.
Remarks
The module is passive. It declares the core Flow dependency, registers durable adapter services, and leaves Durable Task worker/client hosting to the application. This package intentionally does not register storage providers, background workers, endpoints, authentication handlers, or Semantic Kernel services.
IFlowResumeAuthorizer
SourceAuthorizes external resume events before they are delivered to Durable Task.
AuthorizeAsync
ValueTask<FlowResumeAuthorizationResult> AuthorizeAsync(FlowResumeAuthorizationRequest request, CancellationToken cancellationToken = default)
Source
Authorizes a resume request.
Parameters
requestAuthorization request.cancellationTokenCancellation token.
Returns
An authorization result.
FlowResumeAuthorizationRequest
SourceResume-event authorization request.
FlowId
string FlowId { get; }
Source
Gets the flow id.
Version
string Version { get; }
Source
Gets the flow version.
InstanceId
string InstanceId { get; }
Source
Gets the durable instance id.
NodeId
string NodeId { get; }
Source
Gets the waiting node id.
EventName
string EventName { get; }
Source
Gets the external event name.
Caller
string Caller { get; }
Source
Gets the application-defined caller identifier.
Metadata
IReadOnlyDictionary<string, string> Metadata { get; }
Source
Gets application-defined authorization metadata.
FlowResumeAuthorizationResult
SourceAuthorization result for a resume event.
Allow
FlowResumeAuthorizationResult Allow(string code = "flow.resume-allowed", string message = "Resume event allowed.")
Source
Creates an allow result.
Deny
FlowResumeAuthorizationResult Deny(string code, string message)
Source
Creates a deny result.
Allowed
bool Allowed { get; }
Source
Gets a value indicating whether the resume event is allowed.
Code
string Code { get; }
Source
Gets the stable machine-readable result code.
Message
string Message { get; }
Source
Gets the human-readable diagnostic message.