.NET Aspire MongoDB 資料庫整合

包括：主機整合 和 Client 整合

MongoDB 是 NoSQL 資料庫，可提供高效能、高可用性和輕鬆的延展性。 .NET Aspire MongoDB 整合可讓您連線到現有的 MongoDB 實例（包括 MongoDB Atlas），或使用 docker.io/library/mongo 容器映射從 .NET 建立新的實例

** 主機整合

裝載整合 MongoDBserver 將 server 模型化為 MongoDBServerResource 類型，並將資料庫模型化為 MongoDBDatabaseResource 類型。 若要存取這些類型和 API，請在 應用程式主機 專案中新增 📦Aspire託管MongoDB NuGet 套件。

.NET CLI

dotnet add package Aspire.Hosting.MongoDB

PackageReference

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

如需詳細資訊，請參閱 dotnet add package 或 管理 .NET 應用程式中的套件相依性。

新增 MongoDBserver 資源和資料庫資源

在您的應用程式主專案中，呼叫 AddMongoDB 以新增並傳回 MongoDBserver 資源產生器。 將傳回的資源產生器呼叫鏈結至 AddDatabase，以新增 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...

注意

MongoDB 容器啟動速度可能很慢，因此最好使用 持續性 存留期，以避免不必要的重新啟動。 如需詳細資訊，請參閱 容器資源存留期。

當 .NET.NET Aspire 將容器映射新增至應用程式主機時，如上述範例中的 docker.io/library/mongo 映射所示，它會在本機計算機上建立新的 MongoDB 實例。 MongoDB server 資源產生器（mongo 變數）的參考可用來新增資料庫。 資料庫名為 mongodb，然後新增至 ExampleProject。 MongoDB server 資源包含預設認證：

• MONGO_INITDB_ROOT_USERNAME是 admin的值。
• MONGO_INITDB_ROOT_PASSWORD：使用 CreateDefaultPasswordParameter 方法產生的隨機 password。

當應用程式主機執行時，密碼會儲存在應用程式主機的秘密存放區中。 它會被新增至 Parameters 區段，例如：

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

參數的名稱是 mongo-password，但實際上只是使用 -password 後綴來格式化資源名稱。 如需詳細資訊，請參閱 開發中應用程式秘密安全儲存的資訊，及 ASP.NET Core 和 使用參數新增 MongoDBserver 資源。

WithReference 方法會在名為 mongodb 的 ExampleProject 中設定連線，WaitFor 會指示應用程式主機在 mongodb 資源就緒之前，不要啟動相依服務。

提示

如果您想要連線到現有的 MongoDBserver，請改為呼叫 AddConnectionString。 如需詳細資訊，請參閱 參考現有資源。

新增包含數據量的 MongoDBserver 資源

若要將數據磁碟區新增至 MongoDBserver 資源，請在 MongoDBserver 資源上呼叫 WithDataVolume 方法：

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

數據磁碟區用來將 MongoDBserver 數據保存在其容器生命週期之外。 資料容量會掛接在 MongoDBserver 容器中的 /data/db 路徑，當未提供 name 參數時，名稱會隨機產生。 如需有關資料卷的更多詳細資訊，以及它們為何優先於 系結掛接，您可以參閱 Docker 文件：磁碟區。

警告

密碼會儲存在數據磁碟區中。 使用數據磁碟區時，如果密碼變更，在刪除磁碟區之前將無法運作。

新增 MongoDBserver 資源，並使用數據綁定掛載

若要將數據系結掛接新增至 MongoDBserver 資源，請呼叫 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...

重要

相較於 磁碟區，數據 系結掛 接的功能有限，可提供更佳的效能、可移植性和安全性，使其更適合生產環境。 不過，綁定掛載允許直接存取和修改主機系統上的檔案，非常適合用於需要即時變更的開發和測試。

數據系結裝載依賴主計算機的檔案系統，在容器重新啟動時保存 MongoDBserver 數據。 數據綁定掛載在主計算機的 C:\MongoDB\Data 路徑上（或 Unix路徑上的 /MongoDB/Data）在 Windows 系統上，位於 MongoDBserver 容器中。 如需資料系結掛接的詳細資訊，請參閱 Docker 檔：系結掛接。

使用初始化數據系結掛接新增 MongoDBserver 資源

若要將初始化資料夾資料系結掛接新增至 MongoDBserver 資源，請呼叫 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...

初始化數據綁定挂載被用來用數據初始化 MongoDBserver。 初始化數據的系結掛接會在 Windows 上的 C:\MongoDB\Init 路徑掛接，並在主機的 MongoDBserver 容器裡的路徑 /MongoDB/InitUnix上掛接，對應至 MongoDBserver 容器中的 /docker-entrypoint-initdb.d 路徑。 MongoDB 會執行此資料夾中找到的腳本，這對於將數據載入資料庫很有用。

使用參數來新增 MongoDBserver 資源

當您想要明確提供容器映像所使用的密碼時，您可以提供這些認證作為參數。 請考慮下列替代範例：

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

如需提供參數的詳細資訊，請參閱外部參數。

新增 MongoDB Express 資源

MongoDB Express 是以 Web 為基礎的 MongoDB 系統管理員使用者介面。 若要新增對應至 docker.io/library/mongo-express 容器映射的 MongoDB Express 資源，請在 MongoDBserver 資源上呼叫 WithMongoExpress 方法：

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

提示

若要設定 MongoExpressContainerResource 主機埠，請呼叫 WithHostPort API，並提供所需的埠號碼。

上述程式代碼會新增已設定為連線至 MongoDBserver 資源的 MongoDB Express 資源。 預設認證如下：

• ME_CONFIG_MONGODB_SERVER：指派給父系 MongoDBServerResource的名稱，在此情況下會是 mongo。
• ME_CONFIG_BASICAUTH：false的值。
• ME_CONFIG_MONGODB_PORT：指派自父系 MongoDBServerResource中主要端點的目標端口。
• ME_CONFIG_MONGODB_ADMINUSERNAME：父 MongoDBServerResource中設定的相同用戶名稱。
• ME_CONFIG_MONGODB_ADMINPASSWORD：與父 MongoDBServerResource中設定的密碼相同。

此外，WithMongoExpress API 會公開一個類型為 Action<IResourceBuilder<MongoExpressContainerResource>> 的選擇性 configureContainer 參數，您可以使用它來設定 MongoDB Express 容器資源。

主機代管整合健康檢查

托管整合 MongoDB 會自動新增 MongoDBserver 資源的健康檢查。 健康檢查會確認 MongoDBserver 資源正在運行，並且可以建立連線。

主機整合依賴 📦 AspNetCore.HealthChecks。MongoDb NuGet 套件。

Client 整合

若要開始使用 .NET AspireMongoDBclient 整合，請在取用 client的專案中安裝 📦AspireMongoDB驅動程式的 NuGet 套件，也就是使用 MongoDBclient的應用程式專案。 MongoDB client 整合會註冊一個 IMongoClient 實例，使您可以用來與 MongoDBserver 資源互動。 如果您的應用程式主機新增 MongoDB 資料庫資源，也會註冊 IMongoDatabase 實例。

.NET CLI

dotnet add package Aspire.MongoDB.Driver

PackageReference

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

新增 MongoDBclient

在 client取用專案的 Program.cs 檔案中，於任何 IHostApplicationBuilder 上呼叫 AddMongoDBClient 擴充方法，註冊一個 IMongoClient，以便透過相依性注入容器來使用。 方法會採用連接名稱參數。

builder.AddMongoDBClient(connectionName: "mongodb");

提示

connectionName 參數必須符合應用程式主專案中新增 MongoDBserver 資源時所使用的名稱（或提供資料庫資源時的名稱）。 換句話說，當您呼叫 AddDatabase 並提供名稱 mongodb 時，在呼叫 AddMongoDBClient時應該使用相同的名稱 mongodb。 如需詳細資訊，請參閱 添加 MongoDBserver 資源，和資料庫資源。

接著，您可以使用依賴注入來擷取 IMongoClient 實體。 例如，若要從某範例服務取得 client：

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

IMongoClient 可用來與 MongoDBserver 資源互動。 它可用來建立應用程式主專案尚未知道的資料庫。 當您在應用程式主機中定義 MongoDB 資料庫資源時，您可以改為要求相依性插入容器提供 IMongoDatabase 實例。 如需相依性插入的詳細資訊，請參閱 .NET 相依性插入。

新增索引鍵 MongoDBclient

在某些情況下，您可能想要以不同的連線名稱註冊多個 IMongoDatabase 實例。 若要註冊 MongoDB 用戶端，請呼叫 AddKeyedMongoDBClient 方法：

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

重要

使用索引鍵服務時，預期您的 MongoDB 資源已設定兩個具名資料庫，一個用於 mainDb，另一個用於 loggingDb。

然後，您可以使用相依性注入來擷取 IMongoDatabase 實例。 例如，若要從範例服務擷取連線：

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

如需索引鍵服務的詳細資訊，請參閱 .NET 相依性插入：索引鍵服務。

配置

.NET Aspire MongoDB 資料庫整合提供多個組態方法和選項，以符合專案的需求和慣例。

使用連接字串

從 [ConnectionStrings 組態] 區段使用連接字串時，您可以在呼叫 builder.AddMongoDBClient()時提供連接字串的名稱：

builder.AddMongoDBClient("mongo");

連接字串是從組態區段 ConnectionStrings 擷取。 請考慮下列 MongoDB 範例 JSON 組態：

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

或者，請考慮下列 MongoDB Atlas 範例 JSON 組態：

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

如需如何格式化此連接字串的詳細資訊，請參閱 MongoDB：ConnectionString 檔案。

使用組態提供者

.NET Aspire MongoDB 整合支援 Microsoft.Extensions.Configuration。 它會使用 Aspire:MongoDB:Driver 鍵從組態載入 MongoDBSettings。 下列代碼段是 appsettings.json 檔案的範例，可設定一些選項：

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

使用內嵌組態

您也可以傳遞 Action<MongoDBSettings> 委派，以內嵌設定部分或所有選項：

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

組態選項

以下是具有對應預設值的可設定選項：

名字	描述
ConnectionString	要連線之 MongoDB 資料庫資料庫的連接字串。
DisableHealthChecks	布林值，用於指示資料庫健康檢查是否已停用。
HealthCheckTimeout	int? 值，指出以毫秒為單位的 MongoDB 健康情況檢查逾時。
DisableTracing	一個布爾值，指示 OpenTelemetry 追蹤是否已停用。

健康檢查

根據預設，.NET.NET Aspire 整合會為所有服務啟用 健康檢查。 如需詳細資訊，請參閱 .NET.NET Aspire 整合概觀。

根據預設，.NET AspireMongoDBclient 整合會處理下列案例：

• 啟用此功能時，會新增健康檢查，以確認能在特定時間內對 MongoDB 資料庫建立連線並執行命令。
• 與 /health HTTP 端點整合，該端點要求所有已註冊的健康檢查必須通過，這樣應用程式才能視為準備好接受流量。

可檢視性和遙測

.NET .NET Aspire 整合會自動設定記錄、追蹤和度量組態，通常稱為 可觀測性支柱。 如需整合可觀察性和遙測的詳細資訊，請參閱 .NET.NET Aspire 整合概觀。 視支援服務而定，某些整合可能只支援其中一些功能。 例如，某些整合支援記錄和追蹤，但不支援計量。 您也可以使用 組態 一節中呈現的技術來停用遙測功能。

伐木

.NET Aspire MongoDB 資料庫整合使用標準 .NET 記錄，您會看到來自下列類別的日誌條目：

• MongoDB[.*]：來自 MongoDB 命名空間的任何記錄專案。

追蹤

.NET Aspire MongoDB 資料庫整合會使用 OpenTelemetry發出下列追蹤活動：

• MongoDB.Driver.Core.Extensions.DiagnosticSources

指標

.NET Aspire MongoDB 資料庫整合目前不會公開任何 OpenTelemetry 計量。

另請參閱

• MongoDB 資料庫
• .NET .NET Aspire 整合
• .NET Aspire GitHub 存放庫