.NET Aspire Azure Queue Storage 통합

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

Azure Queue Storage 인증된 호출을 통해 전 세계 어디에서나 액세스할 수 있는 많은 수의 메시지를 저장하는 서비스입니다. .NET Aspire Azure Queue Storage 통합을 사용하면 기존 Azure Queue Storage 인스턴스에 연결하거나 .NET 애플리케이션에서 새 인스턴스를 만들 수 있습니다.

호스팅 통합

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

• AzureStorageResource: Azure Storage 리소스를 나타냅니다.
• AzureStorageEmulatorResource: Azure Storage 에뮬레이터 리소스(Azurite)를 나타냅니다.
• AzureBlobStorageResource: Azure Blob 스토리지 리소스를 나타냅니다.
• AzureQueueStorageResource: Azure 큐 스토리지 리소스를 나타냅니다.
• AzureTableStorageResource: Azure 테이블 스토리지 리소스를 나타냅니다.

이러한 형식 및 API에 액세스하려면 📦 프로젝트에 AspireAzure호스팅 및스토리지 NuGet 패키지를 추가하십시오.

dotnet add package Aspire.Hosting.Azure.Storage

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

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

Azure Storage 리소스 추가

앱 호스트 프로젝트에서 AddAzureStorage을 호출하여 Azure Storage 리소스 작성기를 추가한 후 반환합니다.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");

// An Azure Storage resource is required to add any of the following:
//
// - Azure Blob storage resource.
// - Azure Queue storage resource.
// - Azure Table storage resource.

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

앱 호스트에 AzureStorageResource 추가하면 다른 유용한 API를 노출하여 blob, 큐 및 Table Storage 리소스를 Azure 추가합니다. 즉, 다른 스토리지 리소스를 추가하기 전에 AzureStorageResource 추가해야 합니다.

생성된 프로비저닝 Bicep

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

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

param principalId string

param principalType string

resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
  name: take('storage${uniqueString(resourceGroup().id)}', 24)
  kind: 'StorageV2'
  location: location
  sku: {
    name: 'Standard_GRS'
  }
  properties: {
    accessTier: 'Hot'
    allowSharedKeyAccess: false
    minimumTlsVersion: 'TLS1_2'
    networkAcls: {
      defaultAction: 'Allow'
    }
  }
  tags: {
    'aspire-resource-name': 'storage'
  }
}

resource blobs 'Microsoft.Storage/storageAccounts/blobServices@2024-01-01' = {
  name: 'default'
  parent: storage
}

resource storage_StorageBlobDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageTableDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3')
    principalType: principalType
  }
  scope: storage
}

resource storage_StorageQueueDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(storage.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '974c5e8b-45b9-4653-ba55-5f855dd0fb88')
    principalType: principalType
  }
  scope: storage
}

output blobEndpoint string = storage.properties.primaryEndpoints.blob

output queueEndpoint string = storage.properties.primaryEndpoints.queue

output tableEndpoint string = storage.properties.primaryEndpoints.table

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

• kind: 스토리지 계정의 종류입니다. 기본값은 StorageV2.
• sku: 스토리지 계정의 SKU입니다. 기본값은 Standard_GRS.
• properties: 스토리지 계정의 속성:
  • accessTier: 스토리지 계정의 액세스 계층입니다. 기본값은 Hot.
  • allowSharedKeyAccess: 스토리지 계정에서 계정 액세스 키를 사용하여 요청을 승인하도록 허용하는지 여부를 나타내는 부울 값입니다. 기본값은 false.
  • minimumTlsVersion: 스토리지 계정에 대해 지원되는 최소 TLS 버전입니다. 기본값은 TLS1_2.
  • networkAcls: 스토리지 계정의 네트워크 ACL입니다. 기본값은 { defaultAction: 'Allow' }.

스토리지 계정 외에도 Blob 컨테이너를 프로비전합니다.

애플리케이션 액세스 권한을 부여하기 위해 스토리지 계정에 다음 역할 할당이 추가됩니다. 자세한 내용을 보려면 기본 제공 Azure 역할 기반 액세스 제어(Azure RBAC) 역할을/를 참조하세요.

생성된 Bicep은 시작 지점이며 특정 요구 사항을 충족하도록 사용자 지정할 수 있습니다.

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

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

builder.AddAzureStorage("storage")
    .ConfigureInfrastructure(infra =>
    {
        var storageAccount = infra.GetProvisionableResources()
                                  .OfType<StorageAccount>()
                                  .Single();

        storageAccount.AccessTier = StorageAccountAccessTier.Cool;
        storageAccount.Sku = new StorageSku { Name = StorageSkuName.PremiumZrs };
        storageAccount.Tags.Add("ExampleKey", "Example value");
    });

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

• ConfigureInfrastructure API에 대한 호출을 연결합니다.
  • infra 매개 변수는 AzureResourceInfrastructure 형식의 인스턴스입니다.
  • 프로비전 가능한 리소스는 GetProvisionableResources() 메서드를 호출하여 검색됩니다.
  • 단일 StorageAccount 검색됩니다.
  • StorageAccount.AccessTier는 StorageAccountAccessTier.Cool에 할당된다.
  • StorageAccount.Sku는 StorageSku의 Name를 가진 새 PremiumZrs에 할당됩니다.
  • 태그는 ExampleKey 키와 Example value값을 사용하여 스토리지 계정에 추가됩니다.

Azure Storage 리소스를 사용자 지정하는 데 사용할 수 있는 더 많은 구성 옵션이 있습니다. 자세한 내용은 Azure.Provisioning.Storage참조하세요.

기존 Azure Storage 계정에 연결

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

var builder = DistributedApplication.CreateBuilder(args);

var blobs = builder.AddConnectionString("blobs");

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

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

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

{
    "ConnectionStrings": {
        "blobs": "https://{account_name}.blob.core.windows.net/"
    }
}

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

Azure Storage 에뮬레이터 리소스 추가

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

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage")
                     .RunAsEmulator();

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

RunAsEmulator호출하면 에뮬레이터를 사용하여 로컬로 실행되도록 스토리지 리소스가 구성됩니다. 이 경우 에뮬레이터는 "Azurite"입니다. Azurite 오픈 소스 에뮬레이터는 Azure Blob, Queue Storage 및 Table Storage 앱을 테스트하기 위한 무료 로컬 환경을 제공하며 .NET AspireAzure 호스팅 통합에 완벽한 동반자입니다. Azurite는 설치되지 않고 컨테이너로 .NET.NET Aspire에서 사용할 수 있습니다. mcr.microsoft.com/azure-storage/azurite 이미지와 함께 이전 예제와 같이 앱 호스트에 컨테이너를 추가하면 앱 호스트가 시작될 때 컨테이너가 만들어지고 시작됩니다. 자세한 내용은 컨테이너 리소스 수명 주기참조하세요.

Azurite 컨테이너 구성

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

Azurite 컨테이너 포트 구성

기본적으로 .NET.NET Aspire구성된 Azurite 컨테이너는 다음 엔드포인트를 노출합니다.

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

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithBlobPort("blob", 27000)
                                .WithQueuePort("queue", 27001)
                                .WithTablePort("table", 27002);
                     });

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

앞의 코드는 포트 blob, queue및 table각각 수신 대기하도록 Azurite 컨테이너의 기존 27000, 27001및 27002 엔드포인트를 구성합니다. Azurite 컨테이너의 포트는 다음 표와 같이 호스트 포트에 매핑됩니다.

지속적인 수명을 사용하여 Azurite 컨테이너를 구성하기

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

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithLifetime(ContainerLifetime.Persistent);
                     });

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

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

데이터 볼륨을 사용하여 Azurite 컨테이너 구성

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

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataVolume();
                     });

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

데이터 볼륨은 Azurite 데이터를 컨테이너의 수명 주기 외부에 유지하는 데 사용됩니다. 데이터 볼륨은 Azurite 컨테이너의 /data 경로에 탑재되고 name 매개 변수가 제공되지 않으면 이름은 .azurite/{resource name}형식으로 지정됩니다. 데이터 볼륨에 대한 자세한 내용 및바인딩 탑재보다 선호하는 이유에 대한 자세한 내용은 문서: 볼륨참조하세요.

데이터 바인드 마운트를 사용하여 Azurite 컨테이너 구성

Azure Storage 에뮬레이터 리소스에 데이터 바인딩 탑재를 추가하려면 WithDataBindMount 메서드를 호출합니다.

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage").RunAsEmulator(
                     azurite =>
                     {
                         azurite.WithDataBindMount("../Azurite/Data");
                     });

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

데이터 바인드 마운트는 컨테이너 재시작 시 Azurite 데이터를 지속시키기 위해 호스트 컴퓨터의 파일 시스템을 사용합니다. 호스트 머신의 ../Azurite/Data 경로에 데이터 바인드 마운트가 Azurite 컨테이너의 앱 호스트 디렉터리(IDistributedApplicationBuilder.AppHostDirectory)를 기준으로 탑재됩니다. 데이터 바인드 마운트에 대한 자세한 내용은 Docker 문서: 바인드 마운트를 참조하세요.

스토리지 리소스에 연결

.NET .NET Aspire 앱 호스트가 실행되면 Azure Storage Explorer같은 외부 도구에서 스토리지 리소스에 액세스할 수 있습니다. 스토리지 리소스가 Azurite를 사용하여 로컬에서 실행되는 경우 Azure Storage Explorer가 이를 자동으로 감지합니다.

Azure Storage Explorer에서 스토리지 리소스에 연결하려면 다음 단계를 수행합니다.

1. .NET .NET Aspire 앱 호스트를 실행합니다.

2. Azure Storage Explorer를 엽니다.

3. 탐색기 패널을 봅니다.

4. Refresh all 링크를 선택하여 스토리지 계정 목록을 새로 고치세요.

5. 에뮬레이터 & 연결된 노드를 확장합니다.

6. Storage 계정 노드를 확장합니다.

7. 리소스 이름을 접두사로 사용하는 스토리지 계정이 표시됩니다.

   

Azure Storage Explorer를 사용하여 저장소 계정 및 해당 콘텐츠를 자유롭게 탐색할 수 있습니다. Azure Storage Explorer 사용에 대한 자세한 내용은 Storage Explorer시작하기를 참조하세요.

Azure Queue Storage 리소스 추가

앱 호스트 프로젝트에서, Azure에 의해 반환된 AddQueues 인스턴스에 IResourceBuilder<IAzureStorageResource> 호출을 연결해 AddAzureStorage Queue Storage 통합을 등록합니다. 다음 예제에서는 Azure Queue Storage 리소스와 storageQueue 리소스라는 이름의 queues을 추가하는 방법을 보여 줍니다.

var builder = DistributedApplication.CreateBuilder(args);

var queues = builder.AddAzureStorage("storage")
                    .AddQueues("queues");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(queues);

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

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

• Azure이라는 storage Storage 리소스를 추가합니다.
• queues 큐를 스토리지 리소스에 추가합니다.
• storage 리소스를 ExampleProject에 추가한 후, 프로젝트를 시작하기 전에 준비될 때까지 기다립니다.

통합 건강 상태 점검 호스팅

Azure Storage 호스팅 통합은 스토리지 리소스에 대한 상태 검사를 자동으로 추가합니다. 에뮬레이터로 실행하는 경우에만 추가되며 Azurite 컨테이너가 실행 중이고 연결이 설정될 수 있는지 확인합니다. 호스팅 통합은 📦 AspNetCore.HealthChecks와Azure.Storage.Blobs NuGet 패키지에 의존합니다.

Client 통합

.NET Aspire Azure Queue Storage client 통합을 시작하려면 client, 즉 Azure Queue Storage client사용하는 애플리케이션에 대한 프로젝트입니다. Azure Queue Storage client 통합은 QueueServiceClient Queue Storage와 상호 작용하는 데 사용할 수 있는 Azure 인스턴스를 등록합니다.

dotnet add package Aspire.Azure.Storage.Queues

<PackageReference Include="Aspire.Azure.Storage.Queues"
                  Version="*" />

Azure Queue Storage client 추가

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

builder.AddAzureQueueClient("queue");

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

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

구성 설정

.NET Aspire Azure Queue Storage 통합은 프로젝트의 요구 사항 및 규칙에 따라 QueueServiceClient를 구성하기 위한 여러 옵션을 제공합니다.

연결 문자열 사용

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

builder.AddAzureQueueClient("queue");

그런 다음 ConnectionStrings 구성 섹션에서 연결 문자열을 검색하고 두 개의 연결 형식이 지원됩니다.

서비스 URI

권장되는 방법은 ServiceUri 속성과 함께 작동하는 AzureStorageQueuesSettings.Credential사용하여 연결을 설정하는 것입니다. 자격 증명이 구성되지 않은 경우 Azure.Identity.DefaultAzureCredential 사용됩니다.

{
  "ConnectionStrings": {
    "queue": "https://{account_name}.queue.core.windows.net/"
  }
}

연결 문자열

또는 Azure 저장소 연결 문자열를 사용할 수 있습니다.

{
  "ConnectionStrings": {
    "queue": "AccountName=myaccount;AccountKey=myaccountkey"
  }
}

자세한 내용은 Azure Storage 연결 문자열구성을 참조하세요.

구성 공급자 사용

.NET Aspire Azure Queue Storage 통합은 Microsoft.Extensions.Configuration기능을 지원합니다. AzureStorageQueuesSettings 키를 사용하여 구성에서 QueueClientOptions 및 Aspire:Azure:Storage:Queues 로드합니다. 다음 코드 조각은 일부 옵션을 구성하는 appsettings.json 파일의 예입니다.

{
  "Aspire": {
    "Azure": {
      "Storage": {
        "Queues": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

전체 Azure Storage Queuesclient 통합 JSON 스키마는 Aspire참조하십시오.Azure.Data.Queues/ConfigurationSchema.json.

인라인 대리자 사용

Action<AzureStorageQueuesSettings> configureSettings 대리자를 전달하여 상태 검사를 구성하는 등 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다.

builder.AddAzureQueueClient(
    "queue",
    settings => settings.DisableHealthChecks = true);

QueueClientOptions 메서드의 두 번째 매개 변수인 Action<IAzureClientBuilder<QueueServiceClient, QueueClientOptions>> configureClientBuilder 대리자를 사용하여 AddAzureQueueClient 설정할 수도 있습니다. 예를 들어 이 client모든 요청 문제에 대한 사용자 에이전트 헤더의 첫 번째 부분을 설정하려면 다음을 수행합니다.

builder.AddAzureQueueClient(
    "queue",
    configureClientBuilder: clientBuilder =>
        clientBuilder.ConfigureOptions(
            options => options.Diagnostics.ApplicationId = "myapp"));

Client 통합 상태 검사

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

.NET Aspire Azure 큐 스토리지 통합:

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

관찰 가능성 및 원격 분석

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

로깅

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

• Azure.Core
• Azure.Identity

추적

.NET Aspire Azure Queue Storage 통합은 OpenTelemetry를 사용하여 다음 추적 활동을 발생시킨다.

• Azure.Storage.Queues.QueueClient

메트릭

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

참조

• Azure 큐 스토리지 문서
• .NET .NET Aspire 통합
• .NET Aspire GitHub 리포지토리