Durable Task Roslyn Analyzer for C# 編排

Durable Task Roslyn Analyzer 是一款即時程式碼分析器，幫助你在 C# Durable Functions 應用程式中遵循 orchestrator 程式碼約束條件。 它能在程式碼進入生產環境前，偵測到常見問題，例如非確定性 API 使用、錯誤綁定，以及型別不符。

分析儀隨 Microsoft.Azure.Functions.Worker.Extensions.DurableTask NuGet 套件（v1.6.0 及更新版本）一同附贈，預設啟用。 不需要額外的設定。

Durable Task Roslyn Analyzer 是一款即時程式碼分析器，幫助你遵循 C# Durable Task SDK 應用程式中的 orchestrator 程式碼約束 。 它會在建置時偵測常見問題，例如非確定性 API 使用和型別不符，且在程式碼進入生產環境前。

要使用分析器，請將 Microsoft.DurableTask.Analyzers NuGet 套件加入你的專案中：

dotnet add package Microsoft.DurableTask.Analyzers

運作原理

分析器會在 Visual Studio、Visual Studio Code（使用 C# Dev Kit 擴充功能）以及命令列的 dotnet build 中自動執行。 它會檢查你的編排器程式碼，並將診斷結果以警告或錯誤的形式回報在 IDE 的錯誤清單和建置輸出中。

分析未開啟檔案不需要 IDE 設定。 當 NuGet 套件出現在你的專案時，分析器就會立即啟動。

Tip

預設情況下，Visual Studio 只會對你開啟的檔案執行分析器。 要一次分析整個解決方案，請進入 工具>選項>的文字編輯器>C#>Advanced ，並將 背景分析範圍 設為 「整個解決方案」。

針對多項規則，分析器還提供Visual Studio與 VS Code 中的自動程式碼修正（快速動作）。 例如，它可以在一鍵內替換DateTime.Now成 。context.CurrentUtcDateTime

分析器規則

以下章節列出隨 Durable Task Roslyn 分析儀附帶的分析規則，依類別分類。

編排規則

這些規則透過偵測編排方法中非確定性或不安全的 API 使用，來強制執行 編排器程式碼的限制 。

規則識別碼 Severity Description 程序代碼修正
DURABLE0001 Warning 偵測編排中的非確定性DateTime屬性（DateTime.Now， DateTime.UtcNow， DateTime.Today， DateTimeOffset.Now， DateTimeOffset.UtcNow）。 請改用 context.CurrentUtcDateTime。 Yes
DURABLE0002 Warning 在編排中偵測 Guid.NewGuid() 。 請改用 context.NewGuid()。 Yes
DURABLE0003 Warning 偵測協調流程中的 Task.Delay 或 Thread.Sleep。 請改用 context.CreateTimer。 Yes
DURABLE0004 Warning 偵測編排中非固定性的執行緒與任務 API Thread.Start、Task.Run、Task.ContinueWith、TaskFactory.StartNew。 No
DURABLE0005 Warning 偵測在編排中直接使用的 I/O API（例如 HttpClient、Azure 儲存體 用戶端）。 將 I/O 通話移到活動中。 No
DURABLE0006 Warning 偵測 System.Environment API 在編排中的使用情況（例如 GetEnvironmentVariable）。 No
DURABLE0007 Warning 偵測 CancellationToken 編排函數簽名中的參數。 No
DURABLE0008 Warning 偵測編排函數參數中的非[OrchestrationTrigger] 綁定（例如 [EntityTrigger]、 [DurableClient]）。 No
DURABLE0009 Info 建議使用輸入參數而非 context.GetInput<T>()。 No
DURABLE0010 Warning 偵測編排中的非上下文 ILogger 使用。 請改用 context.CreateReplaySafeLogger()。 No
DURABLE0011 Warning 偵測不呼叫 while (true)的無界ContinueAsNew編排迴路。 沒有 ContinueAsNew，編曲歷史會無限增長。 No
規則識別碼 Severity Description 程序代碼修正
DURABLE0001 Warning 偵測編排中的非確定性DateTime屬性（DateTime.Now， DateTime.UtcNow， DateTime.Today， DateTimeOffset.Now， DateTimeOffset.UtcNow）。 請改用 context.CurrentUtcDateTime。 Yes
DURABLE0002 Warning 在編排中偵測 Guid.NewGuid() 。 請改用 context.NewGuid()。 Yes
DURABLE0003 Warning 偵測協調流程中的 Task.Delay 或 Thread.Sleep。 請改用 context.CreateTimer。 Yes
DURABLE0004 Warning 偵測編排中非固定性的執行緒與任務 API Thread.Start、Task.Run、Task.ContinueWith、TaskFactory.StartNew。 No
DURABLE0005 Warning 偵測在編排中直接使用的 I/O API（例如 HttpClient、Azure 儲存體 用戶端）。 將 I/O 通話移到活動中。 No
DURABLE0006 Warning 偵測 System.Environment API 在編排中的使用情況（例如 GetEnvironmentVariable）。 No
DURABLE0009 Info 建議使用輸入參數而非 context.GetInput<T>()。 No
DURABLE0010 Warning 偵測編排中的非上下文 ILogger 使用。 請改用 context.CreateReplaySafeLogger()。 No
DURABLE0011 Warning 偵測不呼叫 while (true)的無界ContinueAsNew編排迴路。 沒有 ContinueAsNew，編曲歷史會無限增長。 No

Note

規則DURABLE0007、DURABLE0008 和 DURABLE1001-DURABLE1003 僅適用於 Azure Functions，且不包含在獨立的 Durable Task SDK 分析器中。

約束規則

這些規則驗證觸發器與用戶端綁定是否套用到正確的參數類型。

規則識別碼 Severity Description 程序代碼修正
DURABLE1001 錯誤 確保[OrchestrationTrigger]僅應用於TaskOrchestrationContext參數。 Yes
DURABLE1002 錯誤 確保[DurableClient]僅應用於DurableTaskClient參數。 Yes
DURABLE1003 錯誤 確保[EntityTrigger]僅應用於TaskEntityDispatcher參數。 Yes

活動規則

這些規則會檢查活動與子編排呼叫中的型別不符與未解決名稱。

規則識別碼 Severity Description 程序代碼修正
DURABLE2001 Warning 偵測活動調用與活動定義之間的輸入類型不匹配。 No
DURABLE2002 Warning 偵測活動調用與活動定義之間的輸出類型不符。 No
DURABLE2003 Info 當活動呼叫的名稱與編譯中任何定義的活動不符時，會進行報告。 No
DURABLE2004 Info 當子編排呼叫引用的名稱與編譯中任何定義的編排器不符時，會進行報告。 No

欲了解更多資訊，請參閱GitHub上的analyzer發布說明。

抑制 Roslyn 分析儀警告

你可以在專案、檔案或行層級抑制分析器的診斷。

使用 隱藏.editorconfig

在您的.editorconfig檔案中新增一個項目以變更規則的嚴重程度或完全停用：

[*.cs]
dotnet_diagnostic.DURABLE0001.severity = none

有效的嚴重度值為 error、 warning、 suggestionsilentnone、 和 。

抑制內嵌 #pragma

用於 #pragma warning disable 抑制程式碼中的特定警告：

#pragma warning disable DURABLE0001
var now = DateTime.UtcNow;
#pragma warning restore DURABLE0001

專案層級的抑制

在您的 <NoWarn> 檔案中新增一個 .csproj 條目，以抑制整個專案的某個規則。

<PropertyGroup>
  <NoWarn>$(NoWarn);DURABLE0001</NoWarn>
</PropertyGroup>

舊版 .NET 內部進程分析器

另有一款較舊的 Roslyn 分析器用於 .NET in-process 程式設計模型。 此分析儀屬於 Microsoft.Azure.WebJobs.Extensions.DurableTask 套件，並使用不同的規則前綴（DF 取代 DURABLE）。 這兩個分析器是完全不同的套件，且不共用規則 ID。

Important

對於進程模型的支援將於 2026 年 11 月 10 日結束。 我們強烈建議您遷移應用程式至隔離工作模式以獲得完整支援。

舊有的流程分析器不會有新規則或改進。

關於進行中分析儀規則（DF0101–DF0307）的資訊，請參閱 Analyzer v0.2.0 版本的發佈頁面。

後續步驟

編排器功能程式碼限制

  • 上次更新時間：