.NET Aspire Azure Cosmos DB 整合

發行項
12/15/2024

在本文中，您將瞭解如何使用 .NET AspireAzure Cosmos DB 整合。 Aspire.Microsoft.Azure.Cosmos 連結庫可用來將 CosmosClient 註冊為 DI 容器中的單一連結庫，以連線到 AzureAzure Cosmos DB。它也會啟用相應的健康檢查、日誌記錄與數據遙測。

開始使用

若要開始使用 .NET AspireAzure Cosmos DB 整合，請在 client-consuming 專案中安裝 📦AspireMicrosoftAzure的 Cosmos NuGet 套件，也就是用於實施 Azure Cosmos DBclient的應用程式專案。

.NET CLI
PackageReference

dotnet add package Aspire.Microsoft.Azure.Cosmos

<PackageReference Include="Aspire.Microsoft.Azure.Cosmos"
                  Version="*" />

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

範例使用方式

在 client取用專案的 Program.cs 檔案中，呼叫 AddAzureCosmosClient 擴充功能，註冊 Microsoft.Azure.Cosmos.CosmosClient，透過相依性注入容器來使用。

builder.AddAzureCosmosClient("cosmosConnectionName");

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

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

如需使用的詳細資訊，請參閱適用於之 NoSQL SDK 的範例。

應用程式主機使用方式

若要將 AzureAzure Cosmos DB 主機支援新增至您的 IDistributedApplicationBuilder，請在應用程式主機專案中安裝 📦Aspire.Hosting.Azure.CosmosDB NuGet 套件。如果您想要 Aspire 為您布建新的 Azure Cosmos DB 帳戶，或是想要使用 Azure Cosmos DB 模擬器，這會很有幫助。如果您想要使用已布建的 AzureAzure Cosmos DB 帳戶，就不需要將它新增至應用程式主機專案。

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.CosmosDB

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

在應用程式主機專案中，註冊 .NET AspireAzure Cosmos DB 整合，並使用下列方法取用服務：

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("myNewCosmosAccountName");
var cosmosdb = cosmos.AddDatabase("myCosmosDatabaseName");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cosmosdb);

提示

若要使用 AzureAzure Cosmos DB 模擬器，請將呼叫鏈結至 AddAzureCosmosDB 方法。

cosmosdb.RunAsEmulator();

啟動 Cosmos DB 模擬器可能需要一些時間。使用 WaitFor 延遲 .NET 專案的程式代碼執行，直到模擬器執行並準備好提供要求為止。

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(cosmosdb)
                            .WaitFor(cosmosdb);

配置

.NET Aspire Azure Cosmos DB 連結庫提供多個選項，根據專案的需求和慣例來設定 CosmosClient 連線。

使用連接字串

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

builder.AddAzureCosmosClient("cosmosConnectionName");

然後，連接字串將會從 [ConnectionStrings 組態] 區段擷取：

{
  "ConnectionStrings": {
    "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
  }
}

建議的連線方法是使用帳戶端點，其可與 MicrosoftAzureCosmosSettings.Credential 屬性搭配使用，以建立聯機。如果未設定認證，則會使用 DefaultAzureCredential：

{
    "ConnectionStrings": {
      "cosmosConnectionName": "https://{account_name}.documents.azure.com:443/"
    }
}

或者，也可以使用 AzureAzure Cosmos DB 連接字串：

{
    "ConnectionStrings": {
    "cosmosConnectionName": "AccountEndpoint=https://{account_name}.documents.azure.com:443/;AccountKey={account_key};"
    }
}

使用組態提供者

.NET Aspire Azure Cosmos DB 整合支援 Microsoft.Extensions.Configuration。它會使用 Aspire:Microsoft:Azure:Cosmos 金鑰，從 appsettings.json 或其他組態檔載入 MicrosoftAzureCosmosSettings。設定選項的範例 appsettings.json：

{
  "Aspire": {
    "Microsoft": {
      "Azure": {
        "Cosmos": {
          "DisableTracing": false,
        }
      }
    }
  }
}

使用內聯委派

您也可以傳遞 Action<MicrosoftAzureCosmosSettings > 委派來設定部分或所有內嵌選項，例如停用程式代碼追蹤：

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    static settings => settings.DisableTracing = true);

您也可以使用 AddAzureCosmosClient 方法的選擇性 Action<CosmosClientOptions> configureClientOptions 參數來設定 Microsoft.Azure.Cosmos.CosmosClientOptions。例如，要為此 client發出的所有要求設定 CosmosClientOptions.ApplicationName 用戶代理標頭後綴：

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => clientOptions.ApplicationName = "myapp");

健康檢查

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

.NET Aspire Azure Cosmos DB 整合目前不會實作健康情況檢查，不過未來版本可能會變更。

可檢視性和遙測

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

伐木

.NET Aspire Azure Cosmos DB 整合會使用下列記錄類別：

Azure-宇宙行動-Request-Diagnostics

除了取得失敗要求 Azure Cosmos DB 的診斷之外，您還可以設定延遲閾值，以決定哪些成功的 Azure Cosmos DB 診斷將被記錄。點作業的預設值為 100 毫秒，非點作業的預設值為 500 毫秒。

builder.AddAzureCosmosClient(
    "cosmosConnectionName",
    configureClientOptions:
        clientOptions => {
            clientOptions.CosmosClientTelemetryOptions = new()
            {
                CosmosThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

追蹤

.NET Aspire Azure Cosmos DB 整合將會使用 OpenTelemetry產生以下追蹤活動：

Azure。Cosmos.Operation

Azure Azure Cosmos DB 追蹤目前處於預覽狀態，因此您必須將實驗性開關設成開啟，以確保發出追蹤。深入瞭解 AzureAzure Cosmos DB中的追蹤。

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

指標

.NET Aspire Azure Cosmos DB 整合目前預設不支援計量，因為 Azure SDK 的限制。

共用方式為