Delen via

integratie van .NET AspireNATS

  • Artikel

omvat:hosting-integratie en Client integratie

NATS is een krachtige, veilige, gedistribueerde berichtensysteem. Met de .NET 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 .NET Aspire-modellen een NATS-server als type NatsServerResource. Om toegang te krijgen tot dit type, installeer het 📦Aspire.Hosting.Nats NuGet-pakket in het app-host project en voeg het vervolgens toe met de builder.

dotnet add package Aspire.Hosting.Nats

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

NATS serverresource toevoegen

Roep in uw app-hostproject AddNats aan op het builder exemplaar 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 .NET.NET Aspire een containerinstallatiekopie toevoegt aan de app-host, zoals weergegeven in het vorige voorbeeld met de docker.io/library/nats-installatiekopie, wordt er een nieuwe 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.

Tip

Als u liever verbinding wilt maken met een bestaande NATS-server, roept u in plaats daarvan AddConnectionString aan. Voor meer informatie, zie Raadpleeg bestaande bronnen.

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. U kunt desgewenst een srcMountPath parameter opgeven om het pad naar de JetStream-gegevensmap op de hostcomputer op te geven (het opgegeven koppelingspad wordt toegewezen aan het -sd argument van de container).

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 gegevensvolumes en details over waarom ze de voorkeur hebben boven Docker.

NATS serverbron toevoegen met 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...

Belangrijk

Gegevens koppelen beperkte functionaliteit hebben in vergelijking met volumes, die betere prestaties, draagbaarheid en beveiliging bieden, waardoor ze geschikter zijn voor productieomgevingen. Bind mounts bieden echter directe toegang en mogelijkheid tot wijziging van bestanden op het hostsysteem, ideaal voor ontwikkeling en testen waar realtime wijzigingen nodig zijn.

Gegevensbindmontages zijn afhankelijk van het bestandssysteem van de hostmachine om de NATS-servergegevens bij herstarten van de container te behouden. De data-bindmount wordt op de hostcomputer gekoppeld aan het pad C:\NATS\Data in Windows (of /NATS/Data op Unix) binnen de server container van de NATS. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Gezondheidscontroles voor hostingintegratie

De NATS hostingintegratie voegt automatisch een statuscontrole toe voor de NATS serverresource. Controleert of de NATS-server draait en of er een verbinding tot stand kan worden gebracht.

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

integratie van Client

Installeer het Aspire NuGet-pakket in het project dat de NATS-client gebruikt om aan de slag te gaan met de NATS-clientintegratie. De NATS-clientintegratie registreert een INatsConnection--exemplaar dat u kunt gebruiken om met NATSte communiceren.

dotnet add package Aspire.NATS.Net

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");

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de NATS serverresource in het hostproject van de app. Zie NATS serverresource toevoegenvoor meer informatie.

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

Inline delegates gebruiken

Geef de Action<NatsClientSettings> configureSettings gedelegeerde door om bepaalde of alle opties inline in te stellen, bijvoorbeeld om statuscontroles uit code uit te schakelen:

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

NATS in het .NET Aspire-manifest

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

gezondheidscontroles voor Client-integratie

Standaard kunnen .NET.NET Aspire integraties statuscontroles voor alle services inschakelen. Zie .NET.NET Aspire overzicht van integratiesvoor meer informatie.

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

.NET .NET Aspire integraties automatisch configuraties voor logboekregistratie, tracering en metrische gegevens instellen, die ook wel bekend staan als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. 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 .NET AspireNATS-integratie maakt gebruik van de volgende logboekcategorieën:

  • NATS

Traceren

De .NET AspireNATS-integratie verzendt de volgende traceringsactiviteiten:

  • NATS.Net

Zie ook