Condividi tramite

.NET .NET Aspire Integrazione di Community Toolkit RavenDB

Include:Integrazione di hosting inclusa —&— Client integrazione inclusaClient

Annotazioni

Questa integrazione fa parte di .NET.NET Aspire Community Toolkit e non è ufficialmente supportata dal team .NET.NET Aspire.

RavenDB è un database NoSQL open source ad alte prestazioni progettato per l'archiviazione dati veloce, efficiente e scalabile. Supporta funzionalità avanzate come le transazioni ACID, la replica dei dati distribuiti e la gestione dei dati delle serie temporali, rendendola una scelta eccellente per lo sviluppo di applicazioni moderne. L'integrazione .NET Aspire di RavenDB consente di connettersi alle istanze di RavenDB esistenti o di creare nuove istanze usando .NETl'immagine del contenitore docker.io/library/ravendb.

Integrazione del servizio di hosting

L'integrazione di hosting di RavenDB modella il server come tipo RavenDBServerResource e il database come tipo RavenDBDatabaseResource. Per accedere a questi tipi e API, aggiungere il pacchetto NuGet CommunityToolkit📦.AspireHosting.RavenDB nel progetto host dell'app.

dotnet add package CommunityToolkit.Aspire.Hosting.RavenDB

Per ulteriori informazioni, consultare dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere la risorsa del server RavenDB e la risorsa di database

Per configurare RavenDB nel progetto host dell'app, chiamare uno dei AddRavenDB metodi di estensione nell'istanza builder per aggiungere una risorsa server RavenDB, quindi chiamare AddDatabase sulla risorsa server per aggiungere un database. Ecco un esempio:

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

Importante

È necessaria una licenza Di RavenDB valida. Se non ne hai ancora uno, puoi richiedere una licenza community gratuita qui.

Quando .NET.NET Aspire aggiunge un'immagine contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/ravendb/ravendb , crea una nuova istanza di RavenDB nel computer locale. Viene aggiunto un riferimento alla risorsa di database RavenDB (la ravendb variabile ) a ExampleProject.

Per ulteriori informazioni, vedere Ciclo di vita delle risorse del contenitore.

Aggiungere una risorsa server RavenDB con volume di dati

Per aggiungere un volume di dati alla risorsa server RavenDB, chiamare il metodo nella Aspire.Hosting.RavenDBBuilderExtensions.WithDataVolume risorsa server RavenDB:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Il volume di dati rimane disponibile al termine del ciclo di vita del contenitore, mantenendo i dati di RavenDB. Il volume di dati viene montato al percorso /var/lib/ravendb/data nel contenitore RavenDB e, quando non viene specificato il parametro name, il nome viene generato in modo casuale. Per ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai bind mount , consultare la documentazione Docker: Volumi.

Aggiungere una risorsa server RavenDB con un montaggio dati associato

Per aggiungere un punto di mount di binding dei dati alla risorsa server di RavenDB, chiamare il metodo 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);

Importante

I montaggi di associazione dati hanno funzionalità limitate rispetto ai volumi, che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i bind mount consentono l'accesso e la modifica diretti dei file sul sistema host, rendendoli ideali per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati di RavenDB tra i riavvii del contenitore. L'associazione dati è montata nel percorso C:\RavenDb\Data su Windows (o /RavenDB/Data su Unix) sulla macchina host nel contenitore RavenDB. Per ulteriori informazioni sui bind mount dei dati, consultare la documentazione Docker: Bind mounts.

Aggiungere una risorsa server RavenDB protetta

Per creare una nuova istanza protetta di RavenDB usando le impostazioni di un file disettings.json preconfigurato o un certificato autofirmato, usare il RavenDBServerSettings.Secured metodo o RavenDBServerSettings.SecuredWithLetsEncrypt per le configurazioni Let's Encrypt. Questi metodi consentono di specificare l'URL del dominio, i dettagli del certificato e le impostazioni aggiuntive del server. Ecco un esempio di come aggiungere una risorsa server RavenDB protetta usando 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);

Importante

Verificare che il percorso del certificato sia accessibile al contenitore montandolo tramite un bind-mount su /etc/ravendb/security.

Verifica dell'integrità delle integrazioni di hosting

L'integrazione dell'hosting di RavenDB aggiunge automaticamente un controllo di integrità per la risorsa server RavenDB, verificando che il server sia in esecuzione e raggiungibile.

L'integrazione dell'hosting si basa sul 📦 pacchetto NuGet AspNetCore.HealthChecks.RavenDB .

Client integrazione

Per iniziare a usare l'integrazione .NET.NET Aspire del client RavenDB, installare il pacchetto NuGet 📦 CommunityToolkit.Aspire.RavenDB.Client nel progetto che consuma il client, ovvero il progetto per l'applicazione che utilizza il client RavenDB. L'integrazione del client RavenDB registra un'istanza di IDocumentStore , che funge da punto di ingresso per interagire con la risorsa server RavenDB o un'istanza di RavenDB esistente. Se l'host dell'app include risorse di database RavenDB, anche le istanze IDocumentSession e IAsyncDocumentSession associate vengono registrate per l'iniezione delle dipendenze.

dotnet add package CommunityToolkit.Aspire.RavenDB.Client

Aggiungere il client RavenDB

Nel file Program.cs del progetto cliente, chiamate il metodo di estensione Microsoft.Extensions.Hosting.RavenDBClientExtension.AddRavenDBClient su qualsiasi IHostApplicationBuilder per registrare un IDocumentStore da usare tramite il container per l'inserimento delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddRavenDBClient(connectionName: "ravendb");

Suggerimento

Il connectionName parametro deve corrispondere al nome usato quando si aggiunge la risorsa server RavenDB (o la risorsa di database, se specificata) nel progetto host dell'app. In altre parole, quando si chiama AddDatabase e si specifica un nome di ravendb, lo stesso nome deve essere usato quando si chiama AddRavenDBClient. Per altre informazioni, vedere Aggiungere una risorsa del server RavenDB e una risorsa di database.

È quindi possibile recuperare l'istanza di IDocumentStore usando l'iniezione di dipendenze. Ad esempio, per recuperare il client da un servizio di esempio:

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

Aggiungere il client RavenDB usando RavenDBClientSettings

Il metodo AddRavenDBClient fornisce sovraccarichi che accettano un oggetto RavenDBClientSettings. In questo modo è possibile usare l'integrazione client indipendentemente dall'integrazione dell'hosting. La RavenDBClientSettings classe contiene i parametri necessari per stabilire una connessione. Altre informazioni sulle opzioni di configurazione disponibili sono disponibili nella sezione Opzioni di configurazione di seguito.

Ecco un esempio:

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

builder.AddRavenDBClient(settings: settings);

Annotazioni

Questi metodi sono ideali per connettersi a un'istanza di RavenDB esistente senza basarsi sull'integrazione dell'hosting. Ciò è particolarmente utile se si dispone già di un'istanza autonoma in esecuzione (ad esempio, nel cloud) e si vuole connettersi a tale istanza usando i dettagli specifici.

Dopo la registrazione, è possibile recuperare l'istanza IDocumentStore e le istanze associate IDocumentSession e IAsyncDocumentSession come segue:

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

Aggiungere il client RavenDB con chiave

Se l'applicazione richiede più IDocumentStore istanze con configurazioni di connessione diverse, è possibile registrare i client RavenDB con chiave usando il Microsoft.Extensions.Hosting.RavenDBClientExtension.AddKeyedRavenDBClient metodo di estensione:

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

È quindi possibile ottenere le istanze di IDocumentStore usando la dependency injection. Ad esempio, per recuperare una connessione da un servizio di esempio:

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

Per ulteriori informazioni sui servizi con chiave, consultare la sezione .NET Inserimento delle Dipendenze: Servizi con Chiave.

Configurazione

L'integrazione .NET Aspire di RavenDB Client offre più approcci di configurazione e opzioni per soddisfare i requisiti e le convenzioni del progetto.

Usare una stringa di connessione

Quando si usa una stringa di connessione dalla ConnectionStrings sezione di configurazione, specificare il nome della stringa di connessione quando si chiama builder.AddRavenDBClient:

builder.AddRavenDBClient("ravendb");

La stringa di connessione verrà recuperata dalla ConnectionStrings sezione di configurazione:

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

Utilizzare i fornitori di configurazione

L'integrazione .NET.NET Aspire di RavenDB supporta Microsoft.Extensions.Configuration. Carica il RavenDBClientSettings dalla configurazione usando la chiave Aspire:RavenDB:Client. Si consideri l'esempio seguente appsettings.json che configura alcune delle opzioni:

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

Utilizzare configurazioni inline

È anche possibile passare il delegato Action<RavenDBClientSettings> per configurare alcune o tutte le opzioni in linea.

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

Opzioni di configurazione

L'integrazione .NET.NET Aspire client di RavenDB offre opzioni di configurazione flessibili tramite la RavenDBClientSettings classe , consentendo di personalizzare la connessione ai requisiti del progetto. Ecco le proprietà principali:

Nome Descrizione
Urls URL di connessione (string[]) del cluster RavenDB.
DatabaseName Opzionale. Nome del database RavenDB a cui creare o connettersi.
CertificatePath Opzionale. Percorso del certificato per le istanze di RavenDB protette.
CertificatePassword Opzionale. Password per il certificato, se necessario.
Certificate Opzionale. X509Certificate2 Istanza per le istanze di RavenDB protette.
CreateDatabase Valore booleano che indica se deve essere creato un nuovo database se non esiste già.
ModifyDocumentStore Opzionale. Un Action per modificare l'istanza IDocumentStore.
DisableHealthChecks Valore booleano che indica se il controllo integrità del database è disabilitato o meno.
HealthCheckTimeout Valore int? che indica il timeout del controllo integrità di RavenDB in millisecondi.
DisableTracing Valore booleano che indica se la traccia OpenTelemetry è disabilitata o meno.

Client verifiche di stato dell'integrazione

L'integrazione .NET.NET Aspire del client RavenDB usa il client configurato per eseguire un'operazione IsHealthyAsync. Se il risultato è true, il controllo dello stato di salute è considerato positivo; in caso contrario, è negativo. Analogamente, se si verifica un'eccezione, il controllo dello stato di salute viene considerato non valido e l'errore si propaga attraverso il fallimento del controllo.

Vedere anche