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

Durable

Namespaces

Type

DurableScopeId

Source

Identifies the trusted application scope that owns a durable aggregate.

Remarks

Scope identifiers must come from an application-authorized context. A caller-supplied route, form, event, or instance identifier is not sufficient authorization to construct a durable operation.

Property

Value

string Value { get; } Source

Gets the opaque scope value.

Type

DurableWorkId

Source

Identifies one accepted durable work aggregate independently of its retries and leases.

Method

New

DurableWorkId New()
Source

Creates a cryptographically random identifier suitable for a new work aggregate.

Returns

A new durable work identifier.

Property

Value

string Value { get; } Source

Gets the opaque identifier value.

Type

DurableCommandId

Source

Identifies one idempotent durable command.

Method

New

DurableCommandId New()
Source

Creates a cryptographically random identifier suitable for a new command.

Returns

A new durable command identifier.

Property

Value

string Value { get; } Source

Gets the opaque identifier value.

Type

DurableIdentifier

Source

Shared validation for opaque durable identifiers.

Method

Require

string Require(string value, string parameterName, int maximumLength)
Source

Validates a required privacy-safe identifier without changing its ordinal value.

Method

RequireText

string RequireText(string value, string parameterName, int maximumLength)
Source

Validates bounded non-control text without claiming it is an opaque identifier.

Method

RequireSafeLabel

string RequireSafeLabel(string value, string parameterName, int maximumLength)
Source

Validates a bounded human label while rejecting common secret, URL, email, and raw-payload shapes.

Type

DurableCommandFingerprint

Source

Identifies the versioned canonical semantic content of a command-bearing durable mutation.

Method

Compare

DurableCommandFingerprintMatch Compare(DurableCommandFingerprint persisted)
Source

Compares a persisted fingerprint without reinterpreting an unknown schema.

Parameters

  • persisted
    Previously persisted fingerprint to compare.

Returns

DurableCommandFingerprintMatch.Exact for identical schemas and digests, DurableCommandFingerprintMatch.Conflict for differing digests under the same schema, or DurableCommandFingerprintMatch.UnsupportedSchema for differing schemas.

Exceptions

  • ArgumentNullException
    Thrown when persisted is null.
Property

SchemaId

string SchemaId { get; } Source

Gets the versioned canonicalization schema.

Property

Sha256

string Sha256 { get; } Source

Gets the lowercase SHA-256 digest of canonical semantic fields.

Type

DurableCommandFingerprints

Source

Creates canonical versioned fingerprints for command-bearing mutations.

Method

Create

DurableCommandFingerprint Create(string schemaId, params object?[] values)
Source

Hashes an ordered sequence of supported semantic values under one schema identity.

Parameters

  • schemaId
    Versioned canonical encoding schema.
  • values
    Values in their contract-defined order; null values receive an explicit marker.

Returns

A fingerprint containing the schema identity and canonical SHA-256 digest.

Exceptions

  • ArgumentException
    Thrown when schemaId is invalid.
  • InvalidOperationException
    Thrown when a value type has no canonical encoding.

Remarks

Ordering is significant. Supported values use the closed canonical encodings below rather than culture-sensitive text conversion. Before either independent compatibility boundary—the first supported publication or any persisted deployment—an unpublished preview schema may receive a one-time compatibility correction. After either boundary, any change to value ordering, null markers, supported types, or their byte encodings must use a new schemaId so persisted fingerprints are never compared under incompatible semantics.

Type

DurableFlowEvaluationInput

Source

Supplies persisted input for exactly one registered Flow node evaluation.

Property

NodeId

string NodeId { get; } Source

Gets the node to evaluate.

Property

Context

DurableEncodedPayload Context { get; } Source

Gets the persisted Flow context.

Property

ResumeEventName

string? ResumeEventName { get; } Source

Gets the external event name, if any.

Property

ResumeEventPayload

DurableEncodedPayload? ResumeEventPayload { get; } Source

Gets the allowlisted external event payload, if any.

Property

IsTimeout

bool IsTimeout { get; } Source

Gets whether the event represents a durable wait timeout.

Property

ActivityCallsiteId

string? ActivityCallsiteId { get; } Source

Gets the activity callsite that produced a result, if any.

Property

ActivityResult

DurableEncodedPayload? ActivityResult { get; } Source

Gets the encoded activity result, if any.

Type

DurableFlowActivityCommand

Source

Describes the durable work command produced by one Flow activity transition.

Property

CallsiteId

string CallsiteId { get; } Source

Gets the stable Flow callsite.

Property

ResultContractVersion

int ResultContractVersion { get; } Source

Gets the expected Flow result contract version.

Property

WorkName

string WorkName { get; } Source

Gets the registered durable work name.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the registered durable work version.

Property

ProviderSafety

DurableProviderSafety ProviderSafety { get; } Source

Gets the provider ambiguity policy.

Property

Work

DurableEncodedPayload Work { get; } Source

Gets the encoded activity work.

Property

ResultExpectation

DurableActivityResultExpectation? ResultExpectation { get; } Source

Gets the exact registered result identity persisted with a new activity wait.

Type

DurableActivityResultExpectation

Source

Captures the exact immutable result identity expected by one persisted Flow activity wait.

Type

DurableFlowEventContract

Source

Describes the exact payload contract accepted by one persisted external-event wait.

Property

PayloadRequired

bool PayloadRequired { get; } Source

Gets whether the external event must carry a payload.

Property

ContractName

string? ContractName { get; } Source

Gets the exact payload contract name, or null for a no-payload wait.

Property

ContractVersion

string? ContractVersion { get; } Source

Gets the exact payload contract version, or null for a no-payload wait.

Property

Classification

DurableDataClassification? Classification { get; } Source

Gets the exact approved classification, or null for a no-payload wait.

Property

RetentionPolicyId

string? RetentionPolicyId { get; } Source

Gets the exact retention policy identity, or null for a no-payload wait.

Type

DurableFlowEventBinding

Source

Binds one typed Flow event callsite to the exact durable payload codec allowed to cross that wait boundary.

Property

Callsite

IFlowEventCallsite Callsite { get; } Source

Gets the exact callsite instance nodes must return when waiting for this event.

Property

PayloadCodec

IDurablePayloadCodec PayloadCodec { get; } Source

Gets the exact durable payload codec instance accepted by this event boundary.

Type

DurableFlowEventBinding<TPayload>

Source

Typed binding between a Flow event callsite and its durable payload codec.

Type parameters

  • TPayload
    Allowlisted event payload type.
Type

DurableFlowEvaluationResult

Source

Carries the persistable result of exactly one Flow transition evaluation.

Property

Kind

FlowTransitionKind Kind { get; } Source

Gets the transition kind.

Property

NodeId

string NodeId { get; } Source

Gets the node that produced the transition.

Property

Context

DurableEncodedPayload? Context { get; } Source

Gets the encoded resulting context for non-fault transitions.

Property

NextNodeId

string? NextNodeId { get; } Source

Gets the declared next node.

Property

EventName

string? EventName { get; } Source

Gets the external wait or timeout event name.

Property

Timeout

FlowTimeout? Timeout { get; } Source

Gets the optional durable wait timeout.

Property

Fault

FlowFault? Fault { get; } Source

Gets a process-level Flow fault.

Property

Activity

DurableFlowActivityCommand? Activity { get; } Source

Gets an atomically accepted activity command.

Property

EventContract

DurableFlowEventContract? EventContract { get; } Source

Gets the exact external-event payload contract for a wait transition.

Type

DurableFlowActivityBinding<TContext>

Source

Binds a Flow activity callsite to one registered durable work contract.

Type parameters

  • TContext
    Flow context type.
Method

EncodeWork

DurableEncodedPayload EncodeWork(IFlowActivityRequest<TContext> activity)
Source

Encodes work from one evaluated activity request.

Method

DecodeResult

FlowActivityWorkResult DecodeResult(DurableEncodedPayload result)
Source

Decodes a persisted result into the typed Flow resume contract.

Property

CallsiteId

string CallsiteId { get; } Source

Gets the stable callsite identifier.

Property

WorkRegistration

DurableWorkRegistration WorkRegistration { get; } Source

Gets the registered durable work contract.

Property

WorkContractVersion

int WorkContractVersion { get; } Source

Gets the immutable activity work contract version.

Property

ResultContractVersion

int ResultContractVersion { get; } Source

Gets the immutable activity result contract version.

Property

ResultExpectation

DurableActivityResultExpectation ResultExpectation { get; } Source

Gets the exact registered payload identity expected of the activity result.

Type

DurableFlowActivityBinding<TContext, TWork, TResult>

Source

Typed binding between a Flow callsite and a durable work registration.

Type

DurableFlowRegistration

Source

Evaluates one registered Flow version through versioned durable codecs.

Method

EvaluateAsync

ValueTask<DurableFlowEvaluationResult> EvaluateAsync(DurableFlowEvaluationInput input, IDurablePayloadCodecRegistry payloadCodecs, CancellationToken cancellationToken = default)
Source

Evaluates and encodes exactly one transition.

Property

FlowId

string FlowId { get; } Source

Gets the stable Flow definition id.

Property

FlowVersion

string FlowVersion { get; } Source

Gets the immutable Flow definition version.

Property

ImplementationVersion

string ImplementationVersion { get; } Source

Gets the application-owned implementation manifest version for executable node semantics not represented by graph topology or contract metadata.

Property

StartNodeId

string StartNodeId { get; } Source

Gets the stable node id used for newly accepted instances.

Property

DefinitionFingerprint

string DefinitionFingerprint { get; } Source

Gets the deterministic lowercase SHA-256 definition-manifest fingerprint.

Property

AuthoringModel

string AuthoringModel { get; } Source

Gets the authoring model required to interpret persisted transition history.

Property

ContextCodec

IDurablePayloadCodec ContextCodec { get; } Source

Gets the Flow context codec.

Property

EventBindings

IReadOnlyList<DurableFlowEventBinding> EventBindings { get; } Source

Gets the exact typed external-event bindings declared by this Flow manifest.

Property

ActivityWorkRegistrations

IReadOnlyList<DurableWorkRegistration> ActivityWorkRegistrations { get; } Source

Gets the exact durable work registrations referenced by activity callsites.

Type

DurableFlowRegistration<TContext>

Source

Typed, reflection-free durable registration for one Flow definition version.

Method

ResolveCodec

IDurablePayloadCodec ResolveCodec(IDurablePayloadCodecRegistry payloadCodecs, IDurablePayloadCodec expected, Type payloadType, string contractName, string contractVersion, string boundary)
Source

Resolves an exact registry codec and verifies that it is the expected registration-owned source or an equivalent package-owned snapshot view. Retains captured guards when a custom registry selects the original raw source, so one evaluation uses one guarded codec instance for both decoding and encoding.

Method

EncodeContext

DurableEncodedPayload EncodeContext(IDurablePayloadCodec contextCodec, TContext context)
Source

Encodes context through the codec selected for the current evaluation.

Type

IDurableFlowRegistry

Source

Resolves immutable durable Flow registrations by id and version.

Method

GetRequired

DurableFlowRegistration GetRequired(string flowId, string flowVersion)
Source

Gets a required Flow registration.

Type

DurableFlowRegistry

Source

Immutable durable Flow registry built at host startup.

Type

DurableTraceDiagnostics

Source

Emits only the value-free diagnostics defined by the durable trace contract.

Type

DurableWorkRetryPolicy

Source

Versioned retry and lease snapshot stored when durable work is accepted.

Property

Default

DurableWorkRetryPolicy Default { get; } Source

Gets the safe default policy for ordinary durable work.

Property

MaximumAttempts

int MaximumAttempts { get; } Source

Gets the maximum number of execution attempts.

Property

MaximumElapsedTime

TimeSpan MaximumElapsedTime { get; } Source

Gets the maximum time from acceptance through retry exhaustion.

Property

InitialRetryDelay

TimeSpan InitialRetryDelay { get; } Source

Gets the first retry delay.

Property

MaximumRetryDelay

TimeSpan MaximumRetryDelay { get; } Source

Gets the retry delay cap.

Property

LeaseDuration

TimeSpan LeaseDuration { get; } Source

Gets the bounded claim lease duration.

Property

RenewalCadence

TimeSpan RenewalCadence { get; } Source

Gets the recommended lease renewal cadence.

Property

MaximumLeaseLifetime

TimeSpan MaximumLeaseLifetime { get; } Source

Gets the maximum lifetime of one claim generation.

Property

BackoffAlgorithm

string BackoffAlgorithm { get; } Source

Gets the versioned backoff algorithm identifier.

Type

DurableWorkRequest

Source

Describes one idempotent durable work submission.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the idempotent command identifier.

Property

IdempotencyKey

string IdempotencyKey { get; } Source

Gets the caller retry key, scoped to the owning scope.

Property

WorkName

string WorkName { get; } Source

Gets the registered work name.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the registered work contract version.

Property

Payload

DurableEncodedPayload Payload { get; } Source

Gets the immutable encoded work payload.

Property

ProviderSafety

DurableProviderSafety ProviderSafety { get; } Source

Gets the provider ambiguity policy snapshot.

Property

RetryPolicy

DurableWorkRetryPolicy RetryPolicy { get; } Source

Gets the retry and lease policy snapshot.

Property

DueAtUtc

DateTimeOffset? DueAtUtc { get; } Source

Gets the first UTC eligibility time, or immediate eligibility when absent.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed versioned fingerprint of mutation-affecting semantic fields.

Type

DurableWorkAcceptance

Source

Records the stable outcome of accepting durable work.

Property

WorkId

DurableWorkId WorkId { get; } Source

Gets the immutable durable work identifier.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the accepted command identifier.

Property

Kind

DurableWorkAcceptanceKind Kind { get; } Source

Gets whether the request was new or deduplicated.

Property

Revision

long Revision { get; } Source

Gets the aggregate revision produced by acceptance.

Property

AcceptedAtUtc

DateTimeOffset AcceptedAtUtc { get; } Source

Gets the authoritative store acceptance time in UTC.

Type

IDurableWorkClient

Source

Accepts durable work outside an existing caller-owned transaction.

Method

EnqueueAsync

ValueTask<DurableOperationResult<DurableWorkAcceptance>> EnqueueAsync(DurableWorkRequest request, CancellationToken cancellationToken = default)
Source

Accepts work atomically in a runtime-owned authoritative-store transaction.

Type

DurableFlowInstanceId

Source

Identifies one durable Flow instance independently of its current node or runtime claim.

Method

New

DurableFlowInstanceId New()
Source

Creates a cryptographically random Flow instance identifier.

Property

Value

string Value { get; } Source

Gets the opaque identifier value.

Type

DurableFlowEventId

Source

Identifies a single-use external Flow event independently of transport retries.

Method

New

DurableFlowEventId New()
Source

Creates a cryptographically random event identifier.

Property

Value

string Value { get; } Source

Gets the opaque identifier value.

Type

DurableFlowStartRequest

Source

Describes one idempotent durable Flow start.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the idempotent command identifier.

Property

IdempotencyKey

string IdempotencyKey { get; } Source

Gets the caller retry key.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the requested Flow instance identifier.

Property

FlowId

string FlowId { get; } Source

Gets the registered Flow definition identifier.

Property

FlowVersion

string FlowVersion { get; } Source

Gets the immutable Flow definition version.

Property

Context

DurableEncodedPayload Context { get; } Source

Gets the encoded initial context.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed semantic command fingerprint.

Type

DurableFlowEventRequest

Source

Delivers one authorized external event only to an active matching wait.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the command identifier used for transport deduplication.

Property

EventId

DurableFlowEventId EventId { get; } Source

Gets the single-use event identifier.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the target Flow instance.

Property

EventName

string EventName { get; } Source

Gets the exact case-sensitive wait event name.

Property

Payload

DurableEncodedPayload? Payload { get; } Source

Gets the optional allowlisted event payload.

Property

ExpectedRevision

long? ExpectedRevision { get; } Source

Gets an optional optimistic Flow revision.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed semantic command fingerprint.

Type

DurableFlowCancelRequest

Source

Requests cooperative cancellation of a durable Flow instance.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the command identifier.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the target Flow instance.

Property

ActorId

string ActorId { get; } Source

Gets the privacy-safe authorized actor identifier recorded for audit.

Property

ReasonCode

string ReasonCode { get; } Source

Gets the privacy-safe cancellation reason code.

Property

ExpectedRevision

long ExpectedRevision { get; } Source

Gets the required optimistic Flow revision.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed semantic command fingerprint.

Type

DurableFlowReleaseRequest

Source

Requests an audited release of a recoverably suspended Flow, or direct adoption of an exact-revision dormant Flow from an older runtime epoch, after an operator has verified runtime compatibility or resolved ambiguous child-work truth.

Remarks

Direct epoch adoption retains the instance's prior nonterminal state and active wait shape. It does not adopt an evaluating, terminal, or current-epoch non-suspended instance, and it never bypasses manifest compatibility.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the idempotent operator command identifier.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the target Flow instance.

Property

ActorId

string ActorId { get; } Source

Gets the privacy-safe authorized operator identifier recorded for audit.

Property

ReasonCode

string ReasonCode { get; } Source

Gets the privacy-safe release reason recorded for audit.

Property

ExpectedRevision

long ExpectedRevision { get; } Source

Gets the required Flow revision.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed semantic command fingerprint.

Type

DurableFlowGetRequest

Source

Requests a payload-free snapshot of one Flow in an application-authorized scope.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the target Flow instance.

Type

DurableFlowListRequest

Source

Requests one bounded, authorized page of payload-free Flow snapshots.

Remarks

The optional recovery filter identifies dormant nonterminal instances whose persisted runtime epoch differs from the active client epoch. It is an inventory aid, not proof that manifest, state-shape, or external-effect recovery checks will permit release.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

State

DurableFlowState? State { get; } Source

Gets the optional lifecycle-state filter.

Property

RequiresRecoveryRelease

bool? RequiresRecoveryRelease { get; } Source

Gets the optional old-epoch recovery filter.

Property

PageSize

int PageSize { get; } Source

Gets the maximum snapshots returned by this page.

Property

ContinuationToken

string? ContinuationToken { get; } Source

Gets the opaque continuation token of at most 512 characters, or null for the first page.

Type

DurableFlowListResult

Source

Represents one bounded page of payload-free Flow snapshots.

Property

Flows

IReadOnlyList<DurableFlowSnapshot> Flows { get; } Source

Gets the immutable page of Flow snapshots.

Property

ContinuationToken

string? ContinuationToken { get; } Source

Gets the next opaque continuation token of at most 512 characters, or null on the final page.

Type

DurableFlowSnapshot

Source

Provides payload-free durable Flow state suitable for status pages, optimistic commands, and operator recovery.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the Flow instance identifier.

Property

FlowId

string FlowId { get; } Source

Gets the immutable Flow definition identifier.

Property

FlowVersion

string FlowVersion { get; } Source

Gets the immutable Flow definition version.

Property

State

DurableFlowState State { get; } Source

Gets the authoritative lifecycle state.

Property

CurrentNodeId

string CurrentNodeId { get; } Source

Gets the current stable node identifier.

Property

Revision

long Revision { get; } Source

Gets the aggregate revision required by optimistic commands.

Property

CreatedAtUtc

DateTimeOffset CreatedAtUtc { get; } Source

Gets when the Flow was accepted.

Property

UpdatedAtUtc

DateTimeOffset UpdatedAtUtc { get; } Source

Gets when the Flow aggregate last changed.

Property

CancellationRequestedAtUtc

DateTimeOffset? CancellationRequestedAtUtc { get; } Source

Gets when cancellation was first requested, if applicable.

Property

TerminalAtUtc

DateTimeOffset? TerminalAtUtc { get; } Source

Gets when a terminal state was reached, if applicable.

Property

TerminalCode

string? TerminalCode { get; } Source

Gets the privacy-safe terminal or suspension code, if present.

Property

RequiresRecoveryRelease

bool RequiresRecoveryRelease { get; } Source

Gets whether this dormant nonterminal instance belongs to an older runtime epoch and requires an audited recovery release before the active runtime may continue it.

Remarks

This inventory flag does not prove manifest compatibility, wait-shape validity, or resolved external-effect truth. Evaluating and terminal rows are false because they are not directly releasable dormant instances.

Type

DurableFlowCommandResult

Source

Records the stable outcome of a durable Flow command.

Property

InstanceId

DurableFlowInstanceId InstanceId { get; } Source

Gets the Flow instance.

Property

Outcome

DurableFlowCommandOutcome Outcome { get; } Source

Gets the command outcome.

Property

State

DurableFlowState State { get; } Source

Gets the resulting authoritative state.

Property

Revision

long Revision { get; } Source

Gets the resulting aggregate revision.

Type

IDurableFlowClient

Source

Starts, resumes, and cancels durable Flow instances through application-authorized calls.

Method

GetAsync

ValueTask<DurableOperationResult<DurableFlowSnapshot>> GetAsync(DurableFlowGetRequest request, CancellationToken cancellationToken = default)
Source

Reads a payload-free snapshot from the authorized scope.

Method

ListAsync

ValueTask<DurableOperationResult<DurableFlowListResult>> ListAsync(DurableFlowListRequest request, CancellationToken cancellationToken = default)
Source

Lists one bounded, authorized page of payload-free Flow snapshots, optionally filtered by lifecycle state and old-epoch recovery requirement.

Method

StartAsync

ValueTask<DurableOperationResult<DurableFlowCommandResult>> StartAsync(DurableFlowStartRequest request, CancellationToken cancellationToken = default)
Source

Accepts an idempotent Flow start.

Method

RaiseEventAsync

ValueTask<DurableOperationResult<DurableFlowCommandResult>> RaiseEventAsync(DurableFlowEventRequest request, CancellationToken cancellationToken = default)
Source

Delivers an authorized event to an active matching wait.

Remarks

V1 does not buffer early events. DurableFlowCommandOutcome.NotWaitingYet means the event id was not consumed and the caller may retry after observing the wait.

Method

CancelAsync

ValueTask<DurableOperationResult<DurableFlowCommandResult>> CancelAsync(DurableFlowCancelRequest request, CancellationToken cancellationToken = default)
Source

Requests cooperative cancellation at an expected revision.

Method

ReleaseSuspensionAsync

ValueTask<DurableOperationResult<DurableFlowCommandResult>> ReleaseSuspensionAsync(DurableFlowReleaseRequest request, CancellationToken cancellationToken = default)
Source

Releases a recoverable suspension or directly adopts a dormant nonterminal Flow from an older runtime epoch, only after exact runtime-manifest, optimistic-revision, and persisted-state-shape validation. Authorization remains application-owned.

Remarks

A direct epoch release preserves the prior ready, event-wait, timer-wait, activity-wait, or cancel-pending state. A terminal result is reported without mutation; incompatible manifests and unsafe state shapes fail.

Type

DurablePayloadCodecSnapshot

Source

Captures validated codec facts separately from caller-owned executable behavior.

Remarks

Capture reads each metadata getter once. Views never poll or dispose the source; callers own its concurrency safety.

Method

CreateView

IDurablePayloadCodec CreateView()
Source

Creates an independent guarded projection without rereading metadata.

Method

Capture

2 overloads
DurablePayloadCodecSnapshot Capture(IDurablePayloadCodec codec)
Source

Captures an untyped raw source or reuses a package-owned view's original snapshot.

DurablePayloadCodecSnapshot Capture<T>(IDurablePayloadCodec<T> codec, string parameterName = "codec")
Source

Captures a typed source and verifies its declared CLR type independently of its contract namespace.

Parameters

  • codec
    Typed source or package-owned view to capture.
  • parameterName
    Public caller parameter name used for codec argument failures.
Method

GetSnapshot

DurablePayloadCodecSnapshot? GetSnapshot(IDurablePayloadCodec codec)
Source

Retrieves provenance only from an unforgeable package implementation.

Method

AreCompatible

bool AreCompatible(IDurablePayloadCodec expected, IDurablePayloadCodec actual)
Source

Accepts exact references or package projections of the same source and complete captured facts.

Method

RetainGuardedView

IDurablePayloadCodec RetainGuardedView(IDurablePayloadCodec expected, IDurablePayloadCodec selected)
Source

Retains captured guards when a compatible registry selects the original raw source.

Remarks

Call after compatibility validation. A selected package view remains authoritative; otherwise an expected view invokes that same selected source without rereading metadata or changing registration state.

Method

RequireEncodedPayload

DurableEncodedPayload RequireEncodedPayload(DurableEncodedPayload? payload)
Source

Distinguishes a missing codec output from an invalid supplied payload.

Method

RequirePayload

DurableEncodedPayload RequirePayload(DurableEncodedPayload? payload)
Source

Rejects incompatible payloads before decode and after encode without changing bytes or exposing values.

Property

Source

IDurablePayloadCodec Source { get; } Source

Gets the exact caller-owned source; metadata equality never substitutes for this identity.

Property

Facts

Metadata Facts { get; } Source

Gets the facts captured once from the source.

Type

Metadata

Source

Complete immutable facts used for identity, indexing and payload guards.

Type

View

Source

Untyped projection used by registry-only sources and untyped provider boundaries.

Type

TypedView<T>

Source

Typed projection preserving the source's typed invocation boundary and payload guards.

Type

DurableCodecContribution

Source

A closed codec contribution; frozen projections are required only for definition-based public paths.

Type

DurableTraceContext

Source

Represents one validated, versioned W3C context that can become durable causal evidence.

Parameters

  • TraceParent
    The normalized version- 00 W3C parent persisted only as a propagation input.
  • TraceId
    The normalized trace identifier parsed from TraceParent .
  • SpanId
    The normalized span identifier parsed from TraceParent .
  • TraceFlags
    The normalized W3C trace flags parsed from TraceParent .
  • TraceState
    The optional bounded opaque state, or null when it was absent or rejected.
  • CorrelationToken
    The runtime-generated value-free token associated with this causal evidence.

Remarks

The type is internal to the Durable package family. It deliberately contains no baggage, authorization, scope, or payload metadata. Its raw W3C members are persistence and propagation inputs only; instrumentation must not tag or log them.

Method

ToActivityContext

ActivityContext ToActivityContext()
Source

Creates the remote W3C context used exclusively for a causal ActivityLink .

Remarks

The recorded bit is retained, all reserved trace-flag bits are ignored, and the normalized opaque state is propagated without becoming a telemetry tag.

Method

CaptureCurrent

DurableTraceContextCapture CaptureCurrent()
Source

Captures the current W3C activity as ambient durable context.

Returns

An absent capture when no valid W3C activity is current; otherwise an ambient capture with a new correlation token.

Method

Capture

DurableTraceContextCapture Capture(Activity? activity)
Source

Captures a sampled activity as ambient durable context.

Parameters

  • activity
    The activity to capture, if one was created by a listener.

Returns

An absent capture for a missing or non-W3C activity; otherwise a validated ambient capture.

Method

Parse

DurableTraceContextCapture Parse(string? traceParent, string? traceState, DurableTraceContextStatus validStatus = DurableTraceContextStatus.Linked)
Source

Parses persisted or ambient W3C members into a bounded durable capture.

Remarks

An invalid parent returns DurableTraceContextStatus.Invalid with ASDUR212 and drops both values. A valid parent with rejected state retains the parent, drops the state, and returns ASDUR213 . Every retained context receives a new runtime-generated correlation token.

Method

CaptureExecution

DurableTraceContextCapture CaptureExecution(Activity? activity, DurableTraceContextCapture committedCause)
Source

Captures a fresh execution activity while retaining the committed cause's value-free status.

Remarks

A listener-created execution activity has a fresh W3C context and is therefore ambient when captured directly. Durable telemetry instead reports the status of the committed trigger ( linked , absent , or invalid ) while persisting the fresh execution context. A missing activity preserves the supplied capture.

Type

DurableTraceContextCapture

Source

Returns a context with a value-free status and optional diagnostic code.

Type

DurableEffectReconciliation<TResult>

Source

Strongly typed result from a provider reconciliation read.

Type parameters

  • TResult
    Registered terminal result type.
Method

Applied

DurableEffectReconciliation<TResult> Applied(TResult result)
Source

Creates an applied result with terminal provider truth.

Method

NotApplied

DurableEffectReconciliation<TResult> NotApplied()
Source

Creates a result proving that the external effect did not occur.

Method

Unknown

DurableEffectReconciliation<TResult> Unknown()
Source

Creates a result that leaves the external effect ambiguous.

Property

Kind

DurableEffectReconciliationKind Kind { get; } Source

Gets the proven provider state.

Property

Result

TResult? Result { get; } Source

Gets the terminal result when Kind is DurableEffectReconciliationKind.Applied .

Type

IDurableEffectReconciler<TWork, TResult>

Source

Performs a side-effect-free provider read after an allowed effect has an unknown outcome.

Type parameters

  • TWork
    Registered work type.
  • TResult
    Registered terminal result type.

Remarks

Reconciliation must never repeat the provider mutation. It queries provider state using the immutable provider key and returns what can be proven. Returning DurableEffectReconciliationKind.Unknown keeps work suspended.

Method

ReconcileAsync

ValueTask<DurableEffectReconciliation<TResult>> ReconcileAsync(DurableWorkerEnvelope<TWork> work, CancellationToken cancellationToken = default)
Source

Reads provider state for the original activity-derived provider key.

Type

DurableEncodedEffectReconciliation

Source

Encoded reconciliation result used by the runtime store boundary.

Property

Kind

DurableEffectReconciliationKind Kind { get; } Source

Gets the proven provider state.

Property

Result

DurableEncodedPayload? Result { get; } Source

Gets the encoded terminal result for an applied effect.

Type

DurableTraceContextValidation

Source

Validates the bounded W3C fields accepted by the durable trace contract.

Type

DurableEncodedPayload

Source

Carries an immutable, versioned, allowlisted payload ready for durable persistence.

Method

Equals

bool Equals(DurableEncodedPayload? other)
Source

Compares payload metadata and canonical content bytes by value.

Parameters

  • other
    Payload to compare.

Returns

true when metadata and content bytes are equal.

Property

ContractName

string ContractName { get; } Source

Gets the stable registered contract name.

Property

ContractVersion

string ContractVersion { get; } Source

Gets the stable registered contract version.

Property

Classification

DurableDataClassification Classification { get; } Source

Gets the approved durable-data classification.

Property

RetentionPolicyId

string RetentionPolicyId { get; } Source

Gets the stable retention policy identity snapshotted by the registered codec.

Property

Content

ReadOnlyMemory<byte> Content { get; } Source

Gets a copy-safe view of the canonical encoded bytes.

Property

Sha256

string Sha256 { get; } Source

Gets the lowercase SHA-256 hash of the exact encoded bytes.

Type

IDurablePayloadCodec

Source

Encodes and decodes one registered durable payload contract without runtime type-name serialization.

Method

EncodeObject

DurableEncodedPayload EncodeObject(object value)
Source

Encodes a value after applying its registration-time data policy.

Method

DecodeObject

object DecodeObject(DurableEncodedPayload payload)
Source

Decodes bytes only when their contract identity exactly matches this codec.

Property

PayloadType

Type PayloadType { get; } Source

Gets the supported CLR payload type.

Property

ContractName

string ContractName { get; } Source

Gets the stable contract name.

Property

ContractVersion

string ContractVersion { get; } Source

Gets the stable contract version.

Property

Classification

DurableDataClassification Classification { get; } Source

Gets the exact classification this codec accepts and emits.

Property

RetentionPolicyId

string RetentionPolicyId { get; } Source

Gets the stable application-owned retention policy identity this codec accepts and emits.

Type

IDurablePayloadCodec<T>

Source

Strongly typed durable payload codec.

Type parameters

  • T
    Registered payload type.
Method

Encode

DurableEncodedPayload Encode(T value)
Source

Encodes a typed payload.

Method

Decode

T Decode(DurableEncodedPayload payload)
Source

Decodes a typed payload.

Type

SystemTextJsonDurablePayloadCodec<T>

Source

Source-generation-friendly JSON codec for an explicitly registered payload type.

Type parameters

  • T
    Registered payload type.
Property

Classification

DurableDataClassification Classification { get; } Source

Gets the approved data classification.

Type

IDurablePayloadCodecRegistry

Source

Resolves only explicitly registered durable payload codecs.

Method

Register

void Register(IDurablePayloadCodec codec)
Source

Registers one codec by CLR type and durable contract identity.

Method

GetRequired

3 overloads
IDurablePayloadCodec GetRequired(Type payloadType)
Source

Gets the required codec for a CLR type.

IDurablePayloadCodec GetRequired(Type payloadType, string contractName, string contractVersion)
Source

Gets a required codec for an exact CLR type and persisted contract identity.

IDurablePayloadCodec GetRequired(string contractName, string contractVersion)
Source

Gets the required codec for persisted contract identity.

Type

DurablePayloadCodecRegistry

Source

Thread-safe in-memory registry for explicitly allowlisted durable payload codecs.

Method

Register

void Register(IDurablePayloadCodec codec)
Source

Remarks

Equivalent raw/view registrations are idempotent. A frozen view upgrades a raw entry without downgrades; references returned before a manual upgrade remain caller-owned references.

Method

AddEntry

void AddEntry(Entry entry)
Source

Populates both indexes with one validated entry; caller holds the lock or owns an unpublished registry.

Method

GetEntry

Entry GetEntry(string contractName, string contractVersion)
Source

Resolves by validated identifiers using captured metadata; caller holds the registry lock.

Type

Entry

Source

One entry is shared by all indexes; an upgrade publishes its canonical view atomically under the registry lock.

Method

Upgrade

void Upgrade(DurablePayloadCodecSnapshot incoming)
Source

Creates before publishing so a failed upgrade leaves every index unchanged.

Type

DurableWorkBinding<TWork, TResult, TExecutor>

Source

Binds an ordinary executor to a definition without resolving services or executing code.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.
  • TExecutor
    Transient ordinary executor implementation.
Method

ReconciledBy

DurableReconciledWorkBinding<TWork, TResult, TExecutor, TReconciler> ReconciledBy<TReconciler>()
Source

Completes a reconcile-before-retry binding with its side-effect-free reconciler.

Type parameters

  • TReconciler
    Transient reconciler for the exact Work/result types.

Returns

A complete immutable binding.

Exceptions

  • InvalidOperationException
    The definition does not declare ReconcileBeforeRetry safety.
Property

Definition

DurableWorkDefinition<TWork, TResult> Definition { get; } Source

Gets the exact definition owning this binding's facts.

Type

DurableReconciledWorkBinding<TWork, TResult, TExecutor, TReconciler>

Source

Complete reconcile-before-retry binding; no repeated contract facts or mutable options.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.
  • TExecutor
    Transient ordinary executor.
  • TReconciler
    Transient side-effect-free reconciler.
Property

Definition

DurableWorkDefinition<TWork, TResult> Definition { get; } Source

Gets the exact definition owning this binding's facts.

Type

DurableExitWorkBinding<TWork, TResult, TExecutor>

Source

Complete ProviderKeyed exit binding; reconciliation is deliberately unavailable.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.
  • TExecutor
    Transient exit-aware executor.
Property

Definition

DurableWorkDefinition<TWork, TResult> Definition { get; } Source

Gets the exact definition owning this binding's facts.

Type

DurableServiceCollectionExtensions

Registration helpers for typed durable worker executors.

Method

AddDurableWork

4 overloads
IServiceCollection AddDurableWork<TWork, TResult, TExecutor>(this IServiceCollection services, DurableWorkBinding<TWork, TResult, TExecutor> binding)
Source

Registers exact definition/binding singleton values and a transient ordinary executor.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.
  • TExecutor
    Ordinary executor.

Parameters

  • services
    Service collection to configure.
  • binding
    Complete ordinary binding.

Returns

The same service collection.

Exceptions

  • ArgumentNullException
    Services or binding is null.
  • InvalidOperationException
    ReconcileBeforeRetry binding lacks its reconciler.

Remarks

Validation precedes descriptor changes. Duplicate Work identities fail when default registries resolve.

IServiceCollection AddDurableWork<TWork, TResult, TExecutor, TReconciler>(this IServiceCollection services, DurableReconciledWorkBinding<TWork, TResult, TExecutor, TReconciler> binding)
Source

Registers exact contract values and transient executor/reconciler implementations.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.
  • TExecutor
    Ordinary executor.
  • TReconciler
    Side-effect-free reconciler.

Parameters

  • services
    Service collection to configure.
  • binding
    Complete reconcile-before-retry binding.

Returns

The same service collection.

Exceptions

  • ArgumentNullException
    Services or binding is null.
IServiceCollection AddDurableWork<TWork, TResult, TExecutor>(this IServiceCollection services, DurableExitWorkBinding<TWork, TResult, TExecutor> binding)
Source

Registers exact contract values and a transient ProviderKeyed exit-aware executor.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.
  • TExecutor
    Exit-aware executor.

Parameters

  • services
    Service collection to configure.
  • binding
    Complete exit binding.

Returns

The same service collection.

Exceptions

  • ArgumentNullException
    Services or binding is null.

Remarks

Deploy exit-capable workers before using new exit-aware Work versions; historical executor semantics remain immutable.

IServiceCollection AddDurableWork<TWork, TResult, TExecutor>(this IServiceCollection services, string workName, string workVersion, DurableProviderSafety providerSafety, IDurablePayloadCodec<TWork> workCodec, IDurablePayloadCodec<TResult> resultCodec)
Source

Registers one versioned work contract, its allowlisted codecs, and its transient executor.

Parameters

  • services
    Service collection to configure.
  • workName
    Stable Work name.
  • workVersion
    Immutable Work version.
  • providerSafety
    External-effect ambiguity policy; use the reconciler overload for reconcile-before-retry.
  • workCodec
    Allowlisted Work codec.
  • resultCodec
    Allowlisted terminal result codec.

Returns

The same service collection.

Exceptions

  • ArgumentException
    Thrown when the registration is invalid.
  • ArgumentNullException
    Thrown when services or a codec is null.
Method

AddDurableWorkExit

IServiceCollection AddDurableWorkExit<TWork, TResult, TExecutor>(this IServiceCollection services, string workName, string workVersion, IDurablePayloadCodec<TWork> workCodec, IDurablePayloadCodec<TResult> resultCodec)
Source

Registers one immutable Work contract whose executor returns an explicit provider-effect exit.

Type parameters

  • TWork
    Executor Work type.
  • TResult
    Executor successful result type.
  • TExecutor
    Exit-aware executor implementation.

Parameters

  • services
    Service collection to configure.
  • workName
    Stable Work name.
  • workVersion
    Immutable Work version.
  • workCodec
    Allowlisted Work input codec.
  • resultCodec
    Allowlisted terminal result codec.

Returns

The same service collection.

Exceptions

  • ArgumentException
    Thrown when the registration is invalid.
  • ArgumentNullException
    Thrown when services or a codec is null.

Remarks

V1 intentionally fixes this registration to DurableProviderSafety.ProviderKeyed . Register a new immutable Work version only after every eligible worker uses a provider that calls DurablePreparedWork.InvokeExitAsync(CancellationToken) ; do not convert an accepted Work version in place. Keep the legacy AddDurableWork{TWork,TResult,TExecutor}(IServiceCollection,string,string,DurableProviderSafety,IDurablePayloadCodec{TWork},IDurablePayloadCodec{TResult}) contract when an executor cannot prove one of the four exit facts.

Method

AddDurableWorkWithReconciler

IServiceCollection AddDurableWorkWithReconciler<TWork, TResult, TExecutor, TReconciler>(this IServiceCollection services, string workName, string workVersion, IDurablePayloadCodec<TWork> workCodec, IDurablePayloadCodec<TResult> resultCodec)
Source

Registers provider work that must reconcile an unknown effect before any retry.

Parameters

  • services
    Service collection to configure.
  • workName
    Stable Work name.
  • workVersion
    Immutable Work version.
  • workCodec
    Allowlisted Work codec.
  • resultCodec
    Allowlisted terminal result codec.

Returns

The same service collection.

Exceptions

  • ArgumentException
    Thrown when the registration is invalid.
  • ArgumentNullException
    Thrown when services or a codec is null.

Remarks

Use this overload for DurableProviderSafety.ReconcileBeforeRetry so unknown effects are reconciled before retry.

Method

AddDurableFlow

IServiceCollection AddDurableFlow<TContext>(this IServiceCollection services, ForgeTrust.AppSurface.Flow.FlowDefinition<TContext> definition, IDurablePayloadCodec<TContext> contextCodec, string implementationVersion, IEnumerable<DurableFlowActivityBinding<TContext>>? activityBindings = null, IEnumerable<DurableFlowEventBinding>? eventBindings = null, ForgeTrust.AppSurface.Flow.IFlowTransitionEvaluator<TContext>? evaluator = null)
Source

Registers one immutable Flow definition, its approved context codec, and its durable activity bindings.

Type parameters

  • TContext
    Flow context type.

Parameters

  • services
    Application service collection.
  • definition
    Immutable Flow definition and version.
  • contextCodec
    Allowlisted durable context codec.
  • implementationVersion
    Application-owned version for node implementation semantics not represented by topology or contract metadata. Change it whenever executable node behavior changes without changing the Flow definition version.
  • activityBindings
    Optional registered activity bindings used by the definition.
  • eventBindings
    Optional typed external-event bindings used by the definition.
  • evaluator
    Optional one-node evaluator override.

Returns

The same service collection.

Type

DurableTraceTelemetry

Source

Owns the fixed, value-free vocabulary emitted by durable trace instrumentation.

Method

Apply

void Apply(Activity? activity, string executionKind, string triggerKind, string flowState, string outcome, Guid correlationToken, DurableTraceContextStatus contextStatus)
Source

Applies the fixed, value-free Durable trace tag vocabulary to an active execution activity.

Remarks

A null activity is a no-op because no listener requested an activity. The emitted keys are ContractVersion , ExecutionKind , TriggerKind , FlowState , Outcome , ContextStatus , and, only when available, CorrelationToken . contextStatus is a DurableTraceContextStatus value from validated durable trace capture; header values, baggage, and tenant data are never emitted.

Type

DurableProblemCodes

Source

Stable diagnostic codes shared by durable results, logs, metrics, operator history, and documentation.

Remarks

Codes are append-only compatibility identifiers. Never renumber or reuse a code for a different condition.

Type

DurableWorkRegistrationCatalog

Source

Materializes and validates local Work values before any codec enumeration can mask duplicate Work.

Property

Registrations

IReadOnlyDictionary<(string Name, string Version), DurableWorkRegistration> Registrations { get; } Source

Gets exact immutable registration values indexed by Work identity.

Property

Contracts

IReadOnlyList<DurableWorkContractIdentity> Contracts { get; } Source

Gets sorted public discovery identities.

Type

DurableRegistryInstallation

Source

Installs acyclic passive defaults without replacing or reordering consumer descriptors.

Method

AddDefaults

void AddDefaults(IServiceCollection services)
Source

Uses TryAdd for each default so module/Work/Flow ordering preserves consumer overrides.

Type

DurableWork

Source

Creates immutable typed Work contracts without activating storage or execution.

Method

Define

DurableWorkDefinition<TWork, TResult> Define<TWork, TResult>(string workName, string workVersion, IDurablePayloadCodec<TWork> workCodec, IDurablePayloadCodec<TResult> resultCodec, DurableProviderSafety providerSafety, DurableWorkRetryPolicy defaultRetryPolicy)
Source

Defines Work identity, codec facts, provider safety and an explicit default retry policy once.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.

Parameters

  • workName
    Stable Work name, at most 200 characters.
  • workVersion
    Immutable Work version, at most 100 characters.
  • workCodec
    Explicitly approved input codec.
  • resultCodec
    Explicitly approved result codec; its identity may differ from Work and input.
  • providerSafety
    Declared provider-effect ambiguity policy.
  • defaultRetryPolicy
    Required request default; use DurableWorkRetryPolicy.Default for ordinary policy.

Returns

A passive definition with stable guarded codec views.

Exceptions

  • ArgumentNullException
    A codec or retry default is null.
  • ArgumentException
    An identifier or declared codec type is invalid.
  • ArgumentOutOfRangeException
    Safety or classification is undefined.
  • InvalidOperationException
    Input and result views of one codec source carry conflicting captured metadata.

Remarks

Metadata is captured once per source. Custom getter exceptions propagate; no serializer or executor runs.

Type

DurableWorkDefinition<TWork, TResult>

Source

Owns immutable Work contract facts and builds equivalent ordinary durable requests.

Type parameters

  • TWork
    Work input type.
  • TResult
    Successful result type.

Remarks

Safe to reuse statically when custom codecs and their dependencies support concurrent calls. Frozen metadata does not freeze application behavior. Changing defaults affects future requests only; accepted Work retains its facts.

Method

CreateRequest

DurableWorkRequest CreateRequest(DurableScopeId scopeId, DurableCommandId commandId, string idempotencyKey, TWork work, DurableWorkRetryPolicy? retryPolicy = null, DateTimeOffset? dueAtUtc = null)
Source

Validates caller choices, encodes input once and creates the existing immutable request.

Parameters

  • scopeId
    Trusted owning scope.
  • commandId
    Caller command identity.
  • idempotencyKey
    Explicit duplicate-submission key, at most 200 characters.
  • work
    Non-null input approved by the codec.
  • retryPolicy
    Optional override; null selects this definition's default.
  • dueAtUtc
    Optional initial eligibility time, normalized to UTC; null means immediately eligible.

Returns

A request with the same fields and fingerprint as equivalent direct construction.

Exceptions

  • ArgumentException
    Caller identities are invalid or the codec rejects the input.
  • ArgumentNullException
    Input is null.
  • InvalidOperationException
    Encoded output is missing or disagrees with captured codec metadata.

Remarks

All caller identity checks precede encoding. Codec exceptions propagate. No registration or storage is required.

Method

ExecutedBy

DurableWorkBinding<TWork, TResult, TExecutor> ExecutedBy<TExecutor>()
Source

Binds an ordinary transient executor; reconcile-before-retry still requires a reconciler before registration.

Type parameters

  • TExecutor
    Class implementing the exact Work/result executor contract.

Returns

A passive binding referencing this exact definition.

Method

ExecutedByExit

DurableExitWorkBinding<TWork, TResult, TExecutor> ExecutedByExit<TExecutor>()
Source

Binds an exit-aware transient executor for ProviderKeyed Work.

Type parameters

  • TExecutor
    Class implementing the exact Work/result exit contract.

Returns

A complete passive exit binding.

Exceptions

  • InvalidOperationException
    The definition does not declare ProviderKeyed safety.
Property

Snapshot

DurableWorkContractSnapshot<TWork, TResult> Snapshot { get; } Source

Gets the authoritative internal contract; binding and registration never reconstruct it.

Property

WorkName

string WorkName { get; } Source

Gets the stable Work name.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the immutable Work version.

Property

ContractIdentity

DurableWorkContractIdentity ContractIdentity { get; } Source

Gets the exact Work registry identity.

Property

WorkCodec

IDurablePayloadCodec<TWork> WorkCodec { get; } Source

Gets the definition-owned guarded input codec with captured metadata.

Property

ResultCodec

IDurablePayloadCodec<TResult> ResultCodec { get; } Source

Gets the definition-owned guarded successful result codec with captured metadata.

Property

ProviderSafety

DurableProviderSafety ProviderSafety { get; } Source

Gets the declared provider-effect ambiguity policy.

Property

DefaultRetryPolicy

DurableWorkRetryPolicy DefaultRetryPolicy { get; } Source

Gets the explicit retry policy used when a request omits an override.

Type

DurableWorkContractSnapshot

Source

Shared closed Work facts used by all built-in registrations and definitions.

Method

Validate

DurableWorkContractIdentity Validate(string workName, string workVersion, DurableProviderSafety providerSafety, DurableWorkRetryPolicy defaultRetryPolicy)
Source

Validates common facts without invoking consumer codec behavior.

Method

Capture

DurableWorkContractSnapshot Capture(string name, string version, DurableProviderSafety safety, IDurablePayloadCodec workCodec, IDurablePayloadCodec resultCodec)
Source

Closes external subclasses of the legacy abstract registration without exposing a new public seam.

Method

CaptureCodecs

(DurablePayloadCodecSnapshot Work, DurablePayloadCodecSnapshot Result) CaptureCodecs<TWorkCodec, TResultCodec>(TWorkCodec workCodec, TResultCodec resultCodec, Func<TWorkCodec, DurablePayloadCodecSnapshot> captureWork, Func<TResultCodec, DurablePayloadCodecSnapshot> captureResult)
Source

Captures each distinct source once, reuses supplied views and rejects conflicting facts for one source.

Remarks

Capture delegates preserve typed invocation when closing generic contracts and untyped legacy subclasses.

Property

Identity

DurableWorkContractIdentity Identity { get; } Source

Exact validated Work name/version.

Property

ProviderSafety

DurableProviderSafety ProviderSafety { get; } Source

Declared provider-effect ambiguity policy.

Property

DefaultRetryPolicy

DurableWorkRetryPolicy DefaultRetryPolicy { get; } Source

Request construction default, never a replacement for accepted policy.

Property

Work

DurablePayloadCodecSnapshot Work { get; } Source

Captured input source and metadata.

Property

Result

DurablePayloadCodecSnapshot Result { get; } Source

Captured successful-result source and metadata.

Type

DurableWorkContractSnapshot<TWork, TResult>

Source

Typed projection of the shared contract; views are created once and never recapture metadata.

Method

Create

DurableWorkContractSnapshot<TWork, TResult> Create(string name, string version, DurableProviderSafety safety, IDurablePayloadCodec<TWork> workCodec, IDurablePayloadCodec<TResult> resultCodec, DurableWorkRetryPolicy retry)
Source

Captures each unique source once, with independent exact generic-type checks.

Property

WorkView

IDurablePayloadCodec<TWork> WorkView { get; } Source

Stable typed input projection used by definition and invocation.

Property

ResultView

IDurablePayloadCodec<TResult> ResultView { get; } Source

Stable typed result projection used by definition and invocation.

Type

AppSurfaceDurableModule

Source

Registers host-neutral durable contracts and registries without starting storage or workers.

Remarks

Add a provider module to select storage and explicitly opt into hosted execution. This module alone performs no network access, schema creation, polling, scheduling, or provider work.

Type

DurableWorkContractIdentity

Source

Identity pair for one durable work contract.

Property

IsDefault

bool IsDefault { get; } Source

Gets whether this value is the default struct value.

Property

WorkName

string WorkName { get; } Source

Gets the work contract name.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the work contract version.

Type

DurableProblem

Source

Provides privacy-safe, actionable details for a failed durable operation.

Property

Code

string Code { get; } Source

Gets the stable machine-readable code.

Property

Problem

string Problem { get; } Source

Gets the safe problem description.

Property

Cause

string Cause { get; } Source

Gets the safe cause description.

Property

Fix

string Fix { get; } Source

Gets the safe corrective guidance.

Property

DocumentationUrl

Uri DocumentationUrl { get; } Source

Gets the canonical documentation URL.

Property

CorrelationId

string CorrelationId { get; } Source

Gets the opaque correlation identifier.

Type

DurableOperationResult<T>

Source

Represents either a successful durable operation value or an actionable problem.

Type parameters

  • T
    Successful value type.
Method

Success

DurableOperationResult<T> Success(T value)
Source

Creates a successful result.

Method

Failure

DurableOperationResult<T> Failure(DurableProblem problem)
Source

Creates a failed result.

Property

IsSuccess

bool IsSuccess { get; } Source

Gets whether the operation succeeded.

Property

Value

T? Value { get; } Source

Gets the successful value, or null when the operation failed.

Property

Problem

DurableProblem? Problem { get; } Source

Gets the problem, or null when the operation succeeded.

Type

DurableFlowDeterminismReport

Source

Reports whether two evaluations of the same persisted Flow input produced byte-for-byte equivalent durable decisions.

Property

FirstEvaluationSha256

string FirstEvaluationSha256 { get; } Source

Gets the canonical SHA-256 fingerprint of the first evaluation.

Property

SecondEvaluationSha256

string SecondEvaluationSha256 { get; } Source

Gets the canonical SHA-256 fingerprint of the second evaluation.

Property

IsDeterministic

bool IsDeterministic { get; } Source

Gets whether both evaluations produced the same durable decision.

Type

DurableFlowDeterminismVerifier

Source

Test harness that evaluates one durable Flow input twice and compares canonical transition bytes.

Remarks

Use this in definition tests and deployment validation. It deliberately executes node code twice, so do not place external effects in nodes and do not use this helper as the production transition commit path. A passing sample proves only that the supplied input was stable; source-generator determinism warnings and explicit persisted inputs remain necessary for other branches.

Method

VerifyAsync

ValueTask<DurableFlowDeterminismReport> VerifyAsync(DurableFlowRegistration registration, DurableFlowEvaluationInput input, IDurablePayloadCodecRegistry payloadCodecs, CancellationToken cancellationToken = default)
Source

Evaluates the same registered input twice and returns canonical decision fingerprints.

Parameters

  • registration
    Exact durable Flow registration to evaluate.
  • input
    Persisted node input to replay twice.
  • payloadCodecs
    Exact allowlisted payload codec registry.
  • cancellationToken
    Token that cancels either evaluation.

Returns

A report whose DurableFlowDeterminismReport.IsDeterministic value compares both runs.

Method

VerifyAndThrowAsync

ValueTask<DurableFlowDeterminismReport> VerifyAndThrowAsync(DurableFlowRegistration registration, DurableFlowEvaluationInput input, IDurablePayloadCodecRegistry payloadCodecs, CancellationToken cancellationToken = default)
Source

Evaluates the same registered input twice and throws when the canonical decisions differ.

Parameters

  • registration
    Exact durable Flow registration to evaluate.
  • input
    Persisted node input to replay twice.
  • payloadCodecs
    Exact allowlisted payload codec registry.
  • cancellationToken
    Token that cancels either evaluation.

Returns

The deterministic comparison report.

Exceptions

  • InvalidOperationException
    Thrown when the two canonical decisions differ.
Type

DurableWorkExecutionContext

Source

Carries one validated work item across the provider-to-application executor boundary.

Remarks

A provider creates this context only after validating its claim and execution fence. It is not an authorization token by itself; a provider must record an effect permit against the same identity immediately before provider I/O.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

WorkId

DurableWorkId WorkId { get; } Source

Gets the immutable work aggregate identifier.

Property

WorkName

string WorkName { get; } Source

Gets the registered work name.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the registered work version.

Property

Payload

DurableEncodedPayload Payload { get; } Source

Gets the encoded work payload.

Property

ProviderSafety

DurableProviderSafety ProviderSafety { get; } Source

Gets the provider ambiguity policy snapshot.

Property

ExecutionIdentity

DurableWorkerExecutionIdentity ExecutionIdentity { get; } Source

Gets the provider-validated execution identity and authorization fence.

Type

DurablePreparedWork

Source

Represents a locally validated work invocation that is ready for the runtime to record an external-effect permit.

Remarks

Preparation decodes the registered payload and resolves the executor before any permit exists. Calling InvokeAsync is the provider-effect boundary and must happen only after the matching permit commits.

Method

InvokeAsync

ValueTask<DurableEncodedPayload> InvokeAsync(CancellationToken cancellationToken = default)
Source

Executes the already prepared provider work and returns its encoded terminal result.

Parameters

  • cancellationToken
    Token that cancels executor invocation.

Returns

The registered codec's encoded terminal result.

Remarks

Call only after the matching external-effect permit commits.

Method

InvokeExitAsync

ValueTask<DurableEncodedWorkExit> InvokeExitAsync(CancellationToken cancellationToken = default)
Source

Executes prepared work and returns its encoded exit fact.

Parameters

  • cancellationToken
    Token that cancels executor invocation.

Returns

The registered codec's encoded success result wrapped as an exit fact.

Remarks

This compatibility implementation preserves legacy prepared Work behavior by calling InvokeAsync(CancellationToken) and wrapping its result as DurableWorkExitKind.Succeeded . Exit-aware registrations override it to return their explicit fact. Call only after the matching external-effect permit commits.

Type

DurableWorkRegistration

Source

Describes and invokes one registered durable work contract without reflection.

Method

Prepare

DurablePreparedWork Prepare(IServiceProvider services, DurableWorkExecutionContext work)
Source

Decodes and validates claimed bytes and resolves local executor dependencies without calling a provider.

Parameters

  • services
    Application service provider used to resolve the executor.
  • work
    Provider-validated execution context.

Returns

A prepared invocation that performs no provider I/O until invoked.

Method

InvokeAsync

ValueTask<DurableEncodedPayload> InvokeAsync(IServiceProvider services, DurableWorkExecutionContext work, CancellationToken cancellationToken = default)
Source

Invokes the registered executor and encodes its terminal business result.

Parameters

  • services
    Application service provider used to resolve the executor.
  • work
    Provider-validated execution context.
  • cancellationToken
    Token that cancels executor invocation.

Returns

The registered codec's encoded terminal result.

Remarks

Runtime code must persist an effect permit before calling this method. Exceptions after that permit represent a potentially applied external effect and must be handled according to ProviderSafety .

Method

ReconcileAsync

ValueTask<DurableEncodedEffectReconciliation> ReconcileAsync(IServiceProvider services, DurableWorkExecutionContext work, CancellationToken cancellationToken = default)
Source

Reconciles an unknown provider outcome without repeating the external mutation.

Parameters

  • services
    Application service provider used to resolve the reconciler.
  • work
    Provider-validated execution context.
  • cancellationToken
    Token that cancels reconciliation.

Returns

Applied, not-applied, or unknown provider truth.

Exceptions

  • InvalidOperationException
    Thrown when no reconciler is registered or reconciliation returns invalid data.
Property

Snapshot

DurableWorkContractSnapshot Snapshot { get; } Source

Gets the closed facts used by provider-local registry aggregation.

Property

RequiresFrozenView

bool RequiresFrozenView { get; } Source

Gets whether the public registration path requires frozen codec projections.

Property

WorkName

string WorkName { get; } Source

Gets the stable work name.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the stable work contract version.

Property

ProviderSafety

DurableProviderSafety ProviderSafety { get; } Source

Gets the declared provider ambiguity policy.

Property

WorkCodec

IDurablePayloadCodec WorkCodec { get; } Source

Gets the work payload codec.

Property

ResultCodec

IDurablePayloadCodec ResultCodec { get; } Source

Gets the result payload codec.

Property

CanReconcile

bool CanReconcile { get; } Source

Gets whether a side-effect-free reconciler is registered.

Type

DurableWorkRegistration<TWork, TResult, TExecutor>

Source

Reflection-free registration for one typed durable worker executor.

Type parameters

  • TWork
    Executor work type.
  • TResult
    Executor terminal result type.
  • TExecutor
    Registered executor implementation.
Type

DurableWorkExitRegistration<TWork, TResult, TExecutor>

Source

Reflection-free registration for one typed executor that returns an explicit durable Work exit.

Type parameters

  • TWork
    Executor Work type.
  • TResult
    Executor successful result type.
  • TExecutor
    Registered executor implementation.
Method

InvokeAsync

ValueTask<DurableEncodedPayload> InvokeAsync(IServiceProvider services, DurableWorkExecutionContext work, CancellationToken cancellationToken = default)
Source

Invokes the exit-aware executor through the legacy success-only provider boundary.

Exceptions

  • DurableWorkExitCompatibilityException
    Thrown when the exit-aware executor returns a non-success exit.

Remarks

Providers that support typed exits must invoke DurablePreparedWork.InvokeExitAsync(CancellationToken) through the provider invocation boundary instead. This compatibility member returns an encoded result only for DurableWorkExitKind.Succeeded ; every non-success exit throws DurableWorkExitCompatibilityException so a legacy provider follows its conservative ambiguous external-outcome path after the effect permit.

Type

IDurableWorkRegistry

Source

Resolves durable work registrations by their stable name and version.

Method

GetRequired

DurableWorkRegistration GetRequired(string workName, string workVersion)
Source

Gets a required registration or throws before work is accepted or claimed.

Parameters

  • workName
    Exact registered Work name.
  • workVersion
    Exact immutable Work version.

Returns

The matching registration.

Exceptions

  • ArgumentException
    Thrown when an identifier is invalid.
  • InvalidOperationException
    Thrown when no exact registration exists.
Property

RegisteredContracts

IReadOnlyList<DurableWorkContractIdentity> RegisteredContracts { get; } Source

Gets all registered work contracts, or throws if unavailable.

Exceptions

  • NotSupportedException
    Thrown when registry implementation does not expose registrations.

Remarks

A custom registry used with the PostgreSQL worker host must return one complete, exact, stable snapshot. The provider normalizes its order while forming the activation-time snapshot and does not reread later mutations, so restart the host to change discovery authority. A registry that cannot enumerate its registrations is valid for other consumers but cannot activate PostgreSQL Work discovery.

Type

DurableWorkRegistry

Source

Immutable registry of durable work registrations built during host startup.

Type

DurableWorkExit<TResult>

Source

Represents the fact returned by an IDurableWorkExitExecutor{TWork,TResult} .

Type parameters

  • TResult
    The successful executor result type.

Remarks

Only Succeeded(TResult) carries a result. The other factories require a bounded, identifier-safe application code and do not provide a result. An executor must return RetryBeforeEffect(string) only when it can prove the failure happened before a provider mutation. Read-only provider I/O is allowed; this boundary is about the provider effect, not the Durable effect permit.

Method

Succeeded

DurableWorkExit<TResult> Succeeded(TResult result)
Source

Creates a successful exit with a terminal result.

Parameters

  • result
    The non-null terminal result.

Returns

A successful exit.

Exceptions

  • ArgumentNullException
    Thrown when result is null.
Method

RetryBeforeEffect

DurableWorkExit<TResult> RetryBeforeEffect(string code)
Source

Creates an exit that proves the executor did not begin a provider mutation.

Parameters

  • code
    A bounded, identifier-safe application diagnostic code.

Returns

A no-effect retry fact for the provider to evaluate.

Remarks

This does not mean a Durable effect permit was absent. It asserts only that the executor did not begin an external provider mutation; read-only provider I/O is allowed. The provider still decides whether the fact is current and retryable.

Method

FailedTerminal

DurableWorkExit<TResult> FailedTerminal(string code)
Source

Creates an exit for a terminal local executor outcome.

Parameters

  • code
    A bounded, identifier-safe application diagnostic code.

Returns

A terminal-failure fact for the provider to evaluate.

Method

AmbiguousExternalOutcome

DurableWorkExit<TResult> AmbiguousExternalOutcome(string code)
Source

Creates an exit for an outcome whose external provider effect may be unknown.

Parameters

  • code
    A bounded, identifier-safe application diagnostic code.

Returns

An ambiguous-outcome fact for the provider to evaluate.

Property

Kind

DurableWorkExitKind Kind { get; } Source

Gets the fact that the executor returned.

Property

Code

string? Code { get; } Source

Gets the safe application code for a non-success exit, or null for success.

Property

Result

TResult? Result { get; } Source

Gets the successful result, or null for a non-success exit.

Type

DurableEncodedWorkExit

Source

Carries the encoded form of a DurableWorkExit{TResult} across the provider boundary.

Remarks

This type exposes no public constructor so providers cannot invent an arbitrary result/code combination. Its result is present only for DurableWorkExitKind.Succeeded , and its code is present only for a non-success exit.

Property

Kind

DurableWorkExitKind Kind { get; } Source

Gets the fact returned by the executor.

Property

Code

string? Code { get; } Source

Gets the safe application code for a non-success exit, or null for success.

Property

Result

DurableEncodedPayload? Result { get; } Source

Gets the encoded successful result, or null for a non-success exit.

Type

IDurableWorkExitExecutor<TWork, TResult>

Source

Executes one opt-in durable Work and returns an explicit provider-effect fact.

Type parameters

  • TWork
    The decoded Work payload type.
  • TResult
    The successful result type.

Remarks

Use this contract only when the executor can honestly return one of the four defined facts. Use IDurableWorkerExecutor{TWork,TResult} for the established success-or-exception contract.

Method

ExecuteAsync

ValueTask<DurableWorkExit<TResult>> ExecuteAsync(DurableWorkerEnvelope<TWork> work, CancellationToken cancellationToken = default)
Source

Executes the Work and returns its explicit exit fact.

Parameters

  • work
    The provider-validated Work envelope.
  • cancellationToken
    Token that cancels executor invocation.

Returns

The executor fact for the provider to translate.

Type

DurableWorkExitCompatibilityException

Source

Indicates that exit-aware Work was invoked through a legacy success-only provider boundary.

Remarks

The exception intentionally includes no result, application code, provider response, or nested exception. Its provider-facing handling remains the ordinary ambiguous-outcome path after a committed effect permit.

Type

DurableTraceActivity

Source

Creates durable runtime activities as new roots with an optional committed-cause link.

Method

StartRoot

DurableTraceActivityScope StartRoot(string operationName, ActivityKind kind, DurableTraceContext? committedCause)
Source

Starts a short-lived unparented durable execution with an optional committed-cause link.

Remarks

The returned scope must be disposed to end the Activity. If a caller ambient Activity exists, creation and disposal run without that execution context so the durable execution remains a root and the caller remains unchanged. Activity-listener failures are relayed synchronously to the caller.

Type

DurableTraceActivityScope

Source

Owns a durable root activity and preserves any caller ambient activity when it is disposed.

Remarks

When a caller has an ambient activity, .NET's ActivitySource has no root-start overload that both bypasses that parent and preserves it for the caller. This scope therefore starts and disposes the Activity on a ThreadPool callback without the caller's execution context. Consumers can add the fixed durable telemetry tags through Activity , but must dispose this scope rather than the exposed activity.

Property

Activity

Activity? Activity { get; } Source

Gets the short-lived root activity, or null when no listener sampled it.

Type

DurableScheduleId

Source

Identifies a durable schedule independently from work, Flow, command, and occurrence identities.

Method

New

DurableScheduleId New()
Source

Creates a cryptographically random schedule identifier.

Returns

A new schedule identifier.

Property

Value

string Value { get; } Source

Gets the opaque identifier value.

Type

DurableScheduleProblemCodes

Source

Stable problem codes returned by durable schedule operations.

Type

DurableScheduleCreateRequest

Source

Requests creation of one durable schedule.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the idempotent command identity.

Property

IdempotencyKey

string IdempotencyKey { get; } Source

Gets the caller retry key, unique within the owning scope.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the caller-selected schedule identity used for deterministic H expansion.

Property

Schedule

DurableSchedule Schedule { get; } Source

Gets the immutable timing and policy definition.

Property

Target

DurableScheduleTarget Target { get; } Source

Gets the registered durable work or Flow target.

Property

DisplayName

string? DisplayName { get; } Source

Gets the optional privacy-safe operator label.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed semantic command fingerprint.

Type

DurableScheduleUpdateRequest

Source

Requests replacement of a schedule definition and target under optimistic concurrency.

Remarks

A successful update increments the schedule generation and invalidates undispatched occurrences from the prior generation. An already-running prior-generation target may finish and continues to occupy its concurrency slot.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the idempotent command identity.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the schedule identity.

Property

ExpectedRevision

long ExpectedRevision { get; } Source

Gets the required authoritative revision.

Property

Schedule

DurableSchedule Schedule { get; } Source

Gets the replacement timing and policy definition.

Property

Target

DurableScheduleTarget Target { get; } Source

Gets the replacement registered target.

Property

DisplayName

string? DisplayName { get; } Source

Gets the replacement optional operator label.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed semantic command fingerprint.

Type

DurableScheduleCommand

Source

Requests a pause, resume, or delete under optimistic concurrency.

Property

Kind

DurableScheduleCommandKind Kind { get; } Source

Gets the operation whose schema is encoded in the fingerprint.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the idempotent command identity.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the schedule identity.

Property

ActorId

string ActorId { get; } Source

Gets the privacy-safe authorized actor identifier recorded in schedule history.

Property

ReasonCode

string ReasonCode { get; } Source

Gets the privacy-safe reason code recorded in schedule history.

Property

ExpectedRevision

long ExpectedRevision { get; } Source

Gets the required authoritative revision.

Property

Fingerprint

DurableCommandFingerprint Fingerprint { get; } Source

Gets the computed operation-specific semantic command fingerprint.

Type

DurableScheduleMutationResult

Source

Records the stable successful result of a schedule mutation.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the schedule identity.

Property

CommandId

DurableCommandId CommandId { get; } Source

Gets the accepted command identity.

Property

Code

DurableScheduleMutationCode Code { get; } Source

Gets the stable successful outcome.

Property

Generation

long Generation { get; } Source

Gets the active definition generation.

Property

Revision

long Revision { get; } Source

Gets the authoritative aggregate revision.

Property

CommittedAtUtc

DateTimeOffset CommittedAtUtc { get; } Source

Gets the authoritative store commit timestamp in UTC.

Type

DurableScheduleSnapshot

Source

Represents an authorized durable schedule query result.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the schedule identity.

Property

DisplayName

string? DisplayName { get; } Source

Gets the optional privacy-safe operator label.

Property

State

DurableScheduleState State { get; } Source

Gets the authoritative lifecycle state.

Property

Generation

long Generation { get; } Source

Gets the active definition generation.

Property

Revision

long Revision { get; } Source

Gets the aggregate revision.

Property

Schedule

DurableSchedule Schedule { get; } Source

Gets the immutable timing and policy definition.

Property

Target

DurableScheduleTargetSnapshot Target { get; } Source

Gets the registered target.

Property

NextOccurrenceUtc

DateTimeOffset? NextOccurrenceUtc { get; } Source

Gets the next materialized or evaluated UTC occurrence.

Type

DurableScheduleTargetSnapshot

Source

Describes the exact registered target and encoded input persisted for a schedule generation.

Remarks

Create and update use a typed DurableScheduleTarget . Queries return this encoded snapshot because a durable schedule can be inspected without loading arbitrary CLR types; applications may resolve its registered codec when they need to decode the approved input.

Property

Kind

DurableScheduleTargetKind Kind { get; } Source

Gets whether this target starts registered durable work or a registered Flow.

Property

RegisteredName

string RegisteredName { get; } Source

Gets the registered work name or Flow id.

Property

RegisteredVersion

string RegisteredVersion { get; } Source

Gets the immutable work or Flow version.

Property

Input

DurableEncodedPayload Input { get; } Source

Gets the allowlisted encoded work input or initial Flow context.

Property

ProviderSafety

DurableProviderSafety? ProviderSafety { get; } Source

Gets the snapshotted work-provider safety, or null for Flow targets.

Type

DurableScheduleListRequest

Source

Requests a bounded authorized schedule listing.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

PageSize

int PageSize { get; } Source

Gets the maximum number of schedules to return.

Property

ContinuationToken

string? ContinuationToken { get; } Source

Gets the opaque continuation token, or null for the first page.

Property

State

DurableScheduleState? State { get; } Source

Gets the optional authoritative lifecycle-state filter.

Property

RequiresRecoveryRelease

bool? RequiresRecoveryRelease { get; } Source

Gets the optional old-epoch nonterminal recovery filter.

Type

DurableScheduleListItem

Source

Represents one payload-free schedule inventory item.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the opaque schedule identity.

Property

DisplayName

string? DisplayName { get; } Source

Gets the optional privacy-safe display label.

Property

State

DurableScheduleState State { get; } Source

Gets the authoritative lifecycle state.

Property

Generation

long Generation { get; } Source

Gets the active definition generation.

Property

Revision

long Revision { get; } Source

Gets the aggregate revision required by mutations.

Property

ScheduleKind

DurableScheduleKind ScheduleKind { get; } Source

Gets the timing definition kind without its expression or payload.

Property

OverlapPolicy

ScheduleOverlapPolicy OverlapPolicy { get; } Source

Gets the immutable overlap policy.

Property

MisfirePolicy

ScheduleMisfirePolicy MisfirePolicy { get; } Source

Gets the immutable misfire policy.

Property

TargetKind

DurableScheduleTargetKind TargetKind { get; } Source

Gets the registered target surface.

Property

TargetName

string TargetName { get; } Source

Gets the registered target name.

Property

TargetVersion

string TargetVersion { get; } Source

Gets the registered target version.

Property

TargetProviderSafety

DurableProviderSafety? TargetProviderSafety { get; } Source

Gets Work provider safety, or null for a Flow target.

Property

NextOccurrenceUtc

DateTimeOffset? NextOccurrenceUtc { get; } Source

Gets the next nominal occurrence time.

Property

RequiresRecoveryRelease

bool RequiresRecoveryRelease { get; } Source

Gets whether this nonterminal schedule belongs to an older runtime epoch.

Type

DurableScheduleListResult

Source

Represents one bounded page of authorized payload-free schedule inventory items.

Property

Schedules

IReadOnlyList<DurableScheduleListItem> Schedules { get; } Source

Gets the immutable page of payload-free schedule inventory items.

Property

ContinuationToken

string? ContinuationToken { get; } Source

Gets the next opaque continuation token to return unchanged in a subsequent DurableScheduleListRequest , or null when this is the last page.

Type

DurableScheduleExplainRequest

Source

Requests a side-effect-free preview of upcoming occurrences before or after persistence.

Property

ScopeId

DurableScopeId ScopeId { get; } Source

Gets the trusted owning scope.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the schedule id used for deterministic H expansion.

Property

Schedule

DurableSchedule Schedule { get; } Source

Gets the definition to explain.

Property

AnchorUtc

DateTimeOffset AnchorUtc { get; } Source

Gets the preview anchor and acceptance-time approximation.

Property

OccurrenceCount

int OccurrenceCount { get; } Source

Gets the maximum number of upcoming occurrences to return.

Type

DurableScheduleExplanation

Source

Describes a side-effect-free evaluated schedule in operationally useful terms.

Remarks

Cron explanations form a discriminated union with Kind : when the kind is DurableScheduleKind.Cron , callers must supply CronDialect , CronGrammar , and IanaTimeZoneId together. For every non-Cron kind, callers must omit all three values. Partial Cron metadata and Cron metadata attached to a non-Cron explanation are invalid.

Property

ScheduleId

DurableScheduleId ScheduleId { get; } Source

Gets the schedule identity.

Property

Kind

DurableScheduleKind Kind { get; } Source

Gets the schedule shape.

Property

OverlapPolicy

ScheduleOverlapPolicy OverlapPolicy { get; } Source

Gets the effective overlap behavior.

Property

MisfirePolicy

ScheduleMisfirePolicy MisfirePolicy { get; } Source

Gets the effective downtime behavior.

Property

NextOccurrencesUtc

IReadOnlyList<DateTimeOffset> NextOccurrencesUtc { get; } Source

Gets upcoming evaluated instants normalized to UTC.

Property

CronDialect

CronDialect? CronDialect { get; } Source

Gets the required Cron dialect for a Cron explanation, or null otherwise.

Property

CronGrammar

CronGrammar? CronGrammar { get; } Source

Gets the required Cron grammar for a Cron explanation, or null otherwise.

Property

IanaTimeZoneId

string? IanaTimeZoneId { get; } Source

Gets the required IANA time zone for a Cron explanation, or null otherwise.

Property

EvaluatorVersion

string? EvaluatorVersion { get; } Source

Gets the pinned evaluator package version when applicable.

Property

JitterSeed

int? JitterSeed { get; } Source

Gets the deterministic H expansion seed when applicable.

Property

TimeZoneRulesFingerprint

string? TimeZoneRulesFingerprint { get; } Source

Gets the fingerprint of the time-zone rules used for this calculation.

Property

Notes

IReadOnlyList<string> Notes { get; } Source

Gets safe explanatory notes, including DST or acceptance-anchor caveats.

Type

IDurableScheduleClient

Source

Creates, inspects, explains, updates, pauses, resumes, and deletes durable schedules.

Remarks

The application must authorize the trusted DurableScopeId before invoking this client. Delete blocks every not-yet-started occurrence but does not revoke a target that already started. Pause preserves same-generation pending work but prevents it from starting until resume.

Method

CreateAsync

ValueTask<DurableOperationResult<DurableScheduleMutationResult>> CreateAsync(DurableScheduleCreateRequest request, CancellationToken cancellationToken = default)
Source

Durably creates a schedule or returns the exact prior idempotent outcome.

Method

UpdateAsync

ValueTask<DurableOperationResult<DurableScheduleMutationResult>> UpdateAsync(DurableScheduleUpdateRequest request, CancellationToken cancellationToken = default)
Source

Replaces the definition and target, incrementing the generation on success.

Method

ApplyLifecycleCommandAsync

ValueTask<DurableOperationResult<DurableScheduleMutationResult>> ApplyLifecycleCommandAsync(DurableScheduleCommand command, CancellationToken cancellationToken = default)
Source

Applies the pause, resume, delete, or recovery-release operation selected by the command kind.

Parameters

  • command
    Lifecycle command whose DurableScheduleCommand.Kind is the sole operation selector.
  • cancellationToken
    Token that cancels the client call.

Returns

The accepted mutation result or an actionable durable problem.

Remarks

Pause blocks new starts without canceling an already-running target; resume makes preserved pending work eligible; delete invalidates every target that has not started; recovery release rebinds restore-fenced state to the active runtime epoch. Callers must not dispatch the same command through a second method-name operation selector.

Method

GetAsync

ValueTask<DurableOperationResult<DurableScheduleSnapshot>> GetAsync(DurableScopeId scopeId, DurableScheduleId scheduleId, CancellationToken cancellationToken = default)
Source

Gets one authorized schedule snapshot.

Method

ListAsync

ValueTask<DurableOperationResult<DurableScheduleListResult>> ListAsync(DurableScheduleListRequest request, CancellationToken cancellationToken = default)
Source

Lists one bounded authorized page of schedule snapshots.

Method

ExplainNextOccurrencesAsync

ValueTask<DurableOperationResult<DurableScheduleExplanation>> ExplainNextOccurrencesAsync(DurableScheduleExplainRequest request, CancellationToken cancellationToken = default)
Source

Explains upcoming occurrences and effective policy without mutating runtime state.

Type

ScheduleOverlapPolicy

Source

Describes how a schedule handles overlapping occurrences.

Remarks

QueueOne is the safe default: it bounds backlog growth while ensuring that an overlap causes one follow-up run after the active run reaches any terminal state. Use Skip only when losing an occurrence is acceptable. AllowConcurrent(int) should be reserved for targets that are safe to execute in parallel.

Method

AllowConcurrent

ScheduleOverlapPolicy AllowConcurrent(int maximumConcurrentRuns)
Source

Creates a bounded concurrent-execution policy.

Parameters

  • maximumConcurrentRuns
    Maximum simultaneously active occurrences.

Returns

A bounded concurrent-execution policy.

Exceptions

  • ArgumentOutOfRangeException
    Thrown when maximumConcurrentRuns is less than two.
Property

QueueOne

ScheduleOverlapPolicy QueueOne { get; } Source

Gets the default policy, which retains one coalesced pending occurrence.

Property

Skip

ScheduleOverlapPolicy Skip { get; } Source

Gets the policy that discards occurrences which overlap an active run.

Property

Kind

ScheduleOverlapPolicyKind Kind { get; } Source

Gets the policy behavior.

Property

MaximumConcurrentRuns

int MaximumConcurrentRuns { get; } Source

Gets the maximum number of active runs. This value is greater than one only for ScheduleOverlapPolicyKind.AllowConcurrent .

Type

ScheduleMisfirePolicy

Source

Describes how a schedule recovers occurrences missed during downtime.

Remarks

RunOnce is the safe default and never enumerates every tick in a long missed range. Bounded catch-up is appropriate only when each nominal occurrence carries distinct business meaning. The runtime may apply a lower per-pass evaluation budget than MaximumOccurrences and continue recovery in a later pass.

Method

CatchUp

ScheduleMisfirePolicy CatchUp(int maximumOccurrences)
Source

Creates an oldest-first bounded catch-up policy.

Parameters

  • maximumOccurrences
    Maximum missed occurrences to materialize before advancing to the future.

Returns

A bounded catch-up policy.

Exceptions

  • ArgumentOutOfRangeException
    Thrown when maximumOccurrences is not positive.
Property

RunOnce

ScheduleMisfirePolicy RunOnce { get; } Source

Gets the default policy, which coalesces a missed range into one recovery run.

Property

Skip

ScheduleMisfirePolicy Skip { get; } Source

Gets the policy that advances past missed occurrences without running them.

Property

Kind

ScheduleMisfirePolicyKind Kind { get; } Source

Gets the misfire behavior.

Property

MaximumOccurrences

int MaximumOccurrences { get; } Source

Gets the maximum number of missed occurrences that may be materialized by one complete catch-up operation.

Type

DurableSchedule

Source

Describes when a durable target should run and how overlap and downtime are handled.

Remarks

Definitions are immutable values. The default composition is ScheduleOverlapPolicy.QueueOne plus ScheduleMisfirePolicy.RunOnce . Use WithOverlap or WithMisfire to opt a particular schedule into different behavior.

Method

At

DurableAtSchedule At(DateTimeOffset at)
Source

Creates a schedule that runs once at an absolute instant.

Parameters

  • at
    The instant to run. It is normalized to UTC.

Returns

An absolute one-time schedule.

Method

After

DurableAfterSchedule After(TimeSpan delay)
Source

Creates a schedule that runs once after durable acceptance.

Parameters

  • delay
    Positive elapsed delay from the authoritative store acceptance timestamp.

Returns

A delayed one-time schedule.

Method

Every

DurableEverySchedule Every(TimeSpan interval, DateTimeOffset? anchor = null)
Source

Creates an elapsed-UTC recurring schedule.

Parameters

  • interval
    Positive elapsed interval.
  • anchor
    Optional absolute anchor. When omitted, the runtime uses the durable acceptance transaction timestamp.

Returns

An elapsed-UTC interval schedule.

Remarks

Use Cron for calendar-time recurrence or daylight-saving-aware wall-clock behavior.

Method

Cron

DurableCronSchedule Cron(string expression, string ianaTimeZoneId, CronGrammar grammar = CronGrammar.Standard)
Source

Creates a CronosV1 calendar schedule.

Parameters

  • expression
    Raw Cronos expression. It is persisted without semantic rewriting.
  • ianaTimeZoneId
    IANA time-zone identifier, for example America/New_York .
  • grammar
    Five-field or seconds-inclusive grammar.

Returns

A CronosV1 schedule.

Remarks

The selected provider validates the expression and time zone before accepting the schedule. Cronos H fields are expanded from a stable cryptographic hash of the schedule id.

Method

WithOverlap

DurableSchedule WithOverlap(ScheduleOverlapPolicy policy)
Source

Returns a copy with the supplied overlap policy.

Parameters

  • policy
    Per-schedule overlap behavior.

Returns

A schedule with the new policy.

Method

WithMisfire

DurableSchedule WithMisfire(ScheduleMisfirePolicy policy)
Source

Returns a copy with the supplied downtime recovery policy.

Parameters

  • policy
    Per-schedule misfire behavior.

Returns

A schedule with the new policy.

Property

Kind

DurableScheduleKind Kind { get; } Source

Gets the persisted schedule shape.

Property

OverlapPolicy

ScheduleOverlapPolicy OverlapPolicy { get; init; } Source

Gets the effective overlap policy. The default is ScheduleOverlapPolicy.QueueOne .

Property

MisfirePolicy

ScheduleMisfirePolicy MisfirePolicy { get; init; } Source

Gets the effective downtime policy. The default is ScheduleMisfirePolicy.RunOnce .

Type

DurableAtSchedule

Source

A one-time schedule at an absolute UTC instant.

Property

AtUtc

DateTimeOffset AtUtc { get; } Source

Gets the absolute run instant, normalized to UTC.

Type

DurableAfterSchedule

Source

A one-time delay anchored to the authoritative store timestamp of the durable acceptance transaction.

Property

Delay

TimeSpan Delay { get; } Source

Gets the elapsed delay from durable acceptance.

Type

DurableEverySchedule

Source

An elapsed-UTC recurring schedule.

Property

Interval

TimeSpan Interval { get; } Source

Gets the elapsed UTC interval.

Property

AnchorUtc

DateTimeOffset? AnchorUtc { get; } Source

Gets the explicit UTC anchor, or null to anchor at durable acceptance.

Type

DurableCronSchedule

Source

A calendar schedule evaluated by a versioned Cronos dialect in an IANA time zone.

Property

Expression

string Expression { get; } Source

Gets the raw expression exactly as supplied.

Property

IanaTimeZoneId

string IanaTimeZoneId { get; } Source

Gets the IANA time-zone identifier.

Property

Dialect

CronDialect Dialect { get; } Source

Gets the versioned public cron semantics.

Property

Grammar

CronGrammar Grammar { get; } Source

Gets the persisted five- or six-field grammar mode.

Type

DurableScheduleTarget

Source

Describes the registered durable target started by each schedule occurrence.

Remarks

Targets encode typed input values immediately through an explicitly supplied durable codec. Persisted schedules never serialize executable delegates or resolve a target from a CLR type name. Registered names and versions accept only ASCII letters, digits, hyphens, underscores, periods, and colons. Empty, whitespace-only, control-containing, and other-character values are rejected.

Method

Work

DurableWorkScheduleTarget<TWork> Work<TWork>(string workName, string workVersion, TWork input, IDurablePayloadCodec<TWork> codec)
Source

Creates a target for a registered durable work type.

Type parameters

  • TWork
    Registered work input type.

Parameters

  • workName
    Stable registry name of at most 200 durable-identifier characters; this is not a CLR assembly-qualified name.
  • workVersion
    Immutable registered work contract version of at most 100 durable-identifier characters.
  • input
    Typed input encoded immediately.
  • codec
    The exact registered durable codec for the input.

Returns

A typed durable work target.

Method

Flow

DurableFlowScheduleTarget<TContext> Flow<TContext>(string flowId, string version, TContext initialContext, IDurablePayloadCodec<TContext> codec)
Source

Creates a target for an immutable registered Flow version.

Type parameters

  • TContext
    Registered Flow context type.

Parameters

  • flowId
    Stable Flow identifier of at most 200 durable-identifier characters.
  • version
    Immutable Flow graph version of at most 100 durable-identifier characters.
  • initialContext
    Typed initial context encoded immediately.
  • codec
    The exact registered durable codec for the context.

Returns

A typed durable Flow target.

Property

Kind

DurableScheduleTargetKind Kind { get; } Source

Gets the target subsystem.

Property

RegisteredName

string RegisteredName { get; } Source

Gets the provider-readable registered Work name or Flow id.

Property

RegisteredVersion

string RegisteredVersion { get; } Source

Gets the provider-readable immutable Work or Flow version.

Property

EncodedInput

DurableEncodedPayload EncodedInput { get; } Source

Gets the immutable encoded input a provider persists without inspecting the CLR generic type.

Type

DurableWorkScheduleTarget<TWork>

Source

A schedule target that enqueues a registered durable work input.

Type parameters

  • TWork
    Registered work input type.
Property

WorkName

string WorkName { get; } Source

Gets the stable registered work name, limited to 200 durable-identifier characters.

Property

WorkVersion

string WorkVersion { get; } Source

Gets the immutable registered work contract version, limited to 100 durable-identifier characters.

Property

Codec

IDurablePayloadCodec<TWork> Codec { get; } Source

Gets the exact codec used to encode the immutable target input.

Property

EncodedInputPayload

DurableEncodedPayload EncodedInputPayload { get; } Source

Gets the immutable encoded target input.

Type

DurableFlowScheduleTarget<TContext>

Source

A schedule target that starts an immutable registered Flow version.

Type parameters

  • TContext
    Registered Flow context type.
Property

FlowId

string FlowId { get; } Source

Gets the stable Flow identifier, limited to 200 durable-identifier characters.

Property

Version

string Version { get; } Source

Gets the immutable Flow graph version, limited to 100 durable-identifier characters.

Property

Codec

IDurablePayloadCodec<TContext> Codec { get; } Source

Gets the exact codec used to encode the immutable initial context.

Property

EncodedInitialContext

DurableEncodedPayload EncodedInitialContext { get; } Source

Gets the immutable encoded initial context.

Enum

DurableCommandFingerprintMatch

Source

Compares a replayed command with a previously persisted semantic fingerprint.

Enum

DurableProviderSafety

Source

Declares how the runtime may recover after an external provider outcome becomes unknown.

Enum

DurableWorkState

Source

Represents the authoritative lifecycle state of a durable work aggregate.

Enum

DurableWorkAcceptanceKind

Source

Indicates whether a durable acceptance was newly committed or deduplicated.

Enum

DurableFlowState

Source

Represents the authoritative lifecycle state of a durable Flow instance.

Enum

DurableFlowCommandOutcome

Source

Describes the result of a durable Flow command.

Enum

DurableTraceContextStatus

Source

Classifies the safely handled state of ambient or persisted durable trace context.

Enum

DurableEffectReconciliationKind

Source

Identifies what a side-effect-free provider reconciliation established.

Enum

DurableDataClassification

Source

Classifies data that has been explicitly approved for durable persistence.

Enum

DurableWorkExitKind

Source

Describes the fact an exit-aware durable executor can prove after it is invoked.

Remarks

An exit is not a durable Work state transition. The provider remains authoritative for permits, claims, cancellation, retry timing, and the resulting persisted state.

Enum

DurableScheduleMutationCode

Source

Identifies the stable successful outcome of a schedule mutation.

Enum

DurableScheduleState

Source

Represents the authoritative lifecycle state of a durable schedule.

Enum

DurableScheduleCommandKind

Source

Identifies the operation represented by a shared schedule lifecycle command.

Enum

ScheduleOverlapPolicyKind

Source

Identifies how a schedule behaves when an occurrence is due while a prior occurrence is still running.

Enum

ScheduleMisfirePolicyKind

Source

Identifies how occurrences missed while the scheduler was unavailable are recovered.

Enum

DurableScheduleKind

Source

Identifies the persisted shape of a durable schedule.

Enum

CronDialect

Source

Identifies the versioned public semantics used to evaluate a cron expression.

Remarks

A behavior-changing Cronos upgrade must introduce a new dialect or an explicit persisted-schedule migration. It must never silently reinterpret a schedule stored as CronosV1 .

Enum

CronGrammar

Source

Identifies whether a CronosV1 expression contains five fields or includes a leading seconds field.

Enum

DurableScheduleTargetKind

Source

Identifies the durable subsystem started by a schedule occurrence.