Aspire NATS 集成

2025-10-02

包含： - Client 集成

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

托管集成

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

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.Hosting.Nats

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

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

添加 NATS 服务器资源

在 AppHost 项目中，调用AddNatsbuilder实例以添加NATS服务器资源：

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

当将 Aspire 容器映像添加到 AppHost 时，如前面的示例中的 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 集成

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

.NETCLI（命令行界面）
包引用

dotnet add package Aspire.NATS.Net

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

添加 NATS 客户端

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

builder.AddNatsClient(connectionName: "nats");

提示

参数 connectionName 必须与在 AppHost 项目中添加 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 依赖项注入：键式服务。

配置

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

使用连接字符串

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

builder.AddNatsClient(connectionName: "nats");

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

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

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

使用配置提供程序

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

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

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

使用命名配置

集成 AspireNATS 支持命名配置，通过该配置，可以使用不同的设置来配置同一资源类型的多个实例。命名配置使用连接名称作为主配置部分下的密钥。

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

在此示例中，当调用nats1时，可以使用nats2和AddNatsClient作为连接名称。

builder.AddNatsClient("nats1");
builder.AddNatsClient("nats2");

命名配置优先于顶级配置。如果同时提供这两种设置，则命名配置中的设置将替代顶级设置。

使用内联委托

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

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

NATS 在 Aspire 清单中

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

Client 集成健康检查

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

Aspire NATS 集成处理以下内容：

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

可观测性和遥测

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

伐木

Aspire NATS 集成使用以下日志类别：

NATS

追踪

Aspire NATS 集成生成以下跟踪活动：

NATS.Net

另请参阅

反馈

此页面是否有帮助？