AppSurface Search
API Reference

Testing

Type

DurableWorkDefinitionObservation

Source

Immutable public facts observed from a typed Work definition.

Method

Capture

DurableWorkDefinitionObservation Capture<TWork, TResult>(DurableWorkDefinition<TWork, TResult> definition)

Captures definition identity, codec metadata, safety, and retry defaults without asserting.

Type

DurableWorkRegistryObservation

Source

Immutable observation of an exact registry lookup.

Method

Capture

DurableWorkRegistryObservation Capture(IDurableWorkRegistry registry, string workName, string workVersion)

Performs the production exact lookup; missing-registration exceptions propagate unchanged.

Type

DurableWorkBindingObservation

Source

Immutable observation of a binding's exact definition reference.

Method

Capture

DurableWorkBindingObservation Capture<TWork, TResult, TExecutor>(DurableWorkBinding<TWork, TResult, TExecutor> binding)

Captures binding identity without resolving services or invoking work.

Type

DurableHealthSnapshotBuilder

Source

Builds production-validated runtime health snapshots for tests.

Remarks

Named states supply representative valid defaults. Overrides are applied before production validation.

Method

ForState

DurableHealthSnapshotBuilder ForState(DurableRuntimeHealthState state)

Selects representative defaults for a defined health state.

Method

WithProblemCode

DurableHealthSnapshotBuilder WithProblemCode(string? value)

Overrides the optional privacy-safe problem code.

Method

WithSchemaCompatible

DurableHealthSnapshotBuilder WithSchemaCompatible(bool value)

Overrides schema compatibility.

Method

WithEpochCompatible

DurableHealthSnapshotBuilder WithEpochCompatible(bool value)

Overrides epoch compatibility.

Method

WithInstalledSchemaVersion

DurableHealthSnapshotBuilder WithInstalledSchemaVersion(int value)

Overrides installed schema version.

Method

WithRequiredSchemaVersion

DurableHealthSnapshotBuilder WithRequiredSchemaVersion(int value)

Overrides required schema version.

Method

WithConfiguredRuntimeEpoch

DurableHealthSnapshotBuilder WithConfiguredRuntimeEpoch(Guid value)

Overrides configured runtime epoch.

Method

WithActiveRuntimeEpoch

DurableHealthSnapshotBuilder WithActiveRuntimeEpoch(Guid? value)

Overrides active runtime epoch.

Method

WithWorkerId

DurableHealthSnapshotBuilder WithWorkerId(string value)

Overrides worker identity.

Method

WithWorkerInstanceId

DurableHealthSnapshotBuilder WithWorkerInstanceId(Guid? value)

Overrides worker instance identity.

Method

WithHostedSurfaces

DurableHealthSnapshotBuilder WithHostedSurfaces(DurableRuntimeSurface value)

Overrides hosted surfaces.

Method

WithObservedAtUtc

DurableHealthSnapshotBuilder WithObservedAtUtc(DateTimeOffset value)

Overrides observation time.

Method

WithStartedAtUtc

DurableHealthSnapshotBuilder WithStartedAtUtc(DateTimeOffset? value)

Overrides runtime start time.

Method

WithLastHeartbeatAtUtc

DurableHealthSnapshotBuilder WithLastHeartbeatAtUtc(DateTimeOffset? value)

Overrides heartbeat time.

Method

WithLastSuccessfulSweepAtUtc

DurableHealthSnapshotBuilder WithLastSuccessfulSweepAtUtc(DateTimeOffset? value)

Overrides last successful sweep time.

Method

WithIsDraining

DurableHealthSnapshotBuilder WithIsDraining(bool value)

Overrides drain state.

Method

WithIsPassActive

DurableHealthSnapshotBuilder WithIsPassActive(bool value)

Overrides active-pass state.

Method

WithDueDispatchCount

DurableHealthSnapshotBuilder WithDueDispatchCount(long value)

Overrides overdue dispatch count.

Method

WithOldestDueAtUtc

DurableHealthSnapshotBuilder WithOldestDueAtUtc(DateTimeOffset? value)

Overrides oldest due instant.

Method

WithOldestDueAge

DurableHealthSnapshotBuilder WithOldestDueAge(TimeSpan? value)

Overrides oldest due age.

Method

Build

DurableRuntimeHealthSnapshot Build()

Builds the selected representative snapshot and delegates all validation to production.

Method

BuildContradictoryForTest

DurableRuntimeHealthSnapshot BuildContradictoryForTest()

Builds a deliberately contradictory snapshot for tests of consumers handling inconsistent fields.

Type

RecordingDurableRuntimePump

Source

Records calls to both durable pump contracts and optionally delegates execution.

Remarks

History is retained for this instance until ClearHistory . Snapshots freeze order and scalar metadata, while requests remain shallow references; callers should not mutate their payload-bearing inputs during assertions. Payload values are never formatted or serialized. Calls canceled before delegate invocation are recorded as canceled. Once a delegate starts, its actual result or exception is recorded even if it ignores a subsequently canceled token.

Method

ClearHistory

void ClearHistory()

Atomically removes current history; already-running calls from earlier generations stay removed.

Property

Admission

Func<DurableRuntimePumpRequest, CancellationToken, ValueTask<DurableRuntimePumpAttempt>>? Admission { get; set; } Source

Delegate for admission-aware attempts; defaults to a completed empty pass.

Property

Pump

Func<DurableRuntimePumpRequest, CancellationToken, ValueTask<DurableRuntimePumpResult>>? Pump { get; set; } Source

Delegate for legacy pump calls; defaults to a completed empty pass.

Property

History

ImmutableArray<DurableRuntimePumpCall> History { get; } Source

Gets an atomic immutable snapshot ordered by invocation start.

Type

DurableRuntimePumpCall

Source

An immutable invocation record; request is the exact shallow caller reference.

Method

ToString

string ToString()

Formats only safe scalar call metadata, never retained request or delegate objects.

Type

DurableRuntimePumpRequestBuilder

Source

Builds validated bounded pump requests with production defaults.

Method

WithMaximumItems

DurableRuntimePumpRequestBuilder WithMaximumItems(int value)

Sets the total item bound.

Method

WithTimeBudget

DurableRuntimePumpRequestBuilder WithTimeBudget(TimeSpan value)

Sets the pass time budget.

Method

WithSurfaces

DurableRuntimePumpRequestBuilder WithSurfaces(DurableRuntimeSurface value)

Sets selected durable surfaces.

Method

Build

DurableRuntimePumpRequest Build()

Creates the production request, preserving its validation exceptions.

Type

DurableRuntimePumpResultBuilder

Source

Builds validated bounded pump results with zero-count defaults.

Method

WithCounts

DurableRuntimePumpResultBuilder WithCounts(int discovered, int claimed, int processed, int deferred, int failed)

Sets all pass counters.

Method

WithHasMore

DurableRuntimePumpResultBuilder WithHasMore(bool value)

Sets whether more immediately eligible work may remain.

Method

WithNextDueAtUtc

DurableRuntimePumpResultBuilder WithNextDueAtUtc(DateTimeOffset? value)

Sets the earliest known future due time.

Method

WithElapsed

DurableRuntimePumpResultBuilder WithElapsed(TimeSpan value)

Sets elapsed pass duration.

Method

Build

DurableRuntimePumpResult Build()

Creates the production result, preserving its validation exceptions.

Type

DurableRuntimePumpAttemptBuilder

Source

Builds a validated pump attempt, defaulting to a completed empty pass.

Method

WithKind

DurableRuntimePumpAttemptBuilder WithKind(DurableRuntimePumpAttemptKind value)

Selects the attempt kind; an explicit result override is preserved regardless of call order.

Method

WithResult

DurableRuntimePumpAttemptBuilder WithResult(DurableRuntimePumpResult? value)

Overrides the completed pass result, including with null; production validation rejects contradictions.

Method

WithProblemCode

DurableRuntimePumpAttemptBuilder WithProblemCode(string? value)

Sets the provider problem code.

Method

Build

DurableRuntimePumpAttempt Build()

Creates the production attempt, preserving its validation exceptions.

Type

DurableExecutionCheckpointObservation

Source

Immutable, payload-free facts recorded when a test execution reaches a checkpoint.

Type

DurableExecutionCheckpointException

Source

A safe deterministic exception emitted by a one-shot test checkpoint.

Property

Name

DurableExecutionCheckpointName Name { get; } Source

Gets the checkpoint that threw.

Property

AttemptNumber

int AttemptNumber { get; } Source

Gets the attempt number supplied by the provider test seam.

Type

DurableWorkExecutionObservation

Source

An immutable Testing-package view of accepted execution-policy facts.

Method

Capture

DurableWorkExecutionObservation Capture(DurableWorkExecutionSnapshot snapshot)

Copies the immutable descriptive facts from a Core execution snapshot.

Type

DurableExecutionCheckpointController

Source

Records bounded immutable checkpoint observations and optionally pauses or throws once at one stage.

Remarks

A checkpoint does not grant execution authority or simulate a provider result. The caller must explicitly release or cancel a configured pause. Both a pause and an observation wait have the configured maximum wait and also honor their caller's cancellation token. Disposal releases every active pause by canceling it.

Method

PauseOnce

void PauseOnce(DurableExecutionCheckpointName name)

Configures one invocation at name to pause once.

Exceptions

  • InvalidOperationException
    Another action is already armed for this checkpoint.
Method

ThrowOnce

void ThrowOnce(DurableExecutionCheckpointName name)

Configures one invocation at name to throw a safe test exception once.

Method

ReachAsync

ValueTask ReachAsync(DurableExecutionCheckpointName name, int attemptNumber, CancellationToken cancellationToken = default)

Records a checkpoint, then applies its armed one-shot pause or exception, if any.

Exceptions

  • DurableExecutionCheckpointException
    A one-shot throw was armed at this stage.
  • TimeoutException
    An armed pause was not released before the configured maximum wait.
Method

WaitForObservationAsync

2 overloads
ValueTask<DurableExecutionCheckpointObservation> WaitForObservationAsync(DurableExecutionCheckpointName name, CancellationToken cancellationToken = default)

Waits for the first retained matching observation, with the configured maximum wait and caller cancellation.

Remarks

The latest observation for a stage remains waitable after bounded history evicts it.

ValueTask<DurableExecutionCheckpointObservation> WaitForObservationAsync(DurableExecutionCheckpointName name, long afterSequence, TimeSpan maximumWait, CancellationToken cancellationToken = default)

Waits for a matching observation recorded after afterSequence .

Parameters

  • name
    The checkpoint stage to observe.
  • afterSequence
    Exclusive global sequence cursor; must be non-negative and no greater than the current sequence.
  • maximumWait
    This wait's maximum duration; must be positive and no greater than the controller's configured maximum.
  • cancellationToken
    Token that can cancel the wait.

Exceptions

  • ArgumentOutOfRangeException
    The cursor or wait duration is outside its valid bounds.
  • TimeoutException
    No qualifying observation arrived within maximumWait .

Remarks

The earliest qualifying observation still in bounded history is returned. If qualifying history was evicted, the latest observation for the stage is returned when it is newer than the cursor. If that latest observation is not newer than the cursor, the wait continues until a qualifying observation arrives or the wait expires.

Method

Release

bool Release(DurableExecutionCheckpointName name)

Releases a currently paused one-shot checkpoint; returns false when none is paused.

Method

Cancel

bool Cancel(DurableExecutionCheckpointName name)

Cancels an armed or active one-shot pause; returns false when nothing can be canceled.

Method

Dispose

void Dispose()

Cancels all active pauses and prevents new checkpoints or arms.

Property

Observations

IReadOnlyList<DurableExecutionCheckpointObservation> Observations { get; } Source

Returns a defensive, read-only copy of the observations retained so far.

Type

DurableScenarioHealthAssessment

Source

A successfully published health assessment used by later pump calls.

Parameters

  • Sequence
    Publication order among successful assessments on this scenario.
  • Snapshot
    The exact production health snapshot returned by the provider.
Type

DurableScenarioPumpInvocation

Source

Identifies one provider admission call, including an eventual outcome after a scenario wait times out.

Remarks

The request and assessment are exact references. Completion is a repeat-awaitable task: a returned attempt describes this invocation only, and a fault after execution starts can still require provider recovery. The scenario retains handles until DurableHostScenario.ClearCompletedPumpInvocations removes them.

Property

Sequence

long Sequence { get; } Source

Gets the invocation-start order within its scenario.

Property

Request

DurableRuntimePumpRequest Request { get; } Source

Gets the exact bounded request passed to provider admission.

Property

Assessment

DurableScenarioHealthAssessment Assessment { get; } Source

Gets the assessment captured before this call; it is advisory, not an admission gate.

Property

Completion

Task<DurableRuntimePumpAttempt> Completion { get; } Source

Gets the eventual provider attempt or its cancellation or exception.

Type

DurableScenarioTimeoutException

Source

Reports that a scenario stopped waiting without inventing a provider outcome.

Remarks

A pump timeout after admission starts includes Invocation . Await its DurableScenarioPumpInvocation.Completion before releasing provider resources. A health timeout or a timeout before admission has no invocation handle. A timeout does not cancel the provider call.

Property

Phase

DurableScenarioPhase Phase { get; } Source

Gets the phase whose wait expired.

Property

Reason

DurableScenarioTimeoutReason Reason { get; } Source

Gets the expired budget.

Property

Invocation

DurableScenarioPumpInvocation? Invocation { get; } Source

Gets the started provider pump invocation, if any.

Property

InvocationStarted

bool InvocationStarted { get; } Source

Gets whether provider pump admission was invoked.

Property

ExecutionStatusUnknown

bool ExecutionStatusUnknown { get; } Source

Gets whether provider execution status remains unknown until the invocation is observed.

Type

DurableHostScenario

Source

Composes a health observation and one or more authoritative pump admissions for deterministic host tests.

Remarks

The latest successfully published health snapshot is advisory. It never gates admission. One overall monotonic budget begins with the first health assessment and never resets; construct a new scenario for a new budget. The supplied TimeProvider must provide monotonic timestamps through TimeProvider.GetTimestamp . The scenario wait deadline never cancels provider work: only the caller's cancellation token reaches provider methods. A scenario retains pump handles and their shallow request references until ClearCompletedPumpInvocations is called or the scenario is released. Await timed-out handles before releasing provider or test resources. This helper does not implement provider persistence or retry policy.

Method

AssessHealthAsync

Task<DurableScenarioHealthAssessment> AssessHealthAsync(CancellationToken cancellationToken = default)

Reads and publishes one health snapshot if its provider result wins the method's terminal decision.

Exceptions

  • DurableScenarioTimeoutException
    An observation or overall budget expired.
  • OperationCanceledException
    The caller canceled the wait or the provider canceled.

Remarks

Failed, canceled, or timed-out reads do not replace the latest assessment. A late provider result after timeout is observed for faults but is never published. Concurrent successful reads publish in method terminal-decision order under the scenario lock, even when the later publication was started first. A provider task finishing does not by itself publish an assessment. A health timeout has no pump invocation handle.

Method

RunDirectPumpOnceAsync

Task<DurableRuntimePumpAttempt> RunDirectPumpOnceAsync(CancellationToken cancellationToken = default)

Invokes authoritative provider admission once after a completed assessment and returns its exact attempt.

Exceptions

  • InvalidOperationException
    No successful health assessment has been published.
  • DurableScenarioTimeoutException
    An observation or overall budget expired.
  • OperationCanceledException
    The caller canceled the wait or the provider canceled.

Remarks

DurableRuntimeHealthSnapshot.CanAttemptPump is advisory and never gates this method. A timeout or caller cancellation after invocation starts leaves a retained handle in PumpInvocations . Await its completion before releasing provider resources; do not infer a refusal or retry safety from a local timeout.

Method

ClearCompletedPumpInvocations

int ClearCompletedPumpInvocations()

Atomically removes terminal pump handles while keeping in-flight handles reachable.

Returns

The number of completed handles removed.

Remarks

The caller retains any handle already obtained from a timeout or prior snapshot. Call this after awaiting timed-out handles when reusing a scenario, so exact request references do not remain in its history.

Property

PumpInvocations

IReadOnlyList<DurableScenarioPumpInvocation> PumpInvocations { get; } Source

Gets an atomic, start-ordered snapshot of retained provider pump invocations.

Property

LatestAssessment

DurableScenarioHealthAssessment? LatestAssessment { get; } Source

Gets the most recently published successful health assessment, if any.

Type

FakeDurableRuntimeHealth

Source

A configurable in-memory health reader for deterministic tests.

Remarks

The configured snapshot is returned unchanged. No payloads are logged or serialized.

Method

GetAsync

ValueTask<DurableRuntimeHealthSnapshot> GetAsync(CancellationToken cancellationToken = default)

Reads the configured snapshot, honoring cancellation before returning.

Property

Snapshot

DurableRuntimeHealthSnapshot Snapshot { get; set; } Source

Gets or sets the snapshot returned to subsequent callers.

Type

FakeDurableRuntimeDrainControl

Source

In-memory drain control that records each state transition request.

Property

IsDraining

bool IsDraining { get; } Source

Gets the current drain state.

Property

History

ImmutableArray<DurableRuntimeDrainTransition> History { get; } Source

Gets an atomic immutable transition snapshot.

Type

DurableRuntimeDrainTransition

Source

A recorded drain-state request in invocation order.

Type

DurableWorkRequestBuilder<TWork, TResult>

Source

Builds a typed Work request by delegating encoding and identity to its definition.

Type parameters

  • TWork
    Typed input.
  • TResult
    Successful result.
Method

WithScope

DurableWorkRequestBuilder<TWork, TResult> WithScope(DurableScopeId value)

Sets owning scope; the default is test-scope .

Method

WithCommand

DurableWorkRequestBuilder<TWork, TResult> WithCommand(DurableCommandId value)

Sets command identity; the default is test-command .

Method

WithIdempotencyKey

DurableWorkRequestBuilder<TWork, TResult> WithIdempotencyKey(string value)

Sets idempotency key.

Method

WithWork

DurableWorkRequestBuilder<TWork, TResult> WithWork(TWork value)

Sets typed work input.

Method

WithRetryPolicy

DurableWorkRequestBuilder<TWork, TResult> WithRetryPolicy(DurableWorkRetryPolicy? value)

Sets a retry override.

Method

WithDueAtUtc

DurableWorkRequestBuilder<TWork, TResult> WithDueAtUtc(DateTimeOffset? value)

Sets initial eligibility time.

Method

Build

DurableWorkRequest Build()

Creates the request through DurableWorkDefinition{TWork,TResult}.CreateRequest .

Type

DurableWorkerEnvelopeBuilder<TPayload>

Source

Builds native worker envelopes while retaining execution and fence identity.

Type parameters

  • TPayload
    Optional typed outcome payload.
Method

WithOutcome

DurableWorkerEnvelopeBuilder<TPayload> WithOutcome(DurableWorkerProjectionOutcome value)

Sets outcome.

Method

WithReasonCode

DurableWorkerEnvelopeBuilder<TPayload> WithReasonCode(string value)

Sets safe reason code.

Method

WithRetryability

DurableWorkerEnvelopeBuilder<TPayload> WithRetryability(DurableWorkerRetryability value)

Sets retry classification.

Method

WithCorrelation

DurableWorkerEnvelopeBuilder<TPayload> WithCorrelation(DurableWorkerCorrelation value)

Sets correlation identity.

Method

WithExecutionIdentity

DurableWorkerEnvelopeBuilder<TPayload> WithExecutionIdentity(DurableWorkerExecutionIdentity value)

Sets required native execution and fencing identity.

Method

WithPayload

DurableWorkerEnvelopeBuilder<TPayload> WithPayload(TPayload? value)

Sets optional typed payload.

Method

Build

DurableWorkerEnvelope<TPayload> Build()

Creates the envelope through DurableWorkerEnvelope{TPayload}.CreateNative .

Enum

DurableRuntimePumpCallKind

Source

Identifies which production pump contract was invoked.

Enum

DurableExecutionCheckpointName

Source

Identifies a deterministic Work execution boundary available to tests.

Enum

DurableScenarioPhase

Source

Identifies the phase in which a durable host scenario stopped waiting.

Enum

DurableScenarioTimeoutReason

Source

Identifies which scenario wait budget expired.