.NET Aspire NATS 集成

项目
03/09/2025

包括： 托管集成和 Client 集成

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

托管集成

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

.NETCLI（命令行界面）
PackageReference

dotnet add package Aspire.Hosting.Nats

<PackageReference Include="Aspire.Hosting.Nats"
                  Version="*" />

有关详细信息，请参阅 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交互。

.NET 命令行界面
PackageReference

dotnet add package Aspire.NATS.Net

<PackageReference Include="Aspire.NATS.Net"
                  Version="*" />

添加 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

通过