.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
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...
Jegyzet
A MongoDB tároló indítása lassú lehet, ezért érdemes állandó élettartamot használni a szükségtelen újraindítások elkerülése érdekében. További információ: tárolóerőforrás élettartama.
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
: Aadmin
értéke. -
MONGO_INITDB_ROOT_PASSWORD
: Apassword
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.
Borravaló
Ha inkább egy meglévő MongoDB kiszolgálóhoz szeretne csatlakozni, hívja meg inkább a AddConnectionString. További információért lásd: Elérhető erőforrások.
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.
Figyelmeztetés
A jelszó az adatkötetben van tárolva. Adatkötet használatakor és ha a jelszó megváltozik, az nem fog működni, amíg nem törli a kötetet.
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...
Fontos
Az adatkötési csatlakoztatások korlátozott funkcionalitással rendelkeznek kötetekhez képest, amelyek jobb teljesítményt, hordozhatóságot és biztonságot nyújtanak, így jobban alkalmasak az éles környezetekhez. A kötési csatlakoztatások azonban lehetővé teszik a fájlok közvetlen elérését és módosítását a gazdarendszeren, ami ideális fejlesztési és tesztelési célokra, ahol valós idejű módosításokra van szükség.
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/Data
Unix) 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...
Borravaló
A MongoExpressContainerResource lánc gazdagépportjának konfigurálásához hívja meg a WithHostPort API-t, és adja meg a kívánt portszámot.
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 esetbenmongo
. -
ME_CONFIG_BASICAUTH
: Afalse
értéke. -
ME_CONFIG_MONGODB_PORT
: A szülőMongoDBServerResource
első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őMongoDBServerResource
konfigurálva van. -
ME_CONFIG_MONGODB_ADMINPASSWORD
: Ugyanaz a jelszó, mint a szülőben beállítottMongoDBServerResource
.
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
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");
Borravaló
A connectionName
paraméternek meg kell egyeznie a MongoDB kiszolgálói erőforrás (vagy ha meg van adva az adatbázis-erőforrás) alkalmazásgazdaprojektben való hozzáadásakor használt névvel. Más szóval, amikor meghívja AddDatabase
, és megadja a mongodb
nevét, ugyanazt a nevet kell használnia AddMongoDBClient
hívásához. További információ: MongoDB kiszolgálói erőforrás és adatbázis-erőforrás hozzáadása.
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");
Fontos
A kulcsos szolgáltatások használatakor a MongoDB erőforrás várhatóan két elnevezett adatbázist konfigurál, egyet a mainDb
, egyet pedig a 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:
Név | Leírás |
---|---|
ConnectionString |
A MongoDB adatbázis kapcsolati sztringje, amelyhez csatlakozni szeretne. |
DisableHealthChecks |
Logikai érték, amely azt jelzi, hogy az adatbázis állapotának ellenőrzése le van-e tiltva. |
HealthCheckTimeout |
Egy int? érték, amely a MongoDB állapot-ellenőrzési időtúllépést jelzi ezredmásodpercben. |
DisableTracing |
Boolean érték, amely azt jelzi, hogy a OpenTelemetry nyomkövetés letiltott állapotban van-e. |
Á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.