Move Version to TaskVersion and use as TaskOption

halspang · halspang · commit bb993ca6fff6 · 2025-05-15T17:45:42.000-07:00
Signed-off-by: halspang &lt;halspang@microsoft.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,8 +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))
-
->>>>>>> 766fa69 (Add version to TaskName)
+- Add TaskVersion and utilize it for version overrides when starting orchestrations ([#416](https://github.com/microsoft/durabletask-dotnet/pull/416))
 
 ## v1.10.0
 
diff --git a/src/Abstractions/TaskName.cs b/src/Abstractions/TaskName.cs
@@ -1,8 +1,6 @@
 ﻿// Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-using System;
-
 namespace Microsoft.DurableTask;
 
 /// <summary>
@@ -27,31 +25,7 @@ public TaskName(string name)
         else
         {
             this.Name = name;
-            this.Version = string.Empty;
-        }
-    }
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="TaskName"/> struct.
-    /// </summary>
-    /// <remarks>
-    /// This <c>TaskName</c> is explicitly versioned, as compared to the default value.
-    /// </remarks>
-    /// <param name="name">The name of the task. Providing <c>null</c> will yield the default struct, ignoring the version.</param>
-    /// <param name="version">Optional. The version of the task. Providing <c>null</c> will yield the default value.</param>
-    public TaskName(string name, string version)
-    {
-        if (name is null)
-        {
-            // Force the default struct when null is passed in.
-            this.Name = null!;
-            this.Version = null!;
-        }
-        else
-        {
-            this.IsVersioned = true;
-            this.Name = name;
-            this.Version = version == null ? null! : version;
+            this.Version = string.Empty; // expose setting Version only when we actually consume it.
         }
     }
 
@@ -70,16 +44,9 @@ public TaskName(string name, string version)
     /// 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>
-    /// Gets the flag denoting if this TaskName is versioned.
-    /// </summary>
-    /// <remarks>
-    /// This flag is used to distinguish between the default (empty version) and a Task with an explicit empty version.
-    /// </remarks>
-    public bool IsVersioned { get; } = false;
-
     /// <summary>
     /// Implicitly converts a <see cref="TaskName"/> into a <see cref="string"/> of the <see cref="Name"/> property value.
     /// </summary>
diff --git a/src/Abstractions/TaskOptions.cs b/src/Abstractions/TaskOptions.cs
@@ -90,6 +90,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>
@@ -108,4 +113,9 @@ 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; }
 }
diff --git a/src/Abstractions/TaskOrchestrationContext.cs b/src/Abstractions/TaskOrchestrationContext.cs
@@ -61,9 +61,9 @@ public abstract class TaskOrchestrationContext
     public abstract bool IsReplaying { get; }
 
     /// <summary>
-    /// Gets or sets the version of the current orchestration instance, which was set when the instance was created.
+    /// Gets the version of the current orchestration instance, which was set when the instance was created.
     /// </summary>
-    public virtual string Version { get; protected internal set; } = string.Empty;
+    public virtual string Version => string.Empty;
 
     /// <summary>
     /// Gets the configuration settings for the orchestration context.
diff --git a/src/Abstractions/TaskVersion.cs b/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);
+    }
+}
diff --git a/src/Client/Grpc/GrpcDurableTaskClient.cs b/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 != null && options.Version != null)
         {
-            version = orchestratorName.Version;
+            version = options.Version;
         }
         else if (!string.IsNullOrEmpty(this.options.DefaultVersion))
         {
diff --git a/src/Worker/Core/DependencyInjection/DurableTaskWorkerBuilderExtensions.cs b/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,
             };
diff --git a/src/Worker/Core/DurableTaskWorkerOptions.cs b/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>
diff --git a/src/Worker/Core/Shims/TaskOrchestrationContextWrapper.cs b/src/Worker/Core/Shims/TaskOrchestrationContextWrapper.cs
@@ -177,10 +177,14 @@ 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 != null && this.invocationContext.Options.Versioning != null
+            ? this.invocationContext.Options.Versioning.DefaultVersion
+            : string.Empty;
+        string version = options != null && 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);
@@ -192,7 +196,7 @@ public override async Task<TResult> CallSubOrchestratorAsync<TResult>(
             {
                 return await this.innerContext.CreateSubOrchestrationInstanceWithRetry<TResult>(
                     orchestratorName.Name,
-                    orchestratorName.Version,
+                    version,
                     instanceId,
                     policy.ToDurableTaskCoreRetryOptions(),
                     input);
@@ -202,7 +206,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,
@@ -213,7 +217,7 @@ public override async Task<TResult> CallSubOrchestratorAsync<TResult>(
             {
                 return await this.innerContext.CreateSubOrchestrationInstance<TResult>(
                     orchestratorName.Name,
-                    orchestratorName.Version,
+                    version,
                     instanceId,
                     input);
             }
diff --git a/test/Grpc.IntegrationTests/OrchestrationPatterns.cs b/test/Grpc.IntegrationTests/OrchestrationPatterns.cs

Original file line number	Diff line number	Diff line change
`@@ -78,10 +78,11 @@ public override async Task<string> ScheduleNewOrchestrationInstanceAsync(`
`78`	`78`	`{`
`79`	`79`	`Check.NotEntity(this.options.EnableEntitySupport, options?.InstanceId);`
`80`	`80`
	`81`	`+ // 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.`
`81`	`82`	`string version = string.Empty;`
`82`		`- if (!string.IsNullOrEmpty(orchestratorName.Version))`
	`83`	`+ if (options != null && options.Version != null)`
`83`	`84`	`{`
`84`		`- version = orchestratorName.Version;`
	`85`	`+ version = options.Version;`
`85`	`86`	`}`
`86`	`87`	`else if (!string.IsNullOrEmpty(this.options.DefaultVersion))`
`87`	`88`	`{`
Original file line number	Diff line number	Diff line change
`@@ -102,6 +102,7 @@ public static IDurableTaskWorkerBuilder UseVersioning(this IDurableTaskWorkerBui`
`102`	`102`	`options.Versioning = new VersioningOptions`
`103`	`103`	`{`
`104`	`104`	`Version = versionOptions.Version,`
	`105`	`+ DefaultVersion = versionOptions.DefaultVersion,`
`105`	`106`	`MatchStrategy = versionOptions.MatchStrategy,`
`106`	`107`	`FailureStrategy = versionOptions.FailureStrategy,`
`107`	`108`	`};`