Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,16 @@ static class HelloSequenceUntyped

You can find the full sample file, including detailed comments, at [samples/AzureFunctionsApp/HelloCitiesUntyped.cs](samples/AzureFunctionsApp/HelloCitiesUntyped.cs).

### Restarting as a clone

```csharp
string cloneId = await client.RestartAsync(
"source-instance",
"clone-instance",
version: "v2",
cancellation: CancellationToken.None);
```

### Class-based syntax

**IMPORTANT**: class based syntax in Durable Functions relies on a package reference to `Microsoft.DurableTask.Generators`. This is still in "preview" and may be subject to significant change before 1.0 or even post-1.0. It is recommended to stick with function-syntax for now.
Expand Down
14 changes: 14 additions & 0 deletions src/Abstractions/TaskOrchestrationContext.cs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,20 @@ public abstract class TaskOrchestrationContext
/// </summary>
public abstract string InstanceId { get; }

/// <summary>
/// Gets the immediate source instance ID when this orchestration was restarted as a clone, or <c>null</c>
/// when no source lineage was supplied by the backend.
/// </summary>
/// <remarks>
/// This is distinct from <see cref="Parent"/> and is not inherited by sub-orchestrations.
/// Cloning a clone identifies that clone as the immediate source, not its original ancestor.
/// The ID is an opaque string, even when it resembles a serialized timestamp.
/// </remarks>
public virtual string? SourceInstanceId =>
this.Properties.TryGetValue("sourceInstanceId", out object? source) && source is string instanceId
? instanceId
: null;

/// <summary>
/// Gets the parent instance or <c>null</c> if there is no parent orchestration.
/// </summary>
Expand Down
38 changes: 38 additions & 0 deletions src/Client/Core/DurableTaskClient.cs
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,44 @@ public virtual Task<string> RestartAsync(
CancellationToken cancellation = default)
=> throw new NotSupportedException($"{this.GetType()} does not support orchestration restart.");

/// <summary>
/// Restarts an orchestration from the beginning using its original name and input and a caller-selected instance ID.
/// </summary>
/// <remarks>
/// <para>
/// This operation does not copy execution history. When the source and target IDs differ, a supporting backend
/// makes the immediate source instance ID available through <see cref="TaskOrchestrationContext.SourceInstanceId"/>
/// on the restarted orchestration.
/// The version is selected using <paramref name="version"/>, including backend-specific
/// defaults when no override is provided.
/// </para>
/// <para>
/// This overload requires a backend that supports cloning with explicit restart IDs and version overrides.
/// Older gRPC servers reject the separate clone request without performing a legacy restart.
/// Upgrade the server before using this overload; a returned instance ID cannot verify whether a version override
/// was honored.
/// </para>
/// </remarks>
/// <param name="instanceId">The required, nonblank ID of the source orchestration.</param>
/// <param name="newInstanceId">The required, nonblank ID of the restarted orchestration.</param>
/// <param name="version">
/// The version override for the restarted orchestration. A <c>null</c> value uses the backend's restart default,
/// which need not be the original version. An empty string explicitly selects the unversioned orchestration.
/// </param>
/// <param name="cancellation">Cancels enqueueing the request, not execution once enqueued.</param>
/// <returns>The instance ID of the restarted orchestration.</returns>
/// <exception cref="ArgumentException">The source was not found or an instance ID is invalid.</exception>
/// <exception cref="ArgumentNullException"><paramref name="instanceId"/> is <c>null</c>.</exception>
/// <exception cref="OrchestrationAlreadyExistsException">The target instance ID conflicts with an existing instance.</exception>
/// <exception cref="InvalidOperationException">The backend rejected the operation or returned an unexpected instance ID.</exception>
/// <exception cref="NotSupportedException">The client or backend does not support explicit restart IDs and version overrides.</exception>
public virtual Task<string> RestartAsync(
string instanceId,
string newInstanceId,
string? version,
CancellationToken cancellation)
Comment thread
bachuv marked this conversation as resolved.
Resolved
=> throw new NotSupportedException($"{this.GetType()} does not support explicit restart IDs and version overrides.");

/// <summary>
/// Rewinds the specified orchestration instance by re-executing any failed Activities, and recursively rewinding
/// any failed suborchestrations with failed Activities.
Expand Down
99 changes: 84 additions & 15 deletions src/Client/Grpc/GrpcDurableTaskClient.cs
Comment thread
bachuv marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
Expand Up @@ -123,11 +123,14 @@ public override async Task<string> ScheduleNewOrchestrationInstanceAsync(
}

DateTimeOffset? startAt = options?.StartAt;
this.logger.SchedulingOrchestration(
request.InstanceId ?? string.Empty,
orchestratorName,
sizeInBytes: request.Input != null ? Encoding.UTF8.GetByteCount(request.Input) : 0,
startAt.GetValueOrDefault(DateTimeOffset.UtcNow));
if (this.logger.IsEnabled(LogLevel.Information))
{
this.logger.SchedulingOrchestration(
request.InstanceId ?? string.Empty,
orchestratorName,
sizeInBytes: request.Input != null ? Encoding.UTF8.GetByteCount(request.Input) : 0,
startAt.GetValueOrDefault(DateTimeOffset.UtcNow));
}

if (startAt.HasValue)
{
Expand Down Expand Up @@ -532,25 +535,69 @@ public override async Task<string> RestartAsync(
RestartWithNewInstanceId = restartWithNewInstanceId,
};

P.RestartInstanceResponse result = await this.InvokeRestartRpcAsync(
instanceId,
() => this.sidecarClient.RestartInstanceAsync(request, cancellationToken: cancellation).ResponseAsync,
cancellation);
return result.InstanceId;
}

/// <inheritdoc/>
public override async Task<string> RestartAsync(
string instanceId,
string newInstanceId,
string? version,
CancellationToken cancellation)
{
Check.NotNullOrEmpty(instanceId);
if (string.IsNullOrWhiteSpace(instanceId))
{
throw new ArgumentException("A nonblank source instance ID is required.", nameof(instanceId));
}

Check.NotEntity(this.options.EnableEntitySupport, instanceId);
if (string.IsNullOrWhiteSpace(newInstanceId))
{
throw new ArgumentException("A nonblank target instance ID is required.", nameof(newInstanceId));
}

Check.NotEntity(this.options.EnableEntitySupport, newInstanceId);
P.CloneInstanceRequest request = new()
{
SourceInstanceId = instanceId,
NewInstanceId = newInstanceId,
Version = version,
};

P.CloneInstanceResponse response;
try
{
P.RestartInstanceResponse result = await this.sidecarClient.RestartInstanceAsync(
request, cancellationToken: cancellation);
return result.InstanceId;
response = await this.InvokeRestartRpcAsync(
instanceId,
() => this.sidecarClient.CloneInstanceAsync(request, cancellationToken: cancellation).ResponseAsync,
cancellation);
}
catch (RpcException e) when (e.StatusCode == StatusCode.NotFound)
catch (RpcException e) when (e.StatusCode == StatusCode.AlreadyExists)
{
throw new ArgumentException($"An orchestration with the instanceId {instanceId} was not found.", e);
throw new OrchestrationAlreadyExistsException(e.Status.Detail);
}
catch (RpcException e) when (e.StatusCode == StatusCode.FailedPrecondition)
catch (RpcException e) when (e.StatusCode == StatusCode.InvalidArgument)
{
throw new InvalidOperationException($"An orchestration with the instanceId {instanceId} cannot be restarted.", e);
throw new ArgumentException(e.Status.Detail, e);
}
catch (RpcException e) when (e.StatusCode == StatusCode.Cancelled)
catch (RpcException e) when (e.StatusCode == StatusCode.Unimplemented)
{
throw new OperationCanceledException(
$"The {nameof(this.RestartAsync)} operation was canceled.", e, cancellation);
throw new NotSupportedException("The backend does not support orchestration cloning.", e);
}

if (!string.Equals(response.InstanceId, newInstanceId, StringComparison.Ordinal))
{
throw new InvalidOperationException(
$"The backend returned clone instance ID '{response.InstanceId}' instead of the requested ID "
+ $"'{newInstanceId}'.");
}

return response.InstanceId;
}

/// <inheritdoc/>
Expand Down Expand Up @@ -764,6 +811,28 @@ static GrpcChannel GetChannel(string? address)
}
#endif

async Task<TResponse> InvokeRestartRpcAsync<TResponse>(
string instanceId, Func<Task<TResponse>> operation, CancellationToken cancellation)
{
try
{
return await operation();
}
catch (RpcException e) when (e.StatusCode == StatusCode.NotFound)
{
throw new ArgumentException($"An orchestration with the instanceId {instanceId} was not found.", e);
}
catch (RpcException e) when (e.StatusCode == StatusCode.FailedPrecondition)
{
throw new InvalidOperationException($"An orchestration with the instanceId {instanceId} cannot be restarted.", e);
}
catch (RpcException e) when (e.StatusCode == StatusCode.Cancelled)
{
throw new OperationCanceledException(
$"The {nameof(this.RestartAsync)} operation was canceled.", e, cancellation);
}
}

async Task<PurgeResult> PurgeInstancesCoreAsync(
P.PurgeInstancesRequest request, CancellationToken cancellation = default)
{
Expand Down
31 changes: 31 additions & 0 deletions src/Grpc/orchestrator_service.proto
Original file line number Diff line number Diff line change
Expand Up @@ -542,6 +542,29 @@ message RestartInstanceResponse {
string instanceId = 1;
}

// Restarts an orchestration from the beginning with the source's original name
// and input, without copying its history. When source and target IDs differ, the
// clone's source lineage identifies sourceInstanceId (the immediate source), not
// an earlier ancestor. Sub-orchestrations must not inherit this source lineage.
message CloneInstanceRequest {
// Required, nonblank ID of the source orchestration.
string sourceInstanceId = 1;

// Required, nonblank target ID; may equal sourceInstanceId.
// Target conflicts follow the backend's existing instance-ID conflict behavior.
string newInstanceId = 2;

// Overrides the cloned orchestration's version when present. An explicit
// empty string selects an unversioned orchestration; absence preserves the
// backend's default restart behavior.
google.protobuf.StringValue version = 3;
}

message CloneInstanceResponse {
// The requested target instance ID.
string instanceId = 1;
}

message CreateTaskHubRequest {
bool recreateIfExists = 1;
}
Expand Down Expand Up @@ -760,6 +783,14 @@ service TaskHubSidecarService {
// Restarts an orchestration instance.
rpc RestartInstance(RestartInstanceRequest) returns (RestartInstanceResponse);

// Clones an orchestration to an explicit target instance ID.
// Implementations must reject invalid requests and unsupported cloning or
// version semantics before scheduling or creating any orchestration.
// Options must not be ignored, and callers and servers must not fall back
// to RestartInstance. Servers without this RPC return UNIMPLEMENTED without
// invoking RestartInstance.
rpc CloneInstance(CloneInstanceRequest) returns (CloneInstanceResponse);

// Waits for an orchestration instance to reach a running or completion state.
rpc WaitForInstanceStart(GetInstanceRequest) returns (GetInstanceResponse);

Expand Down
8 changes: 4 additions & 4 deletions src/Grpc/versions.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# The following files were downloaded from branch main at 2026-10-20 19:46:22 UTC
https://raw.githubusercontent.com/microsoft/durabletask-protobuf/20d2aadae358d8aa526190cbf78fb6c313b0b3db/protos/orchestrator_service.proto
https://raw.githubusercontent.com/microsoft/durabletask-protobuf/20d2aadae358d8aa526190cbf78fb6c313b0b3db/protos/durable-task-scheduler/sandbox_service.proto
https://raw.githubusercontent.com/microsoft/durabletask-protobuf/20d2aadae358d8aa526190cbf78fb6c313b0b3db/protos/durable-task-scheduler/large_payload_purge.proto
# The following files were downloaded from branch vabachu/orchestration-clone-protocol at 2026-11-10 05:20:38 UTC
https://raw.githubusercontent.com/microsoft/durabletask-protobuf/4fb1fb241603166f4283a5d61842f0ff55c5da84/protos/orchestrator_service.proto
https://raw.githubusercontent.com/microsoft/durabletask-protobuf/4fb1fb241603166f4283a5d61842f0ff55c5da84/protos/durable-task-scheduler/sandbox_service.proto
https://raw.githubusercontent.com/microsoft/durabletask-protobuf/4fb1fb241603166f4283a5d61842f0ff55c5da84/protos/durable-task-scheduler/large_payload_purge.proto
14 changes: 14 additions & 0 deletions src/Shared/Grpc/ProtoUtils.cs
Original file line number Diff line number Diff line change
Expand Up @@ -1103,6 +1103,20 @@ internal static T Base64Decode<T>(this MessageParser parser, string encodedMessa
kvp => ConvertValueToObject(kvp.Value));
}

/// <summary>
/// Converts orchestration request properties, preserving source instance IDs as opaque strings.
/// </summary>
/// <param name="properties">The orchestration request properties to convert.</param>
/// <returns>The converted orchestration properties.</returns>
internal static Dictionary<string, object?> ConvertOrchestrationProperties(MapField<string, Value> properties)
{
return properties.ToDictionary(
pair => pair.Key,
pair => pair.Key == "sourceInstanceId" && pair.Value.KindCase == Value.KindOneofCase.StringValue
? pair.Value.StringValue
: ConvertValueToObject(pair.Value));
}

/// <summary>
/// Converts a C# object to a protobuf Value.
/// </summary>
Expand Down
3 changes: 2 additions & 1 deletion src/Worker/Grpc/GrpcDurableTaskWorker.Processor.cs
Original file line number Diff line number Diff line change
Expand Up @@ -896,7 +896,8 @@ await this.ExecuteWithRetryAsync(
_ => null,
};

TaskOrchestration shim = this.shimFactory.CreateOrchestration(name, orchestrator, parent);
Dictionary<string, object?> properties = ProtoUtils.ConvertOrchestrationProperties(request.Properties);
TaskOrchestration shim = this.shimFactory.CreateOrchestration(name, orchestrator, properties, parent);
TaskOrchestrationExecutor executor = new(
runtimeState,
shim,
Expand Down
4 changes: 1 addition & 3 deletions src/Worker/Grpc/GrpcOrchestrationRunner.cs
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,7 @@ public static string LoadAndRun(

List<HistoryEvent> pastEvents = request.PastEvents.Select(ProtoUtils.ConvertHistoryEvent).ToList();
IEnumerable<HistoryEvent> newEvents = request.NewEvents.Select(ProtoUtils.ConvertHistoryEvent);
Dictionary<string, object?> properties = request.Properties.ToDictionary(
pair => pair.Key,
pair => ProtoUtils.ConvertValueToObject(pair.Value));
Dictionary<string, object?> properties = ProtoUtils.ConvertOrchestrationProperties(request.Properties);

OrchestratorExecutionResult? result = null;

Expand Down
Loading
Loading