Aspire NATS integratie

Inclusief: —&— Client integratie

NATS is een krachtige, veilige, gedistribueerde berichtensysteem. Met de AspireNATS-integratie kunt u verbinding maken met bestaande NATS-exemplaren, of nieuwe exemplaren maken vanuit .NET met de docker.io/library/nats containerafbeelding.

Hostingintegratie

NATS hostingintegratie modelleert voor Aspire-modellen een NATS-server als type NatsServerResource. Als u toegang wilt krijgen tot dit type, installeert u de 📦Aspire. Hosting.Nats NuGet-pakket in het AppHost-project en voeg het vervolgens toe met de opbouwfunctie.

dotnet add package Aspire.Hosting.Nats

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

NATS serverresource toevoegen

Roep in uw AppHost-project AddNats het builder exemplaar aan om een NATS serverresource toe te voegen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Wanneer Aspire een containerafbeelding toevoegt aan de AppHost, zoals wordt weergegeven in het voorgaande voorbeeld met de docker.io/library/nats afbeelding, wordt er een nieuw NATS serverexemplaar gemaakt op uw lokale computer. Er wordt een verwijzing naar de NATS-server (de variabele nats) toegevoegd aan de ExampleProject.

De methode WithReference configureert een verbinding in de ExampleProject met de naam "nats". Zie levenscyclus van containerresourcesvoor meer informatie.

NATS serverresource toevoegen met JetStream

Als u de NATS JetStream- wilt toevoegen aan de NATS-serverresource, roept u de methode WithJetStream aan:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

De NATS JetStream-functionaliteit biedt een ingebouwde persistentie-engine met de naam JetStream, waarmee berichten op een later tijdstip kunnen worden opgeslagen en opnieuw kunnen worden afgespeeld.

NATS serverresource toevoegen met verificatieparameters

Als u expliciet de gebruikersnaam en het wachtwoord wilt opgeven, kunt u deze opgeven als parameters. Bekijk het volgende alternatieve voorbeeld:

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

Zie Externe parametersvoor meer informatie.

NATS serverresource toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de NATS serverresource, roept u de WithDataVolume methode aan op de NATS serverresource:

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

Het gegevensvolume wordt gebruikt om de NATS servergegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/lib/nats pad in de NATS servercontainer. Er wordt willekeurig een naam gegenereerd, tenzij u de name parameter opgeeft. Zie voor meer informatie over volumens en details over waarom ze de voorkeur hebben boven Docker.

NATS serverbron toevoegen met een databind-mount

Als u een gegevensbindingskoppeling wilt toevoegen aan de NATS-serverresource, roept u de methode WithDataBindMount aan:

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

Gegevensbindmontages zijn afhankelijk van het bestandssysteem van de hostmachine om de NATS-servergegevens bij herstarten van de container te behouden. De databind-mount is gekoppeld aan het pad C:\NATS\Data op de host-machine onder Windows (of /NATS/Data op Unix) binnen de NATS servercontainer. Zie Docker docs: Bind mounts voor meer informatie over het koppelen van data met bind mounts.

Gezondheidscontroles voor hostingintegratie

De NATS hostingintegratie voegt automatisch een statuscontrole toe voor de NATS serverresource. De gezondheidscontrole verifieert dat de NATS-server draait en dat er verbinding mee kan worden gemaakt.

De hostingintegratie is afhankelijk van het 📦 AspNetCore.HealthChecks.Nats NuGet-pakket.

Client integratie

Installeer het ..Net NuGet-pakket in het klantproject, dat wil zeggen, het project voor de applicatie die de -client gebruikt, om aan de slag te gaan met de integratie van de -client. De NATS-clientintegratie registreert een INatsConnection--exemplaar dat u kunt gebruiken om met NATSte communiceren.

dotnet add package Aspire.NATS.Net

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

NATS-client toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddNatsClient-extensiemethode aan op elke IHostApplicationBuilder om een INatsConnection te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddNatsClient(connectionName: "nats");

Vervolgens kunt u het INatsConnection exemplaar ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de client op te halen uit een service:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Keyed NATS-client toevoegen

Er kunnen situaties zijn waarin u meerdere INatsConnection exemplaren met verschillende verbindingsnamen wilt registreren. Als u cliënten met sleutel NATS wilt registreren, gebruik dan de methode AddKeyedNatsClient.

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

Vervolgens kunt u de IConnection exemplaren ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de verbinding wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over sleutelservices, zie .NET afhankelijkheidsinjectie: sleutelservices.

Configuratie

De AspireNATS-integratie biedt meerdere opties voor het configureren van de NATS-verbinding op basis van de vereisten en conventies van uw project.

Een verbindingsreeks gebruiken

Geef de naam van de verbindingsreeks op wanneer u builder.AddNatsClientaanroept:

builder.AddNatsClient(connectionName: "nats");

De verbindingsreeks wordt opgehaald uit de ConnectionStrings configuratiesectie:

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

Zie de documentatie ConnectionString voor meer informatie over het opmaken van deze verbindingsreeks.

Configuratieproviders gebruiken

De AspireNATS-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de NatsClientSettings vanuit de configuratie met behulp van de Aspire:Nats:Client-sleutel. Het volgende codefragment is een voorbeeld van een appsettings.json-bestand waarmee een aantal van de opties wordt geconfigureerd:

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

Zie NATSvoor het volledige JSON clientintegratieschema Aspire.NATS.Net/ConfigurationSchema.json.

Benoemde configuratie gebruiken

De AspireNATS integratie ondersteunt benoemde configuratie, waarmee u meerdere exemplaren van hetzelfde resourcetype met verschillende instellingen kunt configureren. De benoemde configuratie maakt gebruik van de verbindingsnaam als een sleutel in het hoofdgedeelte van de configuratie.

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

In dit voorbeeld kunnen de nats1 en nats2 verbindingsnamen worden gebruikt wanneer AddNatsClient wordt aangeroepen:

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

Benoemde configuratie heeft voorrang op de configuratie op het hoogste niveau. Als beide zijn opgegeven, overschrijven de instellingen van de benoemde configuratie de instellingen op het hoogste niveau.

Inline delegates gebruiken

Geef de Action<NatsClientSettings> configureSettings delegate door om bepaalde of alle opties inline in te stellen, bijvoorbeeld om gezondheidscontroles uit code uit te schakelen.

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

NATS in het Aspire-manifest

NATS maakt geen deel uit van het Aspire-implementatiemanifest. Het is raadzaam om een beveiligde productie NATS server buiten Aspirein te stellen.

gezondheidscontroles voor Client-integratie

Aspire Standaard schakelen integraties statuscontroles in voor alle services. Zie Aspire het overzicht van integraties voor meer informatie.

De AspireNATS-integratie verwerkt het volgende:

• Integreert met het /health HTTP-eindpunt, dat specificeert dat alle geregistreerde gezondheidscontroles moeten slagen voordat de app als gereed wordt beschouwd om verkeer te accepteren.

Waarneembaarheid en telemetrie

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De AspireNATS-integratie maakt gebruik van de volgende logboekcategorieën:

• NATS

Traceren

De AspireNATS-integratie verzendt de volgende traceringsactiviteiten:

• NATS.Net

Zie ook

• NATS.Net Quickstart
• Aspire Integraties
• Aspire GitHub Repo