這很重要
對於進程模型的支援將於 2026 年 11 月 10 日結束。 我們強烈建議您遷移應用程式至隔離工作模式以獲得完整支援。
Durable Functions 提供 持久計時器,用於編排器功能中實作延遲或設定非同步動作的逾時。 請在協調器函式中使用持久計時器,而不要使用語言內建、可能提供的 sleep 或 delay API。
持久任務 SDK 提供 持久計時器 ,用於編排以實現延遲或設定非同步動作的逾時。 在編排中使用耐用計時器,取代可能內建於語言中的sleep或delay API。
這很重要
目前,PowerShell Durable Task SDK 尚未提供。
持久計時器是使用所提供語言適當 create timer API 建立的任務,如以下範例所示,並以應期時間或持續時間作為參數。
孤立工人模型
[Function("TimerOrchestration")]
public static async Task Run(
[OrchestrationTrigger] TaskOrchestrationContext context)
{
// Put the orchestrator to sleep for 72 hours
DateTime dueTime = context.CurrentUtcDateTime.AddHours(72);
await context.CreateTimer(dueTime, CancellationToken.None);
}
進行中模型
[FunctionName("TimerOrchestration")]
public static async Task Run(
[OrchestrationTrigger] IDurableOrchestrationContext context)
{
// Put the orchestrator to sleep for 72 hours
DateTime dueTime = context.CurrentUtcDateTime.AddHours(72);
await context.CreateTimer(dueTime, CancellationToken.None);
}
// Put the orchestration to sleep for 72 hours
await context.CreateTimer(TimeSpan.FromHours(72), CancellationToken.None);
當你執行計時器任務時 await ,編排器功能會進入休眠狀態直到指定的到期時間。
當你執行計時器任務時 await ,編排會進入休眠狀態直到指定的到期時間。
備註
在等待計時器任務結束時,流程編排會繼續處理其他進入的事件。
耐用計時器的限制
當你建立一個在 UTC 下午 4:30 到期的計時器時,底層的 Durable Task Framework 會將一則訊息放入佇列,該訊息僅在 UTC 下午 4:30 可見。 如果函式應用程式在此期間被縮減到零實例,新增的計時器訊息會確保函式應用程式會在適當的虛擬機上再次啟用。
備註
- 對於 JavaScript、Python 和 PowerShell 應用程式,持久計時器限制為六天。 為了繞過這個限制,可以在迴圈中使用計時器 API
while來模擬較長的延遲。 最新的 .NET 和 Java 應用程式支援任意長的計時器。 - 根據使用的 SDK 版本及儲存供應商,六天或更長的長計時器在內部可能以一系列較短的計時器(例如三天)實現,直到達到期望的到期時間。 這種行為可以在底層資料儲存中觀察到,但不會影響編排行為。
- 不要用內建的日期/時間 API 來取得當前時間。 計算計時器未來到期日期時,務必使用編排器函式的當前時間 API。 如需詳細資訊,請參閱協調器函數程式碼條件約束一文。
當你建立一個在 UTC 下午 4:30 到期的計時器時,底層的 Durable Task Framework 會將一則訊息放入佇列,該訊息僅在 UTC 下午 4:30 可見。 計時器訊息確保當計時器結束時,工作者會再次啟動。
備註
- 指定長時間延遲(例如幾天或更久)可能導致建立多個內部管理的持久計時器。 編排程式碼不需要知道這種行為。 不過,這可能會在框架日誌和儲存的歷史狀態中被看見。
- 不要用內建的日期和時間 API 來取得目前時間。 計算計時器未來到期日期時,務必使用編排上下文的當前時間屬性(例如 .NET 中的
context.CurrentUtcDateTime、Python 中的ctx.current_utc_datetime,或 JavaScript 中的ctx.currentUtcDateTime)。
使用耐用的定時器來管理延遲
以下範例展示了如何使用耐用計時器來延遲執行。 這個例子每天發出帳單通知,持續10天。
孤立工人模型
[Function("BillingIssuer")]
public static async Task Run(
[OrchestrationTrigger] TaskOrchestrationContext context)
{
for (int i = 0; i < 10; i++)
{
DateTime deadline = context.CurrentUtcDateTime.Add(TimeSpan.FromDays(1));
await context.CreateTimer(deadline, CancellationToken.None);
await context.CallActivityAsync("SendBillingEvent");
}
}
進行中模型
[FunctionName("BillingIssuer")]
public static async Task Run(
[OrchestrationTrigger] IDurableOrchestrationContext context)
{
for (int i = 0; i < 10; i++)
{
DateTime deadline = context.CurrentUtcDateTime.Add(TimeSpan.FromDays(1));
await context.CreateTimer(deadline, CancellationToken.None);
await context.CallActivityAsync("SendBillingEvent");
}
}
備註
前述的 C# 範例針對 Durable Functions 2.x。 對於 Durable Functions 1.x,請使用 DurableOrchestrationContext 代替 IDurableOrchestrationContext。 欲了解更多版本間差異,請參閱 Durable Functions versions 條目。
public class BillingIssuer : TaskOrchestrator<object?, string>
{
public override async Task<string> RunAsync(TaskOrchestrationContext context, object? input)
{
for (int i = 0; i < 10; i++)
{
await context.CreateTimer(TimeSpan.FromDays(1), CancellationToken.None);
await context.CallActivityAsync("SendBillingEvent");
}
return "done";
}
}
警告
避免在編排器函式中使用無限迴圈。 關於如何安全且有效地實作無限迴圈情境的資訊,請參見 Eternal orchestrations。
警告
避免在編曲中無限循環。 關於如何安全且有效地實作無限迴圈情境的資訊,請參見 Eternal orchestrations。
使用耐用計時器來設定超時
此範例示範如何使用持久計時器來實作逾時:
孤立工人模型
[Function("TryGetQuote")]
public static async Task<bool> Run(
[OrchestrationTrigger] TaskOrchestrationContext context)
{
TimeSpan timeout = TimeSpan.FromSeconds(30);
DateTime deadline = context.CurrentUtcDateTime.Add(timeout);
using var timeoutCts = new CancellationTokenSource();
Task activityTask = context.CallActivityAsync("GetQuote");
Task timeoutTask = context.CreateTimer(deadline, timeoutCts.Token);
Task winner = await Task.WhenAny(activityTask, timeoutTask);
if (winner == activityTask)
{
// Success case
timeoutCts.Cancel();
return true;
}
else
{
// Timeout case
return false;
}
}
進行中模型
[FunctionName("TryGetQuote")]
public static async Task<bool> Run(
[OrchestrationTrigger] IDurableOrchestrationContext context)
{
TimeSpan timeout = TimeSpan.FromSeconds(30);
DateTime deadline = context.CurrentUtcDateTime.Add(timeout);
using (var cts = new CancellationTokenSource())
{
Task activityTask = context.CallActivityAsync("GetQuote");
Task timeoutTask = context.CreateTimer(deadline, cts.Token);
Task winner = await Task.WhenAny(activityTask, timeoutTask);
if (winner == activityTask)
{
// success case
cts.Cancel();
return true;
}
else
{
// timeout case
return false;
}
}
}
備註
前述的 C# 範例針對 Durable Functions 2.x。 對於 Durable Functions 1.x,請使用 DurableOrchestrationContext 代替 IDurableOrchestrationContext。 欲了解更多版本間差異,請參閱 Durable Functions versions 條目。
public class TryGetQuote : TaskOrchestrator<object?, bool>
{
public override async Task<bool> RunAsync(TaskOrchestrationContext context, object? input)
{
using var cts = new CancellationTokenSource();
Task<double> activityTask = context.CallActivityAsync<double>("GetQuote");
Task timeoutTask = context.CreateTimer(TimeSpan.FromSeconds(30), cts.Token);
Task winner = await Task.WhenAny(activityTask, timeoutTask);
if (winner == activityTask)
{
// success case
cts.Cancel();
return true;
}
else
{
// timeout case
return false;
}
}
}
警告
在 .NET、JavaScript、Python 和 PowerShell 中,如果你的程式碼沒有等它們完成,就取消任何已建立的持久計時器。 請參閱前例以了解如何取消未執行的計時器。 Durable Task Framework 不會將編排狀態改為「完成」,直到所有未完成任務,包括持久計時器任務,都已完成或取消。
警告
如果您的 SDK 支援計時器取消功能 (例如 .NET),而且您的程式碼不會等候這些已建立的持久計時器完成,請取消它們。 請參閱前例以了解如何取消未執行的計時器。 Durable Task Framework 不會將編排狀態改為「完成」,直到所有未完成任務,包括持久計時器任務,都已完成或取消。
此取消機制採用 when-any 模式,不會終止正在進行的活動函數或子協程的執行。 相反地,它只是讓編排器功能忽略結果,繼續前進。 如果你的功能應用程式使用消耗方案,你仍需為放棄活動功能所消耗的時間和記憶體計費。 預設情況下,在消耗計畫中執行的功能有五分鐘的超時時間。 如果超出此限制,Azure Functions 主機就會回收,以停止所有執行並防止失控的計費狀況。 函式逾時是可設定的。
若需更詳細的範例來了解如何在編排器函式中實作逾時設定,請參見「人機互動」記事。
這種使用 When-Any 模式的取消機制不會終止正在進行的活動或子編排的執行。 相反地,它只是讓編曲忽略結果,繼續前進。