.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