Get started with the NATS integration

NATS is a simple, secure and high-performance open-source messaging system for cloud-native applications, IoT messaging, and microservices architectures. The Aspire NATS integration provides a way to connect to existing NATS instances or create new instances from Aspire with the docker.io/library/nats container image.

In this introduction, you’ll see how to install and use the Aspire NATS integrations in a simple configuration. If you already have this knowledge, see NATS hosting integration for full reference details.

Nota

To follow this guide, you must have created an Aspire solution to work with. To learn how to do that, see Build your first Aspire app.

Set up hosting integration

To begin, install the Aspire NATS hosting integration in your Aspire AppHost project:

Aspire CLI

Aspire CLI — Adicionar pacote Aspire.Hosting.Nats

aspire add nats

A Aspire CLI é interativa; escolha o resultado adequado quando solicitado:

Aspire CLI — Exemplo de saída

Select an integration to add:

> nats (Aspire.Hosting.Nats)
> Other results listed as selectable options...

Nota

Se houver apenas um resultado ele será escolhido automaticamente. Confirme a versão mesmo assim.

apphost.cs (C# file-based app)

C# — AppHost.cs

#:package Aspire.Hosting.Nats@*

PackageReference (*.csproj)

XML — Adicionar referência de pacote Aspire.Hosting.Nats

<PackageReference Include="Aspire.Hosting.Nats" Version="*" />

Next, in the AppHost project, create instances of NATS resources and pass them to the consuming client projects:

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

builder.Build().Run();

Set up client integration

To get started with the Aspire NATS client integration, install the package:

.NET CLI

.NET CLI — Add Aspire.NATS.Net package

dotnet add package Aspire.NATS.Net

Program.cs (C# file-based app)

Program.cs

#:package Aspire.NATS.Net@*

PackageReference (*.csproj)

XML — Add Aspire.NATS.Net package reference

<PackageReference Include="Aspire.NATS.Net" Version="*" />

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

builder.AddNatsClient(connectionName: "nats");

You can then retrieve the INatsConnection instance using dependency injection:

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

See also

• NATS hosting integration
• NATS client integration
• NATS documentation