用于 C# 业务流程的持久任务 Roslyn 分析器

Durable Task Roslyn 分析器是一种实时代码分析器，可帮助你在 C# Durable Functions 应用中遵循 orchestrator 代码约束。 它会在代码到达生产之前检测不确定性的 API 使用情况、不正确的绑定和类型不匹配等常见问题。

分析器与 Microsoft.Azure.Functions.Worker.Extensions.DurableTask NuGet 包（v1.6.0 及更高版本）捆绑在一起，默认启用。 无需额外的设置。

Durable Task Roslyn 分析器是一种实时代码分析器，可帮助你遵循 C# Durable Task SDK 应用中的 业务流程协调程序代码约束 。 在代码到达生产之前，它会在生成时检测非确定性 API 使用情况和类型不匹配等常见问题。

若要使用分析器，请将 Microsoft.DurableTask.Analyzers NuGet 包添加到项目：

dotnet add package Microsoft.DurableTask.Analyzers

工作原理

分析器会在 Visual Studio 中、在安装了 C# 开发工具包扩展的 Visual Studio Code 中，以及在命令行上执行 dotnet build 时自动运行。 它会检查你的编排器代码，并在 IDE 的错误列表和生成输出中，将诊断报告为警告或错误。

分析打开的文件不需要 IDE 配置。 分析器在项目中存在 NuGet 包后立即激活。

Tip

默认情况下，Visual Studio仅在打开的文件上运行分析器。 若要一次性分析整个解决方案，请转到 “工具>选项>文本编辑器>C#>高级 ”，并将 后台分析范围 设置为 “整个解决方案”。

对于多个规则，分析器还提供 Visual Studio 和 VS Code 中的 自动代码修复（快速操作）。 例如，它可以在一次单击后替换为DateTime.Nowcontext.CurrentUtcDateTime。

分析器规则

以下部分列出了随 Durable Task Roslyn 分析器一起提供的分析器规则，按类别分组。

业务流程规则

这些规则通过检测业务流程方法中的非确定性或不安全的 API 使用情况来强制实施 业务流程协调程序代码约束 。

规则编号 Severity Description 代码修复
DURABLE0001 Warning 检测编排中的非确定性DateTime属性（DateTime.Now、DateTime.UtcNow、DateTime.Today、DateTimeOffset.Now、DateTimeOffset.UtcNow）。 请改用 context.CurrentUtcDateTime。 是
DURABLE0002 Warning 在 Guid.NewGuid() 编排中检测。 请改用 context.NewGuid()。 是
DURABLE0003 Warning 检测 Task.Delay 或 Thread.Sleep 在编排流程中。 请改用 context.CreateTimer。 是
DURABLE0004 Warning 检测业务流程中的非确定性线程和任务 API（Thread.Start、Task.Run、Task.ContinueWith、TaskFactory.StartNew）。 否
DURABLE0005 Warning 检测直接在编排中使用的 I/O API（例如，HttpClient、Azure 存储 客户端）。 将 I/O 调用移动到活动。 否
DURABLE0006 Warning 检测业务流程中的 System.Environment API 使用（例如 GetEnvironmentVariable）。 否
DURABLE0007 Warning 检测 CancellationToken 编排函数签名中的参数。 否
DURABLE0008 Warning 在编排函数参数中检测非[OrchestrationTrigger] 绑定（例如 [EntityTrigger]，[DurableClient]）。 否
DURABLE0009 信息 建议使用输入参数而不是 context.GetInput<T>()。 否
DURABLE0010 Warning 检测编排中的非上下文 ILogger 使用情况。 请改用 context.CreateReplaySafeLogger()。 否
DURABLE0011 Warning 检测未调用while (true)的ContinueAsNew未绑定业务流程循环。 如果没有 ContinueAsNew，业务流程历史记录将无限期增长。 否
规则编号 Severity Description 代码修复
DURABLE0001 Warning 检测编排中的非确定性DateTime属性（DateTime.Now、DateTime.UtcNow、DateTime.Today、DateTimeOffset.Now、DateTimeOffset.UtcNow）。 请改用 context.CurrentUtcDateTime。 是
DURABLE0002 Warning 在 Guid.NewGuid() 编排中检测。 请改用 context.NewGuid()。 是
DURABLE0003 Warning 检测 Task.Delay 或 Thread.Sleep 在编排流程中。 请改用 context.CreateTimer。 是
DURABLE0004 Warning 检测业务流程中的非确定性线程和任务 API（Thread.Start、Task.Run、Task.ContinueWith、TaskFactory.StartNew）。 否
DURABLE0005 Warning 检测直接在编排中使用的 I/O API（例如，HttpClient、Azure 存储 客户端）。 将 I/O 调用移动到活动。 否
DURABLE0006 Warning 检测业务流程中的 System.Environment API 使用（例如 GetEnvironmentVariable）。 否
DURABLE0009 信息 建议使用输入参数而不是 context.GetInput<T>()。 否
DURABLE0010 Warning 检测编排中的非上下文 ILogger 使用情况。 请改用 context.CreateReplaySafeLogger()。 否
DURABLE0011 Warning 检测未调用while (true)的ContinueAsNew未绑定业务流程循环。 如果没有 ContinueAsNew，业务流程历史记录将无限期增长。 否

注意

规则DURABLE0007、DURABLE0008和 DURABLE1001-DURABLE1003 仅适用于Azure Functions，并且不包括在独立的 Durable Task SDK 分析器中。

绑定规则

这些规则验证触发器和客户端绑定是否应用于正确的参数类型。

规则编号 Severity Description 代码修复
DURABLE1001 错误 保证[OrchestrationTrigger]仅应用于TaskOrchestrationContext参数。 是
DURABLE1002 错误 保证[DurableClient]仅应用于DurableTaskClient参数。 是
DURABLE1003 错误 保证[EntityTrigger]仅应用于TaskEntityDispatcher参数。 是

活动规则

这些规则检查活动和子业务流程调用中的类型不匹配和未解析的名称。

规则编号 Severity Description 代码修复
DURABLE2001 Warning 检测活动调用和活动定义之间的输入类型不匹配。 否
DURABLE2002 Warning 检测活动调用和活动定义之间的输出类型不匹配。 否
DURABLE2003 信息 当检测到活动调用引用的名称与编译中定义的任何活动不匹配时，进行报告。 否
DURABLE2004 信息 当子业务流程调用引用与编译中任何定义的业务流程协调程序不匹配的名称时报告。 否

有关详细信息，请参阅 GitHub 上的 analyzer 发行说明。

禁止显示 Roslyn 分析器警告

可以在项目、文件或行级别取消分析器诊断。

禁止显示 .editorconfig

将条目添加到 .editorconfig 文件以更改规则的严重性或完全禁用它：

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

有效的严重性值为error、、warningsuggestion、silent和none。

使用 进行内联抑制 #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进程内分析器

.NET进程内编程模型存在单独的旧版 Roslyn 分析器。 此分析器是 Microsoft.Azure.WebJobs.Extensions.DurableTask 包的一部分，并使用不同的规则前缀（DF而不是 DURABLE）。 这两个分析器是完全独立的包，不共享规则 ID。

重要

正在停用.NET进程内编程模型。 对新项目使用 .NET 隔离工作程序模型。 旧进程内分析器不会收到新规则或改进。

有关进程内分析器规则（DF0101–DF0307）的信息，请参阅 Analyzer v0.2.0 发布页。

后续步骤

Orchestrator 函数代码约束

  • Last updated on