integratie van .NET AspireNATS
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
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.AddNatsClient
aanroept:
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