integrace .NET AspireNATS

Článek
12/15/2024

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 modely NATSserver jako typ NatsServerResource. Chcete-li získat přístup k tomuto typu, nainstalujte 📦Aspire.Hosting.Nats balíček NuGet 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řidat prostředek NATSserver

V projektu hostitele aplikace zavolejte AddNats na instanci builder a přidejte prostředek NATSserver.

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 NATSserver. Do NATSje přidán odkaz na servernats (proměnnou 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 NATSserver, volejte místo toho AddConnectionString. Další informace naleznete v části Odkaz na existující prostředky.

Přidání prostředku NATSserver pomocí JetStreamu

Chcete-li přidat NATS JetStream do prostředku NATSserver, 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 NATSserver s datovým svazkem

Pokud chcete do prostředku NATSserver přidat datový svazek, zavolejte metodu WithDataVolume prostředku NATSserver:

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...

Objem dat se používá k zachování NATSserver dat mimo životní cyklus kontejneru. Datový svazek je připojen k cestě /var/lib/nats v kontejneru NATSserver. 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 NATSserver s připojením vazby dat

Pokud chcete přidat připojení datové vazby k prostředku NATSserver, 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.

Připojení vazby dat využívají systém souborů hostitelského počítače k zachování NATSserver dat napříč restartováními kontejneru. Připojení datového úložiště je připojeno k cestě C:\NATS\Data ve Windows (nebo do /NATS/Data na Unix) na hostitelském počítači v kontejneru NATSserver. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Hostování kontrol stavu integrace

Integrace hostingu NATS automaticky přidává kontrolu stavu pro prostředek NATSserver. Kontrola stavu ověřuje, že NATSserver běží a že se k němu lze připojit.

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

integrace Client

Pokud chcete začít s integrací .NET AspireNATSclient, nainstalujte 📦Aspire.NATSbalíček NuGet .Net v projektu client, tj. projektu pro aplikaci, která používá NATSclient. Integrace NATSclient 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řidej NATSclient

V souboru Program.cs projektu, který využívá client, zavolejte metodu rozšíření AddNatsClient na libovolném IHostApplicationBuilder a zaregistrujte INatsConnection pro použití prostřednictvím kontejneru injektáže 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 NATSserver do hostitelského projektu aplikace. Pro více informací viz Přidat NATSserver prostředek.

Potom můžete načíst instanci INatsConnection pomocí vkládání závislostí. Například chcete-li získat client z nějaké 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í NATSclient s klíči

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 NATSclientJSON najdete v tématu 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í NATSserver 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