.NET Aspire MongoDB databasintegrering

Artikel
01/22/2025

omfattar:Hostingintegration och Client integration

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

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 appvärd projekt.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.MongoDB

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

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

Lägg till MongoDB serverresurs och databasresurs

I värdprojektet för appen anropar du AddMongoDB för att lägga till och returnera en MongoDB serverresurskompilator. 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...

Not

Den MongoDB container kan vara långsam att starta upp, så det är bäst att använda en beständig livstid för att undvika onödiga omstarter. För mer information, se Containerresursens livslängd.

När .NET.NET Aspire lägger till en containerbild i appvärden, som visas i det föregående exemplet med docker.io/library/mongo bilden, skapar den en ny MongoDB instans på din lokala dator. 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 appvärden kör lagras lösenordet i appvärdens hemliga lagring. 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 ExampleProject med namnet mongodb och WaitFor instruerar appvärden att inte starta den beroende tjänsten förrän mongodb resursen är klar.

Tips

Om du hellre vill ansluta till en befintlig MongoDB server anropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

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 varför de föredras framför bind-monteringarfinns i dokumenten Docker: Volymer.

Varning

Lösenordet lagras i datavolymen. När du använder en datavolym och om lösenordet ändras fungerar det inte förrän du tar bort volymen.

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

Viktig

Data bindningsmonteringar har begränsade funktioner jämfört med volymer, vilket ger bättre prestanda, portabilitet och säkerhet, vilket gör dem mer lämpliga för produktionsmiljöer. Bindningsmonteringar tillåter dock direkt åtkomst och ändring av filer i värdsystemet, perfekt för utveckling och testning där realtidsändringar behövs.

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: Bind monteringar.

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 användargränssnitt för MongoDB administratör. Om du vill lägga till en MongoDB Express-resurs som motsvarar docker.io/library/mongo-express containeravbildningenanropar du metoden WithMongoExpress på MongoDB-serverresursen:

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

Tips

För att konfigurera värdporten för MongoExpressContainerResource kedja ett anrop till WithHostPort-API:et och ange önskat portnummer.

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ärdintegreringen förlitar sig på NuGet-paketet 📦 AspNetCore.HealthChecks.MongoDb.

Client integrering

Kom igång med .NET AspireMongoDB-klientintegrering genom att installera 📦Aspire.MongoDB.Driver NuGet-paket i det projekt som använder klienten, det vill säga projektet för den applikation som använder MongoDB-klienten. MongoDB-klientintegrering registrerar en IMongoClient instans som du kan använda för att interagera med MongoDB serverresursen. Om appvärden lägger till MongoDB databasresurser registreras även en IMongoDatabase instans.

.NET CLI
PackageReference

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");

Tips

Parametern connectionName måste matcha namnet som används när du lägger till serverresursen MongoDB (eller databasresursen om det finns) i appvärdprojektet. Med andra ord, när du anropar AddDatabase och anger ett namn på mongodb ska samma namn användas när du anropar AddMongoDBClient. För mer information, se Lägg till MongoDB serverresurs och databasresurs.

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 värdprojektet för appen ännu inte känner till. När du definierar en MongoDB-databasresurs i appvärden kan du i stället kräva att containern för beroendeinjektion levererar en instans av IMongoDatabase. 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");

Viktig

När du använder nyckelade tjänster förväntas din MongoDB resurs ha konfigurerat två namngivna databaser, en för mainDb och en för 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 beroendeinjektion: Nyckelade tjänster.

Konfiguration

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

.NET 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ä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:

Namn	Beskrivning
`ConnectionString`	Anslutningssträngen för databasen MongoDB att ansluta till.
`DisableHealthChecks`	Ett booleskt värde som anger om databasens hälsokontroll är inaktiverad eller inte.
`HealthCheckTimeout`	Ett värde för `int?` som anger tidsgränsen för hälsokontroll MongoDB i millisekunder.
`DisableTracing`	Ett booleskt värde som anger om OpenTelemetry spårning är inaktiverad eller inte.

Hälsokontroller

Som standard aktiverar .NET.NET Aspire integreringar hälsokontroller för alla tjänster. Mer information finns i översikten över .NET.NET Aspire integreringar.

Som standard hanterar .NET 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

.NET .NET 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 översikten över .NET.NET Aspire 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 Configuration.

Skogsavverkning

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

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

MongoDB.Driver.Core.Extensions.DiagnosticSources

Mätvärden

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

Dela via

.NET Aspire MongoDB databasintegrering

Värdintegrering

Lägg till MongoDB serverresurs och databasresurs

Lägga till MongoDB serverresurs med datavolym

Lägg till MongoDB serverresurs med databindningsmontering

Lägg till MongoDB serverresurs med initieringsdatabindningsmontering

Lägga till MongoDB serverresurs med parametrar

Lägg till MongoDB Express-resurs

Genomföra hälsokontroller för integration

Client integrering

Lägg till MongoDB klient

Lägg till nyckelade MongoDB klient

Konfiguration

Använda en anslutningssträng

Använda konfigurationsprovidrar

Använd inline-konfigurationer

Konfigurationsalternativ

Hälsokontroller

Observerbarhet och telemetri

Skogsavverkning

Spårning

Mätvärden

Se även

Ytterligare resurser