자습서: ASP.NET Core에서 .NET Aspire 메시징 통합 사용하기

아티클
12/15/2024

클라우드 네이티브 앱에는 메시징 큐, 토픽 및 구독과 같은 기능을 제공하는 확장 가능한 메시징 솔루션이 필요한 경우가 많습니다. .NET Aspire 통합은 Azure Service Bus같은 다양한 메시징 공급자에 연결하는 프로세스를 간소화합니다. 이 튜토리얼에서는 ASP.NET Core 앱을 만들고, .NET Aspire 통합을 사용하여 Azure Service Bus에 연결해 알림 시스템을 구축합니다. 제출된 메시지는 구독자가 사용할 수 있도록 Service Bus 토픽으로 전송됩니다. 다음 내용을 배우게 됩니다.

.NET Aspire 통합을 사용하도록 설정된 기본 .NET 앱 만들기
.NET Aspire 통합을 추가하여 Azure Service Bus에 연결합니다.
.NET .NET Aspire 통합 기능을 구성하고 사용하여 데이터 보내기 및 받기

필수 구성 요소

.NET .NET Aspire작업하려면 다음을 로컬에 설치해야 합니다.

.NET 8.0 또는 .NET 9.0
OCI 규격 컨테이너 런타임(예:
- Docker 데스크톱 또는 Podman. 자세한 내용은 컨테이너 런타임을(를) 참조하십시오.
IDE(통합 개발자 환경) 또는 코드 편집기(예:
- Visual Studio 2022 버전 17.9 이상(선택 사항)
- Visual Studio Code(선택 사항)
  - C# Dev Kit: 확장(선택 사항)
- JetBrains Rider 는 .NET.NET Aspire 플러그인와 함께 (선택 사항)

자세한 내용은 .NET.NET Aspire 설정 및 도구및 .NET.NET Aspire SDK참조하세요.

위의 필수 구성 요소 외에도 Azure CLI를 설치해야 합니다. Azure CLI를 설치하려면 Azure CLI 설치 가이드지침을 따릅니다.

Azure Service Bus 계정 설정

이 자습서에서는 토픽 및 구독이 구성된 Azure Service Bus 네임스페이스에 액세스해야 합니다. 다음 옵션 중 하나를 사용하여 필요한 리소스를 설정합니다.

Azure 포털: 토픽 및 구독이 포함된 서비스 버스 계정을 생성합니다.

또는:

Azure CLI: Azure CLI 또는 CloudShell에서 다음 명령을 실행하여 필요한 Azure Service Bus 리소스를 설정합니다.

az group create -n <your-resource-group-name> --location eastus
az servicebus namespace create -g <your-resource-group-name> --name <your-namespace-name> --location eastus
az servicebus topic create -g <your-resource-group-name> --namespace-name <your-namespace-name> --name notifications
az servicebus topic subscription create -g <your-resource-group-name> --namespace-name <your-namespace-name> --topic-name notifications --name mobile

메모

리소스 그룹 이름의 자리 표시자 your-resource-group-name를 자신의 값으로, 네임스페이스 이름의 자리 표시자 your-namespace-name를 자신의 값으로 바꾸십시오. Service Bus 네임스페이스 이름은 Azure전역적으로 고유해야 합니다.

Azure 인증

이 빠른 시작은 암호 없는 인증 또는 연결 문자열을 사용하여 완료할 수 있습니다. 암호 없는 연결은 Azure Active Directory 및 RBAC(역할 기반 액세스 제어)를 사용하여 Service Bus 네임스페이스에 연결합니다. 코드, 구성 파일 또는 보안 스토리지(예: Azure Key Vault)에 하드 코딩된 연결 문자열이 있는 것에 대해 걱정할 필요가 없습니다.

연결 문자열을 사용하여 Service Bus 네임스페이스에 연결할 수도 있지만 실제 애플리케이션 및 프로덕션 환경에는 암호 없는 방법을 사용하는 것이 좋습니다. 자세한 내용은 인증 및 권한 부여 읽거나 암호 없는 개요 페이지방문하세요.

암호 없는 (권장)
연결 문자열

Service Bus 네임스페이스에서 Visual Studio 또는 Azure CLI에 로그인한 사용자 계정에 다음 역할을 할당하십시오.

Service Bus 데이터 소유자: RBAC 역할 할당

샘플 솔루션 만들기

새 .NET Aspire 시작 애플리케이션을 만들려면 Visual Studio, Visual Studio Code또는 .NET CLI를 사용할 수 있습니다.

Visual Studio은 .NET Aspire 템플릿을 제공하여 몇 가지 초기 설정 구성을 처리합니다. 다음 단계를 완료하여 이 빠른 시작을 위한 프로젝트를 만듭니다.

Visual Studio맨 위에서 파일>새 프로젝트>에 이동하십시오.
대화 상자 창에서 Aspire 검색하고 .NET.NET Aspire 시작 앱선택합니다. 다음 선택합니다.
새 프로젝트 구성 화면에서 다음 단계를 따릅니다.
- 프로젝트 이름을 입력합니다 AspireSample.
- 값을 기본값으로 두고다음 을 선택합니다.
추가 정보 화면에서 다음을 수행합니다.
- .NET 9.0(표준 용어 지원) 선택되어 있는지 확인합니다.
- 캐싱에 Redis 사용(지원되는 컨테이너 런타임 필요)이(가) 선택되었는지 확인하고, 만들기를 선택합니다.
- 필요에 따라 테스트 프로젝트를 만들기을 선택할 수 있습니다. 자세한 내용은 첫 번째 .NET.NET Aspire 테스트작성을 참조하세요.

Visual Studio는 .NET Aspire을 사용하기 위해 구조화된 새로운 솔루션을 만듭니다.

Visual Studio Code 몇 가지 초기 설정 구성을 처리하는 .NET Aspire 프로젝트 템플릿을 제공합니다. 다음 단계를 완료하여 이 빠른 시작을 위한 프로젝트를 만듭니다.

새 Visual Studio Code 인스턴스에서(폴더를 열지 않고) .NET 프로젝트 만들기 단추를 선택합니다.
.NET .NET Aspire 시작 앱 템플릿을 선택합니다.

.NET .NET Aspire 템플릿을 아직 설치하지 않은 경우, 다음 dotnet new install 명령을 실행하십시오.

dotnet new install Aspire.ProjectTemplates

이전 .NET CLI 명령을 사용하면 .NET Aspire 템플릿을 사용할 수 있습니다. 템플릿에서 .NET.NET Aspire Starter 앱을 만들려면 다음 dotnet new 명령을 실행합니다.

dotnet new aspire-starter --use-redis-cache --output AspireSample

자세한 내용을 보려면 dotnet new을 참조하세요. .NET CLI는 .NET Aspire사용하도록 구조화된 새 솔루션을 만듭니다.

Worker Service 프로젝트 추가

다음으로 솔루션에 Worker Service 프로젝트를 추가하여 Azure Service Bus로부터 메시지를 검색하고 처리합니다.

솔루션 탐색기에서 최상위 수준 AspireSample 솔루션 노드를 마우스 오른쪽 단추로 클릭하고 추가>새 프로젝트선택합니다.
Worker Service 템플릿을 검색하고 선택한 후 다음을 선택합니다.
프로젝트 이름에 AspireSample.WorkerService 입력하고 다음선택합니다.
추가 정보 화면에서 다음을 수행합니다.
- .NET 9.0 선택되어 있는지 확인합니다.
- 오케스트레이션 등록이 선택되어 있는지 확인하고"만들기" 를 선택합니다.

Visual Studio 솔루션에 프로젝트를 추가하고 AspireSample.AppHost 프로젝트의 Program.cs 파일을 새 코드 줄로 업데이트합니다.

builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");

Visual Studio 도구는 IDistributedApplicationBuilder 개체에 새 프로젝트를 등록하기 위해 이 코드 줄을 추가했으며, 이를 통해 나중에 살펴볼 오케스트레이션 기능을 사용할 수 있습니다.

Visual Studio Code 솔루션 탐색기 솔루션 이름 옆에 있는 + 단추를 선택하여 솔루션에 새 프로젝트를 추가합니다.
프로젝트 템플릿을 필터링하려면 검색 상자에 Worker 입력하고 찾은 Worker Service 템플릿을 선택합니다.
Worker Service 템플릿을 선택하고 프로젝트 이름을 AspireSample.WorkerService입력합니다.
기본 디렉터리 선택하여 솔루션과 동일한 디렉터리에 프로젝트를 만듭니다.
프로젝트 만들기을 선택하여 솔루션에 프로젝트를 추가합니다.
솔루션 탐색기 항목에서 AspireSample.AppHost 프로젝트를 우클릭하여 프로젝트 참조 추가하기를 선택합니다.
builder.Build().Run();호출하기 전에 AspireSample.AppHost 프로젝트의 Program.cs 파일에 다음 코드 줄을 추가합니다.
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

앱의 루트 디렉터리에서 dotnet new 명령을 사용하여 새 Worker Service 앱을 만듭니다.
```
dotnet new worker --name AspireSample.WorkerService
```

dotnet sln 명령을 사용하여 솔루션에 프로젝트를 추가합니다.

dotnet sln AspireSample.sln add AspireSample.WorkerService/AspireSample.WorkerService.csproj

dotnet add 명령을 사용하여 .AppHost 및 .WorkerService 프로젝트 간에 프로젝트 참조를 추가합니다.

dotnet add AspireSample.AppHost/AspireSample.AppHost.csproj reference AspireSample.WorkerService/AspireSample.WorkerService.csproj

builder.Build().Run();호출하기 전에 AspireSample.AppHost 프로젝트의 Program.cs 파일에 다음 코드 줄을 추가합니다.
```
builder.AddProject<Projects.AspireSample_WorkerService>(
    "aspiresample-workerservice");
```

완성된 솔루션 구조는 최상위 디렉터리의 이름이 aspire-messaging가정하면 다음과 유사합니다.

└───📂 aspire-messaging
     ├───📂 AspireSample.WorkerService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.WorkerService.csproj
     │    ├─── Program.cs
     │    └─── Worker.cs
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

API에 .NET.NET Aspire 통합 추가

AspireSample.ApiService 앱에 .NET Aspire Azure Service Bus 통합을 추가합니다.

솔루션 탐색기AspireSample.ApiService.csproj 파일을 두 번 클릭하여 XML 파일을 엽니다.

<ItemGroup> 요소에 다음 <PackageReference> 항목을 추가합니다.

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

솔루션 탐색기에서 AspireSample.ApiService 프로젝트를 마우스 오른쪽 버튼으로 클릭하고 NuGet 패키지 추가를 선택하십시오.
Aspire.Azure.Messaging.ServiceBus을(를) 검색 상자에 입력하고 목록에서 패키지를 선택합니다.
(최신) 버전을 선택하여 패키지를 설치합니다.

dotnet add package Aspire.Azure.Messaging.ServiceBus

AspireSample.ApiService 프로젝트의 Program.cs 파일에서 AddAzureServiceBusClient 확장 메서드에 대한 호출을 추가하여 AddServiceDefaults대한 기존 호출을 바꿉니다.

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

자세한 내용은 AddAzureServiceBusClient참조하세요.

이 메서드는 다음 작업을 수행합니다.

DI 컨테이너에 ServiceBusClient를 등록하여 Azure Service Bus에 연결합니다.
해당 서비스에 대해 해당 상태 검사, 로깅 및 원격 분석을 자동으로 사용하도록 설정합니다.

동일한 프로젝트의 appsettings.json 파일에 해당 연결 정보를 추가합니다.

암호 없는 (권장)
연결 문자열

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
          SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

메모

서비스 URI에 기록된 {your_namespace}를 당신의 Service Bus 네임스페이스 이름으로 교체해야 합니다.

API 엔드포인트 만들기

API는 데이터를 수신하고 Service Bus 토픽에 게시하고 구독자에게 브로드캐스트할 엔드포인트를 제공해야 합니다. AspireSample.ApiService 프로젝트에 다음 엔드포인트를 추가하여 Service Bus 토픽에 메시지를 보냅니다. Program.cs 파일의 모든 내용을 다음 C# 코드로 바꿉니다.

using Azure.Messaging.ServiceBus;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire integrations.
builder.AddServiceDefaults();
builder.AddAzureServiceBusClient("serviceBusConnection");

// Add services to the container.
builder.Services.AddProblemDetails();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseExceptionHandler();

app.MapPost("/notify", static async (ServiceBusClient client, string message) =>
{
    var sender = client.CreateSender("notifications");

    // Create a batch
    using ServiceBusMessageBatch messageBatch =
        await sender.CreateMessageBatchAsync();

    if (messageBatch.TryAddMessage(
            new ServiceBusMessage($"Message {message}")) is false)
    {
        // If it's too large for the batch.
        throw new Exception(
            $"The message {message} is too large to fit in the batch.");
    }

    // Use the producer client to send the batch of
    // messages to the Service Bus topic.
    await sender.SendMessagesAsync(messageBatch);

    Console.WriteLine($"A message has been published to the topic.");
});

app.MapDefaultEndpoints();

app.Run();

.NET Aspire 통합을 Worker Service에 추가

AspireSample.WorkerService 프로젝트에 .NET Aspire Azure Service Bus 통합을 추가합니다. Aspire추가할 때 이전과 동일한 단계를 수행합니다.Azure. Messaging.ServiceBus는 NuGet 패키지를 AspireSample.ApiService 프로젝트에. 추가된 후에는 Service Bus 토픽의 메시지를 처리하도록 작업자 서비스를 구성할 수 있습니다.

AspireSample.WorkerService 프로젝트의 Program.cs 파일에서 기존 코드를 다음 코드로 교체합니다.

using AspireSample.WorkerService;

var builder = Host.CreateApplicationBuilder(args);

builder.AddAzureServiceBusClient("serviceBusConnection");

builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Run();

AddAzureServiceBusClient 메서드는 다음 작업을 수행합니다.

Azure Service Bus에 연결하기 위해 DI 컨테이너에 ServiceBusClient을(를) 등록합니다.
각 서비스에 대한 적절한 상태 검사, 로깅 및 원격 분석을 자동으로 활성화합니다.

AspireSample.WorkerService 프로젝트의 appsettings.json 파일에서 해당 연결 정보를 추가합니다.

암호 없는 (권장)
연결 문자열

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "{your_namespace}.servicebus.windows.net"
  }
}

{
  // Existing configuration is omitted for brevity.
  "ConnectionStrings": {
    "serviceBusConnection": "Endpoint=sb://{your_namespace}.servicebus.windows.net/;
        SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey"
  }
}

메모

사용자 고유의 Service Bus 네임스페이스 이름으로 서비스 URI의 {your_namespace}을 대체해야 합니다.

구독자의 메시지 처리

새 메시지가 messages 큐에 배치되면 작업자 서비스는 메시지를 검색, 처리 및 삭제해야 합니다. 다음 코드와 일치하도록 Worker.cs 클래스를 업데이트합니다.

using Azure.Messaging.ServiceBus;

namespace AspireSample.WorkerService;

public sealed class Worker(
    ILogger<Worker> logger,
    ServiceBusClient client) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            var processor = client.CreateProcessor(
                "notifications",
                "mobile",
                new ServiceBusProcessorOptions());

            // Add handler to process messages
            processor.ProcessMessageAsync += MessageHandler;

            // Add handler to process any errors
            processor.ProcessErrorAsync += ErrorHandler;

            // Start processing
            await processor.StartProcessingAsync();

            logger.LogInformation("""
                Wait for a minute and then press any key to end the processing
                """);

            Console.ReadKey();

            // Stop processing
            logger.LogInformation("""

                Stopping the receiver...
                """);

            await processor.StopProcessingAsync();

            logger.LogInformation("Stopped receiving messages");
        }
    }

    async Task MessageHandler(ProcessMessageEventArgs args)
    {
        string body = args.Message.Body.ToString();

        logger.LogInformation("Received: {Body} from subscription.", body);

        // Complete the message. messages is deleted from the subscription.
        await args.CompleteMessageAsync(args.Message);
    }

    // Handle any errors when receiving messages
    Task ErrorHandler(ProcessErrorEventArgs args)
    {
        logger.LogError(args.Exception, "{Error}", args.Exception.Message);
        
        return Task.CompletedTask;
    }
}

로컬에서 앱 실행 및 테스트

이제 샘플 앱이 테스트할 준비가 되었습니다. API에 제출된 데이터가 Azure Service Bus 토픽으로 전송되고 구독자 작업자 서비스에서 사용되는지 확인합니다.

시작 디버깅 단추를 선택하거나 F5눌러 프로젝트를 시작합니다. .NET .NET Aspire 대시보드 앱이 브라우저에서 열립니다.

시작 디버깅 단추를 선택하거나 F5눌러 프로젝트를 시작합니다. .NET .NET Aspire 대시보드 앱은 브라우저에서 열려야 합니다.

dotnet run --project AspireSample.AppHost실행하여 .NET.NET Aspire 프로젝트를 시작합니다. .NET .NET Aspire 대시보드 앱이 브라우저에서 열려야 합니다.

리소스 페이지의 apiservice 행에서 Endpoints에 있는 링크를 찾아서 weatherforecast 엔드포인트를 엽니다. HTTPS 포트 번호를 확인합니다.
.NET .NET Aspire 대시보드에서 aspiresample-workerservice 프로젝트의 로그로 이동하십시오.
터미널 창에서 curl 명령을 사용하여 API에 테스트 메시지를 보냅니다.
```
curl -X POST -H "Content-Type: application/json" https://localhost:{port}/notify?message=hello%20aspire  
```
{port} 이전에 사용한 포트 번호로 바꿔야 합니다.
aspiresample-workerservice 로그로 다시 전환합니다. 출력 로그에 인쇄된 테스트 메시지가 표시됩니다.

축하합니다! Azure Service Bus에 연결하는 ASP.NET Core API를 Aspire 통합으로 만들고 구성했습니다.

리소스 정리

만든 Azure 리소스가 더 이상 필요하지 않은 경우 다음 Azure CLI 명령을 실행하여 리소스 그룹을 삭제합니다. 리소스 그룹을 삭제하면 리소스 그룹에 포함된 리소스도 삭제됩니다.

az group delete --name <your-resource-group-name>

자세한 내용은 리소스 정리에서 Azure를 참조하십시오.

다음을 통해 공유