Class TestDurableTaskClient

Namespace: XBullet.EasyTesting.AzureFunctions

Assembly: XBullet.EasyTesting.AzureFunctions.dll

Records orchestration starts for isolated-worker client and HTTP starter tests.

public sealed class TestDurableTaskClient : DurableTaskClient, IOrchestrationSubmitter, IAsyncDisposable, ITestScenarioResource

Inheritance: object

DurableTaskClient

TestDurableTaskClient

Implements: IOrchestrationSubmitter

IAsyncDisposable

ITestScenarioResource

Inherited Members: DurableTaskClient.ScheduleNewOrchestrationInstanceAsync(TaskName, CancellationToken)

DurableTaskClient.ScheduleNewOrchestrationInstanceAsync(TaskName, object, CancellationToken)

DurableTaskClient.ScheduleNewOrchestrationInstanceAsync(TaskName, StartOrchestrationOptions, CancellationToken)

DurableTaskClient.RaiseEventAsync(string, string, CancellationToken)

DurableTaskClient.WaitForInstanceStartAsync(string, CancellationToken)

DurableTaskClient.WaitForInstanceCompletionAsync(string, CancellationToken)

DurableTaskClient.TerminateInstanceAsync(string, CancellationToken)

DurableTaskClient.TerminateInstanceAsync(string, object, CancellationToken)

DurableTaskClient.SuspendInstanceAsync(string, CancellationToken)

DurableTaskClient.ResumeInstanceAsync(string, CancellationToken)

DurableTaskClient.GetInstanceAsync(string, CancellationToken)

DurableTaskClient.GetInstanceAsync(string, bool, CancellationToken)

DurableTaskClient.PurgeInstanceAsync(string, CancellationToken)

DurableTaskClient.PurgeAllInstancesAsync(PurgeInstancesFilter, CancellationToken)

DurableTaskClient.ListInstanceIdsAsync(IEnumerable<OrchestrationRuntimeStatus>, DateTimeOffset?, DateTimeOffset?, int, string, CancellationToken)

DurableTaskClient.Name

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods: SnapshotAssertionExtensions.ShouldMatchSnapshot(object?, Action<SnapshotSettings>, CancellationToken, string, string)

SnapshotAssertionExtensions.ShouldMatchSnapshot(object?, string, CancellationToken, string, string)

SnapshotAssertionExtensions.ShouldMatchSnapshot(object?, SnapshotSettings?, CancellationToken, string, string)

Remarks

No orchestrations run automatically. Scheduling returns an explicit instance ID or a unique generated ID. Management operations require explicit handlers and never change seeded state. Configure handlers before concurrent use. Completion-time ID listing retains the SDK's unsupported default.

Constructors

TestDurableTaskClient(string)

Creates a client without runtime or network dependencies.

public TestDurableTaskClient(string name = "test-client")

Parameters

name string: The non-empty client name. Defaults to test-client.

Properties

Entities

Gets the entity client boundary owned by this test client.

public override TestDurableEntityClient Entities { get; }

Property Value

TestDurableEntityClient: A recording client reset alongside orchestration fixtures; entities do not execute automatically.

GetInstanceHandler

Gets or sets metadata lookup behavior.

public Func<string, bool, CancellationToken, Task<OrchestrationMetadata?>>? GetInstanceHandler { get; set; }

Property Value

Func<string, bool, CancellationToken, Task<OrchestrationMetadata>>: An optional callback receiving the instance ID, payload inclusion flag, and caller token. Null reads seeded metadata, returning null when absent.

HistoryHandler

Gets or sets history retrieval behavior.

public Func<string, CancellationToken, Task<IList<HistoryEvent>>>? HistoryHandler { get; set; }

Property Value

Func<string, CancellationToken, Task<IList<HistoryEvent>>>: A required callback receiving instance ID and caller token. History is not generated or replayed.

Operations

Gets all client call attempts, including failed handlers and missing-handler errors.

public IReadOnlyList<RecordedDurableClientOperation> Operations { get; }

Property Value

IReadOnlyList<RecordedDurableClientOperation>: An ordered snapshot. Invalid arguments and pre-canceled calls are excluded; argument values are retained by reference.

PurgeAllHandler

Gets or sets bulk purge behavior.

public Func<PurgeInstancesFilter, PurgeInstanceOptions?, CancellationToken, Task<PurgeResult>>? PurgeAllHandler { get; set; }

Property Value

Func<PurgeInstancesFilter, PurgeInstanceOptions, CancellationToken, Task<PurgeResult>>: A required callback receiving the original filter, options, and caller token.

PurgeHandler

Gets or sets single-instance purge behavior.

public Func<string, PurgeInstanceOptions?, CancellationToken, Task<PurgeResult>>? PurgeHandler { get; set; }

Property Value

Func<string, PurgeInstanceOptions, CancellationToken, Task<PurgeResult>>: A required callback receiving instance ID, original options, and caller token.

QueryHandler

Gets or sets query behavior.

public Func<OrchestrationQuery?, AsyncPageable<OrchestrationMetadata>>? QueryHandler { get; set; }

Property Value

Func<OrchestrationQuery, AsyncPageable<OrchestrationMetadata>>: A callback receiving the original query; required for pageable queries. Cancellation is handled by the returned pageable.

RaiseEventHandler

Gets or sets event submission behavior.

public Func<string, string, object?, CancellationToken, Task>? RaiseEventHandler { get; set; }

Property Value

Func<string, string, object, CancellationToken, Task>: A callback receiving instance ID, event name, original payload, and caller token; required for event submission.

RestartHandler

Gets or sets restart behavior.

public Func<string, bool, CancellationToken, Task<string>>? RestartHandler { get; set; }

Property Value

Func<string, bool, CancellationToken, Task<string>>: A required callback receiving instance ID, the new-ID flag, and caller token. Its result must be non-empty.

ResumeHandler

Gets or sets resumption behavior.

public Func<string, string?, CancellationToken, Task>? ResumeHandler { get; set; }

Property Value

Func<string, string, CancellationToken, Task>: A callback receiving instance ID, optional reason, and caller token; required for resumption.

RewindHandler

Gets or sets rewind behavior.

public Func<string, string, CancellationToken, Task>? RewindHandler { get; set; }

Property Value

Func<string, string, CancellationToken, Task>: A required callback receiving instance ID, reason, and caller token.

ScheduleHandler

Gets or sets scheduling behavior after recording a call.

public Func<RecordedOrchestrationStart, CancellationToken, Task<string>>? ScheduleHandler { get; set; }

Property Value

Func<RecordedOrchestrationStart, CancellationToken, Task<string>>: An optional callback receiving the call and caller token. Null returns the recorded instance ID.

ScheduledOrchestrations

Gets recorded scheduling attempts in invocation order.

public IReadOnlyList<RecordedOrchestrationStart> ScheduledOrchestrations { get; }

Property Value

IReadOnlyList<RecordedOrchestrationStart>: A snapshot including calls whose handlers failed; pre-canceled calls are excluded.

SuspendHandler

Gets or sets suspension behavior.

public Func<string, string?, CancellationToken, Task>? SuspendHandler { get; set; }

Property Value

Func<string, string, CancellationToken, Task>: A callback receiving instance ID, optional reason, and caller token; required for suspension.

TerminateHandler

Gets or sets termination behavior.

public Func<string, TerminateInstanceOptions?, CancellationToken, Task>? TerminateHandler { get; set; }

Property Value

Func<string, TerminateInstanceOptions, CancellationToken, Task>: A required callback receiving instance ID, original options, and caller token; no state changes occur automatically.

WaitForCompletionHandler

Gets or sets completion-wait behavior.

public Func<string, bool, CancellationToken, Task<OrchestrationMetadata>>? WaitForCompletionHandler { get; set; }

Property Value

Func<string, bool, CancellationToken, Task<OrchestrationMetadata>>: A callback receiving instance ID, payload inclusion flag, and caller token; required for completion waits.

WaitForStartHandler

Gets or sets start-wait behavior.

public Func<string, bool, CancellationToken, Task<OrchestrationMetadata>>? WaitForStartHandler { get; set; }

Property Value

Func<string, bool, CancellationToken, Task<OrchestrationMetadata>>: A callback receiving instance ID, payload inclusion flag, and caller token; required for start waits.

Methods

CaptureDiagnosticsAsync(CancellationToken)

Captures a serializable operation timeline and seeded instance summaries.

public ValueTask<object?> CaptureDiagnosticsAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: Cancels before capture begins.

Returns

ValueTask<object>: A detached snapshot containing names, IDs, operation targets, and statuses; payloads, reasons, options, and failures are excluded.

DisposeAsync()

Completes immediately; this client owns no external resources.

public override ValueTask DisposeAsync()

Returns

ValueTask: A completed value task. Recorded calls remain available.

GetAllInstancesAsync(OrchestrationQuery?)

Queries orchestration instances.

public override AsyncPageable<OrchestrationMetadata> GetAllInstancesAsync(OrchestrationQuery? filter = null)

Parameters

filter OrchestrationQuery: Filters down the instances included in the query.

Returns

AsyncPageable<OrchestrationMetadata>: An async pageable of the query results.

GetInstancesAsync(string, bool, CancellationToken)

Fetches orchestration instance metadata from the configured durable store.

public override Task<OrchestrationMetadata?> GetInstancesAsync(string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default)

Parameters

instanceId string: The unique ID of the orchestration instance to wait for.
getInputsAndOutputs bool: Specify true to fetch the orchestration instance's inputs, outputs, and custom status, or false to omit them. The default value is false to minimize the network bandwidth, serialization, and memory costs associated with fetching the instance metadata.
cancellation CancellationToken: A CancellationToken that can be used to cancel the wait operation.

Returns

Task<OrchestrationMetadata>: Returns a OrchestrationMetadata record that describes the orchestration instance and its execution status or null if no instance with ID instanceId is found.

Remarks

You can use the getInputsAndOutputs parameter to determine whether to fetch input and output data for the target orchestration instance. If your code doesn't require access to this data, it's recommended that you set this parameter to false to minimize the network bandwidth, serialization, and memory costs associated with fetching the instance metadata.

GetOrchestrationHistoryAsync(string, CancellationToken)

Retrieves the history of the specified orchestration instance as a list of DurableTask.Core.History.HistoryEvent objects.

public override Task<IList<HistoryEvent>> GetOrchestrationHistoryAsync(string instanceId, CancellationToken cancellation = default)

Parameters

instanceId string: The instance ID of the orchestration.
cancellation CancellationToken: The cancellation token.

Returns

Task<IList<HistoryEvent>>: The list of DurableTask.Core.History.HistoryEvent objects representing the orchestration's history.

Exceptions

NotSupportedException: Thrown if this implementation of DurableTaskClient does not support retrieving orchestration history.
ArgumentNullException: Thrown if instanceId is null.
ArgumentException: Thrown if an orchestration with the specified instanceId does not exist, or if instanceId is the instance ID of an entity.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token.
InvalidOperationException: Thrown if an internal error occurs when attempting to retrieve the orchestration history.

PurgeAllInstancesAsync(PurgeInstancesFilter, PurgeInstanceOptions?, CancellationToken)

Purges orchestration instances metadata from the durable store.

public override Task<PurgeResult> PurgeAllInstancesAsync(PurgeInstancesFilter filter, PurgeInstanceOptions? options = null, CancellationToken cancellation = default)

Parameters

filter PurgeInstancesFilter: The filter for which orchestrations to purge.
options PurgeInstanceOptions: The optional options for purging the orchestration.
cancellation CancellationToken: A CancellationToken that can be used to cancel the purge operation.

Returns

Task<PurgeResult>: This method returns a PurgeResult object after the operation has completed with a PurgedInstanceCount indicating the number of orchestration instances that were purged.

PurgeInstanceAsync(string, PurgeInstanceOptions?, CancellationToken)

Purges orchestration instance metadata from the durable store.

public override Task<PurgeResult> PurgeInstanceAsync(string instanceId, PurgeInstanceOptions? options = null, CancellationToken cancellation = default)

Parameters

instanceId string: The unique ID of the orchestration instance to purge.
options PurgeInstanceOptions: The optional options for purging the orchestration.
cancellation CancellationToken: A CancellationToken that can be used to cancel the purge operation.

Returns

Task<PurgeResult>: This method returns a PurgeResult object after the operation has completed with a PurgedInstanceCount indicating the number of orchestration instances that were purged, including the count of sub-orchestrations purged if any.

Remarks

This method can be used to permanently delete orchestration metadata from the underlying storage provider, including any stored inputs, outputs, and orchestration history records. This is often useful for implementing data retention policies and for keeping storage costs minimal. Only orchestration instances in the Completed, Failed, or Terminated state can be purged.

Purging an orchestration will by default not purge any of the child sub-orchestrations that were started by the orchetration instance. Currently, purging of sub-orchestrations is not supported. If instanceId is not found in the data store, or if the instance is found but not in a terminal state, then the returned PurgeResult object will have a PurgedInstanceCount value of 0. Otherwise, the existing data will be purged and PurgedInstanceCount will be the count of purged instances.

Exceptions

ArgumentNullException: Thrown if instanceId is null.
ArgumentException: Thrown if instanceId is empty or starts with the null character.
InvalidOperationException: Thrown if the orchestration is not in a Completed, Failed, or Terminated state.
NotImplementedException: Thrown if the backend storage provider does not support purging instances.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token.

RaiseEventAsync(string, string, object?, CancellationToken)

Sends an event notification message to a waiting orchestration instance.

public override Task RaiseEventAsync(string instanceId, string eventName, object? eventPayload = null, CancellationToken cancellation = default)

Parameters

instanceId string: The ID of the orchestration instance that will handle the event.
eventName string: The name of the event. Event names are case-insensitive.
eventPayload object: The serializable data payload to include with the event.
cancellation CancellationToken: The cancellation token. This only cancels enqueueing the event to the backend. Does not abort sending the event once enqueued.

Returns

Task: A task that completes when the event notification message has been enqueued.

Remarks

In order to handle the event, the target orchestration instance must be waiting for an event named eventName using the WaitForExternalEvent<T>(string, CancellationToken) API. If the target orchestration instance is not yet waiting for an event named eventName, then the event will be saved in the orchestration instance state and dispatched immediately when the orchestrator calls WaitForExternalEvent<T>(string, CancellationToken). This event saving occurs even if the orchestrator has canceled its wait operation before the event was received.

Orchestrators can wait for the same event name multiple times, so sending multiple events with the same name is allowed. Each external event received by an orchestrator will complete just one task returned by the WaitForExternalEvent<T>(string, CancellationToken) method.

Raised events for a completed or non-existent orchestration instance will be silently discarded.

Exceptions

ArgumentNullException: Thrown if instanceId or eventName is null or empty.

ResetAsync(CancellationToken)

Clears recorded calls, seeded orchestration and entity metadata, and generated ID sequences.

public ValueTask ResetAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: Cancels before state changes. Handlers remain configured.

Returns

ValueTask: A completed value task once state is cleared.

Remarks

Await all in-flight calls before resetting; reset does not cancel handlers or their side effects.

RestartAsync(string, bool, CancellationToken)

Restarts an orchestration instance with the same or a new instance ID.

public override Task<string> RestartAsync(string instanceId, bool restartWithNewInstanceId = false, CancellationToken cancellation = default)

Parameters

instanceId string: The ID of the orchestration instance to restart.
restartWithNewInstanceId bool: If true, a new instance ID will be generated for the restarted orchestration. If false, the original instance ID will be reused.
cancellation CancellationToken: The cancellation token. This only cancels enqueueing the restart request to the backend, or waiting for the termination of an existing non-terminal instance if the implementation supports this behavior. Does not abort restarting the orchestration once enqueued.

Returns

Task<string>: A task that completes when the orchestration instance is successfully restarted. The value of this task is the instance ID of the restarted orchestration instance.

Remarks

This method restarts an existing orchestration instance. If restartWithNewInstanceId is true, a new instance ID will be generated for the restarted orchestration. If false, the original instance ID will be reused. If the existing instance is not in a terminal state, depending on the specific implementation, either: 1. The existing instance will be terminated before being restarted, or 2. An InvalidOperationException will be thrown.

The restarted orchestration will use the same input data as the original instance. If the original orchestration instance is not found, an ArgumentException will be thrown.

Note that this operation is backend-specific and may not be supported by all durable task backends. If the backend does not support restart operations, a NotSupportedException will be thrown.

Exceptions

ArgumentException: Thrown if an orchestration with the specified instanceId was not found.
InvalidOperationException: Thrown when attempting to restart an instance using the same instance Id while the instance has not yet reached a completed or terminal state, in the case that the implementation does not support terminating existing non-terminal instances before restarting.
NotSupportedException: Thrown if the backend does not support restart operations.

ResumeInstanceAsync(string, string?, CancellationToken)

Resumes an orchestration instance that was suspended via SuspendInstanceAsync(string, string, CancellationToken).

public override Task ResumeInstanceAsync(string instanceId, string? reason = null, CancellationToken cancellation = default)

Parameters

instanceId string: The instance ID of the orchestration to resume.
reason string: The optional resume reason.
cancellation CancellationToken: A CancellationToken that can be used to cancel the resume operation. Note, cancelling this token does not re-suspend the orchestration if resume was successful.

Returns

Task: A task that completes when the resume has been committed to the backend.

RewindInstanceAsync(string, string, CancellationToken)

Rewinds the specified orchestration instance by re-executing any failed Activities, and recursively rewinding any failed suborchestrations with failed Activities.

public override Task RewindInstanceAsync(string instanceId, string reason, CancellationToken cancellation = default)

Parameters

instanceId string: The instance ID of the orchestration to rewind.
reason string: The reason for the rewind.
cancellation CancellationToken: The cancellation token. This only cancels enqueueing the rewind request to the backend. It does not abort rewinding the orchestration once the request has been enqueued.

Returns

Task: A task that represents the enqueueing of the rewind operation.

Remarks

The orchestration's history will be replaced with a new history that excludes the failed Activities and suborchestrations, and a new execution ID will be generated for the rewound orchestration instance. As the failed Activities and suborchestrations re-execute, the history will be appended with new TaskScheduled, TaskCompleted, and SubOrchestrationInstanceCompleted events. Note that only orchestrations in a Failed state can be rewound.

Exceptions

NotSupportedException: Thrown if this implementation of DurableTaskClient does not support rewinding orchestrations.
NotImplementedException: Thrown if the backend storage provider does not support rewinding orchestrations.
ArgumentException: Thrown if an orchestration with the specified instanceId does not exist, or if instanceId is the instance ID of an entity.
InvalidOperationException: Thrown if a precondition of the operation fails, for example if the specified orchestration is not in a Failed state.
OperationCanceledException: Thrown if the operation is canceled via the cancellation token.

ScheduleNewOrchestrationInstanceAsync(TaskName, object?, StartOrchestrationOptions?, CancellationToken)

Schedules a new orchestration instance for execution.

public override Task<string> ScheduleNewOrchestrationInstanceAsync(TaskName orchestratorName, object? input = null, StartOrchestrationOptions? options = null, CancellationToken cancellation = default)

Parameters

orchestratorName TaskName: The name of the orchestrator to schedule.
input object: The optional input to pass to the scheduled orchestration instance. This must be a serializable value.
options StartOrchestrationOptions: The options to start the new orchestration with.
cancellation CancellationToken: The cancellation token. This only cancels enqueueing the new orchestration to the backend, or waiting for the termination of an existing non-terminal instance if its status is not in DedupeStatuses. Does not cancel the orchestration once enqueued.

Returns

Task<string>: A task that completes when the orchestration instance is successfully scheduled. The value of this task is the instance ID of the scheduled orchestration instance. If a non-null instance ID was provided via options, the same value will be returned by the completed task.

Remarks

All orchestrations must have a unique instance ID. You can provide an instance ID using the options parameter or you can omit this and a random instance ID will be generated for you automatically. If an orchestration with the specified instance ID already exists and its status is not in the DedupeStatuses field of options, then a new orchestration may be recreated automatically, depending on the configuration of the backend instance store. If the existing orchestration is in a non-terminal state (Pending, Running, etc.), then the orchestration will first be terminated before the new orchestration is created. A null DedupeStatuses field means the deduplication behavior will follow whatever the default deduplication behavior of the backend instance store or implementation of this client is. A non-null, empty field means that all statuses are reusable.

Orchestration instances started with this method will be created in the Pending state and will transition to the Running after successfully awaiting its first task. The exact time it takes before a scheduled orchestration starts running depends on several factors, including the configuration and health of the backend task hub, and whether a start time was provided via options.

The task associated with this method completes after the orchestration instance was successfully scheduled. You can use the GetInstanceAsync(string, bool, CancellationToken) to query the status of the scheduled instance, the WaitForInstanceStartAsync(string, bool, CancellationToken) method to wait for the instance to transition out of the Pending status, or the WaitForInstanceCompletionAsync(string, bool, CancellationToken) method to wait for the instance to reach a terminal state (Completed, Terminated, Failed, etc.).

Exceptions

ArgumentNullException: Thrown if orchestratorName is empty.
OrchestrationAlreadyExistsException: If an orchestration with status in DedupeStatuses with this instance ID already exists.
ArgumentException: Thrown if DedupeStatuses contains 'Terminated', but also allows at least one running status to be reusable. In this case, an existing orchestration with that running status would be terminated, but the creation of the new orchestration would immediately fail due to the existing orchestration now having status 'Terminated'.

Should()

Starts fluent assertions over recorded attempts.

public TestDurableTaskClientAssertions Should()

Returns

TestDurableTaskClientAssertions: A new assertion object that reads current recording snapshots.

SuspendInstanceAsync(string, string?, CancellationToken)

Suspends an orchestration instance, halting processing of it until ResumeInstanceAsync(string, string, CancellationToken) is used to resume the orchestration.

public override Task SuspendInstanceAsync(string instanceId, string? reason = null, CancellationToken cancellation = default)

Parameters

instanceId string: The instance ID of the orchestration to suspend.
reason string: The optional suspension reason.
cancellation CancellationToken: A CancellationToken that can be used to cancel the suspend operation. Note, cancelling this token does not resume the orchestration if suspend was successful.

Returns

Task: A task that completes when the suspend has been committed to the backend.

TerminateInstanceAsync(string, TerminateInstanceOptions?, CancellationToken)

Terminates an orchestration instance and updates its runtime status to Terminated.

public override Task TerminateInstanceAsync(string instanceId, TerminateInstanceOptions? options = null, CancellationToken cancellation = default)

Parameters

instanceId string: The ID of the orchestration instance to terminate.
options TerminateInstanceOptions: The optional options for terminating the orchestration.
cancellation CancellationToken: The cancellation token. This only cancels enqueueing the termination request to the backend. Does not abort termination of the orchestration once enqueued.

Returns

Task: A task that completes when the terminate message is enqueued.

Remarks

This method internally enqueues a "terminate" message in the task hub. When the task hub worker processes this message, it will update the runtime status of the target instance to Terminated. You can use the WaitForInstanceCompletionAsync(string, bool, CancellationToken) to wait for the instance to reach the terminated state.

Terminating an orchestration by default will not terminate any of the child sub-orchestrations that were started by the orchetration instance. If you want to terminate sub-orchestration instances as well, you can set Recursive flag to true which will enable termination of child sub-orchestration instances. It is set to false by default. Terminating an orchestration instance has no effect on any in-flight activity function executions that were started by the terminated instance. Those actions will continue to run without interruption. However, their results will be discarded.

At the time of writing, there is no way to terminate an in-flight activity execution.

Attempting to terminate a completed or non-existent orchestration instance will fail silently.

WaitForInstanceCompletionAsync(string, bool, CancellationToken)

Waits for an orchestration to complete and returns a OrchestrationMetadata object that contains metadata about the started instance.

public override Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default)

Parameters

instanceId string: The unique ID of the orchestration instance to wait for.
getInputsAndOutputs bool: Specify true to fetch the orchestration instance's inputs, outputs, and custom status, or false to omit them. The default value is false to minimize the network bandwidth, serialization, and memory costs associated with fetching the instance metadata.
cancellation CancellationToken: A CancellationToken that can be used to cancel the wait operation.

Returns

Task<OrchestrationMetadata>: Returns a OrchestrationMetadata record that describes the orchestration instance and its execution status or null if no instance with ID instanceId is found.

Remarks

A "completed" orchestration instance is any instance in one of the terminal states. For example, the Completed, Failed, or Terminated states.

Orchestrations are long-running and could take hours, days, or months before completing. Orchestrations can also be eternal, in which case they'll never complete unless terminated. In such cases, this call may block indefinitely, so care must be taken to ensure appropriate timeouts are enforced using the cancellation parameter.

If an orchestration instance is already complete when this method is called, the method will return immediately.

WaitForInstanceStartAsync(string, bool, CancellationToken)

Waits for an orchestration to start running and returns a OrchestrationMetadata object that contains metadata about the started instance.

public override Task<OrchestrationMetadata> WaitForInstanceStartAsync(string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default)

Parameters

instanceId string: The unique ID of the orchestration instance to wait for.
getInputsAndOutputs bool: Specify true to fetch the orchestration instance's inputs, outputs, and custom status, or false to omit them. The default value is false to minimize the network bandwidth, serialization, and memory costs associated with fetching the instance metadata.
cancellation CancellationToken: A CancellationToken that can be used to cancel the wait operation.

Returns

Task<OrchestrationMetadata>: Returns a OrchestrationMetadata record that describes the orchestration instance and its execution status or null if no instance with ID instanceId is found.

Remarks

A "started" orchestration instance is any instance not in the Pending state.

If an orchestration instance is already running when this method is called, the method will return immediately.

WithInstance(OrchestrationMetadata)

Seeds or replaces metadata used by default instance lookups.

public TestDurableTaskClient WithInstance(OrchestrationMetadata metadata)

Parameters

metadata OrchestrationMetadata: Non-null metadata with non-empty name and ID. Scalar values and tags are copied; converter and failure details are retained.

Returns

TestDurableTaskClient: This client for chaining. A configured lookup handler takes precedence.

Remarks

No scheduling or management operation changes these fixtures. Seed inside scenarios after their initial reset.