Delen via

integratie van .NET AspireNATS

  • Artikel

Omvat: Hostingintegratie 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.

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 Docker documentatie: Volumes voor meer informatie over volumens en details over waarom ze de voorkeur hebben boven bind mounts.

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

Belangrijk

Bind mounts voor gegevens hebben beperkte functionaliteit vergeleken 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 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

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