integrace .NET AspireNATS

Článek
01/22/2025

zahrnuje:integrace hostování a Client integrace

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í

NATS hostování integrace 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
Reference balíčku

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. Volitelně můžete zadat parametr srcMountPath pro určení cesty k datovému adresáři JetStream na hostitelském počítači (zadaná cesta připojení se mapuje na argument -sd kontejneru).

Přidání prostředku 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č se upřednostňují před připojení vazby, 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í vazby však umožňují přímý přístup a úpravy souborů v hostitelském systému, které jsou ideální pro vývoj a testování, kde jsou potřebné změny v reálném čase.

Datové vazby úložišť spoléhají na systém souborů hostitele k uchování dat serveru NATS při opětovném spuštění kontejneru. Připojení datové vazby je namontováno na C:\NATS\Data ve Windows (nebo /NATS/Data na Unix) v rámci hostitelského počítače 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.HealthCheck s.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
Reference balíčku

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 tématu Přidání prostředku serveru NATS.

Potom můžete načíst instanci INatsConnection pomocí vkládání závislostí. 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řidání klienta NATS s přiřazeným klíčem

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žití připojovacího řetězce

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 přijímat provoz.

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