.NET Aspire MongoDB 資料庫整合

包括：主機整合 和 Client 整合

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

** 主機整合

整合模型的 MongoDB 伺服器將伺服器視為 MongoDBServerResource 類型，並將資料庫視為 MongoDBDatabaseResource 類型。 若要存取這些類型和 API，請在 📦 專案中新增 AspireMongoDB託管 NuGet 套件。

.NET CLI

dotnet add package Aspire.Hosting.MongoDB

PackageReference

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

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

新增 MongoDB 伺服器資源和資料庫資源

在應用程式主機專案中，呼叫 AddMongoDB 以新增並傳回 MongoDB 伺服器資源產生器。 將傳回的資源產生器呼叫鏈結至 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 伺服器資源產生器（mongo 變數）的參考是用來新增資料庫的。 資料庫名為 mongodb，然後新增至 ExampleProject。 MongoDB 伺服器資源包含預設認證：

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

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

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

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

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

提示

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

使用數據量新增 MongoDB 伺服器資源

若要將數據磁碟區新增至 MongoDB 伺服器資源，請在 MongoDB 伺服器資源上呼叫 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...

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

警告

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

使用數據系結掛接新增 MongoDB 伺服器資源

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

重要

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

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

使用初始化數據系結掛接新增 MongoDB 伺服器資源

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

初始化資料綁定掛載是用來初始化 MongoDB 伺服器的資料。 初始化數據綁定掛載在 Windows 的 C:\MongoDB\Init 路徑（或 Unix上的 /MongoDB/Init 路徑），位於主機上的 MongoDB 伺服器容器中，並映射到 MongoDB 伺服器容器中的 /docker-entrypoint-initdb.d 路徑。 MongoDB 會執行此資料夾中找到的腳本，這對於將數據載入資料庫很有用。

使用參數新增 MongoDB 伺服器資源

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

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 資源，請在 MongoDB 伺服器資源上呼叫 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，並提供所需的埠號碼。

上述程式代碼會新增 MongoDB Express 資源，其設定為連線到 MongoDB 伺服器資源。 預設認證如下：

• 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 會公開一個類型為 configureContainer 的選擇性 Action<IResourceBuilder<MongoExpressContainerResource>> 參數，您可以使用它來設定 MongoDB Express 容器資源。

主機代管整合健康檢查

MongoDB 的主機整合會自動為 MongoDB 伺服器資源新增健康檢查。 健康檢查會驗證 MongoDB 伺服器資源正在運行，並且可以建立連線。

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

Client 整合

若要開始進行 .NET AspireMongoDB 用戶端整合，請在用戶端消費專案，也就是使用 MongoDB 用戶端的應用程式專案中，安裝 📦AspireMongoDB驅動程式 的 NuGet 套件。 MongoDB 用戶端整合會註冊可用來與 MongoDB 伺服器資源互動的 IMongoClient 實例。 如果您的應用程式主機新增 MongoDB 資料庫資源，也會註冊 IMongoDatabase 實例。

.NET CLI

dotnet add package Aspire.MongoDB.Driver

PackageReference

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

新增 MongoDB 用戶端

在用戶端消費端專案的 Program.cs 檔案中，呼叫任何 IHostApplicationBuilder 上的 AddMongoDBClient 擴充方法，來註冊 IMongoClient，以便透過依賴注入容器使用。 方法會採用連接名稱參數。

builder.AddMongoDBClient(connectionName: "mongodb");

提示

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

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

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

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

新增索引鍵 MongoDB 用戶端

在某些情況下，您可能想要以不同的連線名稱註冊多個 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。 它會使用 MongoDBSettings 鍵從組態載入 Aspire:MongoDB:Driver。 下列代碼段是 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 AspireMongoDB 用戶端整合會處理下列案例：

• 啟用此功能時，會新增健康檢查，以確認能在特定時間內對 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 存放庫