integrace databáze .NET AspireMongoDB

Článek
12/13/2024

zahrnuje: integracehostování a integrace Client

MongoDB je databáze NoSQL, která poskytuje vysoký výkon, vysokou dostupnost a snadnou škálovatelnost. Integrace .NET AspireMongoDB umožňuje připojit se k existujícím instancím MongoDB (včetně MongoDB Atlas) nebo vytvářet nové instance z .NET pomocí image kontejneru docker.io/library/mongo

Integrace hostování

Integrace hostování MongoDBserver modeluje server jako typ MongoDBServerResource a databázi jako typ MongoDBDatabaseResource. Pokud chcete získat přístup k těmto typům a rozhraním API, přidejte balíček NuGet 📦Aspire.Hosting.MongoDB do projektu hostitele aplikace .

.NET rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.Hosting.MongoDB

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

Další informace najdete v tématu dotnet add package nebo Manage package dependencies in .NET applications.

Přidejte prostředky MongoDBserver a databázový prostředek.

V hostitelském projektu aplikace zavolejte AddMongoDB, přidejte a poté vraťte MongoDBserver generátor prostředků. Zřetězte volání na vráceného správce prostředků k AddDatabasea přidejte prostředek databáze MongoDB.

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

Poznámka

Kontejner MongoDB může být pomalý, takže je nejlepší použít trvalou životnost, abyste se vyhnuli zbytečným restartováním. Další informace naleznete v tématu Životnost prostředků kontejneru.

Když .NET.NET Aspire přidá do hostitele aplikace image kontejneru, jak je znázorněno v předchozím příkladu s imagí docker.io/library/mongo, vytvoří na místním počítači novou instanci MongoDB. K přidání databáze se používá odkaz na sestavovatele prostředků MongoDBserver (proměnná mongo). Databáze se jmenuje mongodb a pak se přidá do ExampleProject. Prostředek MongoDBserver obsahuje výchozí přihlašovací údaje:

MONGO_INITDB_ROOT_USERNAME: Hodnota admin.
MONGO_INITDB_ROOT_PASSWORD: Náhodné password vygenerované pomocí metody CreateDefaultPasswordParameter.

Když se hostitel aplikace spustí, heslo se uloží do úložiště tajných kódů hostitele aplikace. Přidává se to do oddílu Parameters, například:

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

Název parametru je mongo-password, ale ve skutečnosti pouze formátuje název prostředku s příponou -password. Další informace najdete v tématu Bezpečné ukládání tajných kódů aplikací při vývoji v ASP.NET Core a Přidání prostředku MongoDBserver s parametry.

Metoda WithReference nakonfiguruje připojení v ExampleProject pojmenovaném mongodb a WaitFor dá hostiteli aplikace pokyn, aby nespusloval závislé služby, dokud nebude prostředek mongodb připravený.

Spropitné

Pokud byste se raději připojili k existujícímu MongoDBserver, volejte místo toho AddConnectionString. Pro více informací viz Odkazy na existující prostředky.

Přidejte zdroj MongoDBserver s datovým objemem.

Pokud chcete do prostředku MongoDBserver přidat datový svazek, zavolejte metodu WithDataVolume prostředku MongoDBserver:

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

Objem dat se používá k zachování MongoDBserver dat mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data/db v kontejneru MongoDBserver a pokud není zadaný parametr name, název se náhodně vygeneruje. Další informace o datových svazcích a podrobnosti o tom, proč se jim dává přednost před připojení pomocí vazeb, najdete v dokumentaci Docker: Svazky.

Varování

Heslo je uloženo v datovém svazku. Pokud používáte datový svazek a heslo se změní, svazek nebude fungovat, dokud ho neodstraníte.

Přidejte prostředek MongoDBserver s montováním datové vazby

Pokud chcete přidat připojení vazby dat k prostředku MongoDBserver, zavolejte metodu 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...

Důležitý

Připojení vazby dat mají v porovnání s svazkyomezené funkce, které nabízejí lepší výkon, přenositelnost a zabezpečení, což je vhodnější pro produkční prostředí. Vázané svazky však umožňují přímý přístup a úpravu souborů na hostitelském systému, což je ideální pro vývoj a testování, kde jsou potřebné změny v reálném čase.

Datová připojení typu bind využívají systém souborů hostitelského počítače k zachování MongoDBserver dat při restartování kontejneru. Vazba dat se připojí na cestu C:\MongoDB\Data ve Windows (nebo /MongoDB/Data na Unix) na hostitelském počítači v kontejneru MongoDBserver. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidat prostředek MongoDBserver s připojením svazku inicializačních dat

Chcete-li přidat připojení dat složky inicializace k prostředku MongoDBserver, zavolejte metodu 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...

Inicializační datový svazek se používá k inicializaci MongoDBaserver daty. Připojení datové vazby inicializace je připojeno na cestě C:\MongoDB\Init na Windows (nebo /MongoDB/Init na Unix) na hostitelském počítači v kontejneru MongoDBserver a mapuje se na cestu /docker-entrypoint-initdb.d v kontejneru MongoDBserver. MongoDB spustí skripty nalezené v této složce, což je užitečné pro načtení dat do databáze.

Přidání prostředku MongoDBserver s parametry

Pokud chcete explicitně zadat heslo používané imagí kontejneru, můžete tyto přihlašovací údaje zadat jako parametry. Podívejte se na následující alternativní příklad:

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

Další informace o poskytování parametrů naleznete v tématu Externí parametry.

Přidejte prostředek MongoDB Express

MongoDB Express je webové uživatelské rozhraní správce MongoDB. Pokud chcete přidat prostředek MongoDB Express, který odpovídá image kontejneru docker.io/library/mongo-express, zavolejte metodu WithMongoExpress prostředku MongoDBserver:

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

Spropitné

Pro nakonfigurování portu hostitele pro řetězec MongoExpressContainerResource uskutečněte volání rozhraní API WithHostPort a zadejte požadované číslo portu.

Předchozí kód přidá prostředek MongoDB Express, který je nakonfigurovaný pro připojení k MongoDBserver prostředku. Výchozí přihlašovací údaje jsou:

ME_CONFIG_MONGODB_SERVER: Jméno přiřazené nadřazenému prvku MongoDBServerResource, v tomto případě by to bylo mongo.
ME_CONFIG_BASICAUTH: Hodnota false.
ME_CONFIG_MONGODB_PORT: Přiděleno z cílového portu primárního koncového bodu nadřazeného objektu MongoDBServerResource.
ME_CONFIG_MONGODB_ADMINUSERNAME: Stejné uživatelské jméno, jako je nakonfigurované v nadřazeném MongoDBServerResource.
ME_CONFIG_MONGODB_ADMINPASSWORD: Stejné heslo, jako je nakonfigurováno u nadřazené MongoDBServerResource.

Kromě toho rozhraní API WithMongoExpress zveřejňuje volitelný configureContainer parametr typu Action<IResourceBuilder<MongoExpressContainerResource>>, který použijete ke konfiguraci prostředku kontejneru MongoDB Express.

Hostování kontrol stavu integrace

Integrace hostování MongoDB automaticky přidá kontrolu funkčního stavu prostředku MongoDBserver. Kontrola stavu ověřuje, jestli je prostředek MongoDBserver spuštěný a že se k němu dá navázat připojení.

Integrace hostování spoléhá na balíček NuGet 📦 AspNetCore.HealthChecks.MongoDb.

integrace Client

Pokud chcete začít s integrací .NET AspireMongoDBclient, nainstalujte balíček NuGet 📦Aspire.MongoDB.Driver v projektu využívajícím client, tj. v projektu aplikace používající MongoDBclient. Integrace MongoDBclient zaregistruje instanci IMongoClient, kterou můžete použít k interakci s prostředkem MongoDBserver. Pokud hostitel aplikace přidá prostředky databáze MongoDB, zaregistruje se také instance IMongoDatabase.

rozhraní příkazového řádku
PackageReference

dotnet add package Aspire.MongoDB.Driver

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

Přidejte MongoDBclient

V souboru Program.cs projektu, který využívá client, zavolejte rozšiřující metodu AddMongoDBClient na libovolném IHostApplicationBuilder a zaregistrujte IMongoClient pro použití prostřednictvím kontejneru pro injektování závislostí. Metoda přebírá parametr názvu připojení.

builder.AddMongoDBClient(connectionName: "mongodb");

Spropitné

Parametr connectionName se musí shodovat s názvem použitým při přidávání prostředku MongoDBserver (nebo databázového zdroje, pokud je k dispozici) v hostitelském projektu aplikace. Jinými slovy, když voláte AddDatabase a zadáte jméno mongodb, měli byste totožné jméno použít i při volání AddMongoDBClient. Další informace najdete v tématu Přidání MongoDBserver prostředků a prostředků databáze.

Potom můžete získat instanci IMongoClient pomocí injekce závislostí. Pokud chcete například načíst client z ukázkové služby:

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

IMongoClient slouží k interakci s prostředkem MongoDBserver. Dá se použít k vytvoření databází, které ještě nejsou známé pro hostitelský projekt aplikace. Když v hostiteli aplikace definujete prostředek databáze MongoDB, můžete místo toho vyžadovat, aby kontejner pro injektování závislostí poskytoval instanci IMongoDatabase. Další informace o injektáži závislostí najdete v tématu .NET injektáž závislostí.

Přidejte označené MongoDBclient

Mohou nastat situace, kdy chcete zaregistrovat více instancí IMongoDatabase s různými názvy připojení. Pokud chcete zaregistrovat klíčované klienty MongoDB, zavolejte metodu AddKeyedMongoDBClient:

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

Důležitý

Při použití služeb s klíči se očekává, že váš prostředek MongoDB nakonfiguroval dvě pojmenované databáze, jednu pro mainDb a druhou pro loggingDb.

Potom můžete načíst IMongoDatabase instance pomocí injektáže závislostí. Například pro získání připojení z ukázkové služby:

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

Další informace o klíčových službách najdete v tématu .NET injektování závislostí: klíčové služby.

Konfigurace

Integrace databáze .NET AspireMongoDB poskytuje několik přístupů a možností konfigurace pro splnění požadavků a konvencí projektu.

Použití připojovacího řetězce

Při použití připojovacího řetězce z oddílu konfigurace ConnectionStrings můžete při volání builder.AddMongoDBClient()zadat název připojovacího řetězce:

builder.AddMongoDBClient("mongo");

Řetězec připojení se získá z konfigurační sekce ConnectionStrings. Představte si následující konfiguraci MongoDB jako příklad JSON:

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

Případně zvažte následující MongoDB konfiguraci příkladu Atlasu JSON:

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

Další podrobnosti o tom, jak formátovat tento řetězec připojení, najdete v dokumentaci k ConnectionString MongoDB.

Použití zprostředkovatelů konfigurace

Integrace .NET AspireMongoDB podporuje Microsoft.Extensions.Configuration. Načte MongoDBSettings z konfigurace pomocí klíče Aspire:MongoDB:Driver. Následující fragment kódu je příkladem souboru appsettings.json, který konfiguruje některé z možností:

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

Použijte vložené konfigurace

Můžete také předat delegáta Action<MongoDBSettings> a nastavit některé nebo všechny možnosti přímo.

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

Možnosti konfigurace

Tady jsou konfigurovatelné možnosti s odpovídajícími výchozími hodnotami:

Jméno	Popis
`ConnectionString`	Připojovací řetězec databáze MongoDB, ke které se chcete připojit.
`DisableHealthChecks`	Logická hodnota, která označuje, jestli je kontrola stavu databáze zakázaná nebo ne.
`HealthCheckTimeout`	Hodnota `int?` označující časový limit kontroly stavu MongoDB v milisekundách.
`DisableTracing`	Logická hodnota označující, jestli je trasování OpenTelemetry zakázané nebo ne.

Kontroly stavu

Ve výchozím nastavení integrace .NET.NET Aspire umožňují kontroly stavu pro všechny služby. Další informace naleznete v tématu .NET.NET Aspire přehled integrací.

Integrace .NET AspireMongoDBclient ve výchozím nastavení zpracovává následující scénáře:

Přidá kontrolu stavu, která, pokud je povolena, ověřuje, že lze v určitém čase navázat připojení a spouštět příkazy na databázi MongoDB.
Integruje se s HTTP koncovým bodem /health, který stanovuje, že všechny registrované kontroly stavu musí být úspěšné, aby byla aplikace považována za připravenou k přijímání provozu.

Pozorovatelnost a telemetrie

.NET .NET Aspire integrace automaticky nastaví konfigurace protokolování, trasování a metrik, které se někdy označují jako pilíře pozorovatelnosti. Další informace o pozorovatelnosti a telemetrii integrace najdete v přehledu integrace .NET.NET Aspire. V závislosti na zálohovací službě můžou některé integrace podporovat pouze některé z těchto funkcí. Například některé integrace podporují protokolování a trasování, ale ne metriky. Funkce telemetrie je také možné zakázat pomocí technik uvedených v části Konfigurace.

Protokolování

Integrace databáze .NET AspireMongoDB používá standardní protokolování .NET a zobrazí se položky protokolu z následujících kategorií:

MongoDB[.*]: Libovolné záznamy protokolu z oboru názvů MongoDB.

Trasování

Integrace databáze .NET AspireMongoDB generuje následující aktivity trasování pomocí OpenTelemetry:

MongoDB.Driver.Core.Extensions.DiagnosticSources

Metriky

Integrace databáze .NET AspireMongoDB v současné době nezpřístupňuje žádné metriky OpenTelemetry.

Sdílet prostřednictvím

integrace databáze .NET AspireMongoDB

Integrace hostování

Přidejte prostředky MongoDBserver a databázový prostředek.

Přidejte zdroj MongoDBserver s datovým objemem.

Přidejte prostředek MongoDBserver s montováním datové vazby

Přidat prostředek MongoDBserver s připojením svazku inicializačních dat

Přidání prostředku MongoDBserver s parametry

Přidejte prostředek MongoDB Express

Hostování kontrol stavu integrace

integrace Client

Přidejte MongoDBclient

Přidejte označené MongoDBclient

Konfigurace

Použití připojovacího řetězce

Použití zprostředkovatelů konfigurace

Použijte vložené konfigurace

Možnosti konfigurace

Kontroly stavu

Pozorovatelnost a telemetrie

Protokolování

Trasování

Metriky

Viz také

Další materiály