Merge branch 'main' into wangbill/atag

Author: YunchuWang

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Add user agent header to gRPC called in ([#417](https://github.com/microsoft/durabletask-dotnet/pull/417))
 - Enrich User-Agent Header in gRPC Metadata to indicate Client or Worker as caller ([#421](https://github.com/microsoft/durabletask-dotnet/pull/421))
 - Add extension methods for registering entities by type ([#427](https://github.com/microsoft/durabletask-dotnet/pull/427))
+- Add TaskVersion and utilize it for version overrides when starting orchestrations ([#416](https://github.com/microsoft/durabletask-dotnet/pull/416))
 
 ## v1.10.0
 

src/Abstractions/TaskName.cs

@@ -16,6 +16,7 @@ namespace Microsoft.DurableTask;
     /// <param name="name">The name of the task. Providing <c>null</c> will yield the default struct.</param>
     public TaskName(string name)
     {
+#pragma warning disable 0618
         if (name is null)
         {
             // Force the default struct when null is passed in.
@@ -27,6 +28,7 @@ public TaskName(string name)
             this.Name = name;
             this.Version = string.Empty; // expose setting Version only when we actually consume it.
         }
+#pragma warning restore 0618
     }
 
     /// <summary>
@@ -44,6 +46,7 @@ public TaskName(string name)
     /// Task versions is currently locked to <see cref="string.Empty" /> as it is not yet integrated into task
     /// identification. This is being left here as we intend to support it soon.
     /// </remarks>
+    [Obsolete("Refer to TaskVersion instead.")]
     public string Version { get; }
 
     /// <summary>
@@ -122,6 +125,7 @@ public override int GetHashCode()
     /// <returns>The name and optional version of the current <see cref="TaskName"/> instance.</returns>
     public override string ToString()
     {
+#pragma warning disable 0618
         if (string.IsNullOrEmpty(this.Version))
         {
             return this.Name;
@@ -130,5 +134,6 @@ public override string ToString()
         {
             return this.Name + ":" + this.Version;
         }
+#pragma warning restore 0618
     }
 }

src/Abstractions/TaskOptions.cs

@@ -106,6 +106,11 @@ public SubOrchestrationOptions(TaskOptions options, string? instanceId = null)
     /// Gets the orchestration instance ID.
     /// </summary>
     public string? InstanceId { get; init; }
+
+    /// <summary>
+    /// Gets the version to associate with the sub-orchestration instance.
+    /// </summary>
+    public TaskVersion Version { get; init; } = default!;
 }
 
 /// <summary>
@@ -124,6 +129,11 @@ public record StartOrchestrationOptions(string? InstanceId = null, DateTimeOffse
     /// Gets the tags to associate with the orchestration instance.
     /// </summary>
     public IReadOnlyDictionary<string, string> Tags { get; init; } = ImmutableDictionary.Create<string, string>();
+
+    /// <summary>
+    /// Gets the version to associate with the orchestration instance.
+    /// </summary>
+    public TaskVersion? Version { get; init; }
 }
 
 /// <summary>

src/Abstractions/TaskVersion.cs

@@ -0,0 +1,101 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.DurableTask;
+
+/// <summary>
+/// The version of a durable task.
+/// </summary>
+public readonly struct TaskVersion : IEquatable<TaskVersion>
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TaskVersion"/> struct.
+    /// </summary>
+    /// <param name="version">The version of the task. Providing <c>null</c> will result in the default struct.</param>
+    public TaskVersion(string version)
+    {
+        if (version == null)
+        {
+            this.Version = null!;
+        }
+        else
+        {
+            this.Version = version;
+        }
+    }
+
+    /// <summary>
+    /// Gets the version of a task.
+    /// </summary>
+    public string Version { get; }
+
+    /// <summary>
+    /// Implicitly converts a <see cref="TaskVersion"/> into a <see cref="string"/> of the <see cref="Version"/> property value.
+    /// </summary>
+    /// <param name="value">The <see cref="TaskVersion"/> to be converted into a <see cref="string"/>.</param>
+    public static implicit operator string(TaskVersion value) => value.Version;
+
+    /// <summary>
+    /// Implicitly converts a <see cref="string"/> into a <see cref="TaskVersion"/>.
+    /// </summary>
+    /// <param name="value">The <see cref="string"/> to convert into a <see cref="TaskVersion"/>.</param>
+    public static implicit operator TaskVersion(string value) => new TaskVersion(value);
+
+    /// <summary>
+    /// Compares two <see cref="TaskVersion"/> structs for equality.
+    /// </summary>
+    /// <param name="a">The first <see cref="TaskVersion"/> to compare.</param>
+    /// <param name="b">The second <see cref="TaskVersion"/> to compare.</param>
+    /// <returns><c>true</c> if the two <see cref="TaskVersion"/> objects are equal; otherwise <c>false</c>.</returns>
+    public static bool operator ==(TaskVersion a, TaskVersion b)
+    {
+        return a.Equals(b);
+    }
+
+    /// <summary>
+    /// Compares two <see cref="TaskVersion"/> structs for inequality.
+    /// </summary>
+    /// <param name="a">The first <see cref="TaskVersion"/> to compare.</param>
+    /// <param name="b">The second <see cref="TaskVersion"/> to compare.</param>
+    /// <returns><c>false</c> if the two <see cref="TaskVersion"/> objects are equal; otherwise <c>true</c>.</returns>
+    public static bool operator !=(TaskVersion a, TaskVersion b)
+    {
+        return !a.Equals(b);
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether to <see cref="TaskVersion"/> objects
+    /// are equal using value semantics.
+    /// </summary>
+    /// <param name="other">The other <see cref="TaskVersion"/> to compare to.</param>
+    /// <returns><c>true</c> if the two <see cref="TaskVersion"/> are equal using value semantics; otherwise <c>false</c>.</returns>
+    public bool Equals(TaskVersion other)
+    {
+        return string.Equals(this.Version, other.Version, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether to <see cref="TaskVersion"/> objects
+    /// are equal using value semantics.
+    /// </summary>
+    /// <param name="obj">The other object to compare to.</param>
+    /// <returns><c>true</c> if the two objects are equal using value semantics; otherwise <c>false</c>.</returns>
+    public override bool Equals(object? obj)
+    {
+        if (obj is not TaskVersion other)
+        {
+            return false;
+        }
+
+        return this.Equals(other);
+    }
+
+    /// <summary>
+    /// Calculates a hash code value for the current <see cref="TaskVersion"/> instance.
+    /// </summary>
+    /// <returns>A 32-bit hash code value.</returns>
+    public override int GetHashCode()
+    {
+        return StringComparer.OrdinalIgnoreCase.GetHashCode(this.Version);
+    }
+}

src/Client/Grpc/GrpcDurableTaskClient.cs

@@ -78,10 +78,11 @@ public override async Task<string> ScheduleNewOrchestrationInstanceAsync(
     {
         Check.NotEntity(this.options.EnableEntitySupport, options?.InstanceId);
 
+        // We're explicitly OK with an empty version from the options as that had to be explicitly set. It should take precedence over the default.
         string version = string.Empty;
-        if (!string.IsNullOrEmpty(orchestratorName.Version))
+        if (options?.Version is { } v)
         {
-            version = orchestratorName.Version;
+            version = v;
         }
         else if (!string.IsNullOrEmpty(this.options.DefaultVersion))
         {

src/Client/OrchestrationServiceClientShim/ShimDurableTaskClient.cs

@@ -172,7 +172,7 @@ public override async Task<string> ScheduleNewOrchestrationInstanceAsync(
             Event = new ExecutionStartedEvent(-1, serializedInput)
             {
                 Name = orchestratorName.Name,
-                Version = orchestratorName.Version,
+                Version = options?.Version ?? string.Empty,
                 OrchestrationInstance = instance,
                 ScheduledStartTime = options?.StartAt?.UtcDateTime,
                 Tags = options?.Tags != null ? options.Tags.ToDictionary(kvp => kvp.Key, kvp => kvp.Value) : null,

src/Worker/Core/DependencyInjection/DurableTaskWorkerBuilderExtensions.cs

@@ -102,6 +102,7 @@ public static IDurableTaskWorkerBuilder UseVersioning(this IDurableTaskWorkerBui
             options.Versioning = new VersioningOptions
             {
                 Version = versionOptions.Version,
+                DefaultVersion = versionOptions.DefaultVersion,
                 MatchStrategy = versionOptions.MatchStrategy,
                 FailureStrategy = versionOptions.FailureStrategy,
             };

src/Worker/Core/DurableTaskWorkerOptions.cs

@@ -203,6 +203,11 @@ public class VersioningOptions
         /// </summary>
         public string Version { get; set; } = string.Empty;
 
+        /// <summary>
+        /// Gets or sets the default version that will be used for starting new orchestrations.
+        /// </summary>
+        public string DefaultVersion { get; set; } = string.Empty;
+
         /// <summary>
         /// Gets or sets the versioning strategy for the Durable Task worker.
         /// </summary>

src/Worker/Core/Shims/TaskEntityShim.cs

@@ -221,7 +221,7 @@ public override string ScheduleNewOrchestration(TaskName name, object? input = n
             this.operationActions.Add(new StartNewOrchestrationOperationAction()
             {
                 Name = name.Name,
-                Version = name.Version,
+                Version = options?.Version ?? string.Empty,
                 InstanceId = instanceId,
                 Input = this.dataConverter.Serialize(input),
                 ScheduledStartTime = options?.StartAt?.UtcDateTime,

src/Worker/Core/Shims/TaskOrchestrationContextWrapper.cs

@@ -148,6 +148,7 @@ public override async Task<T> CallActivityAsync<T>(
             }
 
             // TODO: Cancellation (https://github.com/microsoft/durabletask-dotnet/issues/7)
+#pragma warning disable 0618
             if (options?.Retry?.Policy is RetryPolicy policy)
             {
                 return await this.innerContext.ScheduleTask<T>(
@@ -189,6 +190,7 @@ public override async Task<T> CallActivityAsync<T>(
             // Hide the core DTFx types and instead use our own
             throw new TaskFailedException(name, e.ScheduleId, e);
         }
+#pragma warning restore 0618
     }
 
     /// <inheritdoc/>
@@ -201,10 +203,12 @@ public override async Task<TResult> CallSubOrchestratorAsync<TResult>(
         static string? GetInstanceId(TaskOptions? options)
             => options is SubOrchestrationOptions derived ? derived.InstanceId : null;
         string instanceId = GetInstanceId(options) ?? this.NewGuid().ToString("N");
+        string defaultVersion = this.invocationContext.Options?.Versioning?.DefaultVersion ?? string.Empty;
+        string version = options is SubOrchestrationOptions subOptions ? subOptions.Version : defaultVersion;
 
         Check.NotEntity(this.invocationContext.Options.EnableEntitySupport, instanceId);
 
-        // if this orchestration uses entities, first validate that the suborchsestration call is allowed in the current context
+        // if this orchestration uses entities, first validate that the suborchestration call is allowed in the current context
         if (this.entityFeature != null && !this.entityFeature.EntityContext.ValidateSuborchestrationTransition(out string? errorMsg))
         {
             throw new InvalidOperationException(errorMsg);
@@ -216,7 +220,7 @@ public override async Task<TResult> CallSubOrchestratorAsync<TResult>(
             {
                 return await this.innerContext.CreateSubOrchestrationInstanceWithRetry<TResult>(
                     orchestratorName.Name,
-                    orchestratorName.Version,
+                    version,
                     instanceId,
                     policy.ToDurableTaskCoreRetryOptions(),
                     input);
@@ -226,7 +230,7 @@ public override async Task<TResult> CallSubOrchestratorAsync<TResult>(
                 return await this.InvokeWithCustomRetryHandler(
                     () => this.innerContext.CreateSubOrchestrationInstance<TResult>(
                         orchestratorName.Name,
-                        orchestratorName.Version,
+                        version,
                         instanceId,
                         input),
                     orchestratorName.Name,
@@ -237,7 +241,7 @@ public override async Task<TResult> CallSubOrchestratorAsync<TResult>(
             {
                 return await this.innerContext.CreateSubOrchestrationInstance<TResult>(
                     orchestratorName.Name,
-                    orchestratorName.Version,
+                    version,
                     instanceId,
                     input);
             }