Aspire NATS integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

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

Integrering av värdtjänster

NATS värdintegrering för Aspire modellerar en NATS server 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.

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 NATS serverresurs

I Ditt AppHost-projekt anropar du AddNats instansen builder för att lägga till en NATS serverresurs:

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 Aspire lägger till en containeravbildning i AppHost, som visas i föregående exempel med docker.io/library/nats-avbildningen, skapas en ny NATS-serverinstans på din lokala dator. En referens till NATS-servern (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.

Lägga till NATS serverresurs med JetStream

Om du vill lägga till NATS JetStream- till NATS-serverresursen 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.

Lägga till NATS serverresurs med autentiseringsparametrar

När du uttryckligen vill ange användarnamn och lösenord kan du ange dem som parametrar. Tänk dig följande alternativa exempel:

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

Mer information finns i externa parametrar.

Lägga till NATS serverresurs med datavolym

Om du vill lägga till en datavolym i NATS-serverresursen anropar du metoden WithDataVolume på NATS serverresursen:

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 NATS serverdata utanför containerns livscykel. Datavolymen monteras på sökvägen /var/lib/nats i NATS-servercontainern. 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 NATS serverresurs med databindningspunkt

Om du vill lägga till en databindningsmontering till NATS-serverresursen 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...

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara NATS serverdata mellan omstarter av containrar. Databindningsmontering monteras på C:\NATS\Data på Windows (eller /NATS/Data på Unix) på värddatorn i NATS-servercontainern. Mer information om databindningar kan du hitta i Docker Dokumentation: Bindmonteringar.

Hälsokontroller för hostning av integrationer

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

Värdintegreringen förlitar sig på 📦 AspNetCore.HealthChecks.Nats NuGet-paketet.

Client integration

Kom igång med AspireNATS-klientintegrering genom att installera 📦Aspire.NATS.Net NuGet-paket i det klientkrävande projektet, dvs. projektet för det program som använder NATS-klienten. NATS-klientintegrering registrerar en INatsConnection- instans som du kan använda för att interagera med NATS.

dotnet add package Aspire.NATS.Net

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

Lägg till NATS klient

I Program.cs-filen för ditt klientanvändande projekt anropar du tilläggsmetoden AddNatsClient på alla IHostApplicationBuilder för att registrera en INatsConnection för användning via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddNatsClient(connectionName: "nats");

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

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nycklad NATS-klient

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

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

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 NATS klientintegreringsschemat JSON finns i Aspire.NATS.Net/ConfigurationSchema.json.

Använda namngiven konfiguration

Integreringen AspireNATS stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma resurstyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under huvudkonfigurationsavsnittet.

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

I det här exemplet kan anslutningsnamnen nats1 och nats2 användas när du anropar AddNatsClient:

builder.AddNatsClient("nats1");
builder.AddNatsClient("nats2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

Använd inline-delegeringar

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

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

NATS i Aspire-manifestet

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

Client hälsokontroller för integrering

Integreringar aktiverar som standard Aspirehälsokontroller för alla tjänster. Mer information finns i Aspire översikten över integreringar.

Integreringen 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

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 Aspire översikten över 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

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

• NATS

Spårning

Integreringen AspireNATS genererar följande spårningsaktiviteter:

• NATS.Net

Se även

• NATS.Net-snabbstart
• Aspire Integrationer
• Aspire GitHub Repo