Nacos.NET.Config.Encryption 1.0.0

Nacos.NET

.NET client library for Alibaba Nacos — configuration center, service discovery, gRPC v2 protocol, hot-reload, and AES config encryption. Targets .NET 10.

Packages

Dependency graph:

Nacos.NET  (base)
    ├── Nacos.NET.Extensions.Configuration
    ├── Nacos.NET.Config.Encryption
    └── Nacos.NET.AspNetCore  (depends on both above)

Quick Start

ASP.NET Core — full setup in one line:

// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.AddNacos("NacosConfig");  // config center + service registration

appsettings.json / appsettings.Docker.json:

{
  "NacosConfig": {
    "ServerAddresses": ["http://nacos-host:8848/"],
    "UserName": "nacos",
    "Password": "nacos",
    "Namespace": "prod",
    "ServiceName": "my-service",
    "GroupName": "DEFAULT_GROUP",
    "Ip": "my-service",
    "Port": "8080",
    "Listeners": [
      {
        "DataId": "appsettings.json",
        "Group": "DEFAULT_GROUP",
        "Optional": false
      }
    ]
  }
}

Once registered, config changes in the Nacos console are hot-reloaded into IConfiguration — no restart required.

Package Usage

Nacos.NET — Core SDK only

Use when you need config or naming in non-ASP.NET environments (Worker Service, Console, etc.).

// Config service only
services.AddNacosV2Config(configuration, sectionName: "NacosConfig");

// Naming / service discovery only
services.AddNacosV2Naming(configuration, sectionName: "NacosConfig");

Key interfaces:

Nacos.NET.Extensions.Configuration — IConfiguration provider

// Recommended: inject at Host build time (before DI container is created)
builder.Host.UseNacosConfig("NacosConfig");

// Or manually:
builder.Host.ConfigureAppConfiguration((_, cfb) => {
    cfb.AddNacosV2Configuration(cfb.Build().GetSection("NacosConfig"));
});

Config changes in Nacos are propagated to IOptionsMonitor<T> and IConfiguration automatically.

Nacos.NET.AspNetCore — full ASP.NET Core integration

// One-liner (recommended)
builder.AddNacos("NacosConfig");

// Equivalent manual setup:
builder.Host.UseNacosConfig("NacosConfig");                           // config center
builder.Services.AddNacosAspNet(builder.Configuration, "NacosConfig"); // service registration

The service instance is registered with Nacos on app start and deregistered on graceful shutdown.

Nacos.NET.Config.Encryption — AES config decryption

No code changes needed. Declare it in config:

"NacosConfig": {
  "ConfigFilterAssemblies": ["Nacos.NET.Config.Encryption"],
  "ConfigFilterExtInfo": "<Base64-encoded 32-byte AES key>"
}

Values stored in Nacos in ENC(<Base64(IV[16 bytes] + ciphertext)>) format are transparently decrypted before being fed into IConfiguration.

Offline encryption tool (to generate values for the Nacos console):

string cipher = AesConfigFilter.Encrypt("plain-value", base64Key);
// Paste the ENC(...) string into the Nacos console

Choose the right package

Extension method reference

Requirements

• .NET 10.0+
• Nacos 2.x or 3.x server (gRPC v2 protocol)

Acknowledgements

This project is heavily inspired by and partially derived from nacos-sdk-csharp, the official Nacos .NET SDK maintained by the nacos-group community.

Key aspects adopted or referenced from nacos-sdk-csharp:

• gRPC v2 transport layer structure and proto definitions
• INacosConfigService / INacosNamingService interface contracts
• IConfigFilter / ConfigFilterChainManager filter chain pattern
• HTTP API client design for Nacos Open API

This library re-implements and extends those concepts targeting .NET 10, with additions including:

• Nacos 3.x FuzzyWatch config subscription
• AES-256 transparent config decryption (Nacos.NET.Config.Encryption)
• Single-call ASP.NET Core registration (builder.AddNacos())
• Structured logging throughout the filter and transport layers

We are grateful to all contributors of nacos-sdk-csharp for their foundational work.

License

Apache License 2.0 — see LICENSE for the full text.

This project is distributed under the same license as nacos-sdk-csharp (Apache-2.0), in compliance with its license terms.