.NET Aspire MongoDB adatbázis-integráció

Tartalmazza:Üzemeltetési integráció és Client integrációs

MongoDB egy NoSQL-adatbázis, amely nagy teljesítményt, magas rendelkezésre állást és egyszerű méretezhetőséget biztosít. A .NET AspireMongoDB integráció lehetővé teszi a meglévő MongoDB példányokhoz való csatlakozást (beleértve a MongoDB Atlas-et is) vagy új példányok létrehozását .NET használva a docker.io/library/mongo konténer képet.

Üzemeltetési integráció

Az integrációs MongoDB kiszolgáló MongoDBServerResource típusként, az adatbázist pedig MongoDBDatabaseResource típusként modellozza. Az ilyen típusok és API-k eléréséhez adja hozzá a 📦Aspire.Hosting.MongoDB NuGet-csomagot az alkalmazásgazda projektbe.

dotnet add package Aspire.Hosting.MongoDB

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

További információ: dotnet add package vagy Manage package dependencies in .NET applications.

MongoDB kiszolgálói erőforrás és adatbázis-erőforrás hozzáadása

Az alkalmazásgazda projektben hívja meg a(z) AddMongoDB függvényt egy MongoDB szerver erőforrás felépítésére és visszaadására. Kapcsoljon össze egy hívást a visszaadott erőforrás-építőhöz AddDatabase-hoz, hogy MongoDB adatbázis erőforrást adjon hozzá.

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

Amikor .NET.NET Aspire egy konténerképet ad hozzá az alkalmazás hosztjához, ahogyan az az előző példában az docker.io/library/mongo konténerképnél is látható, egy új MongoDB-példányt hoz létre a helyi számítógépén. A MongoDB kiszolgálói erőforrás-szerkesztőre (a mongo változóra) mutató hivatkozás használható adatbázis hozzáadásához. Az adatbázist mongodb névre nevezik el, majd hozzáadják a ExampleProject-hez. A MongoDB kiszolgálói erőforrás az alapértelmezett hitelesítő adatokat tartalmazza:

• MONGO_INITDB_ROOT_USERNAME: A adminértéke.
• MONGO_INITDB_ROOT_PASSWORD: A password metódussal létrehozott véletlenszerű CreateDefaultPasswordParameter.

Az alkalmazásgazda futtatásakor a jelszó az alkalmazásgazda titkos tárolójában lesz tárolva. A Parameters szakaszhoz hozzá van adva, például:

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

A paraméter neve mongo-password, de valójában csak -password utótaggal formázhatja az erőforrás nevét. További információ: Alkalmazáskulcsok biztonságos tárolása a fejlesztés során ASP.NET Core és MongoDB kiszolgálóerőforrás hozzáadása paraméterekkel.

A WithReference metódus konfigurál egy kapcsolatot a ExampleProject nevű mongodb-ben, és a WaitFor arra utasítja az alkalmazásgazdát, hogy ne indítsa el a függő szolgáltatást, amíg az mongodb erőforrás nem áll készen.

MongoDB szerver erőforrás hozzáadása adatkötettel

Ha adatkötetet szeretne hozzáadni a MongoDB kiszolgálóerőforráshoz, hívja meg a WithDataVolume metódust a MongoDB kiszolgálóerőforráson:

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

Az adatkötet a tároló életciklusán kívüli MongoDB kiszolgálóadatok megőrzésére szolgál. Az adatkötet a MongoDB kiszolgálótároló /data/db elérési útjára van csatlakoztatva, és ha nincs megadva name paraméter, a rendszer véletlenszerűen hozza létre a nevet. További információ az adatkötetekről és arról, hogy miért előnyben részesítik őket kötéskötések, lásd Docker dokumentumokat: Kötetek.

MongoDB szerver erőforrás hozzáadása adatok csatolásával

Ha adatkötési csatlakoztatást szeretne hozzáadni a MongoDB kiszolgálóerőforráshoz, hívja meg a WithDataBindMount metódust:

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

Az adat mount-ok a hosztgép fájlrendszerére támaszkodnak a MongoDB kiszolgáló adatainak megőrzéséhez a tároló újraindítása után. Az adatkötés csatlakoztatása a Windows C:\MongoDB\Data (vagy /MongoDB/DataUnix) gazdaszámítógépének MongoDB kiszolgálótárolójában található elérési útjára van csatlakoztatva. Az adatkötési csatlakoztatásokkal kapcsolatos további információkért lásd Docker dokumentumokat: Kötési csatlakoztatások.

MongoDB szerver erőforrás hozzáadása inicializálási adatokhoz kötött csatolással

Ha inicializáló mappa adatkötésének hozzáadását szeretné a MongoDB kiszolgáló erőforrásához, használja a WithInitBindMount metódust:

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

Az inicializálási adatkötés csatlakoztatásával inicializálható a MongoDB kiszolgáló az adatokkal. A kezdeti adatok csatolási pontja a windowsos gazdagépen a C:\MongoDB\Init útvonalon van csatolva (vagy a Unix/MongoDB/Init útvonalon) a MongoDB szerverkonténerben, és a /docker-entrypoint-initdb.d útvonalra van leképezve a MongoDB szerverkonténerben. MongoDB végrehajtja a mappában található szkripteket, amelyek az adatok adatbázisba való betöltéséhez hasznosak.

MongoDB kiszolgálói erőforrás hozzáadása paraméterekkel

Ha explicit módon meg szeretné adni a tárolólemezkép által használt jelszót, paraméterekként megadhatja ezeket a hitelesítő adatokat. Tekintse meg a következő alternatív példát:

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

További információ a paraméterek megadásáról: Külső paraméterek.

MongoDB Express-erőforrás hozzáadása

MongoDB Express egy webes MongoDB rendszergazdai felhasználói felület. Ha olyan MongoDB Express-erőforrást szeretne hozzáadni, amely megfelel a docker.io/library/mongo-express tárolórendszerkép, hívja meg a MongoDB kiszolgáló erőforrásának WithMongoExpress metódusát:

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

Az előző kód hozzáad egy MongoDB Express-erőforrást, amely úgy van konfigurálva, hogy csatlakozzon a MongoDB kiszolgálói erőforráshoz. Az alapértelmezett hitelesítő adatok a következők:

• ME_CONFIG_MONGODB_SERVER: A szülő MongoDBServerResource-hez hozzárendelt név, ebben az esetben mongo.
• ME_CONFIG_BASICAUTH: A falseértéke.
• ME_CONFIG_MONGODB_PORT: A szülő MongoDBServerResourceelsődleges végpontjának célportjából van hozzárendelve.
• ME_CONFIG_MONGODB_ADMINUSERNAME: Ugyanaz a felhasználónév, mint ahogy a szülő MongoDBServerResourcekonfigurálva van.
• ME_CONFIG_MONGODB_ADMINPASSWORD: Ugyanaz a jelszó, mint a szülőben beállított MongoDBServerResource.

Emellett a WithMongoExpress API egy választható configureContainer típusú Action<IResourceBuilder<MongoExpressContainerResource>> paramétert tesz elérhetővé, amelyet az MongoDB Express-tárolóerőforrás konfigurálásához használ.

Integrációs állapotellenőrzések üzemeltetése

A MongoDB üzemeltetési integráció automatikusan hozzáad egy állapotellenőrzést a MongoDB kiszolgálói erőforráshoz. Az állapotellenőrzés ellenőrzi, hogy a MongoDB kiszolgálói erőforrás fut-e, és hogy létre lehet-e hozni vele kapcsolatot.

A hostolási integráció az 📦 AspNetCore.HealthChecks.MongoDb NuGet-csomagon alapul.

Client integráció

Az .NET AspireMongoDB ügyfélintegráció elindításához telepítse a 📦Aspire.MongoDBillesztőprogram NuGet-csomagot abban az ügyfélprojekben, amelyik a MongoDB ügyfelet használó alkalmazás számára készült. A MongoDB-ügyfélintegráció regisztrál egy IMongoClient-példányt, amely a MongoDB kiszolgálói erőforrással való interakcióhoz használható. Ha az alkalmazásgazda MongoDB adatbázis-erőforrásokat ad hozzá, a IMongoDatabase-példány is regisztrálva van.

dotnet add package Aspire.MongoDB.Driver

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

MongoDB-ügyfél hozzáadása

Az ügyfél által használt projekt Program.cs fájljában hívja meg a AddMongoDBClient bővítménymetódusát bármely IHostApplicationBuilder-on, hogy egy IMongoClient-at regisztráljon használatra a függőséginjektáló tárolón keresztül. A metódus egy kapcsolatnévparamétert használ.

builder.AddMongoDBClient(connectionName: "mongodb");

Ezután függőséginjektálással lekérheti a IMongoClient-példányt. Példaként, egy példaszolgáltatásból történő ügyféladatok lekérése:

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

A IMongoClient a MongoDB kiszolgálóerőforrással való interakcióra szolgál. Olyan adatbázisok létrehozására használható, amelyek még nem ismertek az alkalmazásgazdaprojektben. Ha az alkalmazás gazdagépében egy MongoDB adatbázis-erőforrást határoz meg, ehelyett megkövetelheti, hogy a függőséginjektálási konténer biztosítson egy IMongoDatabase-példányt. További információ a függőséginjektálásról: .NET függőséginjektálás.

Kulcsos MongoDB-ügyfél hozzáadása

Előfordulhatnak olyan helyzetek, amikor több IMongoDatabase példányt szeretne regisztrálni különböző kapcsolati nevekkel. A kulcsos MongoDB ügyfelek regisztrálásához hívja meg a AddKeyedMongoDBClient metódust:

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

Ezután függőséginjektálással lekérheti a IMongoDatabase példányokat. Ha például egy példaszolgáltatásból szeretné lekérni a kapcsolatot:

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

További információ a kulcsos szolgáltatásokról: .NET függőséginjektálás: Kulcsos szolgáltatások.

Konfiguráció

A .NET AspireMongoDB adatbázis-integráció számos konfigurációs módszert és lehetőséget kínál a projekt követelményeinek és konvencióinak teljesítéséhez.

A kapcsolati karaktersor használata

Ha kapcsolati sztringet használ a ConnectionStrings konfigurációs szakaszból, megadhatja a kapcsolati sztring nevét builder.AddMongoDBClient()hívásakor:

builder.AddMongoDBClient("mongo");

A kapcsolati sztring lekérése a ConnectionStrings konfigurációs szakaszból történik. Tekintse meg az alábbi MongoDB példát JSON konfigurációra:

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

Másik lehetőségként tekintse meg a következő MongoDB Atlas-példát JSON konfigurációt:

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

A kapcsolati karakterlánc formázásáról további információt a MongoDB: ConnectionString dokumentációjatalál.

Konfigurációs szolgáltatók használata

A .NET AspireMongoDB integráció támogatja a Microsoft.Extensions.Configuration. Betölti a MongoDBSettings-t a konfigurációból a Aspire:MongoDB:Driver kulcs segítségével. Az alábbi kódrészlet egy példa egy appsettings.json fájlra, amely konfigurál néhány beállítást:

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

Beágyazott konfigurációk használata

A Action<MongoDBSettings> delegáltat is átadhatja a beágyazott beállítások egy részének vagy mindegyikének beállításához:

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

Konfigurációs beállítások

A konfigurálható beállítások a megfelelő alapértelmezett értékekkel:

Állapotellenőrzések

Alapértelmezés szerint az .NET.NET Aspire integrációk lehetővé teszik állapotellenőrzéseket az összes szolgáltatás esetében. További információ: .NET.NET Aspire integrációk áttekintése.

Alapértelmezés szerint a .NET AspireMongoDB ügyfélintegráció a következő forgatókönyveket kezeli:

• Ha engedélyezve van, az állapotellenőrzés hozzáadása ellenőrzi, hogy létrejöhet-e kapcsolat, és parancsok végrehajthatók-e a MongoDB adatbázison bizonyos időn belül.
• Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására

Megfigyelhetőség és telemetria

.NET .NET Aspire integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikakonfigurációkat, amelyeket más néven a megfigyelhetőség alappillérei. Az integráció megfigyelhetőségéről és telemetriáról további információt .NET.NET Aspire integrációk áttekintésében. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban ismertetett technikákkal is letilthatók.

Fakitermelés

A .NET AspireMongoDB adatbázis-integráció szabványos .NET naplózást használ, és a naplóbejegyzések a következő kategóriákból származnak:

• MongoDB[.*]: A MongoDB névtérből származó naplóbejegyzések.

Nyomkövetés

A .NET AspireMongoDB adatbázis-integráció a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

• MongoDB.Driver.Core.Extensions.DiagnosticSources

Metrikák

Az .NET AspireMongoDB adatbázis-integráció jelenleg nem tesz közzé OpenTelemetry metrikákat.

Lásd még:

• MongoDB adatbázis
• .NET .NET Aspire integrációk
• .NET Aspire GitHub adattár