다음을 통해 공유

.NET Aspire Azure Cosmos DB 통합

  • 아티클

포함:호스팅 통합 및 Client 통합

Azure Cosmos DB 최신 앱 개발을 위한 완전 관리형 NoSQL 데이터베이스 서비스입니다. .NET Aspire Azure Cosmos DB 통합을 사용하면 기존 Cosmos DB 인스턴스에 연결하거나 Azure Cosmos DB 에뮬레이터를 사용하여 .NET 새 인스턴스를 만들 수 있습니다.

호스팅 통합

.NET .NET Aspire Azure Cosmos DB 호스팅 통합은 다양한 Cosmos DB 리소스를 다음과 같은 형식으로 모델화합니다.

이러한 형식과 API에 액세스하여 표현하려면, 앱 호스트 프로젝트에서 📦Aspire.Hosting.Azure.CosmosDB NuGet 패키지를 추가합니다.

dotnet add package Aspire.Hosting.Azure.CosmosDB

자세한 내용은 dotnet add package 또는 .NET 애플리케이션에서 패키지 종속성을 관리하기를 참조하십시오.

Azure Azure Cosmos DB 리소스 추가

앱 호스트 프로젝트에서 AddAzureCosmosDB을 호출하여 AzureAzure Cosmos DB 리소스 작성기를 추가하고 반환합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db");

// After adding all resources, run the app...

앱 호스트에 AzureCosmosDBResource 추가하면 다른 유용한 API를 노출하여 데이터베이스 및 컨테이너를 추가합니다. 즉, AzureCosmosDBResource을(를) 추가한 후에만 다른 Cosmos DB 리소스를 추가해야 합니다.

중요하다

AddAzureCosmosDB호출할 때 암시적으로 AddAzureProvisioning호출합니다. 그러면 앱 시작 중에 Azure 리소스를 동적으로 생성하는 지원이 추가됩니다. 앱은 적절한 구독 및 위치를 구성해야 합니다. 자세한 내용은 로컬 프로비저닝: 구성참조하세요.

생성된 프로비저닝 Bicep

Bicep 에 대해 처음 접하신다면, 이는 Azure 리소스를 정의하기 위한 도메인별 언어입니다. .NET .NET Aspire사용하면 Bicep을 직접 작성할 필요가 없으며 프로비전 API는 Bicep을 생성합니다. 앱을 게시하면 생성된 Bicep이 매니페스트 파일과 함께 출력됩니다. Azure Azure Cosmos DB 리소스를 추가하면 다음과 같은 Bicep 코드가 생성됩니다.


Azure Azure Cosmos DB Bicep을 토글합니다. 

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param keyVaultName string

resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

resource cosmos 'Microsoft.DocumentDB/databaseAccounts@2024-08-15' = {
  name: take('cosmos-${uniqueString(resourceGroup().id)}', 44)
  location: location
  properties: {
    locations: [
      {
        locationName: location
        failoverPriority: 0
      }
    ]
    consistencyPolicy: {
      defaultConsistencyLevel: 'Session'
    }
    databaseAccountOfferType: 'Standard'
  }
  kind: 'GlobalDocumentDB'
  tags: {
    'aspire-resource-name': 'cosmos'
  }
}

resource connectionString 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  name: 'connectionString'
  properties: {
    value: 'AccountEndpoint=${cosmos.properties.documentEndpoint};AccountKey=${cosmos.listKeys().primaryMasterKey}'
  }
  parent: keyVault
}

위의 Bicep은 다음 기본값으로 AzureAzure Cosmos DB 계정을 프로비전하는 모듈입니다.

  • kind: Cosmos DB 계정의 종류입니다. 기본값은 GlobalDocumentDB.
  • consistencyPolicy: Cosmos DB 계정의 일관성 정책입니다. 기본값은 Session.
  • locations: Cosmos DB 계정의 위치입니다. 기본값은 리소스 그룹의 위치입니다.

Cosmos DB 계정 외에도 Azure Key Vault 리소스를 프로비전합니다. Cosmos DB 계정의 연결 문자열을 안전하게 저장하는 데 사용됩니다. 생성된 Bicep은 시작 지점이며 특정 요구 사항을 충족하도록 사용자 지정할 수 있습니다.

프로비저닝 인프라 사용자 지정

모든 .NET AspireAzure 리소스는 AzureProvisioningResource 형식의 하위 클래스입니다. 이 형식을 사용하면 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API를 사용하여 Azure 리소스를 구성하는 흐름 API를 제공하여 생성된 Bicep을 사용자 지정할 수 있습니다. 예를 들어 kind, consistencyPolicy, locations등을 구성할 수 있습니다. 다음 예제에서는 AzureAzure Cosmos DB 리소스를 사용자 지정하는 방법을 보여 줍니다.

builder.AddAzureCosmosDB("cosmos-db")
    .ConfigureInfrastructure(infra =>
    {
        var cosmosDbAccount = infra.GetProvisionableResources()
                                   .OfType<CosmosDBAccount>()
                                   .Single();

        cosmosDbAccount.Kind = CosmosDBAccountKind.MongoDB;
        cosmosDbAccount.ConsistencyPolicy = new()
        {
            DefaultConsistencyLevel = DefaultConsistencyLevel.Strong,
        };
        cosmosDbAccount.Tags.Add("ExampleKey", "Example value");
    });

앞의 코드는 다음과 같습니다.

Azure Azure Cosmos DB 리소스를 사용자 지정하는 데 사용할 수 있는 더 많은 구성 옵션이 있습니다. 자세한 내용은 Azure.Provisioning.CosmosDB참조하세요. 자세한 내용은 Azure을 참조하세요. 프로비전 사용자 지정.

기존 AzureAzure Cosmos DB 계정에 연결

연결하려는 기존 AzureAzure Cosmos DB 계정이 있을 수 있습니다. 새 AzureAzure Cosmos DB 리소스를 나타내는 대신 앱 호스트에 연결 문자열을 추가할 수 있습니다. 기존 AzureAzure Cosmos DB 계정에 연결을 추가하려면 AddConnectionString 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddConnectionString("cosmos-db");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(cosmos);

// After adding all resources, run the app...

메모

연결 문자열은 데이터베이스 연결, 메시지 브로커, 엔드포인트 URI 및 기타 서비스를 비롯한 광범위한 연결 정보를 나타내는 데 사용됩니다. .NET .NET Aspire 명명법에서 "연결 문자열"이라는 용어는 모든 종류의 연결 정보를 나타내는 데 사용됩니다.

연결 문자열은 앱 호스트의 구성에서 구성되며, 일반적으로 ConnectionStrings 섹션의 사용자 비밀아래에 구성됩니다. 앱 호스트는 이 연결 문자열을 환경 변수로 모든 종속 리소스에 삽입합니다. 예를 들면 다음과 같습니다.

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

종속 리소스는 GetConnectionString 메서드를 호출하고 연결 이름을 매개 변수로 전달하여 삽입된 연결 문자열에 액세스할 수 있습니다. 이 경우 "cosmos-db". GetConnectionString API는 IConfiguration.GetSection("ConnectionStrings")[name]의 약어입니다.

Azure Azure Cosmos DB 데이터베이스 리소스 추가

Azure Azure Cosmos DB 데이터베이스 리소스를 추가하려면 IResourceBuilder<AzureCosmosDBResource> 호출을 AddDatabase API에 연결합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .AddDatabase("db");

// After adding all resources, run the app...

AddDatabase호출하면 Cosmos DB 리소스에 db데이터베이스가 있도록 구성됩니다. 데이터베이스는 이전에 추가한 AzureCosmosDBResource이 나타내는 Cosmos DB 계정에 만들어집니다. 데이터베이스는 컬렉션 및 사용자에 대한 논리적 컨테이너입니다. 자세한 내용은 데이터베이스, 컨테이너 및 항목을 AzureAzure Cosmos DB에서 참조하세요.

메모

AddDatabase API를 사용하여 AzureAzure Cosmos DB 리소스에 데이터베이스를 추가하는 경우 에뮬레이터를 실행하는 경우 데이터베이스가 실제로 에뮬레이터에 만들어지지 않습니다. 이 API는 프로비저닝 인프라에서 생성된 Bicep에 데이터베이스를 포함하기 위한 것입니다.

Azure Azure Cosmos DB 에뮬레이터 리소스 추가

Azure Azure Cosmos DB 에뮬레이터 리소스를 추가하려면 IResourceBuilder<AzureCosmosDBResource> 호출을 RunAsEmulator API에 연결합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db")
                    .RunAsEmulator();

// After adding all resources, run the app...

RunAsEmulator호출하면 에뮬레이터를 사용하여 로컬로 실행되도록 Cosmos DB 리소스가 구성됩니다. 이 경우 에뮬레이터는 AzureAzure Cosmos DB 에뮬레이터. Azure Cosmos DB 에뮬레이터는 Azure Cosmos DB 앱을 테스트하기 위한 무료 로컬 환경을 제공하며 .NET AspireAzure 호스팅 통합에 완벽한 동반자입니다. 에뮬레이터는 설치되지 않고 대신 .NET.NET Aspire이(가) 컨테이너로 접근 가능합니다. mcr.microsoft.com/cosmosdb/emulator 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너를 추가하면 앱 호스트가 시작될 때 컨테이너가 만들어지고 시작됩니다. 자세한 내용은 컨테이너 리소스 수명 주기참조하세요.

Cosmos DB 에뮬레이터 컨테이너 구성

컨테이너 리소스에 사용할 수 있는 다양한 구성이 있습니다. 예를 들어 컨테이너의 포트, 환경 변수, 수명등을 구성할 수 있습니다.

Cosmos DB 에뮬레이터 컨테이너 게이트웨이 포트 구성

기본적으로 .NET Aspire에 의해 구성된 경우 Cosmos DB 에뮬레이터 컨테이너는 다음 엔드포인트를 제공합니다.

끝점 컨테이너 포트 호스트 포트
https 8081 동적인

수신 대기 중인 포트는 기본적으로 동적입니다. 컨테이너가 시작되면 포트가 호스트 컴퓨터의 임의 포트에 매핑됩니다. 엔드포인트 포트를 구성하려면 다음 예제와 같이 RunAsEmulator 메서드에서 제공하는 컨테이너 리소스 작성기에서 호출을 연결합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithGatewayPort(7777);
                     });

// After adding all resources, run the app...

앞의 코드는 Cosmos DB 에뮬레이터 컨테이너의 기존 https 엔드포인트를 포트 8081에서 수신하도록 설정합니다. Cosmos DB 에뮬레이터 컨테이너의 포트는 다음 표와 같이 호스트 포트에 매핑됩니다.

엔드포인트 이름 포트 매핑(container:host)
https 8081:7777
영구 수명을 사용하여 Cosmos DB 에뮬레이터 컨테이너 구성

영구 수명을 사용하여 Cosmos DB 에뮬레이터 컨테이너를 구성하려면 Cosmos DB 에뮬레이터 컨테이너 리소스에서 WithLifetime 메서드를 호출하고 ContainerLifetime.Persistent전달합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithLifetime(ContainerLifetime.Persistent);
                     });

// After adding all resources, run the app...

자세한 내용은 컨테이너 리소스 수명참조하세요.

데이터 볼륨을 사용하여 Cosmos DB 에뮬레이터 컨테이너 구성

Azure Azure Cosmos DB 에뮬레이터 리소스에 데이터 볼륨을 추가하려면 AzureAzure Cosmos DB 에뮬레이터 리소스에서 WithDataVolume 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithDataVolume();
                     });

// After adding all resources, run the app...

데이터 볼륨은 컨테이너의 수명 주기 외부에서 Cosmos DB 에뮬레이터 데이터를 유지하는 데 사용됩니다. 데이터 볼륨은 Cosmos DB 에뮬레이터 컨테이너의 /tmp/cosmos/appdata 경로에 탑재되며, name 매개 변수가 제공되지 않을 때 이름이 생성됩니다. 에뮬레이터에는 AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE 환경 변수가 true로 설정되어 있습니다. 데이터 볼륨에 대한 자세한 내용 및 바인딩 탑재보다 선호되는 이유에 대한 자세한 내용은 Docker 문서: 볼륨참조하세요.

Cosmos DB 에뮬레이터 컨테이너 파티션 수 구성

Cosmos DB 에뮬레이터 컨테이너의 파티션 수를 구성하려면 WithPartitionCount 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var cosmos = builder.AddAzureCosmosDB("cosmos-db").RunAsEmulator(
                     emulator =>
                     {
                         emulator.WithPartitionCount(100); // Defaults to 25
                     });

// After adding all resources, run the app...

앞의 코드는 Cosmos DB 에뮬레이터 컨테이너에 100파티션 수를 갖도록 구성합니다. 이는 AZURE_COSMOS_EMULATOR_PARTITION_COUNT 환경 변수를 설정하기 위한 약식입니다.

호스팅 통합 상태 점검

Azure Cosmos DB 호스팅 통합은 Cosmos DB 리소스에 대한 상태 검사를 자동으로 추가합니다. 상태 검사는 Cosmos DB가 실행 중임을 확인하고, 연결이 가능한지를 점검합니다.

호스팅 통합은 📦 AspNetCore.HealthChecks.CosmosDb NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire Azure Cosmos DB client 통합을 시작하려면 📦Aspire설치합니다. Microsoft.Azure. Cosmos는 client-consuming 프로젝트, 즉 Cosmos DBclient사용하는 애플리케이션의 프로젝트에서 NuGet 패키지를. Cosmos DB client 통합은 Cosmos DB와 상호 작용할 수 있도록 하는 CosmosClient 인스턴스를 등록합니다.

dotnet add package Aspire.Microsoft.Azure.Cosmos

Cosmos DB client 추가

client사용 프로젝트의 Program.cs 파일에서, 모든 IHostApplicationBuilder에 대해 AddAzureCosmosClient 확장 메서드를 호출하여, 종속성 주입 컨테이너를 통해 사용할 CosmosClient를 등록합니다. 메서드는 연결 이름 매개 변수를 사용합니다.

builder.AddAzureCosmosClient(connectionName: "cosmos-db");

팁

connectionName 매개 변수는 앱 호스트 프로젝트에서 Cosmos DB 리소스를 추가할 때 사용되는 이름과 일치해야 합니다. 즉, AddAzureCosmosDB를 호출할 때 cosmos-db의 이름을 제공하여야 하며, 그 동일한 이름을 AddAzureCosmosClient를 호출할 때 사용해야 합니다. 자세한 내용은 AzureAzure Cosmos DB 리소스추가를 참조하세요.

그런 다음 종속성 주입을 사용하여 CosmosClient 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 연결을 검색하려면 다음을 수행합니다.

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

종속성 주입에 대한 자세한 내용은 .NET 종속성 주입참조하세요.

키 입력된 Cosmos DBclient 추가

여러 CosmosClient 인스턴스를 서로 다른 연결 이름으로 등록하려는 경우가 있을 수 있습니다. 키 Cosmos DB 클라이언트를 등록하려면 AddKeyedAzureCosmosClient 메서드를 호출합니다.

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

중요하다

키 지정된 서비스를 사용하는 경우, Cosmos DB 리소스가 mainDb 데이터베이스 및 loggingDb데이터베이스용으로 구성된 두 개의 명명된 데이터베이스가 있어야 한다고 기대됩니다.

그런 다음 종속성 주입을 사용하여 CosmosClient 인스턴스를 검색할 수 있습니다. 예를 들어 예제 서비스에서 연결을 검색하려면 다음을 수행합니다.

public class ExampleService(
    [FromKeyedServices("mainDb")] CosmosClient mainDbClient,
    [FromKeyedServices("loggingDb")] CosmosClient loggingDbClient)
{
    // Use clients...
}

키 지정된 서비스에 대한 자세한 내용은 .NET 종속성 주입: 키 지정된 서비스를 참조하세요.

구성

.NET Aspire Azure Cosmos DB 통합은 프로젝트의 요구 사항 및 규칙에 따라 연결을 구성하는 여러 옵션을 제공합니다.

연결 문자열 사용

ConnectionStrings 구성 섹션에서 연결 문자열을 사용하는 경우 AddAzureCosmosClient 메서드를 호출할 때 연결 문자열의 이름을 제공할 수 있습니다.

builder.AddAzureCosmosClient("cosmos-db");

그런 다음 ConnectionStrings 구성 섹션에서 연결 문자열을 검색합니다.

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

이 연결 문자열의 서식을 지정하는 방법에 대한 자세한 내용은 ConnectionString 설명서를 참조하세요.

구성 공급자 사용

.NET Aspire Azure Cosmos DB 통합은 Microsoft.Extensions.Configuration지원합니다. 설정에서 Aspire:Microsoft:Azure:Cosmos 키를 사용하여 MicrosoftAzureCosmosSettings을 로드합니다. 다음 코드 조각은 일부 옵션을 구성하는 appsettings.json 파일의 예입니다.

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

전체 Cosmos DBclient 통합 JSON 스키마는 Aspire참조하세요. Microsoft.Azure. Cosmos/ConfigurationSchema.json.

인라인 대리자 사용

또한 Action<MicrosoftAzureCosmosSettings> configureSettings 대리자를 전달하여 코드에서 추적을 사용하지 않도록 설정하는 등 일부 또는 모든 옵션을 인라인으로 설정할 수 있습니다.

builder.AddAzureCosmosClient(
    "cosmos-db",
    static settings => settings.DisableTracing = true);

Microsoft.Azure.Cosmos.CosmosClientOptions 메서드의 선택적 Action<CosmosClientOptions> configureClientOptions 매개 변수를 사용하여 AddAzureCosmosClient 설정할 수도 있습니다. 예를 들어 이 CosmosClientOptions.ApplicationName모든 요청 문제에 대해 client 사용자 에이전트 헤더 접미사를 설정합니다.

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

Client 통합 상태 검사

기본적으로 .NET.NET Aspire 통합은 모든 서비스에 대한 상태 검사를 사용하도록 설정합니다. 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요.

.NET Aspire Azure Cosmos DB 통합:

  • MicrosoftAzureCosmosSettings.DisableTracing이 false일 때 연결을 시도하는 Cosmos DB에 대한 상태 검사를 추가합니다.
  • /health HTTP 엔드포인트와 통합되어 있으며, 이 엔드포인트는 등록된 모든 상태 검사가 통과해야 앱이 트래픽을 수락할 준비가 된 것으로 간주되도록 지정합니다.

관찰 가능성 및 원격 분석

.NET .NET Aspire 통합은 로깅, 추적 및 메트릭 구성을 자동으로 설정하며, 이를 관찰성의 핵심 요소로 라고도 합니다. 통합 관찰 가능성 및 원격 분석에 대한 자세한 내용은 .NET.NET Aspire 통합 개요참조하세요. 지원 서비스에 따라 일부 통합은 이러한 기능 중 일부만 지원할 수 있습니다. 예를 들어 일부 통합은 로깅 및 추적을 지원하지만 메트릭은 지원하지 않습니다. 구성 섹션에 제시된 기술을 사용하여 원격 분석 기능을 사용하지 않도록 설정할 수도 있습니다.

로깅

.NET Aspire Azure Cosmos DB 통합은 다음 로그 범주를 사용합니다.

  • Azure-Cosmos-Operation-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 추적은 현재 프리뷰 상태이므로, 추적을 내보내기 위해 실험적 스위치를 설정해야 합니다.

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

자세한 내용은 AzureAzure Cosmos DB SDK 관찰 가능성:추적 특성을 참조하세요.

측정지표

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

참고하십시오