.NET Aspire MongoDB databasintegrering

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

MongoDB server värdintegrering modellerar server som MongoDBServerResource typ och databasen som MongoDBDatabaseResource typ. 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

dotnet add package Aspire.Hosting.MongoDB

PackageReference

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

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

Lägg till MongoDBserver resurs och databasresurs

I ditt appvärdprojekt anropar du AddMongoDB för att lägga till och returnera en resursbyggare för MongoDBserver. 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 MongoDBserver resursbyggare (variabeln mongo) används för att lägga till en databas. Databasen heter mongodb och läggs sedan till i ExampleProject. Den MongoDBserver resursen 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 MongoDBserver resurs 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 MongoDBserveranropar du AddConnectionString i stället. Mer information finns i Referera till befintliga resurser.

Lägga till MongoDBserver resurs med datavolym

Om du vill lägga till en datavolym i den MongoDBserver resursen anropar du metoden WithDataVolume på den MongoDBserver resursen:

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 MongoDBserver data utanför containerns livscykel. Datavolymen monteras vid sökvägen /data/db i container MongoDBserver och när en name-parameter inte anges genereras namnet slumpmässigt. 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 MongoDBserver resurs med databindmontering

Om du vill lägga till en databindningsmontering till den MongoDBserver resursen 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.

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara MongoDBserver data mellan omstarter av containrar. Databindningen är monterad vid platsen C:\MongoDB\Data på Windows (eller /MongoDB/Data på Unix) på värddatorn i MongoDBserver-containern. Mer information om databindningsmonteringar finns i Docker dokument: Bind monteringar.

Lägg till MongoDBserver resurs med initieringsdatabindningsmontering

För att lägga till en databindningsmontering för initieringsmappen till resursen MongoDBserver, anropas 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...

Bindmonteringen för initieringsdata används för att initiera MongoDBserver med data. Initieringsdatabindningen monteras på sökvägen C:\MongoDB\Init i Windows (eller /MongoDB/Init på Unix) på värddatorn inom MongoDBserver-containern och mappas till sökvägen /docker-entrypoint-initdb.d i MongoDBserver-containern. 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 MongoDBserver resurs 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å den MongoDBserver resursen:

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 den MongoDBserver resursen. Standardautentiseringsuppgifterna är:

• ME_CONFIG_MONGODB_SERVER: Namnet som tilldelats den överordnade MongoDBServerResource, i det här fallet skulle det vara mongo.
• ME_CONFIG_BASICAUTH: Värdet 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 den MongoDBserver resursen. Hälsokontrollen verifierar att den MongoDBserver resursen körs och att en anslutning kan upprättas till den.

Värdintegreringen förlitar sig på 📦 AspNetCore.HealthChecks.MongoDb NuGet-paketet.

Client integrering

Kom igång med .NET AspireMongoDBclient-integrationen genom att installera 📦Aspire.MongoDB.Driver NuGet-paketet i det client-förbrukande projektet, det vill säga projektet som använder MongoDBclient. MongoDB client-integreringen registrerar en IMongoClient--instans som du kan använda för att interagera med MongoDBserver-resursen. Om appvärden lägger till MongoDB databasresurser registreras även en IMongoDatabase instans.

.NET CLI

dotnet add package Aspire.MongoDB.Driver

PackageReference

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

Lägg till MongoDBclient

I den Program.cs filen för ditt client-förbrukande projekt anropar du metoden för AddMongoDBClient-tillägg på alla IHostApplicationBuilder för att registrera en IMongoClient för användning via containern för beroendeinmatning. 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 den MongoDBserver resursen (eller databasresursen när den tillhandahålls) 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. Mer information finns i Lägg till MongoDBserver resurs och databasresurs.

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

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

IMongoClient används för att interagera med den MongoDBserver resursen. 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 nycklade MongoDBclient

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

Se även

• MongoDB databas
• .NET .NET Aspire integreringar
• .NET Aspire GitHub lagringsplats