Nacos.Config.Lite 1.1.0

Nacos.Config.Lite

中文文档

A production-ready, lightweight Nacos configuration SDK for .NET. Redesigned with modern async/await patterns, zero gRPC dependencies, optimized for microservices and cloud-native applications.

Why Nacos.Config.Lite? Simple, efficient, and production-ready. Supports automatic failover and local snapshots, making configuration management simple and reliable.

✨ Key Features

Supported Frameworks

• .NET 10.0
• .NET 9.0
• .NET 8.0
• .NET 6.0

Quick Start

1. Installation

dotnet add package Nacos.Config.Lite

2. Configure Service

Using Username/Password Authentication

using Nacos.Config.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddNacosConfigService(options =>
{
    options.ServerAddresses = new List<string> { "http://localhost:8848" };
    options.Namespace = "your-namespace";
    options.UserName = "nacos";
    options.Password = "nacos";
    options.DefaultTimeoutMs = 15000;
    options.EnableSnapshot = true; // Enable local snapshots
});

var app = builder.Build();

Using AK/SK Authentication

builder.Services.AddNacosConfigService(options =>
{
    options.ServerAddresses = new List<string> { "http://localhost:8848" };
    options.Namespace = "your-namespace";
    options.AccessKey = "your-ak";
    options.SecretKey = "your-sk";
});

No Authentication (Local Development)

builder.Services.AddNacosConfigService(options =>
{
    options.ServerAddresses = new List<string> { "http://localhost:8848" };
});

3. Use Configuration Service

using Nacos.Config.Core;

public class YourService
{
    private readonly INacosConfigService _configService;

    public YourService(INacosConfigService configService)
    {
        _configService = configService;
    }

    // Get configuration
    public async Task<string?> GetDatabaseConfig()
    {
        var config = await _configService.GetConfigAsync(
            dataId: "database.json",
            group: "DEFAULT_GROUP"
        );

        return config;
    }

    // Publish configuration
    public async Task<bool> PublishConfig()
    {
        return await _configService.PublishConfigAsync(
            dataId: "app-config.json",
            group: "DEFAULT_GROUP",
            content: "{\"key\":\"value\"}",
            type: "json"
        );
    }

    // Remove configuration
    public async Task<bool> RemoveConfig()
    {
        return await _configService.RemoveConfigAsync(
            dataId: "old-config",
            group: "DEFAULT_GROUP"
        );
    }

    // Listen for configuration changes
    public void ListenConfigChanges()
    {
        var subscription = _configService.Subscribe(
            dataId: "app-config.json",
            group: "DEFAULT_GROUP",
            callback: evt =>
            {
                Console.WriteLine($"Config changed: {evt.NewContent}");
            }
        );

        // Unsubscribe
        // subscription.Dispose();
    }

    // Listen with async callback (for async operations)
    public void ListenWithAsyncCallback()
    {
        var subscription = _configService.Subscribe(
            dataId: "app-config.json",
            group: "DEFAULT_GROUP",
            asyncCallback: async evt =>
            {
                // Perform async operations
                await SaveToDatabase(evt.NewContent);
                await NotifyExternalService(evt.NewContent);
                Console.WriteLine($"Async processing complete: {evt.NewContent}");
            }
        );

        // Unsubscribe
        // subscription.Dispose();
    }
}

4. ASP.NET Core Configuration Integration (Recommended)

New in v1.1.0+: Seamlessly integrate Nacos with ASP.NET Core's configuration system. Your existing code using IConfiguration works without any changes!

Basic Usage

using Nacos.Config.Configuration;
using Nacos.Config.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Step 1: Register Nacos config service
builder.Services.AddNacosConfigService(options =>
{
    options.ServerAddresses = new List<string> { "http://localhost:8848" };
    options.Namespace = "your-namespace";
    options.UserName = "nacos";
    options.Password = "nacos";
});

// Step 2: Add Nacos configuration source
var serviceProvider = builder.Services.BuildServiceProvider();
builder.Configuration.AddNacosConfiguration(
    serviceProvider,
    dataId: "appsettings.json",
    group: "DEFAULT_GROUP",
    reloadOnChange: true);

var app = builder.Build();

// Access configuration using standard IConfiguration API
var encryptionIv = app.Configuration["Encryption:SM4:Iv"];
var databaseHost = app.Configuration["Database:Host"];

Strongly-Typed Configuration

// Define your configuration class
public class EncryptionConfig
{
    public SM4Config? SM4 { get; set; }
}

public class SM4Config
{
    public string? Key { get; set; }
    public string? Iv { get; set; }
}

// Bind configuration to strongly-typed object
var encryptionConfig = app.Configuration
    .GetSection("Encryption")
    .Get<EncryptionConfig>();

Console.WriteLine($"SM4 IV: {encryptionConfig?.SM4?.Iv}");

Configuration Hot Reload

Configuration changes in Nacos are automatically detected and reloaded:

// Monitor configuration changes
var changeToken = app.Configuration.GetReloadToken();
changeToken.RegisterChangeCallback(_ =>
{
    Console.WriteLine("Configuration changed!");
    var newValue = app.Configuration["Encryption:SM4:Iv"];
    Console.WriteLine($"New IV: {newValue}");
}, null);

Nacos Configuration Format

Store your configuration in Nacos as JSON (dataId: appsettings.json):

{
  "Encryption": {
    "SM4": {
      "Key": "your-encryption-key",
      "Iv": "your-initialization-vector"
    }
  },
  "Database": {
    "Host": "localhost",
    "Port": 3306,
    "Name": "mydb"
  }
}

The JSON structure is automatically flattened to configuration keys:

• Encryption:SM4:Key → "your-encryption-key"
• Encryption:SM4:Iv → "your-initialization-vector"
• Database:Host → "localhost"

When to Use Which Approach?

Use Configuration Integration (AddNacosConfiguration) when:

• ✅ You want Nacos config to work with existing IConfiguration code
• ✅ You need strongly-typed configuration binding
• ✅ You want automatic hot reload with IOptionsMonitor
• ✅ You only need to read configuration (most common scenario)

Use INacosConfigService directly when:

• ✅ You need to publish or delete configurations programmatically
• ✅ You need fine-grained control over config operations
• ✅ You want to subscribe to specific config changes with custom logic
• ✅ You're building a configuration management tool

Can I use both? Yes! They work together seamlessly:

// Step 1: Register Nacos config service
builder.Services.AddNacosConfigService(options =>
{
    options.ServerAddresses = new List<string> { "http://localhost:8848" };
    options.Namespace = "your-namespace";
    options.UserName = "nacos";
    options.Password = "nacos";
});

// Step 2: Use Configuration Integration for reading
var serviceProvider = builder.Services.BuildServiceProvider();
builder.Configuration.AddNacosConfiguration(
    serviceProvider,
    dataId: "appsettings.json",
    group: "DEFAULT_GROUP");

// Now you can:
// - Read config via IConfiguration (automatic)
// - Publish config via INacosConfigService (manual)

Configuration Priority

When retrieving configuration, the following priority order is followed:

1. Failover - Manually placed local configuration files (highest priority)
2. Server - Retrieved from Nacos server
3. Snapshot - Local snapshot cache (fallback when server is unavailable)

Failover File Path

{SnapshotPath}/data/config-data/{tenant}/{group}/{dataId}

Default path: %LocalAppData%/nacos/config/data/...

Snapshot File Path

{SnapshotPath}/snapshot/{tenant}/{group}/{dataId}

Configuration Options

Architecture Design

The SDK uses a clean layered architecture:

Application
    ↓
INacosConfigService (Core)
    ↓
├─ INacosConfigClient (HTTP API)
│   └─ IHttpTransport (Transport)
│       ├─ IServerSelector (Server Selection)
│       └─ IAuthenticationProvider (Authentication)
│
└─ ILocalConfigStorage (Storage)

Core Components

• Core: INacosConfigService - User-facing API, integrates all features
• Client: INacosConfigClient - HTTP API wrapper
• Transport: IHttpTransport - HTTP transport using IHttpClientFactory
• Authentication: Three authentication providers (Null/UsernamePassword/AkSk)
• Storage: Local snapshot and failover file management
• Listening: Configuration change listener manager

📊 Performance Benchmarks

Real-world test results on Aliyun ECS (1c2g, Nacos v2.3.2.0):

Average memory per request: ~10KB, industry standard

Feature Status

✅ v1.0.0 Completed

Core Features:

• ✅ HTTP-only client (zero gRPC dependencies)
• ✅ Username/Password authentication
• ✅ AK/SK signature authentication
• ✅ Config CRUD operations (Get/Publish/Remove)
• ✅ Config change listening (long-polling + Channel)
• ✅ Local snapshot caching
• ✅ Server round-robin selection
• ✅ Three-tier fallback strategy (Failover/Server/Snapshot)

Quality Assurance:

• ✅ Polly retry mechanism (exponential backoff)
• ✅ xUnit integration tests (full operation coverage)
• ✅ BenchmarkDotNet performance testing
• ✅ Connection pool optimization (IHttpClientFactory)
• ✅ Memory allocation optimization (~10KB/request)

⏳ Planned Features

High Priority:

• Circuit Breaker pattern
• Distributed Tracing (OpenTelemetry)
• Config encryption/decryption
• .NET Standard 2.0 support

Medium Priority:

• Configuration versioning and rollback
• Batch configuration operations
• Config import/export tools
• Management API

Low Priority:

• Config comparison and merge tools
• Health check endpoints

Comparison with Existing SDK

License

Apache-2.0