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

Workers

Namespaces

Type

DurableWorkerExecutionIdentity

Source

Separates immutable provider-operation identity from retry and lease generations.

Remarks

The provider key is derived from ActivityId , never from an attempt or lease. A new attempt or lease therefore cannot silently create a second logical provider operation.

Method

CreateInitial

DurableWorkerExecutionIdentity CreateInitial(string activityId, long leaseGeneration, long scopeGeneration, string runtimeEpoch)
Source

Creates the first fenced execution identity for one logical provider operation.

Parameters

  • activityId
    Stable activity identity; this also becomes the immutable provider key.
  • leaseGeneration
    Positive provider-authoritative lease generation.
  • scopeGeneration
    Positive provider-authoritative scope generation.
  • runtimeEpoch
    Non-empty opaque runtime recovery epoch. Epoch values are not ordered.

Returns

An identity whose attempt number is one.

Exceptions

  • ArgumentException
    Thrown when required text is empty or invalid.
  • ArgumentOutOfRangeException
    Thrown when a generation is not positive.
Method

Create

DurableWorkerExecutionIdentity Create(string activityId, int attemptNumber, long leaseGeneration, long scopeGeneration, string runtimeEpoch)
Source

Creates a fenced identity from provider-authoritative attempt and generation values.

Parameters

  • activityId
    Stable activity identity; this also becomes the immutable provider key.
  • attemptNumber
    Positive provider-authoritative attempt number.
  • leaseGeneration
    Positive provider-authoritative lease generation.
  • scopeGeneration
    Positive provider-authoritative scope generation.
  • runtimeEpoch
    Non-empty opaque runtime recovery epoch. Epoch values are not ordered.

Returns

A validated execution identity.

Exceptions

  • ArgumentException
    Thrown when required text is empty or invalid.
  • ArgumentOutOfRangeException
    Thrown when an attempt or generation is not positive.
Method

Advance

DurableWorkerExecutionIdentity Advance(int attemptNumber, long leaseGeneration, long scopeGeneration, string runtimeEpoch)
Source

Advances retry and fencing generations while retaining the immutable provider-operation identity.

Parameters

  • attemptNumber
    Attempt number, which must not be lower than the current value.
  • leaseGeneration
    Lease generation, which must not be lower than the current value.
  • scopeGeneration
    Scope generation, which must not be lower than the current value.
  • runtimeEpoch
    Non-empty opaque runtime recovery epoch. Epoch values are not ordered.

Returns

A new identity that preserves ActivityId and ProviderKey .

Exceptions

  • ArgumentException
    Thrown when no field changes or required text is empty or invalid.
  • ArgumentOutOfRangeException
    Thrown when an attempt or generation regresses.
Property

ActivityId

string ActivityId { get; } Source

Gets the immutable activity identity.

Property

AttemptNumber

int AttemptNumber { get; } Source

Gets the monotonically increasing execution attempt number.

Property

LeaseGeneration

long LeaseGeneration { get; } Source

Gets the exact lease generation that authorized execution.

Property

ScopeGeneration

long ScopeGeneration { get; } Source

Gets the owning scope lifecycle generation.

Property

RuntimeEpoch

string RuntimeEpoch { get; } Source

Gets the out-of-band runtime recovery epoch.

Property

ProviderKey

string ProviderKey { get; } Source

Gets the immutable activity-derived provider idempotency key.

Type

DurableWorkerMetadataSafety

Source

Validates the privacy-safe metadata and diagnostic text contract used by durable worker envelopes and diagnostics.

Remarks

The validator intentionally uses conservative name and value checks for the metadata channel. Store raw business payloads in app-owned data stores, not in worker metadata. Metadata should contain opaque ids, reason codes, bounded counts, and classified safe labels that can appear in logs or repair dashboards.

Method

CopySafe

IReadOnlyDictionary<string, string> CopySafe(IReadOnlyDictionary<string, string>? metadata, string paramName = "metadata")
Source

Validates a metadata dictionary and returns a copied read-only dictionary.

Parameters

  • metadata
    Metadata to validate. A null value is treated as an empty dictionary.
  • paramName
    Caller parameter name used in thrown validation exceptions.

Returns

A read-only copy of the supplied safe metadata.

Exceptions

  • ArgumentException
    Thrown when a key or value is null, empty, or whitespace.
  • DurableWorkerUnsafeMetadataException
    Thrown when a key or value appears unsafe.
Method

EnsureSafe

void EnsureSafe(IReadOnlyDictionary<string, string>? metadata, string paramName = "metadata")
Source

Validates that metadata is safe for diagnostics, logs, durable facts, and projection repair reports.

Parameters

  • metadata
    Metadata to validate. A null value is treated as an empty dictionary.
  • paramName
    Caller parameter name used in thrown validation exceptions.

Exceptions

  • ArgumentException
    Thrown when a key or value is null, empty, or whitespace.
  • DurableWorkerUnsafeMetadataException
    Thrown when a key or value appears unsafe.
Method

CopySafeDiagnosticText

string CopySafeDiagnosticText(string value, string label, string paramName)
Source

Validates diagnostic text and returns a trimmed safe value.

Parameters

  • value
    Diagnostic text to validate.
  • label
    Human-readable field label used in validation messages.
  • paramName
    Caller parameter name used in thrown validation exceptions.

Returns

The trimmed diagnostic text.

Exceptions

  • ArgumentException
    Thrown when value is null, empty, or whitespace.
  • DurableWorkerUnsafeMetadataException
    Thrown when value appears unsafe.
Type

IDurableWorkerProjectionContract<TWork, TResult, TProjection>

Source

Records durable worker execution facts and repairs visible projections from those facts.

Type parameters

  • TWork
    Type of work claimed by the chain.
  • TResult
    Type of terminal execution result.
  • TProjection
    Type of visible projection repaired from durable facts.

Remarks

Implementations are app-owned and persistence-specific. The contract separates side-effect execution from projection repair: TryClaimAsync decides whether executor activity may run, CompleteAsync records a terminal fact, and reconciliation methods update projections without re-running executor activity.

Method

TryClaimAsync

ValueTask<DurableWorkerEnvelope<TWork>> TryClaimAsync(TWork work, DurableWorkerCorrelation correlation, CancellationToken cancellationToken = default)
Source

Attempts to claim a work item before executor activity is scheduled.

Parameters

  • work
    Typed work payload.
  • correlation
    Correlation identifiers for the claim.
  • cancellationToken
    Token that cancels claim evaluation.

Returns

A claim envelope. DurableWorkerProjectionOutcome.Claimed means executor activity may be scheduled; duplicate, stale, conflict, and unrecoverable outcomes must not schedule executor activity.

Method

CompleteAsync

ValueTask<DurableWorkerEnvelope<TResult>> CompleteAsync(TWork work, TResult result, DurableWorkerCorrelation correlation, CancellationToken cancellationToken = default)
Source

Records a terminal execution fact after executor activity completes.

Parameters

  • work
    Typed work payload.
  • result
    Terminal result produced by executor activity.
  • correlation
    Correlation identifiers for the completion fact.
  • cancellationToken
    Token that cancels completion recording.

Returns

A completion envelope. Successful completion should lead to projection repair; duplicate completions must not trigger projection repair.

Method

ReconcileProjectionAsync

ValueTask<DurableWorkerEnvelope<TProjection>> ReconcileProjectionAsync(TWork work, TResult result, DurableWorkerCorrelation correlation, CancellationToken cancellationToken = default)
Source

Repairs the visible projection for one terminal execution fact.

Parameters

  • work
    Typed work payload associated with the terminal fact.
  • result
    Terminal result used to derive the visible projection.
  • correlation
    Correlation identifiers for the repair attempt.
  • cancellationToken
    Token that cancels projection repair.

Returns

A projection envelope describing repaired, noop, stale, conflict, or unrecoverable repair behavior.

Method

ReconcilePendingProjectionsAsync

IAsyncEnumerable<DurableWorkerEnvelope<TProjection>> ReconcilePendingProjectionsAsync(DurableWorkerProjectionRepairRequest request, CancellationToken cancellationToken = default)
Source

Repairs a bounded batch of stale or missing projections from durable terminal facts.

Parameters

  • request
    Bounded projection repair request.
  • cancellationToken
    Token that cancels projection repair enumeration.

Returns

Projection repair envelopes for the bounded repair pass.

Type

DurableWorkerProjectionRepairRequest

Source

Describes a bounded projection repair pass over durable worker completion facts.

Remarks

Repair requests are intentionally bounded. Hosts should use small batches and repeatable cursors rather than unbounded background scans. The contract repairs projections only; it must not re-run executor side effects.

Property

Now

DateTimeOffset Now { get; } Source

Gets the clock value used to evaluate stale projections.

Property

MaxStaleness

TimeSpan MaxStaleness { get; } Source

Gets the maximum acceptable projection staleness before repair is attempted.

Property

MaxItems

int MaxItems { get; } Source

Gets the maximum number of pending projection repairs to inspect or return.

Type

AppSurfaceWorkersModule

Source

Registers the passive AppSurface durable worker contract surface.

Remarks

The module intentionally does not register queues, storage providers, background services, Durable Task workers, EF Core contexts, Postgres connections, endpoints, or authentication handlers. Host applications own runtime infrastructure and persistence; this package provides the shared worker contracts.

Type

DurableWorkerCorrelation

Source

Correlates one durable worker operation across claims, executor activity, completion facts, and projection repair.

Remarks

Correlation values should be stable safe identifiers. Do not use provider URLs, raw payload ids that expose private content, credentials, email bodies, prompts, or model output as correlation values.

Method

RequireText

string RequireText(string value, string paramName)
Source

Validates and trims a durable worker identifier.

Parameters

  • value
    Identifier value to validate.
  • paramName
    Caller parameter name used in thrown validation exceptions.

Returns

The trimmed identifier value.

Exceptions

  • ArgumentException
    Thrown when value is null, empty, or whitespace.
Property

WorkerName

string WorkerName { get; } Source

Gets the stable worker or chain name.

Property

WorkId

string WorkId { get; } Source

Gets the stable app-owned work identifier.

Property

InstanceId

string InstanceId { get; } Source

Gets the durable runtime instance identifier.

Property

AttemptId

string AttemptId { get; } Source

Gets the attempt, fence, or generation identifier.

Type

DurableWorkerEnvelope<TPayload>

Source

Carries a durable worker outcome, correlation identifiers, optional typed payload, and privacy-safe metadata.

Type parameters

  • TPayload
    Typed payload associated with the outcome.

Remarks

Envelopes are the stable boundary between app-owned worker contracts and host/runtime adapters. They describe what happened; they do not execute side effects, persist data, or schedule runtime work by themselves.

Method

CreateNative

DurableWorkerEnvelope<TPayload> CreateNative(DurableWorkerProjectionOutcome outcome, string reasonCode, DurableWorkerRetryability retryability, DurableWorkerCorrelation correlation, DurableWorkerExecutionIdentity executionIdentity, TPayload? payload = default, IReadOnlyDictionary<string, string>? metadata = null, DurableWorkerDiagnostic? diagnostic = null)
Source

Creates a native-runtime envelope with required execution and fencing identity.

Parameters

  • outcome
    Defined observable worker outcome.
  • reasonCode
    Stable machine-readable reason code that is sanitized with diagnostic-text safety rules.
  • retryability
    Defined retry classification for the outcome.
  • correlation
    Correlation identifiers for the operation.
  • executionIdentity
    Required native-runtime execution and fencing identity.
  • payload
    Optional typed payload associated with the outcome.
  • metadata
    Optional safe metadata values.
  • diagnostic
    Optional safe diagnostic details.

Returns

A validated native-runtime envelope.

Exceptions

  • ArgumentException
    Thrown when required text or metadata is invalid.
  • ArgumentNullException
    Thrown when correlation or executionIdentity is null.
  • ArgumentOutOfRangeException
    Thrown when outcome or retryability is not defined.
  • DurableWorkerUnsafeMetadataException
    Thrown when metadata appears unsafe.
Property

Outcome

DurableWorkerProjectionOutcome Outcome { get; } Source

Gets the observable worker outcome.

Property

ReasonCode

string ReasonCode { get; } Source

Gets the stable machine-readable reason code.

Property

Retryability

DurableWorkerRetryability Retryability { get; } Source

Gets the retry classification for this outcome.

Property

Correlation

DurableWorkerCorrelation Correlation { get; } Source

Gets correlation identifiers for the operation.

Property

Payload

TPayload? Payload { get; } Source

Gets the optional typed payload associated with the outcome.

Property

Metadata

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

Gets sanitized metadata for logs, durable facts, and projection repair reports.

Property

Diagnostic

DurableWorkerDiagnostic? Diagnostic { get; } Source

Gets optional sanitized diagnostic details.

Property

ExecutionIdentity

DurableWorkerExecutionIdentity? ExecutionIdentity { get; } Source

Gets the native durable execution identity when the envelope was created by a fencing-aware runtime.

Remarks

Legacy adapters may leave this value null . Native runtimes must populate it before invoking a provider executor; projection repair must not use it as authority to repeat an external effect.

Type

DurableWorkerUnsafeMetadataException

Source

Thrown when durable worker diagnostics or metadata contain values that are unsafe to persist or publish.

Remarks

AppSurface worker metadata is designed for logs, projections, and repair reports. It must use stable identifiers, reason codes, and sanitized values rather than raw source payloads, credentials, OAuth tokens, provider URLs, model output, prompts, message bodies, attachments, or unclassified sensitive text.

Type

DurableWorkerDiagnostic

Source

Privacy-safe diagnostic details for a durable worker outcome.

Remarks

Diagnostics are suitable for logs, repair dashboards, and durable records. Keep them explanatory but sanitized: include stable codes, cause and fix guidance, safe counts, and opaque ids. Do not include raw provider payloads, tokens, credentials, prompts, model output, email bodies, attachments, or unclassified sensitive values.

Property

Code

string Code { get; } Source

Gets the stable machine-readable diagnostic 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 fix guidance.

Property

Retryability

DurableWorkerRetryability Retryability { get; } Source

Gets the retry classification for this diagnostic.

Property

Metadata

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

Gets sanitized diagnostic metadata.

Type

IDurableWorkerExecutor<TWork, TResult>

Source

Executes the side-effecting portion of a durable worker chain.

Type parameters

  • TWork
    Type of work claimed by the chain.
  • TResult
    Type of terminal result produced by executor activity.

Remarks

Executors are expected to run inside host-owned durable activities, queue handlers, or equivalent runtime work. They should not be invoked by projection repair paths. Projection repair uses durable completion facts through IDurableWorkerProjectionContract{TWork,TResult,TProjection} instead.

Method

ExecuteAsync

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

Runs the side-effecting worker activity for a claimed work item.

Parameters

  • work
    Claimed work envelope that authorized executor scheduling.
  • cancellationToken
    Token that cancels executor work.

Returns

The terminal result that should be recorded with the projection contract.

Enum

DurableWorkerRetryability

Source

Describes whether a durable worker outcome should be retried automatically.

Remarks

These values are intended for workflow decisions and diagnostics. They do not execute retries directly; host adapters translate the value into the chosen runtime's retry, timer, or operator-alert behavior.

Enum

DurableWorkerProjectionOutcome

Source

Identifies the observable result of durable worker claim, completion, or projection repair work.

Remarks

The numeric values are part of the public worker contract. Do not reorder, remove, renumber, or reuse values. Additive values must be appended with explicit numbers and documented migration behavior.