NacosNetX.Admin 1.2.3

NacosNetX

NacosNetX is a .NET 10 SDK for Nacos configuration, service discovery, registration, authentication, distributed locks, Admin APIs, and AI registry APIs. It follows the Microsoft.Extensions dependency injection, options, logging, and hosting model.

Highlights

• gRPC is the default runtime for Nacos 2.x and later; Nacos 3.2.4 is the pinned live test target.
• Explicit HTTP runtime supports legacy Nacos OpenAPI and the limited Nacos 3.x v3 Client Naming API.
• ASP.NET Core service discovery reads local service snapshots on the request path and refreshes through Nacos on cache misses or expiry.
• Configuration and naming push queues are bounded and coalesce pending updates by key.
• A single NacosRuntimeSupervisor owns asynchronous auth, connection, configuration, registration, and shutdown components.
• A missing required DataId keeps the host alive in a waiting state; creation, deletion, and recreation flow through the live provider.
• Endpoint health is tracked per node with jittered open intervals and half-open recovery probes.
• Retry decisions are based on transient transport failures and operation semantics.
• .NET 10 is the supported target framework.

Installation

dotnet add package NacosNetX.AspNetCore

Add other packages only for features used directly by the application, such as NacosNetX.Admin, NacosNetX.AI, or NacosNetX.Lock.

Quick start

using NacosNetX.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddNacosNetX(options =>
{
    options.ServerAddresses.Add(new Uri("http://127.0.0.1:8848"));
    options.NamespaceId = "public";
});

var app = builder.Build();
app.MapHealthChecks("/health");
app.Run();

Configuration can also come from the standard NacosNetX section. See configuration and runtime architecture for the current options and ownership model.

To add a Nacos-backed document to the Generic Host configuration root, configure it before builder.Build():

{
  "NacosNetX": {
    "ServerAddresses": [ "http://127.0.0.1:8848" ],
    "Configuration": {
      "Enabled": true,
      "DataId": "application.json",
      "GroupName": "DEFAULT_GROUP",
      "Required": true,
      "ReloadOnChange": true
    }
  }
}

builder.Services.AddNacosNetX(builder.Configuration);

IConfigurationProvider.Load() initializes only a local empty snapshot. The runtime supervisor starts the remote fetch and listener in the background, so unavailable Nacos or a not-yet-created required DataId does not fail host startup. Use INacosConfigurationState and INacosRuntimeState to observe readiness. A required configuration becomes ready only after a validated document is active; deleting it clears the effective values and lets registration drain until the document returns.

Runtime protocols

gRPC runtime

The default runtime uses the Nacos gRPC protocol for config, naming, and connection management. gRPC endpoints are derived from each configured HTTP address using GrpcPortOffset, unless GrpcEndpoint is set explicitly. Connection setup attempts the configured endpoints and rotates after transient connection failures. A server reset or stream failure is surfaced to the connection lifecycle so redo work can run for the next connection generation.

HTTP runtime

Set RuntimeProtocol to Http for the legacy OpenAPI runtime. Transient connection failures and HTTP 408, 429, or 5xx responses rotate the shared endpoint selection before retry. Authentication and permission failures are not treated as endpoint failures.

{
  "NacosNetX": {
    "RuntimeProtocol": "Http",
    "ServerAddresses": [
      "http://nacos-a:8848",
      "http://nacos-b:8848"
    ],
    "HttpLongPollingTimeout": "00:00:30",
    "HttpHeartbeatInterval": "00:00:05",
    "HttpHeartbeatMaxConcurrency": 16
  }
}

The legacy HTTP runtime supports config query, publish, CAS, delete and long polling; naming register, deregister, heartbeat, query, service listing and UDP push where the server supports them. Fuzzy watch and config metrics are not supported by this runtime and fail with typed SDK exceptions.

Stock Nacos 3.2.4 removes the legacy v1/v2 client HTTP routes. For its v3 HTTP Naming API, set HttpNamingApiVersion to V3Client; registration, heartbeat, query and deregistration are supported, while service listing and HTTP push subscriptions are not. Keep Config on gRPC by setting ConfigurationProtocol to Grpc:

{
  "NacosNetX": {
    "RuntimeProtocol": "Http",
    "ConfigurationProtocol": "Grpc",
    "HttpNamingApiVersion": "V3Client"
  }
}

Config center

INacosConfigService supports config reads, publish, CAS, delete, listeners, and bounded snapshot fallback. The ASP.NET Core provider parses and validates a candidate document before atomically swapping its immutable effective snapshot, then triggers reload tokens and IOptionsMonitor<T>. Invalid updates retain the last valid snapshot. Delete clears the current values and keeps the watch active. Snapshot persistence is optional and configured through NacosOptions.ConfigSnapshots and SnapshotDirectory.

Service discovery

ASP.NET Core discovery is local-first: a normal business HttpClient request does not query Nacos for every destination selection. The discovery handler reads an immutable local snapshot and applies the configured load balancer. Naming push updates the snapshot; a cache miss or expired entry triggers one coalesced refresh. A recent snapshot may be used during a bounded stale-if-error window.

See service discovery design for cache refresh, expiry, and push behavior.

Service registration

The supervisor starts registration after the application listener, gRPC connection (when selected), required configuration, and local readiness are ready. It drains and deregisters on readiness loss or shutdown. gRPC ephemeral instances expose their connection lease; HTTP instances expose heartbeat risk, loss, recovery confirmation, and re-registration. Configure service name, group, address, port, metadata, drain time, and readiness lease through NacosServiceRegistrationOptions.

Multi-node behavior

The shared endpoint manager keeps health, failure count, last failure, open-until, half-open, and last-success data per node. Failed nodes are bypassed; open intervals include per-instance jitter, and a later request probes an eligible node before returning it to healthy service. Explicit GrpcEndpoint configures one gRPC endpoint while HTTP can still use the full ServerAddresses list.

Resilience and authentication

Retry pipelines exclude caller cancellation, malformed protocol data, validation errors, authentication failures, and permission denials. Read operations and explicitly idempotent operations may retry transient faults. Mutating operations are not retried by default unless their server semantics are known to be idempotent.

When credentials are configured, authentication runs in the background and retries login with bounded backoff. Token expiration preserves the server's tokenTtl; the next refresh time is derived from that lifetime with small jitter. Concurrent refresh and controlled 401 recovery share one single-flight gate. Only safe or idempotent requests receive one auth refresh and retry. Passwords and access tokens are excluded from normal request logging.

Distributed lock, Admin, and AI registry

• NacosNetX.Lock provides lock acquisition, renewal, and release through the advertised server capability set.
• NacosNetX.Admin exposes Nacos Admin OpenAPI operations. Available routes can vary by Nacos version.
• NacosNetX.AI exposes Nacos AI registry queries and writes. Retry behavior follows each operation's side-effect semantics.

ASP.NET Core integration

AddNacosNetX registers SDK services and one NacosRuntimeSupervisor host service. The supervisor starts and stops the SDK-owned connection, auth, configuration, registration, and lock cleanup components in dependency order. Nacos readiness is separate from process startup and is exposed by INacosRuntimeState, INacosConnectionState, INacosConfigurationState, and INacosRegistrationState. Logging uses the host Microsoft.Extensions.Logging providers. The SDK publishes cache and queue measurements through System.Diagnostics.Metrics; metric names and cardinality guidance are documented in observability.

Native AOT

Native AOT is experimental. The protocol registry is generated at build time, request ID access uses generated interfaces, and protocol/auth/config/HTTP naming/Admin JSON serialization uses source-generated metadata or explicit JsonDocument parsing. The smoke app runs as a native binary with reflection-based JSON disabled. Its live path completes a gRPC handshake and exercises config publish/read/listener, naming register/query/subscribe, and local selection against Nacos 2.4.3. CI is configured for cross-platform offline smoke and Linux live integration.

Publish the smoke app for a RID with a native toolchain installed:

dotnet publish Src/samples/NacosNetX.NativeAotSmoke/NacosNetX.NativeAotSmoke.csproj \
  -c Release -r linux-x64 --self-contained

To run the live path, set NACOSNETX_AOT_LIVE=1 and NACOSNETX_AOT_SERVER_ADDRESS, then execute the published binary. It performs the gRPC handshake and selects the explicit HTTP runtime for config and naming checks.

For musl-based Alpine containers use a matching musl RID such as linux-musl-x64. Native AOT output is platform-specific; Windows applications need a Windows RID and native compiler toolchain. Applications that serialize their own DTOs should supply their own System.Text.Json source-generated contexts.

Health checks and observability

The SDK exposes connection and service-registration health checks. Metrics currently include service-cache hits, misses, stale hits and coalesced refreshes, plus config/naming queue publications and coalescing and legacy UDP queue depth/processing duration. Use low-cardinality labels; service names, config keys, endpoints, and user identifiers are not metric dimensions.

Compatibility matrix

The CI matrix is authoritative. Other Nacos releases may work but are not claimed as verified here.

Performance

Performance tests cover local cache selection, protocol registry lookup, payload encoding, and queue behavior. No throughput or latency figures are published here because they depend on the host, server, transport, payload, and concurrency profile. See performance notes.

Testing

dotnet restore Src/NacosNetX.slnx
dotnet build Src/NacosNetX.slnx -c Release --no-restore
dotnet test Src/NacosNetX.slnx -c Release --no-build

Start a local Nacos 2.4.3 for live tests:

docker compose -f Src/docker-compose.nacos.yml up -d

Set NACOSNETX_TEST_SERVER_ADDRESS to target another test server. CI also runs the HTTP compatibility integration against Nacos 1.4.6.

Architecture

• Runtime lifecycle, endpoints, retry, and observability
• Service discovery and cache behavior
• gRPC connection and stream lifecycle
• Native AOT implementation status
• Performance notes and benchmark scope

Known limitations

• HTTP fuzzy watch and config metrics are unsupported.
• HTTP naming UDP push depends on legacy server behavior and network reachability from Nacos to the advertised client IP/port.
• Admin API fields and route behavior differ across Nacos releases.
• Native AOT support is experimental; live native integration currently targets Linux x64 with Nacos 2.4.3, and the live smoke does not exercise Admin operations.
• The real-server integration matrix pins Nacos 3.2.4 and 2.4.3. The 3.2.4 suite uses gRPC for Config and directly exercises the v3 HTTP Naming API.

Versioning and license

NacosNetX follows semantic versioning. Public API compatibility is maintained where practical; behavior changes are documented in release notes. The project is licensed under Apache-2.0.