diff --git a/README.md b/README.md
index 9941a8c4..d0e1157a 100644
--- a/README.md
+++ b/README.md
@@ -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.
diff --git a/src/Abstractions/TaskOrchestrationContext.cs b/src/Abstractions/TaskOrchestrationContext.cs
index 6f6fa793..a128b785 100644
--- a/src/Abstractions/TaskOrchestrationContext.cs
+++ b/src/Abstractions/TaskOrchestrationContext.cs
@@ -25,6 +25,20 @@ public abstract class TaskOrchestrationContext
///
public abstract string InstanceId { get; }
+ ///
+ /// Gets the immediate source instance ID when this orchestration was restarted as a clone, or null
+ /// when no source lineage was supplied by the backend.
+ ///
+ ///
+ /// This is distinct from 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.
+ ///
+ public virtual string? SourceInstanceId =>
+ this.Properties.TryGetValue("sourceInstanceId", out object? source) && source is string instanceId
+ ? instanceId
+ : null;
+
///
/// Gets the parent instance or null if there is no parent orchestration.
///
diff --git a/src/Client/Core/DurableTaskClient.cs b/src/Client/Core/DurableTaskClient.cs
index 03303800..8135037e 100644
--- a/src/Client/Core/DurableTaskClient.cs
+++ b/src/Client/Core/DurableTaskClient.cs
@@ -465,6 +465,44 @@ public virtual Task RestartAsync(
CancellationToken cancellation = default)
=> throw new NotSupportedException($"{this.GetType()} does not support orchestration restart.");
+ ///
+ /// Restarts an orchestration from the beginning using its original name and input and a caller-selected instance ID.
+ ///
+ ///
+ ///
+ /// 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
+ /// on the restarted orchestration.
+ /// The version is selected using , including backend-specific
+ /// defaults when no override is provided.
+ ///
+ ///
+ /// 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.
+ ///
+ ///
+ /// The required, nonblank ID of the source orchestration.
+ /// The required, nonblank ID of the restarted orchestration.
+ ///
+ /// The version override for the restarted orchestration. A null value uses the backend's restart default,
+ /// which need not be the original version. An empty string explicitly selects the unversioned orchestration.
+ ///
+ /// Cancels enqueueing the request, not execution once enqueued.
+ /// The instance ID of the restarted orchestration.
+ /// The source was not found or an instance ID is invalid.
+ /// is null.
+ /// The target instance ID conflicts with an existing instance.
+ /// The backend rejected the operation or returned an unexpected instance ID.
+ /// The client or backend does not support explicit restart IDs and version overrides.
+ public virtual Task RestartAsync(
+ string instanceId,
+ string newInstanceId,
+ string? version,
+ CancellationToken cancellation)
+ => throw new NotSupportedException($"{this.GetType()} does not support explicit restart IDs and version overrides.");
+
///
/// Rewinds the specified orchestration instance by re-executing any failed Activities, and recursively rewinding
/// any failed suborchestrations with failed Activities.
diff --git a/src/Client/Grpc/GrpcDurableTaskClient.cs b/src/Client/Grpc/GrpcDurableTaskClient.cs
index f18c7565..75b9858d 100644
--- a/src/Client/Grpc/GrpcDurableTaskClient.cs
+++ b/src/Client/Grpc/GrpcDurableTaskClient.cs
@@ -123,11 +123,14 @@ public override async Task 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)
{
@@ -532,25 +535,69 @@ public override async Task RestartAsync(
RestartWithNewInstanceId = restartWithNewInstanceId,
};
+ P.RestartInstanceResponse result = await this.InvokeRestartRpcAsync(
+ instanceId,
+ () => this.sidecarClient.RestartInstanceAsync(request, cancellationToken: cancellation).ResponseAsync,
+ cancellation);
+ return result.InstanceId;
+ }
+
+ ///
+ public override async Task 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;
}
///
@@ -764,6 +811,28 @@ static GrpcChannel GetChannel(string? address)
}
#endif
+ async Task InvokeRestartRpcAsync(
+ string instanceId, Func> 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 PurgeInstancesCoreAsync(
P.PurgeInstancesRequest request, CancellationToken cancellation = default)
{
diff --git a/src/Grpc/orchestrator_service.proto b/src/Grpc/orchestrator_service.proto
index 2429fff4..faa2aea6 100644
--- a/src/Grpc/orchestrator_service.proto
+++ b/src/Grpc/orchestrator_service.proto
@@ -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;
}
@@ -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);
diff --git a/src/Grpc/versions.txt b/src/Grpc/versions.txt
index 6f9983e3..db9e88c3 100644
--- a/src/Grpc/versions.txt
+++ b/src/Grpc/versions.txt
@@ -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
diff --git a/src/Shared/Grpc/ProtoUtils.cs b/src/Shared/Grpc/ProtoUtils.cs
index 981610ee..d1eff344 100644
--- a/src/Shared/Grpc/ProtoUtils.cs
+++ b/src/Shared/Grpc/ProtoUtils.cs
@@ -1103,6 +1103,20 @@ internal static T Base64Decode(this MessageParser parser, string encodedMessa
kvp => ConvertValueToObject(kvp.Value));
}
+ ///
+ /// Converts orchestration request properties, preserving source instance IDs as opaque strings.
+ ///
+ /// The orchestration request properties to convert.
+ /// The converted orchestration properties.
+ internal static Dictionary ConvertOrchestrationProperties(MapField properties)
+ {
+ return properties.ToDictionary(
+ pair => pair.Key,
+ pair => pair.Key == "sourceInstanceId" && pair.Value.KindCase == Value.KindOneofCase.StringValue
+ ? pair.Value.StringValue
+ : ConvertValueToObject(pair.Value));
+ }
+
///
/// Converts a C# object to a protobuf Value.
///
diff --git a/src/Worker/Grpc/GrpcDurableTaskWorker.Processor.cs b/src/Worker/Grpc/GrpcDurableTaskWorker.Processor.cs
index 6bf28781..1afba758 100644
--- a/src/Worker/Grpc/GrpcDurableTaskWorker.Processor.cs
+++ b/src/Worker/Grpc/GrpcDurableTaskWorker.Processor.cs
@@ -896,7 +896,8 @@ await this.ExecuteWithRetryAsync(
_ => null,
};
- TaskOrchestration shim = this.shimFactory.CreateOrchestration(name, orchestrator, parent);
+ Dictionary properties = ProtoUtils.ConvertOrchestrationProperties(request.Properties);
+ TaskOrchestration shim = this.shimFactory.CreateOrchestration(name, orchestrator, properties, parent);
TaskOrchestrationExecutor executor = new(
runtimeState,
shim,
diff --git a/src/Worker/Grpc/GrpcOrchestrationRunner.cs b/src/Worker/Grpc/GrpcOrchestrationRunner.cs
index 5fbe2228..17567227 100644
--- a/src/Worker/Grpc/GrpcOrchestrationRunner.cs
+++ b/src/Worker/Grpc/GrpcOrchestrationRunner.cs
@@ -126,9 +126,7 @@ public static string LoadAndRun(
List pastEvents = request.PastEvents.Select(ProtoUtils.ConvertHistoryEvent).ToList();
IEnumerable newEvents = request.NewEvents.Select(ProtoUtils.ConvertHistoryEvent);
- Dictionary properties = request.Properties.ToDictionary(
- pair => pair.Key,
- pair => ProtoUtils.ConvertValueToObject(pair.Value));
+ Dictionary properties = ProtoUtils.ConvertOrchestrationProperties(request.Properties);
OrchestratorExecutionResult? result = null;
diff --git a/test/Client/Grpc.Tests/GrpcDurableTaskClientRestartTests.cs b/test/Client/Grpc.Tests/GrpcDurableTaskClientRestartTests.cs
new file mode 100644
index 00000000..07f8c803
--- /dev/null
+++ b/test/Client/Grpc.Tests/GrpcDurableTaskClientRestartTests.cs
@@ -0,0 +1,299 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using DurableTask.Core.Exceptions;
+using Google.Protobuf;
+using Grpc.Core;
+using Microsoft.Extensions.Logging.Abstractions;
+using P = Microsoft.DurableTask.Protobuf;
+
+namespace Microsoft.DurableTask.Client.Grpc.Tests;
+
+public class GrpcDurableTaskClientRestartTests
+{
+ [Theory]
+ [InlineData("target", null)]
+ [InlineData("target", "")]
+ [InlineData("target", "v2")]
+ [InlineData("source", null)]
+ public async Task RestartAsync_ExplicitInstanceId_UsesCloneRpcAndForwardsTargetAndVersion(string target, string? version)
+ {
+ // Arrange
+ using CancellationTokenSource cancellation = new();
+ P.CloneInstanceRequest? captured = null;
+ CancellationToken capturedCancellation = default;
+ Mock invoker = CreateInvoker((request, callOptions) =>
+ {
+ captured = P.CloneInstanceRequest.Parser.ParseFrom(request.ToByteArray());
+ capturedCancellation = callOptions.CancellationToken;
+ return Task.FromResult(new P.CloneInstanceResponse { InstanceId = target });
+ });
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ string result = await client.RestartAsync(
+ "source", target, version, cancellation.Token);
+
+ // Assert
+ result.Should().Be(target);
+ captured.Should().NotBeNull();
+ captured!.SourceInstanceId.Should().Be("source");
+ captured.NewInstanceId.Should().Be(target);
+ captured.Version.Should().Be(version);
+ capturedCancellation.Should().Be(cancellation.Token);
+ invoker.Verify(x => x.AsyncUnaryCall(
+ It.Is>(method => method.Name == "CloneInstance"),
+ It.IsAny(), It.IsAny(), It.IsAny()), Times.Once);
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Theory]
+ [InlineData(false)]
+ [InlineData(true)]
+ public async Task RestartAsync_LegacyDefaultArguments_UseRestartRpc(bool useBaseClient)
+ {
+ // Arrange
+ using CancellationTokenSource cancellation = new();
+ List<(P.RestartInstanceRequest Request, CancellationToken Cancellation)> captured = new();
+ Mock invoker = CreateInvoker((request, callOptions) =>
+ {
+ captured.Add((P.RestartInstanceRequest.Parser.ParseFrom(request.ToByteArray()), callOptions.CancellationToken));
+ return Task.FromResult(new P.RestartInstanceResponse { InstanceId = "source" });
+ });
+ await using GrpcDurableTaskClient grpcClient = CreateClient(invoker);
+ DurableTaskClient client = grpcClient;
+
+ // Act
+ string[] results = useBaseClient
+ ? new[]
+ {
+ await client.RestartAsync("source"),
+ await client.RestartAsync("source", default),
+ await client.RestartAsync("source", default, default),
+ await client.RestartAsync("source", default, cancellation.Token),
+ }
+ : new[]
+ {
+ await grpcClient.RestartAsync("source"),
+ await grpcClient.RestartAsync("source", default),
+ await grpcClient.RestartAsync("source", default, default),
+ await grpcClient.RestartAsync("source", default, cancellation.Token),
+ };
+
+ // Assert
+ results.Should().Equal("source", "source", "source", "source");
+ captured.Should().HaveCount(4);
+ captured.Should().OnlyContain(call => call.Request.InstanceId == "source" && !call.Request.RestartWithNewInstanceId);
+ captured.Select(call => call.Cancellation).Should().Equal(default, default, default, cancellation.Token);
+ invoker.Verify(x => x.AsyncUnaryCall(
+ It.Is>(method => method.Name == "RestartInstance"),
+ It.IsAny(), It.IsAny(), It.IsAny()), Times.Exactly(4));
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Theory]
+ [InlineData(false)]
+ [InlineData(true)]
+ public async Task RestartAsync_LegacyBool_PreservesRequest(bool newInstanceId)
+ {
+ // Arrange
+ P.RestartInstanceRequest? captured = null;
+ Mock invoker = CreateInvoker((request, _) =>
+ {
+ captured = P.RestartInstanceRequest.Parser.ParseFrom(request.ToByteArray());
+ return Task.FromResult(new P.RestartInstanceResponse { InstanceId = "returned-id" });
+ });
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ string result = await client.RestartAsync("source", newInstanceId);
+
+ // Assert
+ result.Should().Be("returned-id");
+ captured!.InstanceId.Should().Be("source");
+ captured.RestartWithNewInstanceId.Should().Be(newInstanceId);
+ invoker.Verify(x => x.AsyncUnaryCall(
+ It.Is>(method => method.Name == "RestartInstance"),
+ It.IsAny(), It.IsAny(), It.IsAny()), Times.Once);
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Theory]
+ [InlineData(null)]
+ [InlineData("")]
+ [InlineData(" ")]
+ public async Task RestartAsync_InvalidTarget_DoesNotSendRequest(string? target)
+ {
+ // Arrange
+ Mock invoker = new(MockBehavior.Strict);
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync("source", target!, null, default);
+
+ // Assert
+ await act.Should().ThrowAsync().WithParameterName("newInstanceId");
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Theory]
+ [InlineData(null)]
+ [InlineData("")]
+ [InlineData(" ")]
+ [InlineData("\t")]
+ public async Task RestartAsync_InvalidSource_DoesNotSendRequest(string? source)
+ {
+ // Arrange
+ Mock invoker = new(MockBehavior.Strict);
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync(source!, "target", null, default);
+
+ // Assert
+ await act.Should().ThrowAsync();
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Theory]
+ [InlineData("@counter@source", "target")]
+ [InlineData("source", "@counter@target")]
+ public async Task RestartAsync_EntityId_DoesNotSendRequest(string source, string target)
+ {
+ // Arrange
+ Mock invoker = new(MockBehavior.Strict);
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync(source, target, null, default);
+
+ // Assert
+ await act.Should().ThrowAsync();
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Fact]
+ public async Task RestartAsync_CloneResponseWithWrongTarget_ThrowsInvalidOperation()
+ {
+ // Arrange
+ Mock invoker = CreateInvoker((_, _) =>
+ Task.FromResult(new P.CloneInstanceResponse { InstanceId = "unexpected-id" }));
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync("source", "target", null, default);
+
+ // Assert
+ await act.Should().ThrowAsync()
+ .WithMessage("*unexpected-id*target*");
+ }
+
+ [Theory]
+ [InlineData(StatusCode.NotFound, typeof(ArgumentException))]
+ [InlineData(StatusCode.FailedPrecondition, typeof(InvalidOperationException))]
+ [InlineData(StatusCode.InvalidArgument, typeof(ArgumentException))]
+ [InlineData(StatusCode.AlreadyExists, typeof(OrchestrationAlreadyExistsException))]
+ [InlineData(StatusCode.Cancelled, typeof(OperationCanceledException))]
+ [InlineData(StatusCode.Unimplemented, typeof(NotSupportedException))]
+ [InlineData(StatusCode.Unavailable, typeof(RpcException))]
+ public async Task RestartAsync_ExplicitInstanceId_RpcError_MapsError(StatusCode status, Type expectedException)
+ {
+ // Arrange
+ using CancellationTokenSource cancellation = new();
+ Mock invoker = CreateInvoker((_, _) =>
+ Task.FromException(new RpcException(new Status(status, "test failure"))));
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync(
+ "source", "target", null, cancellation.Token);
+
+ // Assert
+ Exception exception = (await act.Should().ThrowAsync()).Which;
+ exception.GetType().Should().Be(expectedException);
+ if (exception is OperationCanceledException canceled)
+ {
+ canceled.CancellationToken.Should().Be(cancellation.Token);
+ }
+ }
+
+ [Theory]
+ [InlineData(StatusCode.NotFound, typeof(ArgumentException))]
+ [InlineData(StatusCode.FailedPrecondition, typeof(InvalidOperationException))]
+ [InlineData(StatusCode.Cancelled, typeof(OperationCanceledException))]
+ [InlineData(StatusCode.Unimplemented, typeof(RpcException))]
+ [InlineData(StatusCode.AlreadyExists, typeof(RpcException))]
+ public async Task RestartAsync_LegacyBool_RpcError_PreservesErrorMapping(StatusCode status, Type expectedException)
+ {
+ // Arrange
+ using CancellationTokenSource cancellation = new();
+ Mock invoker = CreateInvoker((_, _) =>
+ Task.FromException(new RpcException(new Status(status, "test failure"))));
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync("source", true, cancellation.Token);
+
+ // Assert
+ Exception exception = (await act.Should().ThrowAsync()).Which;
+ exception.GetType().Should().Be(expectedException);
+ if (exception is OperationCanceledException canceled)
+ {
+ canceled.CancellationToken.Should().Be(cancellation.Token);
+ }
+ }
+
+ [Fact]
+ public async Task RestartAsync_ExplicitInstanceId_UnsupportedServer_DoesNotFallbackToRestart()
+ {
+ // Arrange
+ Mock invoker = CreateInvoker((_, _) =>
+ Task.FromException(
+ new RpcException(new Status(StatusCode.Unimplemented, "unknown method"))));
+ await using GrpcDurableTaskClient client = CreateClient(invoker);
+
+ // Act
+ Func act = () => client.RestartAsync("source", "target", null, default);
+
+ // Assert
+ NotSupportedException exception = (await act.Should().ThrowAsync()).Which;
+ exception.InnerException.Should().BeOfType()
+ .Which.StatusCode.Should().Be(StatusCode.Unimplemented);
+ invoker.Verify(x => x.AsyncUnaryCall(
+ It.Is>(method => method.Name == "CloneInstance"),
+ It.IsAny(), It.IsAny(), It.IsAny()), Times.Once);
+ invoker.VerifyNoOtherCalls();
+ }
+
+ [Fact]
+ public void RestartAsync_BaseImplementation_DoesNotSilentlyIgnoreExplicitInstanceId()
+ {
+ // Arrange
+ Mock client = new("test") { CallBase = true };
+
+ // Act
+ Action act = () => client.Object.RestartAsync("source", "target", null, default);
+
+ // Assert
+ act.Should().Throw();
+ }
+
+ static GrpcDurableTaskClient CreateClient(Mock invoker) =>
+ new("test", new GrpcDurableTaskClientOptions { CallInvoker = invoker.Object, EnableEntitySupport = true },
+ NullLogger.Instance);
+
+ static Mock CreateInvoker(Func> response)
+ where TRequest : class
+ where TResponse : class
+ {
+ Mock invoker = new(MockBehavior.Strict);
+ invoker.Setup(x => x.AsyncUnaryCall(
+ It.IsAny>(),
+ It.IsAny(), It.IsAny(), It.IsAny()))
+ .Returns((Method _, string? _, CallOptions options, TRequest request) =>
+ new AsyncUnaryCall(
+ response(request, options), Task.FromResult(new Metadata()), () => Status.DefaultSuccess,
+ () => new Metadata(), () => { }));
+ return invoker;
+ }
+}
diff --git a/test/Grpc.IntegrationTests/GrpcDurableTaskClientIntegrationTests.cs b/test/Grpc.IntegrationTests/GrpcDurableTaskClientIntegrationTests.cs
index 5fd9dc00..36cca5a7 100644
--- a/test/Grpc.IntegrationTests/GrpcDurableTaskClientIntegrationTests.cs
+++ b/test/Grpc.IntegrationTests/GrpcDurableTaskClientIntegrationTests.cs
@@ -280,6 +280,34 @@ public async Task RestartAsync_EndToEnd(bool restartWithNewInstanceId)
restartedMetadata!.RuntimeStatus.Should().Be(OrchestrationRuntimeStatus.Completed);
}
+ [Fact]
+ public async Task RestartAsync_ExplicitInstanceId_UnsupportedServer_DoesNotRestartOrCreateInstance()
+ {
+ // Arrange
+ await using HostTestLifetime server = await this.StartAsync();
+ string source = await server.Client.ScheduleNewOrchestrationInstanceAsync(
+ OrchestrationName, input: false, cancellation: this.TimeoutToken);
+ await server.Client.WaitForInstanceStartAsync(source, this.TimeoutToken);
+ await server.Client.RaiseEventAsync(source, "event", cancellation: this.TimeoutToken);
+ OrchestrationMetadata original = await server.Client.WaitForInstanceCompletionAsync(source, this.TimeoutToken);
+ List before = await server.Client.GetAllInstancesAsync().ToListAsync(this.TimeoutToken);
+ string target = Guid.NewGuid().ToString("N");
+
+ // Act
+ Func act = () => server.Client.RestartAsync(
+ source, target, null, this.TimeoutToken);
+
+ // Assert
+ await act.Should().ThrowAsync();
+ List after = await server.Client.GetAllInstancesAsync().ToListAsync(this.TimeoutToken);
+ after.Select(instance => instance.InstanceId).Should().BeEquivalentTo(before.Select(instance => instance.InstanceId));
+ (await server.Client.GetInstanceAsync(target, cancellation: this.TimeoutToken)).Should().BeNull();
+ OrchestrationMetadata? sourceAfter = await server.Client.GetInstanceAsync(source, cancellation: this.TimeoutToken);
+ sourceAfter.Should().NotBeNull();
+ sourceAfter!.RuntimeStatus.Should().Be(OrchestrationRuntimeStatus.Completed);
+ sourceAfter.CreatedAt.Should().Be(original.CreatedAt);
+ }
+
[Fact]
public async Task RestartAsync_InstanceNotFound_ThrowsArgumentException()
{
diff --git a/test/Worker/Core.Tests/Shims/TaskOrchestrationContextWrapperTests.cs b/test/Worker/Core.Tests/Shims/TaskOrchestrationContextWrapperTests.cs
index 1f687013..655dcb14 100644
--- a/test/Worker/Core.Tests/Shims/TaskOrchestrationContextWrapperTests.cs
+++ b/test/Worker/Core.Tests/Shims/TaskOrchestrationContextWrapperTests.cs
@@ -27,6 +27,45 @@ public void Ctor_NullParent_Populates()
VerifyWrapper(wrapper, innerContext, invocationContext, input);
}
+ [Theory]
+ [InlineData(null)]
+ [InlineData("original-instance")]
+ [InlineData("previous-clone")]
+ public void SourceInstanceId_ReadsImmediateSourceFromProperties(string? source)
+ {
+ // Arrange
+ TestOrchestrationContext innerContext = new();
+ OrchestrationInvocationContext invocationContext = new("Test", new(), NullLoggerFactory.Instance, null);
+ Dictionary properties = new();
+ if (source is not null)
+ {
+ properties["sourceInstanceId"] = source;
+ }
+
+ TaskOrchestrationContextWrapper wrapper = new(innerContext, invocationContext, "input", properties);
+
+ // Act
+ string? actual = wrapper.SourceInstanceId;
+
+ // Assert
+ actual.Should().Be(source);
+ wrapper.Parent.Should().BeNull();
+ }
+
+ [Fact]
+ public void SourceInstanceId_WithoutProperties_IsNull()
+ {
+ // Arrange
+ TaskOrchestrationContextWrapper wrapper = new(
+ new TestOrchestrationContext(), new("Test", new(), NullLoggerFactory.Instance, null), "input");
+
+ // Act
+ string? source = wrapper.SourceInstanceId;
+
+ // Assert
+ source.Should().BeNull();
+ }
+
[Fact]
public void Ctor_NonNullParent_Populates()
{
diff --git a/test/Worker/Grpc.Tests/GrpcDurableTaskWorkerTests.cs b/test/Worker/Grpc.Tests/GrpcDurableTaskWorkerTests.cs
index 2743cba2..ee1e6a1b 100644
--- a/test/Worker/Grpc.Tests/GrpcDurableTaskWorkerTests.cs
+++ b/test/Worker/Grpc.Tests/GrpcDurableTaskWorkerTests.cs
@@ -12,6 +12,7 @@
using Grpc.Core;
using Grpc.Core.Interceptors;
using Microsoft.DurableTask;
+using Microsoft.DurableTask.Converters;
using Microsoft.DurableTask.Tests.Logging;
using Microsoft.DurableTask.Tracing;
using Microsoft.DurableTask.Worker;
@@ -53,6 +54,84 @@ public class GrpcDurableTaskWorkerTests
static readonly MethodInfo OnRunOrchestratorAsyncMethod = typeof(GrpcDurableTaskWorker)
.GetNestedType("Processor", BindingFlags.NonPublic)!
.GetMethod("OnRunOrchestratorAsync", BindingFlags.Instance | BindingFlags.NonPublic)!;
+
+ [Theory]
+ [InlineData(null)]
+ [InlineData("original-instance")]
+ [InlineData("previous-clone")]
+ [InlineData("dt:2026-01-01T00:00:00.0000000Z")]
+ [InlineData("dto:2026-01-01T00:00:00.0000000+00:00")]
+ public async Task OnRunOrchestratorAsync_Properties_ExposeImmediateSource(string? source)
+ {
+ // Arrange
+ P.OrchestratorRequest request = new()
+ {
+ InstanceId = "clone",
+ ExecutionId = "clone-execution",
+ NewEvents =
+ {
+ new P.HistoryEvent
+ {
+ Timestamp = Timestamp.FromDateTime(DateTime.UtcNow),
+ ExecutionStarted = new P.ExecutionStartedEvent
+ {
+ Name = "CloneOrchestration",
+ OrchestrationInstance = new P.OrchestrationInstance
+ {
+ InstanceId = "clone",
+ ExecutionId = "clone-execution",
+ },
+ },
+ },
+ },
+ };
+ if (source is not null)
+ {
+ request.Properties.Add("sourceInstanceId", Value.ForString(source));
+ }
+
+ request.Properties.Add("dateTime", Value.ForString("dt:2026-01-01T00:00:00.0000000Z"));
+ request.Properties.Add("dateTimeOffset", Value.ForString("dto:2026-01-01T00:00:00.0000000+00:00"));
+ P.OrchestratorResponse? completed = null;
+ Mock clientMock = new(
+ MockBehavior.Strict, new object[] { Mock.Of() });
+ clientMock.Setup(client => client.CompleteOrchestratorTaskAsync(
+ It.IsAny(), It.IsAny(), It.IsAny(),
+ It.IsAny()))
+ .Callback(
+ (response, _, _, _) => completed = response)
+ .Returns(CreateUnaryCall(Task.FromResult(new P.CompleteTaskResponse())));
+ object? actualDateTime = null;
+ object? actualDateTimeOffset = null;
+ ITaskOrchestrator? orchestrator = FuncTaskOrchestrator.Create