.NET Aspire NATS 集成

包括: 托管集成和 Client 集成

NATS 是一种高性能、安全的分布式消息传送系统。 通过 .NET AspireNATS 集成,可以连接到现有 NATS 实例,或使用 .NET从 docker.io/library/nats 创建新实例。

托管集成

NATS 集成将 .NET Aspire 模型的 NATS 服务器托管为 NatsServerResource 类型。 若要访问此类型,请在 📦 项目中安装 Aspire.Hosting.Nats NuGet 包,然后通过生成器添加它。

dotnet add package Aspire.Hosting.Nats

有关详细信息,请参阅 dotnet add package管理 .NET 应用程序中的包依赖项

添加 NATS 服务器资源

在应用主机项目中,对 AddNats 实例调用 builder 以添加 NATS 服务器资源:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

当 .NET.NET Aspire 将容器映像添加到应用主机时,如上例中所示的 docker.io/library/nats 映像,它会在本地计算机上创建新的 NATS 服务器实例。 将对 NATS 服务器(即 nats 变量)的引用添加到了 ExampleProject

WithReference 方法在名为 ExampleProject"nats" 中配置连接。 有关详细信息,请参阅 容器资源生命周期

提示

如果想要连接到现有 NATS 服务器,请改为调用 AddConnectionString。 有关详细信息,请参阅 引用现有资源

使用 JetStream 添加 NATS 服务器资源

若要将 NATS JetStream 添加到 NATS 服务器资源,请调用 WithJetStream 方法:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithJetStream();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

NATS JetStream 功能提供一个名为 JetStream 的内置持久性引擎,使消息稍后可以存储和重播。

使用身份验证参数添加 NATS 服务器资源

如果要显式提供用户名和密码,可以将其作为参数提供。 请考虑以下替代示例:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var nats = builder.AddNats(
    name: "nats",
    userName: username,
    password: password);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);


// After adding all resources, run the app...

有关详细信息,请参阅 外部参数

使用数据卷添加 NATS 服务器资源

若要将数据卷添加到 NATS 服务器资源,请在 WithDataVolume 服务器资源上调用 NATS 方法:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

数据卷用于在其容器生命周期之外保留 NATS 服务器数据。 数据卷装载在 /var/lib/nats 服务器容器中的 NATS 路径上。 除非您设置 name 参数,否则将随机生成一个名称。 有关数据卷的更多信息,以及为什么它们比绑定挂载更受欢迎的原因,请参阅Docker 文档:数据卷

添加带数据绑定挂载的 NATS 服务器资源

要将数据绑定安装点添加到 NATS 服务器资源,请调用 WithDataBindMount 方法:

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataBindMount(
                      source: @"C:\NATS\Data",
                      isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

重要

数据绑定装载的功能有限,相比之下,提供更好的性能、可移植性和安全性,使得卷更适用于生产环境。 但是,绑定装载允许直接访问和修改主机系统上的文件,非常适合在需要实时更改的情况下进行开发和测试。

数据绑定装载依赖于主机的文件系统在容器重启时保留 NATS 服务器数据。 数据绑定挂载在主机上的 Windows C:\NATS\Data 路径(或 /NATS/Data 上的 Unix)的 NATS 服务器容器中。 有关数据绑定装载的详细信息,请参阅 Docker 文档:绑定装载

托管集成运行状况检查

托管集成的 NATS 会自动为 NATS 服务器资源添加运行状况检查。 运行状况检查验证 NATS 服务器是否正在运行,并且可以建立与服务器的连接。

托管集成依赖于 📦 AspNetCore.HealthChecks.Nats NuGet 包。

Client 集成

若要开始 .NET AspireNATS 客户端集成,请在客户端使用项目中安装 📦AspireNATS.Net NuGet 包,即使用 NATS 客户端的应用程序项目。 NATS 客户端集成注册了一个 INatsConnection 实例,用于与 NATS交互。

dotnet add package Aspire.NATS.Net

添加 NATS 客户端

在客户端使用项目的 Program.cs 文件中,对任何 AddNatsClient 调用 IHostApplicationBuilder 扩展方法,将 INatsConnection 注册到依赖注入容器中以供使用。 该方法采用连接名称参数。

builder.AddNatsClient(connectionName: "nats");

提示

connectionName 参数必须与在应用主机项目中添加 NATS 服务器资源时使用的名称匹配。 有关详细信息,请参阅 添加 NATS 服务器资源

然后,可以使用依赖项注入检索 INatsConnection 实例。 例如,若要从服务检索客户端:

public class ExampleService(INatsConnection connection)
{
    // Use connection...
}

有关依赖项注入的详细信息,请参阅 .NET 依赖项注入

添加已加密的NATS客户端

在某些情况下,可能需要使用不同的连接名称注册多个 INatsConnection 实例。 若要注册密钥 NATS 客户端,请调用 AddKeyedNatsClient 方法:

builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");

然后,可以使用依赖项注入检索 IConnection 实例。 例如,若要从示例服务检索连接,

public class ExampleService(
    [FromKeyedServices("chat")] INatsConnection chatConnection,
    [FromKeyedServices("queue")] INatsConnection queueConnection)
{
    // Use connections...
}

有关密钥服务的详细信息,请参阅 .NET 依赖项注入:键式服务

配置

.NET Aspire NATS 集成提供了多个选项,用于根据项目的要求和约定配置 NATS 连接。

使用连接字符串

调用 builder.AddNatsClient时提供连接字符串的名称:

builder.AddNatsClient(connectionName: "nats");

连接字符串从 ConnectionStrings 配置部分中检索而来。

{
  "ConnectionStrings": {
    "nats": "nats://nats:4222"
  }
}

有关如何设置此连接字符串格式的详细信息,请参阅 ConnectionString 文档

使用配置提供程序

.NET Aspire NATS 集成支持 Microsoft.Extensions.Configuration。 它使用 Aspire:Nats:Client 键从配置中加载 NatsClientSettings。 以下代码片段是配置某些选项的 appsettings.json 文件示例:

{
  "Aspire": {
    "Nats": {
      "Client": {
        "ConnectionString": "nats://nats:4222",
        "DisableHealthChecks": true,
        "DisableTracing": true
      }
    }
  }
}

有关完整的 NATS 客户端集成 JSON 架构,请参阅 Aspire。NATS.Net/ConfigurationSchema.json

使用内联委托

传递 Action<NatsClientSettings> configureSettings 委托以直接设置一些或所有选项,例如禁用代码中的健康检查:

builder.AddNatsClient(
    "nats",
    static settings => settings.DisableHealthChecks  = true);

NATS 在 .NET Aspire 清单中

NATS 不属于 .NET Aspire部署清单。 建议在 NATS之外设置一台安全的 .NET Aspire 生产服务器。

Client 集成健康检查

默认情况下,.NET.NET Aspire 集成会为所有服务启用 健康检查。 有关详细信息,请参阅 .NET.NET Aspire 集成概述

.NET Aspire NATS 集成处理以下内容:

  • /health HTTP 终结点集成,该终结点要求所有已注册的健康检查都必须通过,应用才能被视为准备好接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标等配置,这些配置有时称为 可观测性的基础支柱。 有关集成可观测性和遥测的详细信息,请参阅 .NET.NET Aspire 集成概述。 根据支持服务,某些集成可能仅支持其中一些功能。 例如,某些集成支持日志记录和跟踪,但不支持指标。 也可以使用 配置 部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire NATS 集成使用以下日志类别:

  • NATS

追踪

.NET Aspire NATS 集成发出以下跟踪活动:

  • NATS.Net

另请参阅