Skip to content

Commit 45323e5

Browse files
halspanghalspang
committed
Add durable task scheduler versioning doc
Signed-off-by: Hal Spang <[email protected]>
1 parent a7c74bf commit 45323e5

File tree

2 files changed

+238
-0
lines changed

2 files changed

+238
-0
lines changed

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,8 @@
124124
href: ./durable-task-scheduler/durable-task-scheduler-dashboard.md
125125
- name: Auto-purge
126126
href: ./durable-task-scheduler/durable-task-scheduler-auto-purge.md
127+
- name: Versioning
128+
href: ./durable-task-scheduler/durable-task-scheduler-versioning.md
127129
- name: Durable Functions
128130
items:
129131
- name: Throughput benchmark

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

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
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+
zone_pivot_groups: df-languages
7+
---
8+
9+
# Orchestration Versioning
10+
11+
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 that the orchestration executes the same steps each time 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 provide a `NonDeterministicError` instead of allowing the orchestration to continue.
12+
13+
Now, with orchestration versioning, there is a way to prevent this and 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.
14+
15+
::: zone pivot="javascript"
16+
17+
[!INCLUDE [preview-sample-limitations](./includes/preview-sample-limitations.md)]
18+
19+
::: zone-end
20+
21+
::: zone pivot="powershell"
22+
23+
[!INCLUDE [preview-sample-limitations](./includes/preview-sample-limitations.md)]
24+
25+
::: zone-end
26+
27+
::: zone pivot="python"
28+
29+
> [!IMPORTANT]
30+
> Currently, versioning is not available in the Python SDK.
31+
32+
::: zone-end
33+
34+
::: zone pivot="csharp,java"
35+
36+
## Client/Context Based Conditional Versioning
37+
38+
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 seeen below:
39+
40+
::: zone-end
41+
42+
::: zone pivot="csharp"
43+
44+
```csharp
45+
builder.Services.AddDurableTaskClient(builder =>
46+
{
47+
builder.UseDurableTaskScheduler(connectionString);
48+
builder.UseDefaultVersion("1.0.0");
49+
});
50+
```
51+
52+
::: zone-end
53+
54+
::: zone pivot="java"
55+
56+
```java
57+
public DurableTaskClient durableTaskClient(DurableTaskProperties properties) {
58+
// Create client using Azure-managed extensions
59+
return DurableTaskSchedulerClientExtensions.createClientBuilder(properties.getConnectionString())
60+
.defaultVersion("1.0")
61+
.build();
62+
}
63+
```
64+
65+
::: zone-end
66+
67+
::: zone pivot="csharp,java"
68+
69+
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 and 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.
70+
71+
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, as long as newer versions of an orchestration have the appropriate version gating, both the old and the new version so of the orchestration can run together on the same host. An example of how the version can be used can be seen below:
72+
73+
::: zone-end
74+
75+
::: zone pivot="csharp"
76+
77+
```csharp
78+
[DurableTask]
79+
class HelloCities : TaskOrchestrator<string, List<string>>
80+
{
81+
private readonly string[] Cities = ["Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo"];
82+
83+
public override async Task<List<string>> RunAsync(TaskOrchestrationContext context, string input)
84+
{
85+
List<string> results = [];
86+
foreach (var city in Cities)
87+
{
88+
results.Add(await context.CallSayHelloAsync($"{city} v{context.Version}"));
89+
if (context.CompareVersionTo("2.0.0") >= 0)
90+
{
91+
results.Add(await context.CallSayGoodbyeAsync($"{city} v{context.Version}"));
92+
}
93+
}
94+
95+
Console.WriteLine("HelloCities orchestration completed.");
96+
return results;
97+
}
98+
}
99+
```
100+
101+
::: zone-end
102+
103+
::: zone pivot="java"
104+
105+
```java
106+
public TaskOrchestration create() {
107+
return ctx -> {
108+
List<String> results = new ArrayList<>();
109+
for (String city : new String[]{ "Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo" }) {
110+
results.add(ctx.callActivity("SayHello", city, String.class).await());
111+
if (VersionUtils.compareVersions(ctx.getVersion(), "2.0.0") >= 0) {
112+
// Simulate a delay for newer versions
113+
results.add(ctx.callActivity("SayGoodbye", city, String.class).await());
114+
}
115+
}
116+
ctx.complete(results);
117+
};
118+
}
119+
```
120+
121+
::: zone-end
122+
123+
::: zone pivot="csharp,java"
124+
125+
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.
126+
127+
### When to Use Client Versioning
128+
129+
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.
130+
131+
## Worker Based Versioning
132+
133+
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 so of orchestrations before those orchestrations start executing. Worker versioning has several fields to set, which are detailed below:
134+
135+
1. The version of the worker itself
136+
2. The default version that will be applied to sub-orchestrations started by the worker
137+
3. The strategy that the worker will use to match against the orchestration's version
138+
4. The strategy that the worker should take if the version does not meet the matching strategy
139+
140+
The different match strategies are as follows:
141+
142+
| Name | Description |
143+
|----------------|------------------------------------------------------------------------------------------|
144+
| None | The version is not considered when work is being processed |
145+
| Strict | The version in the orchestration and the worker must match exactly |
146+
| CurrentOrOlder | The version in the orchestration must be equal to or less than the version in the worker |
147+
148+
The different failure strategies are as follows:
149+
150+
| Name | Description |
151+
|--------|-----------------------------------------------------------------------------------------------------------|
152+
| Reject | The orchestration will be rejected by the worker but remain in the work queue to be attempted again later |
153+
| Fail | The orchestration will be failed and removed from the work queue |
154+
155+
Similar to the client versioning, these are all set via the standard host builder pattern:
156+
157+
::: zone-end
158+
159+
::: zone pivot="csharp"
160+
161+
```csharp
162+
builder.Services.AddDurableTaskWorker(builder =>
163+
{
164+
builder.AddTasks(r => r.AddAllGeneratedTasks());
165+
builder.UseDurableTaskScheduler(connectionString);
166+
builder.UseVersioning(new DurableTaskWorkerOptions.VersioningOptions
167+
{
168+
Version = "1.0.0",
169+
DefaultVersion = "1.0.0",
170+
MatchStrategy = DurableTaskWorkerOptions.VersionMatchStrategy.Strict,
171+
FailureStrategy = DurableTaskWorkerOptions.VersionFailureStrategy.Reject,
172+
});
173+
});
174+
```
175+
176+
::: zone-end
177+
178+
::: zone pivot="java"
179+
180+
```java
181+
private static DurableTaskGrpcWorker createTaskHubServer() {
182+
DurableTaskGrpcWorkerBuilder builder = new DurableTaskGrpcWorkerBuilder();
183+
builder.useVersioning(new DurableTaskGrpcWorkerVersioningOptions(
184+
"1.0",
185+
"1.0",
186+
DurableTaskGrpcWorkerVersioningOptions.VersionMatchStrategy.CURRENTOROLDER,
187+
DurableTaskGrpcWorkerVersioningOptions.VersionFailureStrategy.REJECT));
188+
189+
// Orchestrations can be defined inline as anonymous classes or as concrete classes
190+
builder.addOrchestration(new TaskOrchestrationFactory() {
191+
@Override
192+
public String getName() { return "HelloCities"; }
193+
194+
@Override
195+
public TaskOrchestration create() {
196+
return ctx -> {
197+
List<String> results = new ArrayList<>();
198+
for (String city : new String[]{ "Seattle", "Amsterdam", "Hyderabad", "Kuala Lumpur", "Shanghai", "Tokyo" }) {
199+
results.add(ctx.callActivity("SayHello", city, String.class).await());
200+
}
201+
ctx.complete(results);
202+
};
203+
}
204+
});
205+
206+
// Activities can be defined inline as anonymous classes or as concrete classes
207+
builder.addActivity(new TaskActivityFactory() {
208+
@Override
209+
public String getName() { return "SayHello"; }
210+
211+
@Override
212+
public TaskActivity create() {
213+
return ctx -> {
214+
String input = ctx.getInput(String.class);
215+
return "Hello, " + input + "!";
216+
};
217+
}
218+
});
219+
220+
return builder.build();
221+
}
222+
```
223+
224+
::: zone-end
225+
226+
::: zone pivot="csharp,java"
227+
228+
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 is simply returned to the work queue. When it is 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 cannot handle the orchestration will reject it while workers that can handle it will. The ability to have mixed workers/orchestration versions allows for scenarios like blue-green deployments.
229+
230+
The `Fail` failure strategy should be used when no other versions are expected. In this case, the new version is an anomoly 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.
231+
232+
### When to Use Worker Versioning
233+
234+
Worker versioning should be used in instances where the desired reaction for an orchestration of an unknown or unsupported version should not be worked on at all. Instead of placing version handling code in the worker, worker versioning stops the orchestration from ever executing. This allows for much simpler code in the orchestrations themselves. Without any code changes to them, various deployment scenarios can be handled, like blue-green deployments mentioned before.
235+
236+
::: zone-end

0 commit comments

Comments
 (0)