integración .NET AspireNATS
incluye: integración de hospedaje de
e integración de Client
NATS es un sistema de mensajería distribuido de alto rendimiento y seguro. La integración de .NET AspireNATS permite conectarse a instancias de NATS existentes o crear nuevas instancias a partir de .NET con la imagen de contenedor docker.io/library/nats.
Integración de hospedaje
NATS la integración de hospedaje para .NET Aspire modela un servidor NATS como tipo de NatsServerResource. Para acceder a este tipo de acceso, instale el paquete NuGet 📦Aspire.Hosting.Nats en el proyecto de host de la aplicación y luego agréguelo al constructor.
dotnet add package Aspire.Hosting.Nats
Para obtener más información, consulte dotnet add package o Administrar las dependencias del paquete en las aplicaciones .NET.
Agregar NATS recurso de servidor
En el proyecto host de la aplicación, llame a AddNats en la instancia de builder para agregar un recurso de servidor NATS:
var builder = DistributedApplication.CreateBuilder(args);
var nats = builder.AddNats("nats");
builder.AddProject<Projects.ExampleProject>()
.WithReference(nats);
// After adding all resources, run the app...
Cuando .NET.NET Aspire agrega una imagen de contenedor al host de la aplicación, como se muestra en el ejemplo anterior con la imagen de docker.io/library/nats, crea una nueva instancia de servidor NATS en el equipo local. Se agrega una referencia al servidor de NATS (la variable nats) al ExampleProject.
El método WithReference configura una conexión en el ExampleProject denominado "nats". Para obtener más información, consulte ciclo de vida de los recursos de contenedor.
Propina
Si prefiere conectarse a un servidor NATS existente, llame a AddConnectionString en su lugar. Para obtener más información, vea Hacer referencia a los recursos existentes.
Adición de un recurso de servidor de NATS con JetStream
Para agregar el NATS JetStream al recurso del servidor NATS, llame al método WithJetStream.
var builder = DistributedApplication.CreateBuilder(args);
var nats = builder.AddNats("nats");
.WithJetStream();
builder.AddProject<Projects.ExampleProject>()
.WithReference(nats);
// After adding all resources, run the app...
La funcionalidad NATS JetStream proporciona un motor de persistencia integrado denominado JetStream que permite almacenar y reproducir mensajes más adelante.
Agregar NATS recurso de servidor con parámetros de autenticación
Si desea proporcionar explícitamente el nombre de usuario y la contraseña, puede proporcionarlos como parámetros. Considere el siguiente ejemplo alternativo:
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...
Para obtener más información, vea Parámetros externos.
Agregar NATS recurso de servidor con volumen de datos
Para agregar un volumen de datos al recurso del servidor de NATS, llame al método WithDataVolume en el recurso del servidor de NATS:
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...
El volumen de datos se usa para conservar los datos del servidor de NATS fuera del ciclo de vida de su contenedor. El volumen de datos está montado en la ruta /var/lib/nats dentro del contenedor NATS. Un nombre se genera de forma aleatoria a menos que proporcione un conjunto del parámetro name. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren sobre los bind mounts, consulte la Docker documentación: Volúmenes.
Añadir el recurso del servidor NATS con montaje enlazado de datos
Para agregar un punto de montaje de datos al recurso de NATS del servidor, llame al método WithDataBindMount.
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...
Importante
Los montajes de unión de datos tienen una funcionalidad limitada en comparación con los volúmenes, los cuales ofrecen un mejor rendimiento, portabilidad y seguridad, lo que los hace más adecuados para entornos de producción. Sin embargo, los montajes de unión permiten el acceso directo y la modificación de archivos en el sistema host, lo cual es ideal para el desarrollo y las pruebas donde se requieren cambios en tiempo real.
Los montajes de vinculación de datos dependen del sistema de archivos del equipo host para conservar los datos del servidor de NATS a través de los reinicios de los contenedores. El montaje de datos en modo bind se monta en la carpeta C:\NATS\Data en Windows (o en la carpeta /NATS/Data en Unix) en la máquina anfitriona dentro del contenedor del servidor NATS. Para obtener más información sobre los montajes de enlace de datos, consulte Docker documentos: Enlazar montajes.
Comprobaciones de salud de integración de hospedaje
La integración de hospedaje de NATS agrega automáticamente una comprobación de estado para el recurso del servidor de NATS. La comprobación de estado comprueba que el NATS servidor se está ejecutando y que se puede establecer una conexión a él.
La integración de alojamiento depende del paquete NuGet AspNetCore.HealthChecks.Nats 📦.
Client integración
Para empezar a trabajar con la integración del cliente de .NET AspireNATS, instale el paquete NuGet de .Net 📦Aspire.NATS en el proyecto que utiliza el cliente, es decir, el proyecto de la aplicación que usa el cliente de NATS. La integración de cliente NATS registra una instancia de INatsConnection que puede usar para interactuar con NATS.
dotnet add package Aspire.NATS.Net
Agregar cliente NATS
En el archivo Program.cs del proyecto que consume el cliente, llame al método de extensión AddNatsClient en cualquier IHostApplicationBuilder para registrar un INatsConnection para su uso a través del contenedor de inserción de dependencias. El método toma un parámetro de nombre de conexión.
builder.AddNatsClient(connectionName: "nats");
Propina
El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso de servidor NATS en el proyecto host de la aplicación. Para obtener más información, consulte Añadir NATS recurso de servidor.
A continuación, puede recuperar la instancia de INatsConnection mediante la inyección de dependencias. Por ejemplo, para recuperar el cliente de un servicio:
public class ExampleService(INatsConnection connection)
{
// Use connection...
}
Para obtener más información sobre la inserción de dependencias, consulte .NET inserción de dependencias.
Adición de un cliente de NATS con clave
Puede haber situaciones en las que quiera registrar varias instancias de INatsConnection con nombres de conexión diferentes. Para registrar clientes de NATS con clave, llame al método AddKeyedNatsClient:
builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");
A continuación, puede recuperar las instancias de IConnection mediante la inyección de dependencias. Por ejemplo, para recuperar la conexión de un servicio de ejemplo:
public class ExampleService(
[FromKeyedServices("chat")] INatsConnection chatConnection,
[FromKeyedServices("queue")] INatsConnection queueConnection)
{
// Use connections...
}
Para obtener más información sobre los servicios con claves, consulte .NET inserción de dependencias: Servicios con claves.
Configuración
La integración de .NET AspireNATS proporciona varias opciones para configurar la conexión NATS en función de los requisitos y convenciones del proyecto.
Uso de una cadena de conexión
Proporcione el nombre de la cadena de conexión al llamar a builder.AddNatsClient:
builder.AddNatsClient(connectionName: "nats");
La cadena de conexión se obtiene de la sección de configuración del ConnectionStrings.
{
"ConnectionStrings": {
"nats": "nats://nats:4222"
}
}
Consulte la documentación de ConnectionString para obtener más información sobre cómo dar formato a esta cadena de conexión.
Uso de proveedores de configuración
La integración .NET AspireNATS admite Microsoft.Extensions.Configuration. Carga el NatsClientSettings desde la configuración usando la clave Aspire:Nats:Client. El fragmento de código siguiente es un ejemplo de un archivo appsettings.json que configura algunas de las opciones:
{
"Aspire": {
"Nats": {
"Client": {
"ConnectionString": "nats://nats:4222",
"DisableHealthChecks": true,
"DisableTracing": true
}
}
}
}
Para obtener el esquema completo de integración de cliente NATSJSON, consulte Aspire.NATS.Net/ConfigurationSchema.json.
Use delegados en línea
Pase el delegado Action<NatsClientSettings> configureSettings para configurar algunas o todas las opciones en línea, por ejemplo, para deshabilitar las comprobaciones de estado a través del código.
builder.AddNatsClient(
"nats",
static settings => settings.DisableHealthChecks = true);
NATS en el manifiesto .NET Aspire
NATS no está incluido en el .NET Aspiremanifiesto de implementación. Se recomienda configurar un servidor de producción seguro NATS fuera de .NET Aspire.
chequeos de salud en la integración de Client
De forma predeterminada, las integraciones .NET.NET Aspire habilitan comprobaciones de estado para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.
La integración de .NET AspireNATS controla lo siguiente:
- Se integra con el punto de conexión HTTP de
/health, que especifica que todas las comprobaciones de estado registradas deben pasar para que la aplicación se considere lista para aceptar el tráfico.
Observabilidad y telemetría
.NET .NET Aspire integraciones establecen automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las características de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.
Registro
La integración de .NET AspireNATS usa las siguientes categorías de registro:
NATS
Rastreo
La integración de .NET AspireNATS emite las siguientes actividades de rastreo:
NATS.Net
