Skip to content

Commit 3437f73

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #302772 from halspang/halspang/dts_versioning
Add durable task scheduler versioning doc
2 parents 538c2b0 + e256b40 commit 3437f73

File tree

2 files changed

+246
-0
lines changed

2 files changed

+246
-0
lines changed

‎articles/azure-functions/durable/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,8 @@
134134
items:
135135
- name: Configure autoscale for Azure Container Apps hosting
136136
href: ./durable-task-scheduler/durable-task-scheduler-auto-scaling.md
137+
- name: Versioning
138+
href: ./durable-task-scheduler/durable-task-scheduler-versioning.md
137139
- name: Billing
138140
href: ./durable-task-scheduler/durable-task-scheduler-dedicated-sku.md
139141
- name: Troubleshoot

‎articles/azure-functions/durable/durable-task-scheduler/durable-task-scheduler-versioning.md

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
---
2+
title: Configure Versioning for Durable Task Scheduler (preview)
3+
description: Learn how to use orchestration versioning in Durable Task Scheduler.
4+
ms.topic: how-to
5+
ms.date: 07/16/2025
6+
author: halspang
7+
ms.author: azfuncdf
8+
zone_pivot_groups: df-languages
9+
---
10+
11+
# Orchestration Versioning
12+
13+
A key area to consider when using a durable orchestration system is how to handle the upgrading/downgrading of orchestrations. When an orchestration is interrupted and later resumed (for instance, during a host update), Durable Task Scheduler will replay the events of the orchestration. This is done to ensure reliability - the system replays to ensure all previous steps were executed successfully before the next step is taken - which is a core promise of the durable execution paradigm. So, if an orchestration changes between deployments, the steps it takes may no longer be the same. If this does happen, the system will throw a `NonDeterministicError` instead of allowing the orchestration to continue.
14+
15+
Orchestration versioning helps to prevent problems related to non-determinism, allowing you to work seamlessly with new (or old) orchestrations. Durable Task Scheduler has two different styles of versioning which will be explored below. Note that the different versioning styles can be used separately or together.
16+
17+
::: zone pivot="javascript"
18+
19+
[!INCLUDE [preview-sample-limitations](./includes/preview-sample-limitations.md)]
20+
21+
::: zone-end
22+
23+
::: zone pivot="powershell"
24+
25+
[!INCLUDE [preview-sample-limitations](./includes/preview-sample-limitations.md)]
26+
27+
::: zone-end
28+
29+
::: zone pivot="python"
30+
31+
> [!IMPORTANT]
32+
> Currently, versioning isn't available in the Python SDK.
33+
34+
::: zone-end
35+
36+
::: zone pivot="csharp,java"
37+
38+
## Client/context-based conditional versioning
39+
40+
In order for an orchestration to have a version, it must first be set in the client. For the .NET SDK, this is done through the standard host builder extensions, as seen below:
41+
42+
::: zone-end
43+
44+
::: zone pivot="csharp"
45+
46+
> [!NOTE]
47+
> Available in the .NET SDK since v1.9.0.
48+
49+
```csharp
50+
builder.Services.AddDurableTaskClient(builder =>
51+
{
52+
builder.UseDurableTaskScheduler(connectionString);
53+
builder.UseDefaultVersion("1.0.0");
54+
});
55+
```
56+
57+
::: zone-end
58+
59+
::: zone pivot="java"
60+
61+
> [!NOTE]
62+
> Available in the Java SDK since v1.6.0.
63+
64+
```java
65+
public DurableTaskClient durableTaskClient(DurableTaskProperties properties) {
66+
// Create client using Azure-managed extensions
67+
return DurableTaskSchedulerClientExtensions.createClientBuilder(properties.getConnectionString())
68+
.defaultVersion("1.0")
69+
.build();
70+
}
71+
```
72+
73+
::: zone-end
74+
75+
::: zone pivot="csharp,java"
76+
77+
Once that is added, any orchestration started by this host will use the version `1.0.0`. The version itself is a simple string and accepts any value. However, the SDK will try to convert it to .NET's `System.Version`. If it can be converted, that library is used for comparison, if not, a simple string comparison is used.
78+
79+
By supplying the version in the client, it also becomes available in the `TaskOrchestrationContext`. This means the version can be used in conditional statements. So long as newer versions of an orchestration have the appropriate version gating, both the old and the new version of the orchestration can run together on the same host. An example of how the version can be used is:
80+
81+
::: zone-end
82+
83+
::: zone pivot="csharp"
84+
85+
```csharp
86+
[DurableTask]
87+
class HelloCities : TaskOrchestrator<string, List<string>>
88+
{
89+
private readonly string[] Cities = ["Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo"];
90+
91+
public override async Task<List<string>> RunAsync(TaskOrchestrationContext context, string input)
92+
{
93+
List<string> results = [];
94+
foreach (var city in Cities)
95+
{
96+
results.Add(await context.CallSayHelloAsync($"{city} v{context.Version}"));
97+
if (context.CompareVersionTo("2.0.0") >= 0)
98+
{
99+
results.Add(await context.CallSayGoodbyeAsync($"{city} v{context.Version}"));
100+
}
101+
}
102+
103+
Console.WriteLine("HelloCities orchestration completed.");
104+
return results;
105+
}
106+
}
107+
```
108+
109+
::: zone-end
110+
111+
::: zone pivot="java"
112+
113+
```java
114+
public TaskOrchestration create() {
115+
return ctx -> {
116+
List<String> results = new ArrayList<>();
117+
for (String city : new String[]{ "Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo" }) {
118+
results.add(ctx.callActivity("SayHello", city, String.class).await());
119+
if (VersionUtils.compareVersions(ctx.getVersion(), "2.0.0") >= 0) {
120+
// Simulate a delay for newer versions
121+
results.add(ctx.callActivity("SayGoodbye", city, String.class).await());
122+
}
123+
}
124+
ctx.complete(results);
125+
};
126+
}
127+
```
128+
129+
::: zone-end
130+
131+
::: zone pivot="csharp,java"
132+
133+
In this example, we've added a `SayGoodbye` activity to the `HelloCities` orchestration. This is only called if the orchestration is at least version `2.0.0`. With the simple conditional statement, any orchestration with a version less than `2.0.0` will continue to function and any new orchestration will have the new activity in it.
134+
135+
### When to use client versioning
136+
137+
Client versioning provides the simplest mechanism for versioning orchestrations, but interacting with the version is also the most programming intensive. Essentially, the two functionalities that client versioning provides are the ability to set a version for all orchestrations and the ability to programmatically handle the version in the orchestration. It should be used if a standard version is desired across all versions or if custom logic around specific versions is required.
138+
139+
## Worker-based versioning
140+
141+
An additional strategy that can be used for handling versions is setting up worker versioning. Orchestrations will still need a client version in order to have the version set, but this method allows the user to avoid conditionals in their orchestrations. Worker versioning allows the worker itself to choose how to act on different version of orchestrations before those orchestrations start executing. Worker versioning requires the following fields to be set:
142+
143+
1. The version of the worker itself
144+
2. The default version that will be applied to suborchestrations started by the worker
145+
3. The strategy that the worker will use to match against the orchestration's version
146+
4. The strategy that the worker should take if the version doesn't meet the matching strategy
147+
148+
The different match strategies are as follows:
149+
150+
| Name | Description |
151+
|----------------|------------------------------------------------------------------------------------------|
152+
| None | The version isn't considered when work is being processed |
153+
| Strict | The version in the orchestration and the worker must match exactly |
154+
| CurrentOrOlder | The version in the orchestration must be equal to or less than the version in the worker |
155+
156+
The different failure strategies are as follows:
157+
158+
| Name | Description |
159+
|--------|-----------------------------------------------------------------------------------------------------------|
160+
| Reject | The orchestration will be rejected by the worker but remain in the work queue to be attempted again later |
161+
| Fail | The orchestration will be failed and removed from the work queue |
162+
163+
Similar to the client versioning, these are all set via the standard host builder pattern:
164+
165+
::: zone-end
166+
167+
::: zone pivot="csharp"
168+
169+
```csharp
170+
builder.Services.AddDurableTaskWorker(builder =>
171+
{
172+
builder.AddTasks(r => r.AddAllGeneratedTasks());
173+
builder.UseDurableTaskScheduler(connectionString);
174+
builder.UseVersioning(new DurableTaskWorkerOptions.VersioningOptions
175+
{
176+
Version = "1.0.0",
177+
DefaultVersion = "1.0.0",
178+
MatchStrategy = DurableTaskWorkerOptions.VersionMatchStrategy.Strict,
179+
FailureStrategy = DurableTaskWorkerOptions.VersionFailureStrategy.Reject,
180+
});
181+
});
182+
```
183+
184+
::: zone-end
185+
186+
::: zone pivot="java"
187+
188+
```java
189+
private static DurableTaskGrpcWorker createTaskHubServer() {
190+
DurableTaskGrpcWorkerBuilder builder = new DurableTaskGrpcWorkerBuilder();
191+
builder.useVersioning(new DurableTaskGrpcWorkerVersioningOptions(
192+
"1.0",
193+
"1.0",
194+
DurableTaskGrpcWorkerVersioningOptions.VersionMatchStrategy.CURRENTOROLDER,
195+
DurableTaskGrpcWorkerVersioningOptions.VersionFailureStrategy.REJECT));
196+
197+
// Orchestrations can be defined inline as anonymous classes or as concrete classes
198+
builder.addOrchestration(new TaskOrchestrationFactory() {
199+
@Override
200+
public String getName() { return "HelloCities"; }
201+
202+
@Override
203+
public TaskOrchestration create() {
204+
return ctx -> {
205+
List<String> results = new ArrayList<>();
206+
for (String city : new String[]{ "Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo" }) {
207+
results.add(ctx.callActivity("SayHello", city, String.class).await());
208+
}
209+
ctx.complete(results);
210+
};
211+
}
212+
});
213+
214+
// Activities can be defined inline as anonymous classes or as concrete classes
215+
builder.addActivity(new TaskActivityFactory() {
216+
@Override
217+
public String getName() { return "SayHello"; }
218+
219+
@Override
220+
public TaskActivity create() {
221+
return ctx -> {
222+
String input = ctx.getInput(String.class);
223+
return "Hello, " + input + "!";
224+
};
225+
}
226+
});
227+
228+
return builder.build();
229+
}
230+
```
231+
232+
::: zone-end
233+
234+
::: zone pivot="csharp,java"
235+
236+
The `Reject` failure strategy should be used when the desired behavior is to have the orchestration try again at a later time/on a different worker. When an orchestration is rejected, it's simply returned to the work queue. When it's dequeued again, it could land on a different worker or the same one again. The process will repeat until a worker that can actually handle the orchestration is available. This strategy allows for the seamless handling of deployments in which an orchestration is updated. As the deployment progresses, workers that can't handle the orchestration will reject it while workers that can handle it will process it. The ability to have mixed workers/orchestration versions allows for scenarios like blue-green deployments.
237+
238+
The `Fail` failure strategy should be used when no other versions are expected. In this case, the new version is an anomaly and no worker should even attempt to work on it. So, the Durable Task Scheduler will fail the orchestration, putting it in a terminal state.
239+
240+
### When to Use Worker Versioning
241+
242+
Worker versioning should be used in scenarios where orchestrations of an unknown or unsupported version shouldn't be executed at all. Instead of placing version handling code in the worker, worker versioning stops the orchestration from ever executing. This allows for much simpler orchestration code. Without any code changes, various deployment scenarios can be handled, like blue-green deployments mentioned before.
243+
244+
::: zone-end

0 commit comments

Comments
 (0)