.NET Aspire Azure Cosmos DB 통합

아티클
12/15/2024

이 문서에서는 .NET AspireAzure Cosmos DB 통합을 사용하는 방법을 알아봅니다. Aspire.Microsoft.Azure.Cosmos 라이브러리는 AzureAzure Cosmos DB연결하기 위해 DI 컨테이너에서 CosmosClient 싱글톤으로 등록하는 데 사용됩니다. 또한 관련 상태 검사, 로깅 및 원격 분석을 사용하도록 설정합니다.

시작

.NET Aspire Azure Cosmos DB 통합을 시작하려면 📦Aspire설치합니다. Microsoft.Azure. Cosmos는 client사용 중인 프로젝트, 즉 Azure Cosmos DBclient사용하는 애플리케이션에 대한 프로젝트의 NuGet 패키지를.

.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의 에 대한 예제를 참조하세요.

앱 호스트 사용

Azure Azure Cosmos DB 호스팅 지원을 IDistributedApplicationBuilder에 추가하려면, 📦Aspire호스팅 패키지와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);

팁

Azure Azure 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 요청 진단이 기록될지 결정할 수 있습니다. 기본값은 지점 작업의 경우 100ms, 지점이 아닌 작업의 경우 500ms입니다.

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 추적은 현재 프리뷰 상태이므로, 추적을 내보내기 위해 실험적 스위치를 설정해야 합니다. Azure Azure Cosmos DB추적에 대해 자세히 알아봅니다.

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

측정지표

.NET Aspire Azure Cosmos DB 통합은 현재 Azure SDK의 제한 사항으로 인해 기본적으로 메트릭을 지원하지 않습니다.

다음을 통해 공유