RedNb.Nacos
2.3.0
dotnet add package RedNb.Nacos --version 2.3.0
NuGet\Install-Package RedNb.Nacos -Version 2.3.0
<PackageReference Include="RedNb.Nacos" Version="2.3.0" />
<PackageVersion Include="RedNb.Nacos" Version="2.3.0" />
<PackageReference Include="RedNb.Nacos" />
paket add RedNb.Nacos --version 2.3.0
#r "nuget: RedNb.Nacos, 2.3.0"
#:package RedNb.Nacos@2.3.0
#addin nuget:?package=RedNb.Nacos&version=2.3.0
#tool nuget:?package=RedNb.Nacos&version=2.3.0
RedNb.Nacos
English | 简体中文
面向 Nacos 3.2.4 的 .NET 8 / .NET 10 SDK。配置和服务发现默认使用 gRPC;AI 与管理操作按服务器实际能力选择 HTTP Client、Admin 或 Console 通道。
当前稳定版可在 NuGet.org 和 GitHub Release 查看。SDK 版本与 Nacos 服务端版本分别编号。
2.2.0 已发布:新增 Aspire 一键启动示例,修复 HTTP 健康检查协议头重复拼接;1534 次测试及 11 项 CI 检查全部通过。见 Release 与验收结果。
2.1.1 维护更新:升级 xUnit.net v3 测试基础设施,SDK 公共 API 和运行时功能保持一致。1500 次测试及 CI 11 项检查全部通过,见 xUnit v3 升级报告。
2.1.0 已完成验收:1500 项测试通过,CI 11 项检查全部成功。新增 Windows/Linux NativeAOT 支持与客户端级 JSON Context 注入,并修复 JSON 数值/容器、YAML 合并及 AI 管理接口契约。详细证据见 2.1.0 验收报告。
从 1.x 升级包含命名空间和默认实现的破坏性调整,请先阅读迁移说明。不支持 Nacos 2.x;其他 3.x 小版本的支持范围见能力矩阵。
安装
普通 .NET 应用推荐安装依赖注入包:
dotnet add package RedNb.Nacos.DependencyInjection
ASP.NET Core 应用需要配置热更新、健康检查和服务注册时,安装:
dotnet add package RedNb.Nacos.AspNetCore
需要全部组件时,可安装聚合包:
dotnet add package RedNb.Nacos.All
上述包会自动引入所需依赖,无需把六个包全部手动添加。
选择类库
| NuGet 包 | 用途 |
|---|---|
| RedNb.Nacos | 接口、模型、选项和公共功能 |
| RedNb.Nacos.Http | 显式 HTTP 客户端和 v3 管理接口 |
| RedNb.Nacos.Grpc | 配置、服务发现、原生锁和 AI 组合客户端 |
| RedNb.Nacos.DependencyInjection | 推荐的 DI 注册入口、命名客户端 |
| RedNb.Nacos.AspNetCore | IConfiguration 热更新、健康检查、服务注册 |
| RedNb.Nacos.All | 纯依赖聚合包,方便体验全部组件 |
推荐用法
using Microsoft.Extensions.DependencyInjection;
using RedNb.Nacos.DependencyInjection;
using RedNb.Nacos.Config;
var services = new ServiceCollection();
services.AddNacos(options =>
{
options.ServerAddresses = Environment.GetEnvironmentVariable("NACOS_SERVER") ?? "localhost:8848";
options.ConsoleAddresses = Environment.GetEnvironmentVariable("NACOS_CONSOLE") ?? "localhost:8080";
options.Username = Environment.GetEnvironmentVariable("NACOS_USERNAME");
options.Password = Environment.GetEnvironmentVariable("NACOS_PASSWORD");
});
await using var provider = services.BuildServiceProvider();
var config = provider.GetRequiredService<IConfigService>();
var content = await config.GetConfigAsync("app-config", "DEFAULT_GROUP", 5000);
只需配置或服务发现时,可使用 AddNacosConfig / AddNacosNaming。AI 通过 AddNacosAi 单独启用,命名空间管理通过 AddNacosAdministration 单独启用。各模块延迟创建,不会因为注册基础服务就连接 AI 或锁模块。
多个 Nacos 环境使用 services.AddNacos("environment-name", configure),再通过 GetRequiredKeyedService<IConfigService>("environment-name") 获取。不同名称的客户端和缓存相互隔离。
不使用 DI 时可用 NacosGrpcFactory.CreateConfigServiceAsync(options)、CreateNamingServiceAsync(options);AI 推荐 new NacosAiClient(options),不需要调用者自行组合两种通道。具体使用见 samples。
一键运行示例
启动 Docker,将 RedNb.Nacos.Sample.AppHost 设为启动项目按 F5,或使用 .NET 10 SDK 运行:
dotnet run --project samples/RedNb.Nacos.Sample.AppHost
Aspire 自动启动 Nacos 3.2.4、初始化本地鉴权与示例配置,再启动 Web API、Console 和本地 echo AI 示例;动态端口及 gRPC 偏移自动注入。具体参数、Dashboard 与生命周期说明见构建和测试指南。Aspire 仅用于示例,安装 SDK 无需引入它。
环境和验证
2.3.0 增加多地址/多组件健康检查和 PEM 私有 CA、mTLS 传输配置,并修复订阅恢复、配置原子更新与请求超时。健康检查模式、HTTP 管道所有权及缓存格式迁移见健康检查、TLS 与缓存迁移。升级前需在线预热 Naming 缓存,并重新生成手工维护的 HTTP failover 文件。
- API 端口默认 8848,客户端 gRPC 默认 9848,控制台默认 8080;显式映射不同端口时请配置地址和 GrpcPortOffset。
- 默认鉴权使用用户名密码/token。默认 Nacos 插件不提供本 SDK 旧版本假设的 AK/SK 登录接口。
- 单机 Docker 部署
- 构建和集成测试
- 完整改进计划
- 2.1.0 NativeAOT 验收报告
- 2.0.0 测试报告
- 文档索引
NativeAOT(2.1.0)
已验证 .NET 8 / .NET 10 × win-x64 / linux-x64 的原生 SDK 客户端和独立 ASP.NET Core Minimal API,包括源码引用与实际 NuGet 包消费者。验证覆盖配置与服务发现、AI 生命周期、ACK 收发,以及本地服务器重启后的配置监听、Naming 和 MCP 后端恢复。
SDK 协议模型使用源生成 JSON 元数据。自定义请求、响应或扩展对象通过 NacosClientOptions.JsonTypeInfoResolver 注册应用的 JsonSerializerContext;自定义泛型磁盘缓存可传入 JsonTypeInfo<T>。普通 JIT 保留用户类型的反射回退;NativeAOT 或禁用 JSON 反射时,未注册类型会明确报错。
使用方法见 NativeAOT 指南,示例见 原生 SDK 与 原生 Minimal API。现有 MVC/Swagger 示例不属于 NativeAOT 验收范围;ARM64、macOS、Linux musl、TLS/代理、多节点集群及外部 LLM 等范围尚未认证。
能力边界
纯 HTTP 配置监听和 Fuzzy Watch 会明确报不支持;使用推荐 gRPC 入口。MCP/Agent Console 操作在 3.2.4 上限定 public 空间。旧 Maintainer 接口保留迁移错误提示,不再发送 v1/v2 请求;已实现的新管理功能以能力矩阵为准。原生锁是服务器互斥原语,不提供 fencing 或可重入语义。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Logging.Abstractions (>= 10.0.1)
- Microsoft.Extensions.Options (>= 10.0.1)
- YamlDotNet (>= 16.3.0)
-
net8.0
- Microsoft.Extensions.Logging.Abstractions (>= 8.0.2)
- Microsoft.Extensions.Options (>= 8.0.2)
- YamlDotNet (>= 16.3.0)
NuGet packages (5)
Showing the top 5 NuGet packages that depend on RedNb.Nacos:
| Package | Downloads |
|---|---|
|
RedNb.Nacos.Http
Nacos .NET SDK HTTP Client - HTTP-based Nacos client implementation |
|
|
RedNb.Nacos.Grpc
Nacos .NET SDK gRPC Client - High-performance gRPC-based Nacos client |
|
|
RedNb.Nacos.DependencyInjection
Nacos .NET SDK Dependency Injection Extensions - DI extensions for Microsoft.Extensions.DependencyInjection |
|
|
RedNb.Nacos.AspNetCore
Nacos .NET SDK ASP.NET Core Integration - Configuration provider, health checks, service discovery and middleware |
|
|
RedNb.Nacos.All
Nacos .NET SDK All-in-One - Meta package that includes all Nacos SDK components for easy installation |
GitHub repositories
This package is not used by any popular GitHub repositories.