Edit

.NET Aspire NATS component

  • Article

In this article, you learn how to use the .NET Aspire NATS component to send logs and traces to a NATS Server. The component supports persistent logs and traces across application restarts via configuration.

Prerequisites

Get started

To get started with the .NET Aspire NATS component, install the Aspire.NATS.Net NuGet package.

dotnet add package Aspire.NATS.Net --prerelease

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Example usage

In the Program.cs file of your projects, call the AddNatsClient extension method to register an INatsConnection to send logs and traces to NATS and the .NET Aspire Dashboard. The method takes a connection name parameter.

builder.AddNatsClient("nats");

You can then retrieve the INatsConnection instance using dependency injection. For example, to retrieve the client from a service:

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

Configuration

The .NET Aspire NATS component provides multiple options to configure the NATS connection based on the requirements and conventions of your project.

Use a connection string

Provide the name of the connection string when you call builder.AddNatsClient():

builder.AddNatsClient("myConnection");

The connection string is retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "myConnection": "nats://nats:4222"
  }
}

See the ConnectionString documentation for more information on how to format this connection string.

Use configuration providers

The .NET Aspire NATS component supports Microsoft.Extensions.Configuration. It loads the NatsClientSettings from configuration using the Aspire:Nats:Client key. Example appsettings.json that configures some of the options:

{
  "Aspire": {
    "Nats": {
      "Client": {
        "DisableHealthChecks": true
      }
    }
  }
}

Use inline delegates

Pass the Action<NatsClientSettings> configureSettings delegate to set up some or all the options inline, for example to disable health checks from code:

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

AppHost extensions

In your AppHost project, install the Aspire.Hosting.Nats library with NuGet:

dotnet add package Aspire.Hosting.Nats

Then, in the Program.cs file of AppHost, register a NATS server and consume the connection using the following methods:

var nats = builder.AddNats("nats");

var myService = builder.AddProject<Projects.MyService>()
                       .WithReference(nats);

The WithReference method configures a connection in the MyService project named nats. In the Program.cs file of MyService, the NATS connection can be consumed using:

builder.AddNatsClient("nats");

Persistent logs and traces

Register NATS with a data directory in your .AppHost project to retain NATS's data and configuration across application restarts.

var NATS = builder.AddNATS("NATS", NATSDataDirectory: "./NATSdata");

The directory specified must already exist.

NATS in the .NET Aspire manifest

NATS isn't part of the .NET Aspire deployment manifest. It's recommended you set up a secure production NATS server outside of .NET Aspire.

Health checks

By default, .NET Aspire components enable health checks for all services. For more information, see .NET Aspire components overview.

The .NET Aspire NATS component handles the following:

  • Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.

Observability and telemetry

.NET Aspire components automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about component observability and telemetry, see .NET Aspire components overview. Depending on the backing service, some components may only support some of these features. For example, some components support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire NATS component uses the following log categories:

  • NATS

Tracing

The .NET Aspire NATS component emits the following tracing activities:

  • NATS.Net

See also