Dapr .NET SDK 最佳实践 on Dapr 文档库

Dapr .NET SDK 中的错误模型

Mon, 01 Jan 0001 00:00:00 +0000

Dapr .NET SDK 支持 Dapr 运行时实现的更丰富的错误模型。该模型为应用程序提供了一种使用额外上下文来丰富错误的方式，使应用程序的使用者能够更好地理解问题并更快地解决它。您可以在这里阅读有关更丰富的错误模型的更多信息，并可以在这里找到实现这些错误的 Dapr proto 文件。

Dapr .NET SDK 实现了 Dapr 运行时支持的所有详细信息，在 Dapr.Common.Exceptions 命名空间中实现，并通过 DaprException 扩展方法 TryGetExtendedErrorInfo 访问。目前，此详细信息提取仅支持存在详细信息的 RpcException。

// ExtendedErrorInfo 的使用示例

try
{
 // 使用 Dapr 客户端执行某些会抛出 DaprException 的操作。
}
catch (DaprException daprEx)
{
 if (daprEx.TryGetExtendedErrorInfo(out DaprExtendedErrorInfo errorInfo))
 {
 Console.WriteLine(errorInfo.Code);
 Console.WriteLine(errorInfo.Message);

 foreach (DaprExtendedErrorDetail detail in errorInfo.Details)
 {
 Console.WriteLine(detail.ErrorType);
 switch (detail.ErrorType)
 {
 case ExtendedErrorType.ErrorInfo:
 Console.WriteLine(detail.Reason);
 Console.WriteLine(detail.Domain);
 break;
 default:
 Console.WriteLine(detail.TypeUrl);
 break;
 }
 }
 }
}

DaprExtendedErrorInfo

包含与错误关联的 Code（状态代码）和 Message（错误消息），从内部的 RpcException 解析而来。还包含从异常的详细信息中解析的 DaprExtendedErrorDetails 集合。

DaprExtendedErrorDetail

所有详细信息都实现抽象的 DaprExtendedErrorDetail 并具有关联的 DaprExtendedErrorType。

Experimental Attributes

Mon, 01 Jan 0001 00:00:00 +0000

Experimental Attributes

Experimental Attributes 简介

随着 .NET 8 的发布，C# 12 引入了 [Experimental] 属性，它提供了一种标准化的方式来标记仍在开发或实验阶段的 API。该属性定义在 System.Diagnostics.CodeAnalysis 命名空间中，需要一个诊断 ID 参数，用于在使用实验性 API 时生成编译器警告。

在 Dapr .NET SDK 中，我们现在使用 [Experimental] 属性而不是 [Obsolete] 来标记尚未通过稳定生命周期认证的构建块和组件。这种方法提供了更清晰的区分：

Experimental APIs — 已经可用但仍在演进的功能，尚未根据 Dapr Component Certification Lifecycle 认证为稳定。
Obsolete APIs — 真正已被弃用并将在未来版本中移除的功能。

在 Dapr .NET SDK 中的使用

在 Dapr .NET SDK 中，我们在类级别为仍处于 Component Certification Lifecycle 的 Alpha 或 Beta 阶段的构建块应用 [Experimental] 属性。该属性包括：

一个用于标识实验性构建块的诊断 ID
一个指向该构建块相关文档的 URL

例如：

using System.Diagnostics.CodeAnalysis;
namespace Dapr.Cryptography.Encryption 
{ 
 [Experimental("DAPR_CRYPTOGRAPHY", UrlFormat = "https://docs.dapr.io/developing-applications/building-blocks/cryptography/cryptography-overview/")] 
 public class DaprEncryptionClient 
 { 
 // Implementation 
 } 
}

诊断 ID 遵循 DAPR_[BUILDING_BLOCK_NAME] 的命名约定，例如：

Integration testing with Dapr.Testcontainers

Mon, 01 Jan 0001 00:00:00 +0000

概述

Dapr.Testcontainers 是一个辅助包，用于使用容器针对真实的 Dapr 运行时组件编写集成测试。它封装了 Testcontainers 库来启动 Dapr 边车、控制平面服务（placement 和 scheduler）以及特定 Dapr 构建块所需的基础设施。

重要

Dapr.Testcontainers 是初始版本。API 仍在演进中，可能在未来的版本中发生变化。我们尽量保持变化最小，但在该包成熟的过程中，你应预期可能出现破坏性变更。

包

Dapr.Testcontainers（核心 harness 和基础设施）
Dapr.Testcontainers.Xunit（可选的 xUnit 辅助工具）

前置条件

一个容器运行时（Docker Desktop、Podman 或等效工具）。
能够拉取 Dapr 和依赖镜像的网络访问。

核心概念

Dapr.Testcontainers 围绕环境和harness来建模测试：

DaprTestEnvironment：共享基础设施（网络、placement、scheduler、可选 Redis）。当你需要多个应用共享 Dapr 控制平面或运行多应用测试时使用它。
DaprHarnessBuilder：为特定构建块（工作流、作业、分布式锁或对话）创建 harness。
DaprTestApplicationBuilder：使用 harness 启动你的测试应用，并将 Dapr 端点连接到配置。

基本工作流测试示例

下面的示例反映了 .NET SDK 测试套件中的工作流集成测试，展示了典型设置：

var componentsDir = TestDirectoryManager.CreateTestDirectory("workflow-components");

await using var environment = await DaprTestEnvironment.CreateWithPooledNetworkAsync(needsActorState: true);
await environment.StartAsync();

var harness = new DaprHarnessBuilder(componentsDir)
 .WithEnvironment(environment)
 .BuildWorkflow();

await using var testApp = await DaprHarnessBuilder.ForHarness(harness)
 .ConfigureServices(builder =>
 {
 builder.Services.AddDaprWorkflowBuilder(opt =>
 {
 opt.RegisterWorkflow<TestWorkflow>();
 });
 })
 .BuildAndStartAsync();

using var scope = testApp.CreateScope();
var workflowClient = scope.ServiceProvider.GetRequiredService<DaprWorkflowClient>();

await workflowClient.ScheduleNewWorkflowAsync(nameof(TestWorkflow), input: 42);

配置 Dapr 运行时

DaprRuntimeOptions 让你控制 Dapr 镜像版本、App ID、日志级别和容器日志：

Dapr 源代码分析器和生成器

Mon, 01 Jan 0001 00:00:00 +0000

Dapr 支持日益丰富的可选 Roslyn 分析器和代码修复提供程序，用于检查代码中的代码质量问题。从 v1.16 版本开始，开发者可以在每个标准功能包的基础上，从 NuGet 安装额外的项目，从而在解决方案中启用这些分析器。

Note

Dapr .NET SDK 的未来版本将默认包含这些分析器，无需单独安装包。

规则违规通常标记为 Info 或 Warning，因此如果分析器发现问题，不一定会中断构建。所有代码分析违规都带有前缀 “DAPR”，并通过该前缀后的数字进行唯一区分。

Note

目前，诊断标识符的前两位数字与不同的 Dapr 包一一对应，但随着更多分析器的开发，这一映射方式未来可能会发生变化。

安装和配置分析器

在 v1.16 Dapr 版本发布后，以下包将可通过 NuGet 获取：

Dapr.Actors.Analyzers
Dapr.Jobs.Analyzers
Dapr.Workflow.Analyzers

在您希望运行分析器的每个项目中安装每个 NuGet 包。该包将作为项目依赖项安装，分析器将在您编写代码时或作为 CI/CD 构建的一部分运行。分析器会标记现有代码中的问题，并在构建项目时警告您新出现的问题。

我们的许多分析器都有关联的代码修复，可以自动纠正问题。如果您的 IDE 支持此功能，任何可用的代码修复都将作为代码中的内联菜单选项显示。

此外，我们的大多数分析器还应该报告代码中被识别为规则关键方面的特定语法所在的行号和列号。如果您的 IDE 支持，双击任何分析器警告应该直接跳转到违反分析器规则的代码部分。

抑制特定分析器

如果您希望阻止分析器对项目的某个特定部分进行检查，可以通过多种方式单独抑制其输出。有关在项目或文件中抑制分析器的更多信息，请阅读相关的 .NET 文档。

禁用所有分析器

如果您希望在不移除任何提供分析器的包的情况下禁用项目中的所有分析器，请在 csproj 文件中将 EnableNETAnalyzers 属性设置为 false。

可用的分析器

诊断 ID	Dapr 包	类别	严重性	添加版本	描述	可用代码修复
DAPR1301	Dapr.Workflow	Usage	Warning	1.16	工作流类型未向依赖注入提供程序注册	Yes
DAPR1302	Dapr.Workflow	Usage	Warning	1.16	工作流活动类型未向依赖注入提供程序注册	Yes
DAPR1401	Dapr.Actors	Usage	Warning	1.16	Actor 计时器方法调用要求在类型上存在指定的回调方法	No
DAPR1402	Dapr.Actors	Usage	Warning	1.16	Actor 类型未向依赖注入注册	Yes
DAPR1403	Dapr.Actors	Interoperability	Info	1.16	将 options.UseJsonSerialization 设置为 true 以支持与非 .NET actor 的互操作性	Yes
DAPR1404	Dapr.Actors	Usage	Warning	1.16	调用 app.MapActorsHandlers 以映射 Dapr actor 的端点	Yes
DAPR1501	Dapr.Jobs	Usage	Warning	1.16	Job 调用要求为 IEndpointRouteBuilder 上每个预期的作业设置和配置 MapDaprScheduledJobHandler	No

分析器类别

以下是分析器可以分配到的各个有效类别，这些类别是按照 .NET 分析器使用的标准类别建模的：