Aspire MongoDB databasintegrering

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

MongoDB är en NoSQL-databas som ger hög prestanda, hög tillgänglighet och enkel skalbarhet. Med integreringen AspireMongoDB kan du ansluta till befintliga MongoDB instanser (inklusive MongoDB Atlas) eller skapa nya instanser från .NET med containeravbildningendocker.io/library/mongo

Värdintegrering

Servern MongoDB som är värd för integration modellerar servern som typ MongoDBServerResource och databasen som typ MongoDBDatabaseResource. Om du vill komma åt dessa typer och API:er lägger du till 📦Aspire. Gästfrihet.MongoDB NuGet-paket i AppHost-projektet .

dotnet add package Aspire.Hosting.MongoDB

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

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET program.

Lägg till MongoDB serverresurs och databasresurs

I ditt AppHost-projekt anropar du AddMongoDB för att lägga till och returnera en MongoDB serverresursbyggare. Länka ett anrop till den returnerade resursbyggaren till AddDatabaseför att lägga till en MongoDB databasresurs.

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithLifetime(ContainerLifetime.Persistent);

var mongodb = mongo.AddDatabase("mongodb");

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

// After adding all resources, 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/library/mongo , skapas en ny MongoDB instans på den lokala datorn. En referens till din MongoDB serverresursbyggare (variabeln mongo) används för att lägga till en databas. Databasen heter mongodb och läggs sedan till i ExampleProject. Den MongoDB serverresursen innehåller standardautentiseringsuppgifter:

• MONGO_INITDB_ROOT_USERNAME: Ett värde av admin.
• MONGO_INITDB_ROOT_PASSWORD: Slumpmässig password genereras med hjälp av metoden CreateDefaultPasswordParameter.

När AppHost körs lagras lösenordet i AppHosts hemliga arkiv. Det läggs till i avsnittet Parameters, till exempel:

{
  "Parameters:mongo-password": "<THE_GENERATED_PASSWORD>"
}

Namnet på parametern är mongo-password, men egentligen är det bara att formatera resursnamnet med ett -password suffix. Mer information finns i Säker lagring av apphemligheter under utveckling i ASP.NET Core och Lägg till MongoDB serverresurs med parametrar.

Metoden WithReference konfigurerar en anslutning i det ExampleProject namngivna mongodb och WaitFor instruerar AppHost att inte starta den beroende tjänsten förrän resursen mongodb är klar.

Lägga till MongoDB serverresurs med datavolym

Om du vill lägga till en datavolym i MongoDB-serverresursen anropar du metoden WithDataVolume på MongoDB serverresursen:

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataVolume();

var mongodb = mongo.AddDatabase("mongodb");

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

// After adding all resources, run the app...

Datavolymen används för att bevara MongoDB serverdata utanför containerns livscykel. Datavolymen monteras på sökvägen /data/db i servercontainern MongoDB och om ingen name-parameter anges genereras namnet slumpvis. Mer information om datavolymer och information om varför de föredras framför bindningsmonteringar finns i Docker dokument: Volymer.

Lägg till MongoDB serverresurs med databindningsmontering

Om du vill lägga till en databindningsmontering till MongoDB-serverresursen anropar du metoden WithDataBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithDataBindMount(@"C:\MongoDB\Data");

var mongodb = mongo.AddDatabase("mongodb");

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

// After adding all resources, run the app...

Monteringar av databindningar förlitar sig på värddatorns filsystem för att bevara serverdata MongoDB vid omstarter av containrar. Databindningsmonteringen monteras på sökvägen C:\MongoDB\Data i Windows (eller /MongoDB/Data på Unix) på värddatorn i MongoDB-servercontainern. Mer information om databindningsmonteringar finns i Docker dokument: Bindningsmonteringar.

Lägg till MongoDB serverresurs med initieringsdatabindningsmontering

Om du vill lägga till en initieringsmappsdatabindningsmontering till MongoDB-serverresursen anropar du metoden WithInitBindMount:

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithInitBindMount(@"C:\MongoDB\Init");

var mongodb = mongo.AddDatabase("mongodb");

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

// After adding all resources, run the app...

Initieringsdatabindningsmonteringen används för att initiera MongoDB-servern med data. Initieringsdatabindningsmonteringen monteras på sökvägen C:\MongoDB\Init i Windows (eller /MongoDB/Init på Unix) på värddatorn i MongoDB-servercontainern och mappas till sökvägen /docker-entrypoint-initdb.d i MongoDB-servercontainern. MongoDB kör skripten som finns i den här mappen, vilket är användbart för att läsa in data i databasen.

Lägga till MongoDB serverresurs med parametrar

När du uttryckligen vill ange lösenordet som används av containeravbildningen kan du ange dessa autentiseringsuppgifter som parametrar. Tänk dig följande alternativa exempel:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var mongo = builder.AddMongoDB("mongo", username, password);
var mongodb = mongo.AddDatabase("mongodb");

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

// After adding all resources, run the app...

Mer information om hur du tillhandahåller parametrar finns i Externa parametrar.

Lägg till MongoDB Express-resurs

MongoDB Express är ett webbaserat MongoDB användargränssnitt för administratörer. Om du vill lägga till en MongoDB Express-resurs som motsvarar containeravbildningendocker.io/library/mongo-expressWithMongoExpress anropar du metoden på serverresursenMongoDB:

var builder = DistributedApplication.CreateBuilder(args);

var mongo = builder.AddMongoDB("mongo")
                   .WithMongoExpress();

var mongodb = mongo.AddDatabase("mongodb");

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

// After adding all resources, run the app...

Föregående kod lägger till en MongoDB Express-resurs som är konfigurerad för att ansluta till MongoDB-serverresursen. Standardautentiseringsuppgifterna är:

• ME_CONFIG_MONGODB_SERVER: Namnet som tilldelats den överordnade MongoDBServerResource, i det här fallet skulle det vara mongo.
• ME_CONFIG_BASICAUTH: Ett värde av false.
• ME_CONFIG_MONGODB_PORT: Tilldelad från den primära slutpunktens målport för den överordnade MongoDBServerResource.
• ME_CONFIG_MONGODB_ADMINUSERNAME: Samma användarnamn som konfigurerats i den överordnade MongoDBServerResource.
• ME_CONFIG_MONGODB_ADMINPASSWORD: Samma lösenord som konfigurerats i den överordnade MongoDBServerResource.

Dessutom exponerar WithMongoExpress-API:et en valfri configureContainer parameter av typen Action<IResourceBuilder<MongoExpressContainerResource>> som du använder för att konfigurera MongoDB Express-containerresursen.

Genomföra hälsokontroller för integration

MongoDB värdintegrering lägger automatiskt till en hälsokontroll för MongoDB serverresursen. Hälsokontrollen verifierar att MongoDB serverresursen körs och att en anslutning kan upprättas till den.

Värdtjänstintegration förlitar sig på NuGet-paketet AspNetCore.HealthChecks.MongoDb.

Client integrering

För att börja med integrationen av -klienten, installera .Drivrutins-NuGet-paketet. i det projekt som förbrukar klienten, det vill säga projektet för applikationen som använder -klienten. Klientintegrering MongoDB registrerar en IMongoClient-instans som du kan använda för att interagera med serverresursen MongoDB . Om din AppHost lägger till MongoDB databasresurser registreras även IMongoDatabase-instansen .

dotnet add package Aspire.MongoDB.Driver

<PackageReference Include="Aspire.MongoDB.Driver"
                  Version="*" />

Lägg till MongoDB klient

I Program.cs-filen för ditt klientanvändande projekt anropar du AddMongoDBClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera IMongoClient för användning i beroendeinjektionscontainern. Metoden tar en parameter för anslutningsnamn.

builder.AddMongoDBClient(connectionName: "mongodb");

Du kan sedan hämta IMongoClient-instansen med hjälp av dependency injection. Om du till exempel vill hämta klienten från en exempeltjänst:

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

IMongoClient används för att interagera med MongoDB-serverresursen. Den kan användas för att skapa databaser som inte redan är kända för AppHost-projektet. När du definierar en MongoDB databasresurs i din AppHost kan du i stället kräva att containern för beroendeinmatning tillhandahåller en IMongoDatabase instans. Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nyckelade MongoDB klient

Det kan finnas situationer där du vill registrera flera IMongoDatabase instanser med olika anslutningsnamn. Om du vill registrera nyckelade MongoDB klienter anropar du metoden AddKeyedMongoDBClient:

builder.AddKeyedMongoDBClient(name: "mainDb");
builder.AddKeyedMongoDBClient(name: "loggingDb");

Sedan kan du hämta IMongoDatabase-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta anslutningen från en exempeltjänst:

public class ExampleService(
    [FromKeyedServices("mainDb")] IMongoDatabase mainDatabase,
    [FromKeyedServices("loggingDb")] IMongoDatabase loggingDatabase)
{
    // Use databases...
}

Mer information om nyckelade tjänster finns i .NET beroendeinmatning: Nyckelade tjänster.

Konfiguration

Aspire MongoDB databasintegrering 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 ConnectionStrings konfigurationsavsnittet kan du ange namnet på anslutningssträngen när du anropar builder.AddMongoDBClient():

builder.AddMongoDBClient("mongo");

Anslutningssträngen hämtas från avsnittet ConnectionStrings konfiguration. Överväg följande MongoDB exempel JSON konfiguration:

{
  "ConnectionStrings": {
    "mongo": "mongodb://server:port/test",
  }
}

Du kan också överväga följande MongoDB Atlas-exempel JSON konfiguration:

{
  "ConnectionStrings": {
    "mongo": "mongodb+srv://username:password@server.mongodb.net/",
  }
}

Mer information om hur du formaterar den här anslutningssträngen finns i MongoDB: ConnectionString-dokumentation.

Använda konfigurationsprovidrar

Aspire MongoDB-integrationen stöder Microsoft.Extensions.Configuration. Den läser in MongoDBSettings från konfigurationen med hjälp av Aspire:MongoDB:Driver-nyckeln. Följande kodfragment är ett exempel på en appsettings.json fil som konfigurerar några av alternativen:

{
  "Aspire": {
    "MongoDB": {
      "Driver": {
        "ConnectionString": "mongodb://server:port/test",
        "DisableHealthChecks": false,
        "HealthCheckTimeout": 10000,
        "DisableTracing": false
      }
    }
  }
}

Använda namngiven konfiguration

Integreringen AspireMongoDB stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma resurstyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under huvudkonfigurationsavsnittet.

{
  "Aspire": {
    "MongoDB": {
      "Driver": {
        "mongo1": {
          "ConnectionString": "mongodb://server1:port/test",
          "DisableHealthChecks": false,
          "HealthCheckTimeout": 10000
        },
        "mongo2": {
          "ConnectionString": "mongodb://server2:port/test",
          "DisableTracing": true,
          "HealthCheckTimeout": 5000
        }
      }
    }
  }
}

I det här exemplet kan anslutningsnamnen mongo1 och mongo2 användas när du anropar AddMongoDBClient:

builder.AddMongoDBClient("mongo1");
builder.AddMongoDBClient("mongo2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

Använd inline-konfigurationer

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

builder.AddMongoDBClient("mongodb",
    static settings => settings.ConnectionString = "mongodb://server:port/test");

Konfigurationsalternativ

Här är de konfigurerbara alternativen med motsvarande standardvärden:

Client hälsokontroller för integrering

Som standard Aspire har klientintegreringarhälsokontroller aktiverade för alla tjänster. På samma sätt möjliggör många Aspirehostingintegrationer även hälsokontrolländpunkter. Mer information finns i:

• .NET hälsokontroller för appar i C#
• Hälsokontroller i ASP.NET Core

Som standard hanterar AspireMongoDB klientintegrering följande scenarier:

• Lägger till en hälsokontroll som, när den är aktiverad, verifierar att en anslutning kan göras och att kommandon kan köras mot MongoDB-databasen inom en viss tid.
• Integrerar med /health HTTP-slutpunkten, vilket innebär att alla registrerade hälsotester måste godkännas för att appen ska anses redo att ta emot trafik.

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Konfiguration .

Skogsavverkning

Aspire MongoDB databasintegrering använder standardloggning .NET och du ser loggposter från följande kategorier:

• MongoDB[.*]: Alla loggposter från MongoDB namnområdet.

Spårning

Aspire MongoDB-databasintegreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• MongoDB.Driver.Core.Extensions.DiagnosticSources

Mätvärden

Aspire MongoDB databasintegrering exponerar för närvarande inte några OpenTelemetry mått.

Se även

• MongoDB databas
• Aspire Integrationer
• Aspire GitHub Repo