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 voor .NET Aspire modellen een NATSserver als het type NatsServerResource. Installeer de 📦Aspireom toegang te krijgen tot dit type. Gastvrijheid.Nats NuGet-pakket in de app-host project en voeg het vervolgens toe aan de opbouwfunctie.

dotnet add package Aspire.Hosting.Nats

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

NATS server-resource toevoegen

Roep in uw app-hostproject AddNats aan op het builder exemplaar om een NATSserver-resource 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 wordt weergegeven in het vorige voorbeeld met de docker.io/library/nats-installatiekopie, wordt er een nieuw NATSserver exemplaar op uw lokale computer gemaakt. Er wordt een verwijzing naar uw NATSserver (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 NATSserver, roept u in plaats daarvan AddConnectionString aan. Voor meer informatie, zie Raadpleeg bestaande bronnen.

NATS server resource toevoegen met JetStream

Als u de NATS JetStream- wilt toevoegen aan de NATSserver-resource, 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 server bron toevoegen met gegevensvolume

Als u een gegevensvolume wilt toevoegen aan de NATSserver-resource, roept u de WithDataVolume methode aan voor de NATSserver-resource:

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 NATSserver gegevens buiten de levenscyclus van de container te behouden. Het gegevensvolume wordt gekoppeld aan het /var/lib/nats pad in de NATSserver container. Er wordt willekeurig een naam gegenereerd, tenzij u de name parameter opgeeft. Zie Dockervoor meer informatie over gegevensvolumes en details over waarom ze de voorkeur hebben boven bindingskoppelingen.

NATS server resource toevoegen met gegevensbinding koppelen

Als u een koppeling voor gegevensbinding wilt toevoegen aan de NATSserver-resource, 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.

Gegevensbind-mounts vertrouwen op het bestandssysteem van de hostmachine om de NATSserver gegevens bij het opnieuw opstarten van de container te behouden. De koppeling voor gegevensbinding wordt gekoppeld aan de C:\NATS\Data in Windows (of /NATS/Data op Unix) pad op de hostcomputer in de NATSserver container. Zie Docker docs: Bindingskoppelingenvoor meer informatie over koppelingskoppelingen voor gegevens.

Gezondheidscontroles voor hostingintegratie

De NATS hostingintegratie voegt automatisch een statuscontrole toe voor de NATSserver resource. De gezondheidscontrole verifieert of de NATSserver actief is en of er een verbinding tot stand kan worden gebracht.

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

integratie van Client

Installeer de .NET AspireNATSom aan de slag te gaan met de client📦Aspire-integratie.NATS.Net NuGet-pakket in het clientverbruikende project, namelijk het project voor de toepassing die gebruikmaakt van de NATSclient. De NATSclient-integratie registreert een exemplaar van INatsConnection dat u kunt gebruiken om met NATSte communiceren.

dotnet add package Aspire.NATS.Net

NATS client toevoegen

Roep in het Program.cs-bestand van uw project dat clientverbruikt 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 NATSserver resource in het app-hostproject. Zie NATSserver resource toevoegenvoor meer informatie.

Vervolgens kunt u het INatsConnection exemplaar ophalen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de client wilt ophalen uit een service:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET afhankelijkheidsinjectie.

Voeg sleutel NATSclient toe

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

Voor het complete NATSclient integratie JSON schema, zie 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 aanbevolen een veilige productieomgeving NATSserver buiten .NET Aspireop te zetten.

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