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

Durable

Namespaces

Type

DurableTraceContextValidation

Source

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

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

  • TSuccessful 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

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

DurableTraceContext

Source

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

Parameters

  • TraceParentThe normalized version-00 W3C parent persisted only as a propagation input.
  • TraceIdThe normalized trace identifier parsed from TraceParent.
  • SpanIdThe normalized span identifier parsed from TraceParent.
  • TraceFlagsThe normalized W3C trace flags parsed from TraceParent.
  • TraceStateThe optional bounded opaque state, or null when it was absent or rejected.
  • CorrelationTokenThe 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

  • activityThe 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.

Enum

DurableTraceContextStatus

Source

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

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

  • persistedPreviously 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

  • ArgumentNullExceptionThrown 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

  • schemaIdVersioned canonical encoding schema.
  • valuesValues in their contract-defined order; null values receive an explicit marker.

Returns

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

Exceptions

  • ArgumentExceptionThrown when schemaId is invalid.
  • InvalidOperationExceptionThrown 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 the first supported publication or 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.

Enum

DurableCommandFingerprintMatch

Source

Compares a replayed command with a previously persisted semantic fingerprint.

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

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

  • otherPayload 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

  • TRegistered 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

  • TRegistered 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.

Enum

DurableDataClassification

Source

Classifies data that has been explicitly approved for durable persistence.

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

  • registrationExact durable Flow registration to evaluate.
  • inputPersisted node input to replay twice.
  • payloadCodecsExact allowlisted payload codec registry.
  • cancellationTokenToken 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

  • registrationExact durable Flow registration to evaluate.
  • inputPersisted node input to replay twice.
  • payloadCodecsExact allowlisted payload codec registry.
  • cancellationTokenToken that cancels either evaluation.

Returns

The deterministic comparison report.

Exceptions

  • InvalidOperationExceptionThrown when the two canonical decisions differ.
Type

DurableTraceDiagnostics

Source

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

Type

DurableEffectReconciliation<TResult>

Source

Strongly typed result from a provider reconciliation read.

Type Parameters

  • TResultRegistered 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

  • TWorkRegistered work type.
  • TResultRegistered 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.

Enum

DurableEffectReconciliationKind

Source

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

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

  • cancellationTokenToken that cancels executor invocation.

Returns

The registered codec's encoded terminal result.

Remarks

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

  • servicesApplication service provider used to resolve the executor.
  • workProvider-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

  • servicesApplication service provider used to resolve the executor.
  • workProvider-validated execution context.
  • cancellationTokenToken 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

  • servicesApplication service provider used to resolve the reconciler.
  • workProvider-validated execution context.
  • cancellationTokenToken that cancels reconciliation.

Returns

Applied, not-applied, or unknown provider truth.

Exceptions

  • InvalidOperationExceptionThrown when no reconciler is registered or reconciliation returns invalid data.
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

  • TWorkExecutor work type.
  • TResultExecutor terminal result type.
  • TExecutorRegistered executor implementation.
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

  • workNameExact registered Work name.
  • workVersionExact immutable Work version.

Returns

The matching registration.

Exceptions

  • ArgumentExceptionThrown when an identifier is invalid.
  • InvalidOperationExceptionThrown when no exact registration exists.
Type

DurableWorkRegistry

Source

Immutable registry of durable work registrations built during host startup.

Type

DurableServiceCollectionExtensions

Source

Registration helpers for typed durable worker executors.

Method

AddDurableWork

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

  • servicesService collection to configure.
  • workNameStable Work name.
  • workVersionImmutable Work version.
  • providerSafetyExternal-effect ambiguity policy; use the reconciler overload for reconcile-before-retry.
  • workCodecAllowlisted Work codec.
  • resultCodecAllowlisted terminal result codec.

Returns

The same service collection.

Exceptions

  • ArgumentExceptionThrown when the registration is invalid.
  • ArgumentNullExceptionThrown when services or a codec is null.
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

  • servicesService collection to configure.
  • workNameStable Work name.
  • workVersionImmutable Work version.
  • workCodecAllowlisted Work codec.
  • resultCodecAllowlisted terminal result codec.

Returns

The same service collection.

Exceptions

  • ArgumentExceptionThrown when the registration is invalid.
  • ArgumentNullExceptionThrown 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

  • TContextFlow context type.

Parameters

  • servicesApplication service collection.
  • definitionImmutable Flow definition and version.
  • contextCodecAllowlisted durable context codec.
  • implementationVersionApplication-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.
  • activityBindingsOptional registered activity bindings used by the definition.
  • eventBindingsOptional typed external-event bindings used by the definition.
  • evaluatorOptional one-node evaluator override.

Returns

The same service collection.

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

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.

Enum

DurableFlowState

Source

Represents the authoritative lifecycle state of a durable Flow instance.

Enum

DurableFlowCommandOutcome

Source

Describes the result of a durable Flow command.

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.

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.

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

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.

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

  • TPayloadAllowlisted 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

  • TContextFlow 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.

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.

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

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

  • maximumConcurrentRunsMaximum simultaneously active occurrences.

Returns

A bounded concurrent-execution policy.

Exceptions

  • ArgumentOutOfRangeExceptionThrown 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

  • maximumOccurrencesMaximum missed occurrences to materialize before advancing to the future.

Returns

A bounded catch-up policy.

Exceptions

  • ArgumentOutOfRangeExceptionThrown 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.

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.

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

  • TWorkRegistered work input type.

Parameters

  • workNameStable registry name of at most 200 durable-identifier characters; this is not a CLR assembly-qualified name.
  • workVersionImmutable registered work contract version of at most 100 durable-identifier characters.
  • inputTyped input encoded immediately.
  • codecThe 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

  • TContextRegistered Flow context type.

Parameters

  • flowIdStable Flow identifier of at most 200 durable-identifier characters.
  • versionImmutable Flow graph version of at most 100 durable-identifier characters.
  • initialContextTyped initial context encoded immediately.
  • codecThe 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

  • TWorkRegistered 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

  • TContextRegistered 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

DurableScheduleTargetKind

Source

Identifies the durable subsystem started by a schedule occurrence.

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

  • atThe 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

  • delayPositive 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

  • intervalPositive elapsed interval.
  • anchorOptional 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

  • expressionRaw Cronos expression. It is persisted without semantic rewriting.
  • ianaTimeZoneIdIANA time-zone identifier, for example America/New_York.
  • grammarFive-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

  • policyPer-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

  • policyPer-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.

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.

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

  • commandLifecycle command whose DurableScheduleCommand.Kind is the sole operation selector.
  • cancellationTokenToken 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.

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.

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.