integrace databáze .NET AspireMongoDB

2025-06-11

Zahrnuje:Včetně integrace hostování Integrace hostování —&— integrace zahrnuta integrace

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í

Server MongoDB, který hostuje integraci, je modelován jako typ MongoDBServerResource, a databáze 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
Odkaz na balíček

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řidání prostředku serveru MongoDB a databázového prostředku

V hostitelském projektu aplikace zavolejte AddMongoDB, abyste přidali a vrátili konfigurační objekt serveru MongoDB. 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 MongoDB tvůrce prostředků serveru ( mongo proměnná). Databáze se jmenuje mongodb a pak se přidá do ExampleProject. Prostředek MongoDB serveru 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 a ASP.NET Core přidání MongoDB prostředku serveru 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 serveru MongoDB, volejte místo toho AddConnectionString. Pro více informací viz Odkazy na existující prostředky.

Přidejte serverový prostředek MongoDB s datovým objemem

Chcete-li přidat datový objem do serverového prostředku MongoDB, použijte metodu WithDataVolume na serverovém prostředku MongoDB:

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

Datový svazek slouží k zachování dat serveru MongoDB mimo životní cyklus kontejneru. Datový svazek se připojí k cestě /data/db v kontejneru serveru MongoDB 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.

Důležitý

Některé integrace databází, včetně integrace .NET AspireMongoDB, nemůžou úspěšně používat datové svazky po nasazení do Azure Container Apps (ACA). Důvodem je to, že ACA používá Server k připojení kontejnerů ke svazkům dat protokol SMB (Message Block) a některé systémy toto připojení nemůžou používat. Na řídicím panelu Aspire má databáze ovlivněná tímto problémem stav Aktivace nebo Selhání aktivace , ale nikdy není uvedená jako Spuštěná.

Problém můžete vyřešit nasazením do clusteru Kubernetes, například do služeb AzureKubernetes (AKS). Další informace viz nasazení .NET.NET Aspire.

Přidání prostředku serveru MongoDB s připojením datového úložiště

Pokud chcete přidat data bind mount k prostředku serveru MongoDB, 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 spoléhají na systém souborů hostitelského počítače k zachování dat serveru MongoDB po celou dobu restartování kontejneru. Datový připojovací bod je připojen na cestu C:\MongoDB\Data v systému Windows (nebo /MongoDB/Data na Unix) na hostitelském počítači v serverovém kontejneru MongoDB. Další informace o připojeních datových vazeb najdete v dokumentaci Docker: Připojení vazby.

Přidání MongoDB prostředku serveru s připojením inicializačních dat

Chcete-li přidat připojení datové inicializační složky k prostředku serveru MongoDB jako bind mount, 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...

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

Přidejte prostředek serveru MongoDB 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 MongoDB prostředek Express, který odpovídá docker.io/library/mongo-express obrazu kontejneru, zavolejte metodu WithMongoExpress na prostředku serveru MongoDB.

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á MongoDB prostředek Express, který je nakonfigurovaný pro připojení k MongoDB prostředku serveru. 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ává kontrolu stavu pro serverový prostředek MongoDB. Zdravotní kontrola ověřuje, že prostředek serveru MongoDB je spuštěný a že k němu lze navázat připojení.

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

integrace Client

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

.NET rozhraní příkazového řádku
Odkaz na balíček

dotnet add package Aspire.MongoDB.Driver

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

Důležitý

Balíček NuGet Aspire.MongoDB.Driver závisí na MongoDB.Driver balíčku NuGet. S vydáním verze 3.0.0 produktu MongoDB.Driver byla zavedena zásadní změna narušující binární kompatibilitu. Pro vyřešení tohoto řešení byl vytvořen nový integrační balíček klienta Aspire.MongoDB.Driver.v3. Původní Aspire.MongoDB.Driver balíček nadále odkazuje na MongoDB.Driver verzi 2.30.0 a zajišťuje kompatibilitu s předchozími verzemi RabbitMQ integrace klienta. Aspire.MongoDB.Driver.v3 Nový balíček odkazuje na MongoDB.Driver verzi 3.0.0. V budoucí verzi .NET.NET Aspirese Aspire.MongoDB.Driver aktualizuje na verzi 3.x a balíček Aspire.MongoDB.Driver.v3 bude zastaralý. Další informace najdete v tématu Upgrade na verzi 3.0.

Přidejte klienta MongoDB

V souboru Program.cs klientského projektu zavolejte metodu rozšíření AddMongoDBClient na libovolném IHostApplicationBuilder a zaregistrujte IMongoClient pro použití prostřednictvím kontejneru injekce 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í MongoDB prostředku serveru (nebo databázového zdroje, pokud je zadaný) 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í prostředku serveru MongoDB a databázového prostředku.

Potom můžete získat instanci IMongoClient pomocí injekce závislostí. Například pro získání klienta z ukázkové služby:

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

IMongoClient se používá k interakci se serverovým zdrojem MongoDB. 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 klienta MongoDB s klíčem

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.

Client testy stavu integrace

Ve výchozím nastavení mají .NET.NET Aspireklientské integracekontroly stavu povoleny pro všechny služby. Podobně mnoho .NET.NET Aspirehostovacích integrací také povoluje koncové body kontroly stavu. Další informace najdete tady:

Integrace klienta ve výchozím nastavení .NET AspireMongoDB 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řidání prostředku serveru MongoDB a databázového prostředku

Přidejte serverový prostředek MongoDB s datovým objemem

Přidání prostředku serveru MongoDB s připojením datového úložiště

Přidání MongoDB prostředku serveru s připojením inicializačních dat

Přidejte prostředek serveru MongoDB s parametry

Přidejte prostředek MongoDB Express

Hostování kontrol stavu integrace

integrace Client

Přidejte klienta MongoDB

Přidejte klienta MongoDB s klíčem

Konfigurace

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

Použití zprostředkovatelů konfigurace

Použijte vložené konfigurace

Možnosti konfigurace

Client testy stavu integrace

Pozorovatelnost a telemetrie

Protokolování

Trasování

Metriky

Viz také

Váš názor

Další materiály