Aspire Community Toolkit och RavenDB-integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

RavenDB är en högpresterande NoSQL-databas med öppen källkod som är utformad för snabb, effektiv och skalbar datalagring. Den stöder avancerade funktioner som ACID-transaktioner, distribuerad datareplikering och datahantering i tidsserier, vilket gör det till ett utmärkt val för modern programutveckling. Med Aspire RavenDB-integreringen kan du ansluta till befintliga RavenDB-instanser eller skapa nya instanser från .NETatt använda docker.io/library/ravendb containeravbildning.

Integrering av värdtjänster

RavenDB-värdintegrering modellerar servern som RavenDBServerResource typ och databas som RavenDBDatabaseResource typ. Om du vill komma åt dessa typer och API:er lägger du till 📦 CommunityToolkit.Aspire. Hosting.RavenDB NuGet-paketet i AppHost-projektet .

dotnet add package CommunityToolkit.Aspire.Hosting.RavenDB

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

Mer information finns i dotnet lägg till paket eller Hantera paketberoenden i .NET applikationer.

Lägga till RavenDB-serverresurs och databasresurs

Om du vill konfigurera RavenDB i ditt AppHost-projekt anropar du någon av tilläggsmetoderna AddRavenDB på instansen builder för att lägga till en RavenDB-serverresurs och anropar AddDatabase sedan serverresursen för att lägga till en databas. Här är ett exempel:

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

När Aspire en containeravbildning läggs till i AppHost, som du ser i föregående exempel med avbildningen docker.io/ravendb/ravendb , skapas en ny RavenDB-instans på den lokala datorn. En referens till din RavenDB-databasresurs (variabeln ravendb ) läggs till i ExampleProject.

Mer information finns i Livscykel för containerresurser.

Lägga till RavenDB-serverresurs med datavolym

Om du vill lägga till en datavolym i RavenDB-serverresursen Aspire.Hosting.RavenDBBuilderExtensions.WithDataVolume anropar du metoden på RavenDB-serverresursen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Datavolymen förblir tillgänglig när containerns livscykel har upphört, vilket bevarar RavenDB-data. Datavolymen monteras vid /var/lib/ravendb/data sökvägen i RavenDB-containern och när en name parameter inte anges genereras namnet slumpmässigt. Mer information om datavolymer och om varför de föredras framför bind mountsfinns i Docker dokument: Volymer.

Lägg till RavenDB-serverresurs med databindningsmontering

Om du vill lägga till en databindningsmontering till RavenDB-serverresursen Aspire.Hosting.RavenDBBuilderExtensions.WithDataBindMount anropar du metoden:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara RavenDB-data mellan omstarter av containrar. Databindningsmonteringen C:\RavenDb\Data monteras på sökvägen på Windows (eller /RavenDB/Data på Unix) på värddatorn i RavenDB-containern. Mer information om bindningspunkter för data finns i Docker dokumentation: Bindningspunkter.

Lägg till en skyddad RavenDB-serverresurs

Om du vill skapa en ny skyddad RavenDB-instans med hjälp av inställningar från en förkonfigurerad settings.json-fil eller ett självsignerat certifikat använder du RavenDBServerSettings.Secured metoden eller RavenDBServerSettings.SecuredWithLetsEncrypt för Let's Encrypt-konfigurationer. Med de här metoderna kan du ange domänens URL, certifikatinformation och ytterligare serverinställningar. Här är ett exempel på hur du lägger till en skyddad RavenDB-serverresurs med hjälp av 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);

Utför hälsokontroller för integration

RavenDB-värdintegreringen lägger automatiskt till en hälsokontroll för RavenDB-serverresursen och verifierar att servern körs och är åtkomlig.

Värdintegrationen förlitar sig på 📦 NuGet-paketet AspNetCore.HealthChecks.RavenDB.

Client integration

Kom igång med Aspire RavenDB-klientintegrering genom att 📦 installera CommunityToolkit.Aspire. RavenDB.Client NuGet-paketet i det klientkrävande projektet, dvs. projektet för programmet som använder RavenDB-klienten. RavenDB-klientintegrering registrerar en IDocumentStore-instans , som fungerar som startpunkt för att interagera med RavenDB-serverresursen eller en befintlig RavenDB-instans. Om din AppHost innehåller RavenDB-databasresurser registreras även associerade IDocumentSession - och IAsyncDocumentSession-instanser för beroendeinmatning.

dotnet add package CommunityToolkit.Aspire.RavenDB.Client

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

Lägg till RavenDB-klient

I Program.cs-filen för ditt klientkonsumerande projekt anropar du Microsoft.Extensions.Hosting.RavenDBClientExtension.AddRavenDBClient-tilläggsmetoden på valfri IHostApplicationBuilder för att registrera en IDocumentStore för användning via beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddRavenDBClient(connectionName: "ravendb");

Du kan sedan hämta instansen IDocumentStore genom beroendeinjektion. Om du till exempel vill hämta klienten från en exempeltjänst:

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

Lägg till RavenDB-klient med hjälp av RavenDBClientSettings

Metoden AddRavenDBClient innehåller överlagringar som accepterar ett RavenDBClientSettings objekt. På så sätt kan du använda klientintegrering oberoende av värdintegrering. Klassen RavenDBClientSettings innehåller de parametrar som behövs för att upprätta en anslutning. Mer information om tillgängliga konfigurationsalternativ finns i avsnittet Konfigurationsalternativ nedan.

Här är ett exempel:

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

builder.AddRavenDBClient(settings: settings);

Efter registreringen kan du hämta instansen IDocumentStore och dess associerade IDocumentSession instanser och IAsyncDocumentSession instanser på följande sätt:

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

Lägg till nyckelkonfigurerad RavenDB-klient

Om programmet kräver flera IDocumentStore instanser med olika anslutningskonfigurationer kan du registrera nyckelade RavenDB-klienter med hjälp av Microsoft.Extensions.Hosting.RavenDBClientExtension.AddKeyedRavenDBClient tilläggsmetoden:

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

Sedan kan du hämta IDocumentStore-instans genom dependency injection. Om du till exempel vill hämta en anslutning från en exempeltjänst:

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

Mer information om nyckeltjänster finns i .NET beroendeinjektion: Nyckeltjänster.

Konfiguration

Aspire RavenDB-integreringen Client innehåller flera konfigurationsmetoder och alternativ för att uppfylla kraven och konventionerna i ditt projekt.

Använda en anslutningssträng

När du använder en anslutningssträng från konfigurationsavsnittet ConnectionStrings anger du namnet på anslutningssträngen när du anropar builder.AddRavenDBClient:

builder.AddRavenDBClient("ravendb");

Anslutningssträngen hämtas från konfigurationsavsnittet ConnectionStrings :

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

Använda konfigurationsprovidrar

RavenDB-integrationen Aspire stöder Microsoft.Extensions.Configuration. Den läser in RavenDBClientSettings från konfigurationen med hjälp av Aspire:RavenDB:Client nyckeln. Överväg följande exempel appsettings.json som konfigurerar några av alternativen:

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

Använd inline-konfigurationer

Du kan också använda Action<RavenDBClientSettings> delegate för att konfigurera några eller alla alternativ direkt:

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

Konfigurationsalternativ

Aspire RavenDB-klientintegreringen ger flexibla konfigurationsalternativ via RavenDBClientSettings klassen så att du kan skräddarsy anslutningen till projektets krav. Här är de viktigaste egenskaperna:

Client hälsokontroller för integrering

Aspire RavenDB-klientintegrering använder den konfigurerade klienten för att utföra en IsHealthyAsync. Om resultatet är trueanses hälsokontrollen vara hälsosam, annars är den ohälsosam. På samma sätt, om det finns ett undantag, anses hälsokontrollen vara ohälsosam och felet sprids genom hälsokontrollens misslyckande.

Se även

• RavenDB
• RavenDB-guide Dockerfile
• RavenDB-kod
• AspireCommunity Toolkit-repoGitHub