integrace .NET AspireNATS

Článek
03/10/2025

zahrnuje: integraci hostování a Client integraci

NATS je vysoce výkonný, zabezpečený a distribuovaný systém zasílání zpráv. Integrace umožňuje připojit se k existujícím instancím nebo vytvářet nové instance z pomocíimage kontejneru .

Integrace hostování

Integrace hostování pro .NET Aspire modeluje server NATS jako typ NatsServerResource. Chcete-li získat přístup k tomuto typu, nainstalujte balíček NuGet 📦Aspire.Hosting.Nats v projektu hostitele aplikace a pak ho přidejte pomocí builderu.

.NET rozhraní příkazového řádku
Package Reference

dotnet add package Aspire.Hosting.Nats

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

Další informace najdete v tématu dotnet add package nebo Správa závislostí balíčků v .NET aplikacích.

Přidání prostředku serveru NATS

V projektu hostitele aplikace zavolejte AddNats na instanci builder a přidejte prostředek serveru NATS:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí docker.io/library/nats, vytvoří na místním počítači novou instanci serveru NATS. Do NATSse přidá odkaz na váš nats server (proměnná ExampleProject).

Metoda WithReference nakonfiguruje připojení v ExampleProject s názvem "nats". Další informace najdete v tématu životní cyklus prostředků kontejneru.

Spropitné

Pokud byste se raději připojili k existujícímu serveru NATS, volejte místo toho AddConnectionString. Další informace naleznete v části Odkaz na existující prostředky.

Přidání prostředku serveru NATS pomocí nástroje JetStream

Pokud chcete přidat NATS JetStream do prostředku serveru NATS, zavolejte metodu WithJetStream:

var builder = DistributedApplication.CreateBuilder(args);

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

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

// After adding all resources, run the app...

Funkce NATS JetStream poskytuje integrovaný modul trvalosti s názvem JetStream, který umožňuje ukládat a přehrávat zprávy později.

Přidejte prostředek serveru NATS s parametry ověřování.

Pokud chcete explicitně zadat uživatelské jméno a heslo, můžete je zadat jako parametry. Podívejte se na následující alternativní příklad:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var nats = builder.AddNats(
    name: "nats",
    userName: username,
    password: password);

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


// After adding all resources, run the app...

Další informace naleznete v tématu Externí parametry.

Přidejte prostředek serveru NATS s datovým svazkem

Chcete-li přidat datový svazek do prostředku serveru NATS, zavolejte metodu WithDataVolume na prostředku serveru NATS.

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataVolume(isReadOnly: false);

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

// After adding all resources, run the app...

Datový svazek slouží k zachování dat serveru NATS mimo životní cyklus kontejneru. Datový svazek je připojen k cestě /var/lib/nats v kontejneru serveru NATS. Název se generuje náhodně, pokud neposkytnete sadu pro parametr name. Další informace o datových svazcích a podrobnosti o tom, proč jsou preferovány před připojeními vazeb, najdete v dokumentaci Docker - Svazky.

Přidání prostředku serveru NATS s připojením datového úložiště

Pokud chcete přidat připojení datové vazby k prostředku serveru NATS, zavolejte metodu WithDataBindMount.

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataBindMount(
                      source: @"C:\NATS\Data",
                      isReadOnly: false);

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

// After adding all resources, run the app...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Připojení pomocí vazeb však umožňují přímý přístup a úpravu souborů v hostitelském systému, což je ideální pro vývoj a testování, kde je nutné provádět změny v reálném čase.

Datové přípojné body využívají systém souborů hostitelského stroje pro uložení dat serveru NATS při opětovném spuštění kontejneru. Datová vazba je namontována na cestě C:\NATS\Data na Windows (nebo /NATS/Data na Unix) na hostitelském počítači v kontejneru serveru NATS. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Hostování kontrol stavu integrace

Integrace hostování NATS automaticky přidá kontrolu stavu pro prostředek serveru NATS. Kontrola stavu ověřuje, jestli je server NATS spuštěný a že se k němu dá navázat připojení.

Integrace hostování spoléhá na balíček NuGet AspNetCore.HealthChecks.Nats.

integrace Client

Pokud chcete začít s integrací klienta .NET AspireNATS, nainstalujte balíček NuGet 📦Aspire.NATS.Net v projektu, který využívá klienta, tj. v projektu aplikace, který používá klienta NATS. Integrace klienta NATS registruje instanci INatsConnection, kterou můžete použít k interakci s NATS.

.NET rozhraní příkazového řádku
Odkaz na balíček

dotnet add package Aspire.NATS.Net

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

Přidejte klienta NATS

V souboru Program.cs projektu využívajícího klienta zavolejte metodu rozšíření AddNatsClient na libovolném IHostApplicationBuilder a zaregistrujte INatsConnection pro použití prostřednictvím kontejneru injekce závislostí. Metoda přebírá parametr názvu připojení.

builder.AddNatsClient(connectionName: "nats");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku serveru NATS v projektu hostitele aplikace. Další informace najdete v části Přidat prostředek serveru NATS.

Potom můžete načíst instanci INatsConnection pomocí dependency injection. Pokud chcete například načíst klienta ze služby:

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

Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidat klienta s klíčem NATS

Mohou nastat situace, kdy budete chtít zaregistrovat více instancí INatsConnection s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty NATS, zavolejte metodu AddKeyedNatsClient:

builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");

Potom můžete načíst IConnection instance pomocí injektáže závislostí. Pokud například chcete získat připojení z příkladové služby:

public class ExampleService(
    [FromKeyedServices("chat")] INatsConnection chatConnection,
    [FromKeyedServices("queue")] INatsConnection queueConnection)
{
    // Use connections...
}

Další informace o klíčových službách najdete v tématu .NET injektáž závislostí: klíčové služby.

Konfigurace

Integrace .NET AspireNATS nabízí několik možností konfigurace připojení NATS na základě požadavků a konvencí projektu.

Použijte připojovací řetězec

Při volání builder.AddNatsClientzadejte název připojovacího řetězce:

builder.AddNatsClient(connectionName: "nats");

Řetězec připojení se načte z oddílu konfigurace ConnectionStrings:

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

Další informace o formátování tohoto připojovacího řetězce najdete v dokumentaci ConnectionString.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireNATS podporuje Microsoft.Extensions.Configuration. Načte NatsClientSettings z konfigurace pomocí klíče Aspire:Nats:Client. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Kompletní schéma integrace klienta NATSJSON můžete najít v sekci Aspire.NATS.Net/ConfigurationSchema.json.

Použití vložených delegátů

Předat delegáta Action<NatsClientSettings> configureSettings pro nastavení některých nebo všech možností přímo, například zakázat zdravotní kontroly přímo v kódu.

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

NATS v manifestu .NET Aspire

NATS není součástí manifestu nasazení .NET Aspire. Doporučujeme nastavit zabezpečený produkční NATS server mimo .NET Aspire.

Client kontroly stavu integrace

Ve výchozím nastavení integrace .NET.NET Aspire umožňují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.

Integrace .NET AspireNATS zpracovává následující:

Integruje se s koncovým bodem HTTP /health, který určuje, že všechny registrované kontroly stavu musí projít, aby byla aplikace považována za připravenou k přijetí datového toku.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace .NET AspireNATS používá následující kategorie protokolů:

NATS

Trasování

Integrace .NET AspireNATS generuje následující aktivity trasování:

NATS.Net

Sdílet prostřednictvím