Make DurableTaskClient method names consistent (#112)

Author: jviau

CHANGELOG.md

@@ -3,6 +3,12 @@
 ## v1.0.0
 
 - Added `SuspendInstanceAsync` and `ResumeInstanceAsync` to `DurableTaskClient`.
+- Rename `DurableTaskClient` methods
+    - `TerminateAsync` -> `TerminateInstanceAsync`
+    - `PurgeInstances` -> `PurgeAllInstancesAsync`
+    - `PurgeInstanceMetadataAsync` -> `PurgeInstanceAsync`
+    - `GetInstanceMetadataAsync` -> `GetInstanceAsync`
+    - `GetInstances` -> `GetAllInstancesAsync`
 - `TaskOrchestrationContext.CreateReplaySafeLogger` now creates `ILogger` directly (as opposed to wrapping an existing `ILogger`).
 - Durable Functions class-based syntax now resolves `ITaskActivity` instances from `IServiceProvider`, if available there.
 - `DurableTaskClient` methods have been touched up to ensure `CancellationToken` is included, as well as is the last parameter.

src/Client/Core/DependencyInjection/DurableTaskClientExtensions.cs

@@ -30,7 +30,7 @@ public static Task<PurgeResult> PurgeInstancesAsync(
     {
         Check.NotNull(client);
         PurgeInstancesFilter filter = new(createdFrom, createdTo, statuses);
-        return client.PurgeInstancesAsync(filter, cancellation);
+        return client.PurgeAllInstancesAsync(filter, cancellation);
     }
 
     /// <summary>

src/Client/Core/DurableTaskClient.cs

@@ -73,7 +73,7 @@ public virtual Task<string> ScheduleNewOrchestrationInstanceAsync(
     /// and health of the backend task hub, and whether a start time was provided via <paramref name="options" />.
     /// </para><para>
     /// The task associated with this method completes after the orchestration instance was successfully scheduled. You
-    /// can use the <see cref="GetInstanceMetadataAsync(string, bool, CancellationToken)"/> to query the status of the
+    /// can use the <see cref="GetInstancesAsync(string, bool, CancellationToken)"/> to query the status of the
     /// scheduled instance, the <see cref="WaitForInstanceStartAsync(string, bool, CancellationToken)"/> method to wait
     /// for the instance to transition out of the <see cref="OrchestrationRuntimeStatus.Pending"/> status, or the
     /// <see cref="WaitForInstanceCompletionAsync(string, bool, CancellationToken)"/> method to wait for the instance to
@@ -140,10 +140,67 @@ public virtual Task RaiseEventAsync(
     public abstract Task RaiseEventAsync(
         string instanceId, string eventName, object? eventPayload = null, CancellationToken cancellation = default);
 
-    /// <inheritdoc cref="TerminateAsync(string, object, CancellationToken)"/>
-    public virtual Task TerminateAsync(
+    /// <inheritdoc cref="WaitForInstanceStartAsync(string, bool, CancellationToken)"/>
+    public virtual Task<OrchestrationMetadata> WaitForInstanceStartAsync(
+        string instanceId, CancellationToken cancellation)
+        => this.WaitForInstanceStartAsync(instanceId, false, cancellation);
+
+    /// <summary>
+    /// Waits for an orchestration to start running and returns a <see cref="OrchestrationMetadata"/>
+    /// object that contains metadata about the started instance.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A "started" orchestration instance is any instance not in the <see cref="OrchestrationRuntimeStatus.Pending"/>
+    /// state.
+    /// </para><para>
+    /// If an orchestration instance is already running when this method is called, the method will return immediately.
+    /// </para>
+    /// </remarks>
+    /// <param name="instanceId">The unique ID of the orchestration instance to wait for.</param>
+    /// <param name="getInputsAndOutputs">
+    /// Specify <c>true</c> to fetch the orchestration instance's inputs, outputs, and custom status, or <c>false</c> to
+    /// omit them. The default value is <c>false</c> to minimize the network bandwidth, serialization, and memory costs
+    /// associated with fetching the instance metadata.
+    /// </param>
+    /// <param name="cancellation">A <see cref="CancellationToken"/> that can be used to cancel the wait operation.</param>
+    /// <returns>
+    /// Returns a <see cref="OrchestrationMetadata"/> record that describes the orchestration instance and its execution
+    /// status or <c>null</c> if no instance with ID <paramref name="instanceId"/> is found.
+    /// </returns>
+    public abstract Task<OrchestrationMetadata> WaitForInstanceStartAsync(
+        string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default);
+
+    /// <inheritdoc cref="WaitForInstanceCompletionAsync(string, bool, CancellationToken)"/>
+    public virtual Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(
         string instanceId, CancellationToken cancellation)
-        => this.TerminateAsync(instanceId, null, cancellation);
+        => this.WaitForInstanceCompletionAsync(instanceId, false, cancellation);
+
+    /// <summary>
+    /// Waits for an orchestration to complete and returns a <see cref="OrchestrationMetadata"/>
+    /// object that contains metadata about the started instance.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// A "completed" orchestration instance is any instance in one of the terminal states. For example, the
+    /// <see cref="OrchestrationRuntimeStatus.Completed"/>, <see cref="OrchestrationRuntimeStatus.Failed"/>, or
+    /// <see cref="OrchestrationRuntimeStatus.Terminated"/> states.
+    /// </para><para>
+    /// 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 <paramref name="cancellation"/> parameter.
+    /// </para><para>
+    /// If an orchestration instance is already complete when this method is called, the method will return immediately.
+    /// </para>
+    /// </remarks>
+    /// <inheritdoc cref="WaitForInstanceStartAsync(string, bool, CancellationToken)"/>
+    public abstract Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(
+        string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default);
+
+    /// <inheritdoc cref="TerminateInstanceAsync(string, object, CancellationToken)"/>
+    public virtual Task TerminateInstanceAsync(string instanceId, CancellationToken cancellation)
+        => this.TerminateInstanceAsync(instanceId, null, cancellation);
 
     /// <summary>
     /// Terminates a running orchestration instance and updates its runtime status to
@@ -175,17 +232,16 @@ public virtual Task TerminateAsync(
     /// termination of the orchestration once enqueued.
     /// </param>
     /// <returns>A task that completes when the terminate message is enqueued.</returns>
-    public abstract Task TerminateAsync(
+    public abstract Task TerminateInstanceAsync(
         string instanceId, object? output = null, CancellationToken cancellation = default);
 
-    /// <inheritdoc cref="WaitForInstanceStartAsync(string, bool, CancellationToken)"/>
-    public virtual Task<OrchestrationMetadata> WaitForInstanceStartAsync(
-        string instanceId, CancellationToken cancellation)
-        => this.WaitForInstanceStartAsync(instanceId, false, cancellation);
+    /// <inheritdoc cref="SuspendInstanceAsync(string, string, CancellationToken)"/>
+    public virtual Task SuspendInstanceAsync(string instanceId, CancellationToken cancellation)
+        => this.SuspendInstanceAsync(instanceId, null, cancellation);
 
     /// <summary>
-    /// Suspends an orchestration instance, halting processing of it until <see cref="ResumeInstanceAsync" /> is used
-    /// to resume the orchestration.
+    /// Suspends an orchestration instance, halting processing of it until
+    /// <see cref="ResumeInstanceAsync(string, string, CancellationToken)" /> is used to resume the orchestration.
     /// </summary>
     /// <param name="instanceId">The instance ID of the orchestration to suspend.</param>
     /// <param name="reason">The optional suspension reason.</param>
@@ -197,8 +253,12 @@ public virtual Task<OrchestrationMetadata> WaitForInstanceStartAsync(
     public abstract Task SuspendInstanceAsync(
         string instanceId, string? reason = null, CancellationToken cancellation = default);
 
+    /// <inheritdoc cref="ResumeInstanceAsync(string, string, CancellationToken)"/>
+    public virtual Task ResumeInstanceAsync(string instanceId, CancellationToken cancellation)
+        => this.ResumeInstanceAsync(instanceId, null, cancellation);
+
     /// <summary>
-    /// Resumes an orchestration instance that was suspended via <see cref="SuspendInstanceAsync" />.
+    /// Resumes an orchestration instance that was suspended via <see cref="SuspendInstanceAsync(string, string, CancellationToken)" />.
     /// </summary>
     /// <param name="instanceId">The instance ID of the orchestration to resume.</param>
     /// <param name="reason">The optional resume reason.</param>
@@ -210,63 +270,10 @@ public abstract Task SuspendInstanceAsync(
     public abstract Task ResumeInstanceAsync(
         string instanceId, string? reason = null, CancellationToken cancellation = default);
 
-    /// <summary>
-    /// Waits for an orchestration to start running and returns a <see cref="OrchestrationMetadata"/>
-    /// object that contains metadata about the started instance.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// A "started" orchestration instance is any instance not in the <see cref="OrchestrationRuntimeStatus.Pending"/>
-    /// state.
-    /// </para><para>
-    /// If an orchestration instance is already running when this method is called, the method will return immediately.
-    /// </para>
-    /// </remarks>
-    /// <param name="instanceId">The unique ID of the orchestration instance to wait for.</param>
-    /// <param name="getInputsAndOutputs">
-    /// Specify <c>true</c> to fetch the orchestration instance's inputs, outputs, and custom status, or <c>false</c> to
-    /// omit them. The default value is <c>false</c> to minimize the network bandwidth, serialization, and memory costs
-    /// associated with fetching the instance metadata.
-    /// </param>
-    /// <param name="cancellation">A <see cref="CancellationToken"/> that can be used to cancel the wait operation.</param>
-    /// <returns>
-    /// Returns a <see cref="OrchestrationMetadata"/> record that describes the orchestration instance and its execution
-    /// status or <c>null</c> if no instance with ID <paramref name="instanceId"/> is found.
-    /// </returns>
-    public abstract Task<OrchestrationMetadata> WaitForInstanceStartAsync(
-        string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default);
-
-    /// <inheritdoc cref="WaitForInstanceCompletionAsync(string, bool, CancellationToken)"/>
-    public virtual Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(
-        string instanceId, CancellationToken cancellation)
-        => this.WaitForInstanceCompletionAsync(instanceId, false, cancellation);
-
-    /// <summary>
-    /// Waits for an orchestration to complete and returns a <see cref="OrchestrationMetadata"/>
-    /// object that contains metadata about the started instance.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// A "completed" orchestration instance is any instance in one of the terminal states. For example, the
-    /// <see cref="OrchestrationRuntimeStatus.Completed"/>, <see cref="OrchestrationRuntimeStatus.Failed"/>, or
-    /// <see cref="OrchestrationRuntimeStatus.Terminated"/> states.
-    /// </para><para>
-    /// 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 <paramref name="cancellation"/> parameter.
-    /// </para><para>
-    /// If an orchestration instance is already complete when this method is called, the method will return immediately.
-    /// </para>
-    /// </remarks>
-    /// <inheritdoc cref="WaitForInstanceStartAsync(string, bool, CancellationToken)"/>
-    public abstract Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(
-        string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default);
-
-    /// <inheritdoc cref="GetInstanceMetadataAsync(string, bool, CancellationToken)"/>
-    public virtual Task<OrchestrationMetadata?> GetInstanceMetadataAsync(
+    /// <inheritdoc cref="GetInstancesAsync(string, bool, CancellationToken)"/>
+    public virtual Task<OrchestrationMetadata?> GetInstancesAsync(
         string instanceId, CancellationToken cancellation)
-        => this.GetInstanceMetadataAsync(instanceId, false, cancellation);
+        => this.GetInstancesAsync(instanceId, false, cancellation);
 
     /// <summary>
     /// Fetches orchestration instance metadata from the configured durable store.
@@ -278,15 +285,15 @@ public abstract Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(
     /// memory costs associated with fetching the instance metadata.
     /// </remarks>
     /// <inheritdoc cref="WaitForInstanceStartAsync(string, bool, CancellationToken)"/>
-    public abstract Task<OrchestrationMetadata?> GetInstanceMetadataAsync(
+    public abstract Task<OrchestrationMetadata?> GetInstancesAsync(
         string instanceId, bool getInputsAndOutputs = false, CancellationToken cancellation = default);
 
     /// <summary>
     /// Queries orchestration instances.
     /// </summary>
-    /// <param name="query">Filters down the instances included in the query.</param>
+    /// <param name="filter">Filters down the instances included in the query.</param>
     /// <returns>An async pageable of the query results.</returns>
-    public abstract AsyncPageable<OrchestrationMetadata> GetInstances(OrchestrationQuery? query = null);
+    public abstract AsyncPageable<OrchestrationMetadata> GetAllInstancesAsync(OrchestrationQuery? filter = null);
 
     /// <summary>
     /// Purges orchestration instance metadata from the durable store.
@@ -314,7 +321,7 @@ public abstract Task<OrchestrationMetadata> WaitForInstanceCompletionAsync(
     /// <see cref="PurgeResult.PurgedInstanceCount"/> value of <c>1</c> or <c>0</c>, depending on whether the target
     /// instance was successfully purged.
     /// </returns>
-    public abstract Task<PurgeResult> PurgeInstanceMetadataAsync(
+    public abstract Task<PurgeResult> PurgeInstanceAsync(
         string instanceId, CancellationToken cancellation = default);
 
     /// <summary>
@@ -328,7 +335,7 @@ public abstract Task<PurgeResult> PurgeInstanceMetadataAsync(
     /// This method returns a <see cref="PurgeResult"/> object after the operation has completed with a
     /// <see cref="PurgeResult.PurgedInstanceCount"/> indicating the number of orchestration instances that were purged.
     /// </returns>
-    public abstract Task<PurgeResult> PurgeInstancesAsync(
+    public abstract Task<PurgeResult> PurgeAllInstancesAsync(
         PurgeInstancesFilter filter, CancellationToken cancellation = default);
 
     // TODO: Create task hub

src/Client/Core/OrchestrationMetadata.cs

@@ -11,7 +11,7 @@ namespace Microsoft.DurableTask.Client;
 /// </summary>
 /// <remarks>
 /// Instances of this class are produced by methods in the <see cref="DurableTaskClient"/> class, such as
-/// <see cref="DurableTaskClient.GetInstanceMetadataAsync(string, CancellationToken)"/>,
+/// <see cref="DurableTaskClient.GetInstancesAsync(string, CancellationToken)"/>,
 /// <see cref="DurableTaskClient.WaitForInstanceStartAsync(string, CancellationToken)"/> and
 /// <see cref="DurableTaskClient.WaitForInstanceCompletionAsync(string, CancellationToken)"/>.
 /// </remarks>
@@ -117,7 +117,7 @@ public OrchestrationMetadata(string name, string instanceId)
     /// </summary>
     /// <remarks>
     /// This method can only be used when inputs and outputs are explicitly requested from the
-    /// <see cref="DurableTaskClient.GetInstanceMetadataAsync(string, CancellationToken)"/> or
+    /// <see cref="DurableTaskClient.GetInstancesAsync(string, CancellationToken)"/> or
     /// <see cref="DurableTaskClient.WaitForInstanceCompletionAsync(string, CancellationToken)"/> method that produced
     /// this <see cref="OrchestrationMetadata"/> object.
     /// </remarks>
@@ -143,7 +143,7 @@ public OrchestrationMetadata(string name, string instanceId)
     /// </summary>
     /// <remarks>
     /// This method can only be used when inputs and outputs are explicitly requested from the
-    /// <see cref="DurableTaskClient.GetInstanceMetadataAsync(string, CancellationToken)"/> or
+    /// <see cref="DurableTaskClient.GetInstancesAsync(string, CancellationToken)"/> or
     /// <see cref="DurableTaskClient.WaitForInstanceCompletionAsync(string, CancellationToken)"/> method that produced
     /// this <see cref="OrchestrationMetadata"/> object.
     /// </remarks>
@@ -169,7 +169,7 @@ public OrchestrationMetadata(string name, string instanceId)
     /// </summary>
     /// <remarks>
     /// This method can only be used when inputs and outputs are explicitly requested from the
-    /// <see cref="DurableTaskClient.GetInstanceMetadataAsync(string, CancellationToken)"/> or
+    /// <see cref="DurableTaskClient.GetInstancesAsync(string, CancellationToken)"/> or
     /// <see cref="DurableTaskClient.WaitForInstanceCompletionAsync(string, CancellationToken)"/> method that produced
     /// this <see cref="OrchestrationMetadata"/> object.
     /// </remarks>

src/Client/Core/PurgeInstancesFilter.cs

@@ -10,6 +10,8 @@ namespace Microsoft.DurableTask.Client;
 /// <param name="CreatedTo">Date created to.</param>
 /// <param name="Statuses">The statuses.</param>
 public record PurgeInstancesFilter(
-    DateTimeOffset? CreatedFrom, DateTimeOffset? CreatedTo, IEnumerable<OrchestrationRuntimeStatus>? Statuses)
+    DateTimeOffset? CreatedFrom = null,
+    DateTimeOffset? CreatedTo = null,
+    IEnumerable<OrchestrationRuntimeStatus>? Statuses = null)
 {
 }