NATS client integration

To get started with the Aspire NATS client integration, install the Aspire.NATS.Net NuGet package in the consuming client project:

dotnet add package Aspire.NATS.Net

Add NATS client API

In the Program.cs file of your client-consuming project, call the AddNatsClient extension method to register an INatsConnection for use through dependency injection. The method takes a connection name parameter:

builder.AddNatsClient(connectionName: "nats");

You can then retrieve the INatsConnection instance using dependency injection. For example, to retrieve the connection object from an example service:

public class ExampleService(INatsConnection connection)
{
    // Use connection...
}

Add keyed NATS client API

There might be situations where you want to register multiple INatsConnection instances with different connection names. To register keyed NATS clients, call the AddKeyedNatsClient method:

builder.AddKeyedNatsClient(name: "products");
builder.AddKeyedNatsClient(name: "orders");

Then you can retrieve the INatsConnection instances using dependency injection. For example, to retrieve the connection from an example service:

public class ExampleService(
    [FromKeyedServices("products")] INatsConnection productsConnection,
    [FromKeyedServices("orders")] INatsConnection ordersConnection)
{
    // Use connections...
}

For more information on keyed services, see .NET dependency injection: Keyed services.

Connection properties

When you reference a NATS resource using WithReference, the following connection properties are made available to the consuming project:

NATS server

The NATS server resource exposes the following connection properties:

Example connection string:

Uri: nats://admin:p%40ssw0rd1@localhost:4222

Configuration

The Aspire NATS client integration provides multiple configuration approaches. You can provide configuration using appsettings.json, configuration keys, or inline code.

Use configuration providers

The Aspire NATS client integration supports Microsoft.Extensions.Configuration. It loads the NatsClientSettings from configuration using the Aspire:Nats:Client key:

{
  "Aspire": {
    "Nats": {
      "Client": {
        "ConnectionString": "nats://localhost:4222",
        "DisableHealthChecks": false,
        "DisableTracing": false
      }
    }
  }
}

For the complete NATS client integration JSON schema, see Aspire.NATS.Net/ConfigurationSchema.json.

Use inline delegates

You can also pass the Action<NatsClientSettings> delegate to set up some or all the options inline:

builder.AddNatsClient(
    "nats",
    static settings => settings.DisableHealthChecks = true);

Health checks

By default, the Aspire NATS integration handles health checks using the AspNetCore.HealthChecks.Nats package. This integration registers a health check that verifies the connection to the NATS server.

The NATS client integration registers a health check using the connection name. The health check verifies that the connection is active and can be used to send and receive messages.

Observability and telemetry

Tracing

The Aspire NATS integration emits tracing activities using OpenTelemetry. The integration automatically enables tracing for NATS operations.

The following are the tracing activities emitted by NATS components:

• "NATS": Emitted by NatsConnection.
• "NATS.Net": Emitted by the NATS .NET client library.

For more information about tracing activities, see NATS .NET client library: OpenTelemetry support.

See also

• NATS documentation
• NATS .NET client
• Aspire integrations overview
• Aspire GitHub repo