.NET .NET Aspire Integración de RavenDB con el kit de herramientas comunitario

Incluye: Integración de alojamiento —&— Client integración

RavenDB es una base de datos NoSQL de código abierto de alto rendimiento diseñada para el almacenamiento de datos rápido, eficaz y escalable. Admite características avanzadas, como transacciones ACID, replicación de datos distribuidos y administración de datos de serie temporal, lo que lo convierte en una excelente opción para el desarrollo de aplicaciones modernas. La .NET Aspire integración de RavenDB permite conectarse a instancias existentes de RavenDB o crear nuevas instancias desde .NET usando la imagen de contenedor docker.io/library/ravendb.

Integración de hospedaje

La integración de hospedaje de RavenDB modeliza el servidor como de tipo RavenDBServerResource y la base de datos como de tipo RavenDBDatabaseResource. Para acceder a estos tipos y API, agregue el paquete NuGet CommunityToolkit📦.Aspire.Hosting.RavenDB en el proyecto host de la aplicación.

dotnet add package CommunityToolkit.Aspire.Hosting.RavenDB

<PackageReference Include="CommunityToolkit.Aspire.Hosting.RavenDB"
                  Version="*" />

Para obtener más información, consulte dotnet add package o Administrar las dependencias de paquetes en las aplicaciones .NET.

Adición de recursos de servidor de RavenDB y recurso de base de datos

Para configurar RavenDB en el proyecto host de la aplicación, llame a uno de los AddRavenDB métodos de extensión de la builder instancia para agregar un recurso de servidor RavenDB y, a continuación, llame a AddDatabase en el recurso de servidor para agregar una base de datos. Este es un ejemplo:

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer");
var ravendb = ravenServer.AddDatabase("ravendb");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravendb)
       .WaitFor(ravendb);

// After adding all resources, build and 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 docker.io/ravendb/ravendb, se crea una nueva instancia de RavenDB en su equipo local. Se agrega una referencia al recurso de base de datos RavenDB (la ravendb variable) a ExampleProject.

Para obtener más información, consulte ciclo de vida de los recursos de contenedores.

Adición de un recurso de servidor RavenDB con volumen de datos

Para agregar un volumen de datos al recurso del servidor RavenDB, llame al Aspire.Hosting.RavenDBBuilderExtensions.WithDataVolume método en el recurso del servidor RavenDB:

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
                         .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravenServer)
       .WaitFor(ravenServer);

El volumen de datos permanece disponible después de que finalice el ciclo de vida del contenedor, conservando los datos de RavenDB. El volumen de datos se monta en la /var/lib/ravendb/data ruta de acceso del contenedor RavenDB y, cuando no se proporciona un name parámetro, el nombre se genera aleatoriamente. Para obtener más información sobre los volúmenes de datos y los detalles sobre por qué se prefieren a bind mounts, consulte la Docker documentación: Volúmenes.

Adición de un recurso de servidor RavenDB con montaje de enlace de datos

Para agregar un montaje de vínculos de datos al recurso del servidor RavenDB, llame al método Aspire.Hosting.RavenDBBuilderExtensions.WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var ravenServer = builder.AddRavenDB("ravenServer")
                         .WithDataBindMount(source: @"C:\RavenDb\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravenServer)
       .WaitFor(ravenServer);

Los montajes de vinculación de datos dependen del sistema de archivos del equipo anfitrión para mantener los datos de RavenDB durante los reinicios del contenedor. El montaje del enlace de datos se monta en la C:\RavenDb\Data ruta de acceso en Windows (o /RavenDB/Data en Unix) en la máquina host del contenedor RavenDB. Para obtener más información sobre los montajes vinculados de datos, consulte la documentación Docker: Montajes vinculados.

Adición de un recurso de servidor RavenDB protegido

Para crear una nueva instancia de RavenDB protegida mediante la configuración de un archivo desettings.json preconfigurado o un certificado autofirmado, use el RavenDBServerSettings.Secured método o RavenDBServerSettings.SecuredWithLetsEncrypt para las configuraciones Let's Encrypt. Estos métodos permiten especificar la dirección URL del dominio, los detalles del certificado y la configuración adicional del servidor. Este es un ejemplo de cómo agregar un recurso de servidor RavenDB protegido mediante Let's Encrypt:

var builder = DistributedApplication.CreateBuilder(args);

var serverSettings = RavenDBServerSettings.SecuredWithLetsEncrypt(
    domainUrl: "https://mycontainer.development.run",
    certificatePath: "/etc/ravendb/security/cluster.server.certificate.mycontainer.pfx");

var ravendb = builder.AddRavenDB("ravenSecuredServer", serverSettings)
    .WithBindMount("C:/RavenDB/Server/Security", "/etc/ravendb/security", false)
    .AddDatabase("ravendbSecured");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(ravendb)
       .WaitFor(ravendb);

Comprobaciones de estado de la integración de hospedaje

La integración de hospedaje de RavenDB agrega automáticamente una comprobación de estado para el recurso del servidor RavenDB, comprobando que el servidor se está ejecutando y es accesible.

La integración de hospedaje se basa en el 📦 paquete NuGet AspNetCore.HealthChecks.RavenDB .

integración Client

Para empezar a trabajar con la .NET.NET Aspire integración del cliente de RavenDB, instale el 📦 CommunityToolkit.Aspire.RavenDB.Client paquete NuGet en el proyecto que utiliza el cliente, es decir, el proyecto de la aplicación que utiliza el cliente RavenDB. La integración de cliente de RavenDB registra una instancia de IDocumentStore , que actúa como punto de entrada para interactuar con el recurso del servidor RavenDB o una instancia de RavenDB existente. Si el host de la aplicación incluye recursos de base de datos de RavenDB, las instancias de IDocumentSession e IAsyncDocumentSession asociadas también se registran para la inserción de dependencias.

dotnet add package CommunityToolkit.Aspire.RavenDB.Client

<PackageReference Include="CommunityToolkit.Aspire.RavenDB.Client"
                  Version="*" />

Adición de un cliente ravenDB

En el archivo Program.cs de su proyecto que usa el cliente, invoque el método de extensión Microsoft.Extensions.Hosting.RavenDBClientExtension.AddRavenDBClient en cualquier IHostApplicationBuilder para registrar un IDocumentStore a utilizar mediante el contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

builder.AddRavenDBClient(connectionName: "ravendb");

A continuación, puede recuperar la instancia IDocumentStore usando la inyección de dependencias. Por ejemplo, para recuperar el cliente de un servicio de ejemplo:

public class ExampleService(IDocumentStore client)
{
    // Use client...
}

Adición de un cliente ravenDB mediante RavenDBClientSettings

El AddRavenDBClient método proporciona sobrecargas que aceptan un RavenDBClientSettings objeto . Esto le permite usar la integración de cliente independientemente de la integración de hospedaje. La RavenDBClientSettings clase contiene los parámetros necesarios para establecer una conexión. Puede encontrar más detalles sobre las opciones de configuración disponibles en la sección Opciones de configuración siguiente.

Este es un ejemplo:

var settings = new RavenDBClientSettings
{
    Urls = new[] { serverUrl },
    DatabaseName =  myDatabaseName,
    Certificate = myCertificate
};

builder.AddRavenDBClient(settings: settings);

Después del registro, puede recuperar la IDocumentStore instancia y sus instancias asociadas IDocumentSession e IAsyncDocumentSession como se indica a continuación:

var documentStore = host.Services.GetRequiredService<IDocumentStore>();
var session = host.Services.GetRequiredService<IDocumentSession>();
var asyncSession = host.Services.GetRequiredService<IAsyncDocumentSession>();

Adición de un cliente ravenDB con clave

Si la aplicación requiere varias IDocumentStore instancias con distintas configuraciones de conexión, puede registrar clientes de RavenDB con claves mediante el método de Microsoft.Extensions.Hosting.RavenDBClientExtension.AddKeyedRavenDBClient extensión:

builder.AddKeyedRavenDBClient(serviceKey: "production", connectionName: "production");
builder.AddKeyedRavenDBClient(serviceKey: "testing", connectionName: "testing");

A continuación, puede recuperar las instancias de IDocumentStore usando inyección de dependencias. Por ejemplo, para recuperar una conexión de un servicio de ejemplo:

public class ExampleService(
    [FromKeyedServices("production")] IDocumentStore production,
    [FromKeyedServices("testing")] IDocumentStore testing)
{
    // Use databases...
}

Para obtener más información sobre los servicios con clave, consulte .NET Inserción de Dependencias: Servicios con Clave.

Configuración

La .NET Aspire integración de RavenDB Client proporciona varios enfoques y opciones de configuración para cumplir los requisitos y convenciones del proyecto.

Uso de una cadena de conexión

Al usar una cadena de conexión de la ConnectionStrings sección de configuración, proporcione el nombre de la cadena de conexión al llamar a builder.AddRavenDBClient:

builder.AddRavenDBClient("ravendb");

La cadena de conexión se recuperará de la ConnectionStrings sección de configuración:

{
  "ConnectionStrings": {
    "ravendb": "Url=http://localhost:8080/;Database=ravendb"
  }
}

Uso de proveedores de configuración

La .NET.NET Aspire integración de RavenDB admite Microsoft.Extensions.Configuration. Carga la configuración desde RavenDBClientSettings utilizando la clave Aspire:RavenDB:Client. Considere el ejemplo siguiente appsettings.json que configura algunas de las opciones:

{
  "Aspire": {
    "RavenDB": {
      "Client": {
        "ConnectionString": "URL=http://localhost:8080;Database=ravendb",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      }
    }
  }
}

Utilice configuraciones en línea

También puede pasar el delegado de Action<RavenDBClientSettings> para configurar algunas o todas las opciones en línea.

builder.AddRavenDBClient(connectionName: "ravendb", configureSettings: 
    settings => 
    {
        settings.CreateDatabase = true;
        settings.Certificate = myCertificate;
        settings.DisableTracing = true;
    }

Opciones de configuración

La .NET.NET Aspire integración de cliente de RavenDB proporciona opciones de configuración flexibles a través de la RavenDBClientSettings clase , lo que le permite adaptar la conexión a los requisitos del proyecto. Estas son las propiedades clave:

Client verificaciones de estado de la integración

La .NET.NET Aspire integración del cliente de RavenDB utiliza el cliente configurado para llevar a cabo un IsHealthyAsync. Si el resultado es true, la verificación de salud se considera saludable; de lo contrario, se considera no saludable. Del mismo modo, si hay una excepción, la comprobación de estado se considera no saludable y el error se propaga debido al fallo en la comprobación de estado.

Consulte también

• RavenDB
• Ejecución en un Docker contenedor
• Código de RavenDB
• .NET Aspire Repositorio del kit de herramientas de GitHub la comunidad