.NET Aspire NATS integrering

Artikel
12/12/2024

omfattar:Värdtjänstintegration och Client integrering

NATS är ett högpresterande, säkert, distribuerat meddelandesystem. Med integreringen .NET AspireNATS kan du ansluta till befintliga NATS-instanser eller skapa nya instanser från .NET med docker.io/library/nats containeravbildningen.

Värdintegrering

NATS värdintegrering för .NET Aspire modellerar en NATSserver som NatsServerResource typ. Om du vill komma åt den här typen installerar du 📦Aspire.Hosting.Nats NuGet-paketet i apphost-projektet, och lägg sedan till det med byggaren.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Nats

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

Mer information finns i dotnet add package eller hantera paketberoenden i .NET applikationer.

Lägg till NATSserver resurs

I appvärdprojektet anropar du AddNats på builder-instansen för att lägga till en NATSserver resurs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

När .NET.NET Aspire lägger till en containeravbildning till appvärden, som du ser i föregående exempel med docker.io/library/nats avbildningen, skapas en ny NATSserver instans på den lokala datorn. En referens till din NATSserver (variabeln nats) läggs till i ExampleProject.

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "nats". Mer information finns i Livscykel för containerresurser.

Tips

Om du hellre vill ansluta till en befintlig NATSserveranropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägga till NATSserver resurs med JetStream

Om du vill lägga till NATS JetStream- till resursen NATSserver anropar du metoden 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...

Funktionen NATS JetStream har en inbyggd beständighetsmotor som kallas JetStream som gör att meddelanden kan lagras och spelas upp igen vid ett senare tillfälle. Du kan också ange en srcMountPath parameter för att ange sökvägen till JetStream-datakatalogen på värddatorn (den angivna monteringssökvägen mappar till containerns -sd argument).

Lägga till NATSserver resurs med datavolym

Om du vill lägga till en datavolym i den NATSserver resursen anropar du metoden WithDataVolume på den NATSserver resursen:

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

Datavolymen används för att bevara NATSserver data utanför containerns livscykel. Datavolymen är monterad på sökvägen /var/lib/nats i NATSserver-containern. Ett namn genereras slumpmässigt om du inte anger parametern name. För mer information om datavolymer och varför de föredras framför bind mounts, se Docker dokumentation: Volymer.

Lägg till NATSserver resurs med databindningsmontering

Om du vill lägga till en databindningsmontering till den NATSserver resursen anropar du metoden 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...

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

Databindningar förlitar sig på värdmaskinens filsystem för att lagra NATSserver data mellan omstarter av containrar. Databindningen monteras på C:\NATS\Data-sökvägen i Windows (eller på /NATS/Data på Unix) på värddatorn i NATSserver-containern. Mer information om databindningsmonteringar finns i Docker dokument: Bind monteringar.

Hälsokontroller för hostning av integrationer

NATS värdintegrering lägger automatiskt till en hälsokontroll för den NATSserver resursen. Hälsokontrollen verifierar att NATSserver körs och att en anslutning kan upprättas till den.

Värdintegrering förlitar sig på 📦 AspNetCore.HealthChecks.Nats NuGet-paket.

Client integration

Kom igång med .NET AspireNATSclient-integreringen genom att installera 📦Aspire.NATS.Net NuGet-paket i projektet som konsumerar client, dvs. projektet för programmet som använder NATSclient. NATS client-integreringen registrerar en INatsConnection--instans som du kan använda för att interagera med NATS.

.NET CLI
PackageReference

dotnet add package Aspire.NATS.Net

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

Lägg till NATSclient

I Program.cs-filen i ditt projekt som använder clientanropar du tilläggsmetoden AddNatsClient för vilka som helst IHostApplicationBuilder för att registrera en INatsConnection för användning via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddNatsClient(connectionName: "nats");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till den NATSserver resursen i appvärdprojektet. Mer information finns i Lägg till NATSserver resurs.

Du kan sedan hämta INatsConnection-instans med hjälp av beroendeinjektion. Om du till exempel vill hämta client från en tjänst:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till med nyckel NATSclient

Det kan finnas situationer där du vill registrera flera INatsConnection instanser med olika anslutningsnamn. Om du vill registrera nyckelade NATS klienter anropar du metoden AddKeyedNatsClient:

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

Sedan kan du hämta IConnection-instansen med hjälp av dependency injection. Om du till exempel vill hämta anslutningen från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinmatning: Nyckelade tjänster.

Konfiguration

.NET Aspire NATS-integreringen innehåller flera alternativ för att konfigurera NATS-anslutningen baserat på kraven och konventionerna i projektet.

Använda en anslutningssträng

Ange namnet på anslutningssträngen när du anropar builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration:

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

Mer information om hur du formaterar anslutningssträngen finns i ConnectionString-dokumentationen.

Använda konfigurationsprovidrar

.NET Aspire NATS-integreringen stöder Microsoft.Extensions.Configuration. Den läser in NatsClientSettings från konfigurationen med hjälp av Aspire:Nats:Client-nyckeln. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

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

Det fullständiga NATSclient integrationsschemat JSON finns i Aspire.NATS.Net/ConfigurationSchema.json.

Använd inline-delegeringar

Skicka Action<NatsClientSettings> configureSettings-ombudet för att konfigurera vissa eller alla alternativ infogade, till exempel för att inaktivera hälsokontroller från kod:

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

NATS i .NET Aspire-manifestet

NATS ingår inte i .NET Aspiredistributionsmanifestet. Vi rekommenderar att du konfigurerar en säker produktionsmiljö NATSserver utanför .NET Aspire.

Client hälsokontroller för integrering

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Integreringen .NET AspireNATS hanterar följande:

Integrerar med /health HTTP-slutpunkten, som anger att alla registrerade hälsokontroller måste klara för att appen ska anses vara redo att acceptera trafik.

Observerbarhet och telemetri

.NET .NET Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i översikten över .NET.NET Aspire integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

.NET Aspire NATS-integreringen använder följande loggkategorier:

NATS

Spårning

Integreringen .NET AspireNATS genererar följande spårningsaktiviteter:

NATS.Net

Dela via