RedNb.Nacos 2.3.0

dotnet add package RedNb.Nacos --version 2.3.0
                    
NuGet\Install-Package RedNb.Nacos -Version 2.3.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="RedNb.Nacos" Version="2.3.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="RedNb.Nacos" Version="2.3.0" />
                    
Directory.Packages.props
<PackageReference Include="RedNb.Nacos" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add RedNb.Nacos --version 2.3.0
                    
#r "nuget: RedNb.Nacos, 2.3.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package RedNb.Nacos@2.3.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=RedNb.Nacos&version=2.3.0
                    
Install as a Cake Addin
#tool nuget:?package=RedNb.Nacos&version=2.3.0
                    
Install as a Cake Tool

RedNb.Nacos

NuGet GitHub Release CI .NET Tested 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 文件。

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 或可重入语义。

源码按 Apache-2.0 发布,见 LICENSE。感谢 Nacos 社区。

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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.

Version Downloads Last Updated
2.3.0 271 10/23/2026
2.2.0 202 10/16/2026
2.1.1 179 10/16/2026
2.1.0 1,104 9/15/2026
2.0.0 231 9/13/2026
1.0.3 283 1/18/2026
1.0.2 222 1/18/2026
1.0.1 239 1/18/2026
1.0.0 192 1/16/2026