.NET Aspire Azure Service Bus 통합

아티클
12/15/2024

클라우드 네이티브 앱에는 Azure Service Bus같은 메시징 서비스와의 통신이 필요한 경우가 많습니다. 메시징 서비스는 애플리케이션을 분리하고 큐, 토픽 및 구독, 원자성 트랜잭션, 부하 분산 등의 기능을 사용하는 시나리오를 가능하게 합니다. .NET Aspire Service Bus 통합은 앱을 Azure Service Bus에 연결하면서 다음과 같은 이슈를 처리합니다.

DI 컨테이너에 ServiceBusClient가 Azure Service Bus에 연결되도록 등록됩니다.
코드를 통해 또는 구성 파일 설정을 통해 인라인으로 ServiceBusClient 구성을 적용합니다.

필수 구성 요소

Azure 구독 - 무료로 하나 만들기
네임스페이스를 Service Bus 네임스페이스추가하는 방법에 대해 자세히 알아봅니다. 또는 프로덕션 환경에서 권장되지 않는 연결 문자열을 사용할 수 있습니다.

시작

.NET Aspire Azure Service Bus 통합을 시작하려면 📦Aspire.Azure.Messaging.ServiceBus NuGet 패키지를 Azure Service Busclient를 사용하는 애플리케이션의 프로젝트, 즉 client-consuming 프로젝트에 설치합니다.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

<PackageReference Include="Aspire.Azure.Messaging.ServiceBus"
                  Version="*" />

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

예제 사용

client을(를) 사용하는 프로젝트의 Program.cs 파일에서 AddAzureServiceBusClient 확장을 호출하여, 종속성 주입 컨테이너를 통해 사용할 ServiceBusClient을(를) 등록합니다.

builder.AddAzureServiceBusClient("messaging");

종속성 주입을 사용하여 구성된 ServiceBusClient 인스턴스를 검색하려면 생성자 매개 변수로 필요합니다. 예를 들어 예제 서비스에서 client 검색하려면 다음을 수행합니다.

public class ExampleService(ServiceBusClient client)
{
    // ...
}

앱 호스트 사용

Azure Service Bus 호스팅 지원을 IDistributedApplicationBuilder에 추가하려면, 앱 호스트 프로젝트에서 📦Aspire. 호스팅.Azure. ServiceBus NuGet 패키지를 설치합니다.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

앱 호스트 프로젝트에서 Service Bus 통합을 등록하고 다음 방법을 사용하여 서비스를 사용합니다.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureServiceBus("messaging")
    : builder.AddConnectionString("messaging");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(serviceBus)

구성

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

구성 공급자 사용

Service Bus 통합은 Microsoft.Extensions.Configuration을 지원합니다. Aspire:Azure:Messaging:ServiceBus 키를 사용하여 appsettings.json 또는 다른 구성 파일에서 AzureMessagingServiceBusSettings을 불러옵니다.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Identifier": "CLIENT_ID"
          }
        }
      }
    }
  }
}

appsettings.json 파일의 Aspire:Azure:Messaging:ServiceBus 섹션에서 구성을 설정한 경우 매개 변수를 전달하지 않고 메서드 AddAzureServiceBusClient 호출하면 됩니다.

인라인 대리자를 사용하십시오

또한 Action<AzureMessagingServiceBusSettings> 대리자를 전달하여 일부 또는 모든 옵션을 인라인으로 설정할 수도 있습니다(예: FullyQualifiedNamespace설정).

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.FullyQualifiedNamespace = "YOUR_SERVICE_BUS_NAMESPACE");

AddAzureServiceBus 메서드의 두 번째 매개 변수인 Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>> 대리자를 사용하여 ServiceBusClientOptions 설정할 수도 있습니다. 예를 들어 client을 식별하기 위해 ServiceBusClient ID를 설정합니다.

builder.AddAzureServiceBusClient(
    "messaging",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.Identifier = "CLIENT_ID"));

구성 옵션

다음 구성 가능한 옵션은 AzureMessagingServiceBusSettings 클래스를 통해 노출됩니다.

이름	묘사
`ConnectionString`	Service Bus 네임스페이스에 연결하는 데 사용되는 연결 문자열입니다.
`Credential`	Service Bus 네임스페이스에 인증하는 데 사용되는 자격 증명입니다.
`FullyQualifiedNamespace`	완전히 정규화된 서비스 버스 네임스페이스입니다.
`DisableTracing`	Service Bus client에 대한 추적을 비활성화합니다.
^†`HealthCheckQueueName`	상태 확인에 사용되는 큐의 이름입니다.
^†`HealthCheckTopicName`	상태 검사에 사용되는 항목의 이름입니다.

^† 상태 검사를 사용하도록 설정할 때 이름 옵션 중 하나 이상이 필수입니다.

관찰 가능성 및 원격 분석

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

로깅

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

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

추적

메모

.NET Azure SDK의 Service Bus ActivitySource 지원은 실험적이며 향후 활동 형태가 예고 없이 변경될 수 있습니다.

다음과 같은 여러 가지 방법으로 추적을 사용하도록 설정할 수 있습니다.

Azure.Experimental.EnableActivitySource 런타임 설정 구성 값을 true으로 설정합니다. 다음 중 하나를 사용하여 수행할 수 있습니다.
- AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);호출합니다.
- 프로젝트 파일에 RuntimeHostConfigurationOption 설정을 추가합니다.
```
<ItemGroup>
    <RuntimeHostConfigurationOption
         Include="Azure.Experimental.EnableActivitySource"
         Value="true" />
</ItemGroup>
```
AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE 환경 변수를 "true"로 설정합니다.
- WithEnvironment("AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE", "true") 함수 호출을 체인으로 연결하여 달성할 수 있습니다.

사용하도록 설정하면, .NET AspireAzure Service Bus 통합은 OpenTelemetry를 사용하여 다음의 추적 활동을 내보냅니다.

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

자세한 내용은 다음을 참조하세요.

지표

.NET Aspire Azure Service Bus 통합은 현재 .NETAzure SDK의 제한 사항으로 인해 기본적으로 메트릭을 지원하지 않습니다. 나중에 변경되는 경우 이 섹션은 해당 변경 내용을 반영하도록 업데이트됩니다.

다음을 통해 공유