AppSurface Search
Section API Reference
API Reference Language: C# Component: Flow Audience: developer

DurableTask

Type

AppSurfaceFlowDurableTaskModule

Source

Registers 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.

Type

IDurableTaskFlowRunner<TContext>

Source

Evaluates AppSurface Flow nodes as Durable Task orchestration decisions.

Type parameters

  • TContext
    Serializable context type carried by the flow.

Remarks

This service is the AppSurface mapping layer between durable orchestration code and the core host-neutral IFlowTransitionEvaluator{TContext} . Hosts still own Durable Task worker/client setup, instance and activity scheduling, registered work/result codecs, persisted state, timers, replay, and external event delivery.

Method

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

  • flowId
    Flow id to start.
  • version
    Flow version to start.
  • instanceId
    Durable Task instance id associated with the flow.
  • context
    Initial flow context.
  • cancellationToken
    Token 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. Typed Activity outcomes return DurableTaskFlowDecisionKind.ScheduleActivity .

Exceptions

  • ArgumentException
    Thrown when flowId , version , or instanceId is empty.
  • ArgumentNullException
    Thrown when context is 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.

Method

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

  • step
    Current durable flow step.
  • cancellationToken
    Token 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

  • ArgumentNullException
    Thrown when step is null.
  • ArgumentException
    Thrown when step carries both a resume event and an activity result. A node evaluation can resume from only one external input at a time.

Remarks

When AppSurfaceFlowDurableTaskOptions.ValidateContextSerialization is enabled, this method validates the input context before executing the node and validates returned contexts before scheduling a node or activity, waiting, timing out, or completing. Disabling that option skips the context round-trip check. Activity work/result codec registration remains a host responsibility. Callers must branch on the returned decision kind.

Method

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

  • step
    Current durable flow step carrying a resume event.
  • expectedEventName
    Event name the orchestration is waiting for.
  • cancellationToken
    Token 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

  • ArgumentException
    Thrown when expectedEventName is empty.
  • ArgumentNullException
    Thrown when step is 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.

Type

DurableTaskFlowRunner<TContext>

Source

Default implementation of IDurableTaskFlowRunner{TContext} .

Type parameters

  • TContext
    Serializable context type carried by the flow.
Type

SystemTextJsonFlowContextSerializer

Source

System.Text.Json implementation of IFlowContextSerializer .

Type

DenyAllFlowResumeAuthorizer

Source

Default 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.

Type

DurableTaskFlowStep<TContext>

Source

Input used by the Durable Task adapter to evaluate one flow node.

Type parameters

  • TContext
    Serializable context type carried by the flow.
Property

FlowId

string FlowId { get; } Source

Gets the flow id.

Property

Version

string Version { get; } Source

Gets the flow version.

Property

InstanceId

string InstanceId { get; } Source

Gets the durable instance id.

Property

NodeId

string NodeId { get; } Source

Gets the current node id.

Property

Context

TContext Context { get; } Source

Gets the current flow context.

Property

ResumeEvent

FlowResumeEvent? ResumeEvent { get; } Source

Gets the optional external event or timeout used to resume the node.

Property

ActivityResult

FlowActivityWorkResult? ActivityResult { get; init; } Source

Gets an optional typed activity result used to resume this node.

Remarks

Set this property when replaying a prior DurableTaskFlowDecisionKind.ScheduleActivity decision. Do not also supply ResumeEvent ; the shared evaluator rejects ambiguous resume inputs.

Type

IFlowResumeAuthorizer

Source

Authorizes external resume events before they are delivered to Durable Task.

Method

AuthorizeAsync

ValueTask<FlowResumeAuthorizationResult> AuthorizeAsync(FlowResumeAuthorizationRequest request, CancellationToken cancellationToken = default)
Source

Authorizes a resume request.

Parameters

  • request
    Authorization request.
  • cancellationToken
    Cancellation token.

Returns

An authorization result.

Type

FlowResumeAuthorizationRequest

Source

Resume-event authorization request.

Property

FlowId

string FlowId { get; } Source

Gets the flow id.

Property

Version

string Version { get; } Source

Gets the flow version.

Property

InstanceId

string InstanceId { get; } Source

Gets the durable instance id.

Property

NodeId

string NodeId { get; } Source

Gets the waiting node id.

Property

EventName

string EventName { get; } Source

Gets the external event name.

Property

Caller

string Caller { get; } Source

Gets the application-defined caller identifier.

Property

Metadata

IReadOnlyDictionary<string, string> Metadata { get; } Source

Gets application-defined authorization metadata.

Type

FlowResumeAuthorizationResult

Source

Authorization result for a resume event.

Method

Allow

FlowResumeAuthorizationResult Allow(string code = "flow.resume-allowed", string message = "Resume event allowed.")
Source

Creates an allow result.

Method

Deny

FlowResumeAuthorizationResult Deny(string code, string message)
Source

Creates a deny result.

Property

Allowed

bool Allowed { get; } Source

Gets a value indicating whether the resume event is allowed.

Property

Code

string Code { get; } Source

Gets the stable machine-readable result code.

Property

Message

string Message { get; } Source

Gets the human-readable diagnostic message.

Type

IDurableTaskFlowClient<TContext>

Source

Authorizes external resume requests before a host raises a Durable Task external event.

Type parameters

  • TContext
    Serializable context type carried by the flow.
Method

AuthorizeResumeAsync

ValueTask<FlowResumeAuthorizationResult> AuthorizeResumeAsync(FlowResumeAuthorizationRequest request, CancellationToken cancellationToken = default)
Source

Authorizes a resume event.

Parameters

  • request
    Resume authorization request.
  • cancellationToken
    Cancellation token.

Returns

The authorization result.

Type

DurableTaskFlowClient<TContext>

Source

Default implementation of IDurableTaskFlowClient{TContext} .

Type parameters

  • TContext
    Serializable context type carried by the flow.
Type

FlowContextSerializationValidator

Source

Validates that a flow context can survive a serializer round trip before durable execution starts.

Method

Validate

FlowContextSerializationResult Validate<TContext>(TContext context)
Source

Validates a context by serializing and deserializing it.

Type parameters

  • TContext
    Context type.

Parameters

  • context
    Context instance.

Returns

A success or failure result.

Type

FlowContextSerializationResult

Source

Result produced by FlowContextSerializationValidator .

Parameters

  • Succeeded
    Whether validation succeeded.
  • Message
    Validation message.
  • Exception
    Exception captured from the serializer, if any.
Method

Success

FlowContextSerializationResult Success()
Source

Creates a successful validation result.

Method

Failure

FlowContextSerializationResult Failure(string message, Exception exception)
Source

Creates a failed validation result.

Type

IFlowContextSerializer

Source

Serializes flow contexts for Durable Task persistence validation.

Method

Serialize

string Serialize<TContext>(TContext context)
Source

Serializes a context to a string payload.

Type parameters

  • TContext
    Context type.

Parameters

  • context
    Context instance.

Returns

Serialized payload.

Method

Deserialize

TContext Deserialize<TContext>(string payload)
Source

Deserializes a context from a string payload.

Type parameters

  • TContext
    Context type.

Parameters

  • payload
    Serialized payload.

Returns

Deserialized context.

Type

FlowRetryPolicy

Source

Describes 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.

Property

MaxAttempts

int MaxAttempts { get; } Source

Gets the maximum number of attempts, including the first attempt.

Property

FirstRetryInterval

TimeSpan FirstRetryInterval { get; } Source

Gets the delay before the first retry.

Property

BackoffCoefficient

double BackoffCoefficient { get; } Source

Gets the backoff coefficient applied by the durable host.

Type

AppSurfaceFlowDurableTaskOptions

Source

Configures 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.

Property

ValidateContextSerialization

bool ValidateContextSerialization { get; set; } Source

Gets or sets whether the adapter validates flow context serialization before evaluating durable decisions.

Property

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.

Property

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.

Type

DurableTaskFlowDecision<TContext>

Source

Durable Task adapter decision created from one flow node evaluation.

Type parameters

  • TContext
    Serializable context type carried by the flow.
Method

ScheduleNode

DurableTaskFlowDecision<TContext> ScheduleNode(string nodeId, TContext context, FlowRetryPolicy? retryPolicy = null)
Source

Creates a schedule-node decision.

Parameters

  • nodeId
    Node id to schedule next.
  • context
    Context to pass to the scheduled node.
  • retryPolicy
    Optional retry policy requested for the scheduled node work.

Exceptions

  • ArgumentException
    Thrown when nodeId is null, empty, or white space.
  • ArgumentNullException
    Thrown when context is 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.

Method

WaitForExternalEvent

2 overloads
DurableTaskFlowDecision<TContext> WaitForExternalEvent(string nodeId, string eventName, TContext context, FlowTimeout? timeout)
Source

Creates a wait-for-external-event decision.

Parameters

  • nodeId
    Node id where the durable flow is waiting.
  • eventName
    External event name the orchestration should wait for.
  • context
    Context to persist while waiting.
  • timeout
    Optional timeout associated with the external event wait.

Exceptions

  • ArgumentException
    Thrown when nodeId or eventName is null, empty, or white space.
  • ArgumentNullException
    Thrown when context is 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.

DurableTaskFlowDecision<TContext> WaitForExternalEvent(string nodeId, IFlowEventCallsite eventCallsite, TContext context, FlowTimeout? timeout)
Source

Creates a wait-for-external-event decision with an exact typed payload contract.

Parameters

  • nodeId
    Node id where the durable flow is waiting.
  • eventCallsite
    Exact event name and durable payload contract.
  • context
    Context to persist while waiting.
  • timeout
    Optional timeout associated with the external event wait.

Returns

A typed external-event wait decision.

Exceptions

  • ArgumentException
    Thrown when nodeId is empty.
  • ArgumentException
    Thrown when the event name, contract name, or contract version exposed by eventCallsite is empty.
  • ArgumentNullException
    Thrown when eventCallsite , its payload type, or context is null.

Remarks

This overload preserves the callsite metadata emitted by the shared Flow transition evaluator. The host remains responsible for authorization, persisted wait ownership, payload decoding, and duplicate delivery handling.

Method

Complete

DurableTaskFlowDecision<TContext> Complete(string nodeId, TContext context)
Source

Creates a complete decision.

Parameters

  • nodeId
    Node id that completed the durable flow.
  • context
    Final flow context.

Exceptions

  • ArgumentException
    Thrown when nodeId is null, empty, or white space.
  • ArgumentNullException
    Thrown when context is null.

Remarks

Complete decisions are terminal and do not carry wait, timeout, retry, fault, or diagnostic details. Inspect Kind before reading kind-specific properties.

Method

TimedOut

DurableTaskFlowDecision<TContext> TimedOut(string nodeId, string eventName, TContext context)
Source

Creates a timeout decision.

Parameters

  • nodeId
    Node id that handled the timeout branch.
  • eventName
    Event whose wait timed out.
  • context
    Context after timeout handling.

Exceptions

  • ArgumentException
    Thrown when nodeId or eventName is null, empty, or white space.
  • ArgumentNullException
    Thrown when context is 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.

Method

Faulted

DurableTaskFlowDecision<TContext> Faulted(string nodeId, FlowFault fault, string? diagnostic = null)
Source

Creates a fault decision.

Parameters

  • nodeId
    Node id associated with the fault.
  • fault
    Flow fault details.
  • diagnostic
    Optional human-readable diagnostic detail.

Exceptions

  • ArgumentException
    Thrown when nodeId is null, empty, or white space.
  • ArgumentNullException
    Thrown when fault is 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.

Method

IgnoreLateEvent

DurableTaskFlowDecision<TContext> IgnoreLateEvent(string nodeId, string eventName, string diagnostic)
Source

Creates an ignored-late-event decision.

Parameters

  • nodeId
    Node id that received the late or mismatched event.
  • eventName
    Late or mismatched event name.
  • diagnostic
    Human-readable reason the event was ignored.

Exceptions

  • ArgumentException
    Thrown when nodeId , eventName , or diagnostic is 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.

Method

ScheduleActivity

DurableTaskFlowDecision<TContext> ScheduleActivity(string nodeId, IFlowActivityRequest<TContext> activity)
Source

Creates a decision that asks the Durable Task host to schedule one typed activity.

Parameters

  • nodeId
    Node that requested the activity and will receive its result.
  • activity
    Typed activity metadata, work, and persisted Flow context.

Returns

An activity scheduling decision.

Exceptions

  • ArgumentException
    Thrown when nodeId or activity metadata is empty, a contract version is invalid, or the work value does not implement its declared type.
  • ArgumentNullException
    Thrown when activity or one of its required values is null.

Remarks

The adapter does not execute the activity. The host maps the declared CLR types and contract versions to its registered codecs/executor, persists the decision before dispatch, and supplies a FlowActivityWorkResult on the next DurableTaskFlowStep{TContext} evaluation.

Property

Kind

DurableTaskFlowDecisionKind Kind { get; } Source

Gets the decision kind.

Property

Context

TContext? Context { get; } Source

Gets the context carried by the decision, when present.

Property

NodeId

string? NodeId { get; } Source

Gets the node id associated with the decision.

Property

EventName

string? EventName { get; } Source

Gets the external event associated with the decision.

Property

EventCallsite

IFlowEventCallsite? EventCallsite { get; } Source

Gets the exact typed external-event contract for a wait decision, or null for a no-payload string wait.

Remarks

The Durable Task host uses this metadata to select an allowlisted payload codec and validate the delivered event against its persisted wait registration before resuming the Flow node. The decision does not authorize or decode the event itself.

Property

Timeout

FlowTimeout? Timeout { get; } Source

Gets the optional timeout for a wait decision.

Property

RetryPolicy

FlowRetryPolicy? RetryPolicy { get; } Source

Gets the retry policy requested for scheduled node work, when present.

Property

Fault

FlowFault? Fault { get; } Source

Gets fault details for a fault decision.

Property

Diagnostic

string? Diagnostic { get; } Source

Gets a human-readable diagnostic message.

Property

Activity

IFlowActivityRequest<TContext>? Activity { get; } Source

Gets the typed activity request for a DurableTaskFlowDecisionKind.ScheduleActivity decision.

Enum

DurableTaskFlowDecisionKind

Source

Identifies 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.