.NET Aspire를 사용하는 Azure Functions(미리 보기)

2025-05-12

.NET Aspire 는 클라우드에서 분산 애플리케이션의 개발을 간소화하는 의견 스택입니다. .NET Aspire와 Azure Functions의 통합을 통해 .NET Aspire 앱 호스트의 일부로 Azure Functions .NET 프로젝트를 개발, 디버그 및 오케스트레이션할 수 있습니다.

중요합니다

.NET Aspire와 Azure Functions의 통합은 현재 미리 보기로 제공되며 변경될 수 있습니다.

필수 조건

.NET Aspire와 함께 Azure Functions를 사용하기 위한 개발 환경을 설정합니다.

.NET 9 SDK 및 .NET Aspire 9.0 이상을 설치합니다. .NET 9 SDK가 필요하지만 .NET Aspire 9.0은 .NET 8 및 .NET 9 프레임워크를 지원합니다.
Visual Studio를 사용하는 경우 버전 17.12 이상으로 업데이트합니다. Visual Studio용 Azure Functions 도구의 최신 버전도 있어야 합니다. 업데이트를 확인하려면 다음을 수행합니다.
1. 도구>옵션으로 이동합니다.
2. 프로젝트 및 솔루션에서 Azure Functions를 선택합니다.
3. 업데이트 확인을 선택하고 메시지가 표시되면 업데이트를 설치합니다.

솔루션 구조

Azure Functions 및 .NET Aspire를 사용하는 솔루션에는 앱 호스트 프로젝트와 하나 이상의 Functions 프로젝트를 비롯한 여러 프로젝트가 있습니다.

앱 호스트 프로젝트는 애플리케이션의 진입점입니다. Functions 프로젝트를 포함하여 애플리케이션 구성 요소의 설정을 오케스트레이션합니다.

솔루션에는 일반적으로 서비스 기본 프로젝트 도 포함됩니다. 이 프로젝트는 애플리케이션의 프로젝트에서 사용할 기본 서비스 및 구성 집합을 제공합니다.

앱 호스트 프로젝트

통합을 성공적으로 구성하려면 앱 호스트 프로젝트가 다음 요구 사항을 충족하는지 확인합니다.

앱 호스트 프로젝트는 Aspire.Hosting.Azure.Functions를 참조해야 합니다. 이 패키지는 통합에 필요한 논리를 정의합니다.
앱 호스트 프로젝트에는 오케스트레이션에 포함하려는 각 Functions 프로젝트에 대한 프로젝트 참조가 있어야 합니다.
앱 호스트의 Program.cs 파일에서 AddAzureFunctionsProject<TProject>() 인스턴스에 대해 IDistributedApplicationBuilder을(를) 호출하여 프로젝트를 포함해야 합니다. .NET Aspire의 다른 프로젝트 형식에 사용하는 AddProject<TProject>() 메서드 대신 이 메서드를 사용합니다. 만약 AddProject<TProject>()를 사용하면, 해당 Functions 프로젝트를 제대로 시작할 수 없습니다.

다음 예제에서는 앱 호스트 프로젝트에 대한 최소 Program.cs 파일을 보여줍니다.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject");

builder.Build().Run();

Azure Functions 프로젝트

통합을 성공적으로 구성하려면 Azure Functions 프로젝트가 다음 요구 사항을 충족하는지 확인합니다.

Functions 프로젝트는 Microsoft.Azure.Functions.Worker 및 Microsoft.Azure.Functions.Worker.Sdk의 2.x 버전을 참조해야 합니다. 또한 Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore 참조를 2.x 버전으로 업데이트해야 합니다.
Program.cs 파일은 IHostApplicationBuilder의 버전을 사용해야 합니다. 이 요구 사항은 FunctionsApplication.CreateBuilder(args)을 사용해야 한다는 것을 의미합니다.
솔루션에 서비스 기본 프로젝트가 포함된 경우 Functions 프로젝트가 이를 사용하도록 구성되어 있는지 확인합니다.
- Functions 프로젝트에는 서비스 기본 프로젝트에 대한 프로젝트 참조가 포함되어야 합니다.
- IHostApplicationBuilder에서 Program.cs를 빌드하기 전에 builder.AddServiceDefaults() 호출을 포함하도록 합니다.

다음 예제에서는 .NET Aspire에 사용되는 Functions 프로젝트에 대한 최소 Program.cs 파일을 보여 줍니다.

using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.AddServiceDefaults();

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

이 예제에는 다른 Program.cs 많은 예제 및 Azure Functions 템플릿에 표시되는 기본 Application Insights 구성이 포함되지 않습니다. 대신 메서드를 호출하여 .NET Aspire에서 OpenTelemetry 통합을 구성합니다 builder.AddServiceDefaults .

통합을 최대한 활용하려면 다음 지침을 고려하세요.

Functions 프로젝트에 직접 Application Insights 통합을 포함하지 마세요. .NET Aspire의 모니터링은 대신 OpenTelemetry 지원을 통해 처리됩니다. 서비스 기본 프로젝트를 통해 Azure Monitor로 데이터를 내보내도록 .NET Aspire를 구성할 수 있습니다.
Functions 프로젝트에 대한 파일에서 local.settings.json 사용자 지정 앱 설정을 정의하지 마세요. local.settings.json에 있어야 하는 유일한 설정은 "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"입니다. 앱 호스트 프로젝트를 통해 다른 모든 앱 구성을 설정합니다.

.NET Aspire를 사용한 연결 구성

앱 호스트 프로젝트는 리소스를 정의하고 코드를 사용하여 리소스 간에 연결을 만드는 데 도움이 됩니다. 이 섹션에서는 Azure Functions 프로젝트에서 사용하는 연결을 구성하고 사용자 지정하는 방법을 보여 줍니다.

.NET Aspire에는 시작하는 데 도움이 되는 기본 연결 권한이 포함되어 있습니다. 그러나 이러한 권한은 애플리케이션에 적절하지 않거나 충분하지 않을 수 있습니다.

Azure RBAC(역할 기반 액세스 제어)를 사용하는 시나리오의 경우 프로젝트 리소스에 대한 메서드를 호출 WithRoleAssignments() 하여 권한을 사용자 지정할 수 있습니다. 호출 WithRoleAssignments()할 때 모든 기본 역할 할당이 제거되고 원하는 전체 집합 역할 할당을 명시적으로 정의해야 합니다. Azure Container Apps에서 애플리케이션을 호스트하는 경우 WithRoleAssignments()을 사용하는 것은 AddAzureContainerAppEnvironment()에서 DistributedApplicationBuilder을 호출해야 합니다.

Azure Functions 호스트 스토리지

Azure Functions에는 몇 가지 핵심 동작에 대한 호스트 스토리지 연결(AzureWebJobsStorage) 이 필요합니다. 앱 호스트 프로젝트에서 AddAzureFunctionsProject<TProject>()를 호출하면 기본적으로 AzureWebJobsStorage 연결이 생성되어 Functions 프로젝트에 제공됩니다. 이 기본 연결은 로컬 개발 실행에 Azure Storage 에뮬레이터를 사용하고 배포될 때 스토리지 계정을 자동으로 프로비전합니다. 더 많은 제어를 위해 Functions 프로젝트 리소스를 호출 .WithHostStorage() 하여 이 연결을 바꿀 수 있습니다.

.NET Aspire가 호스트 스토리지 연결에 대해 설정하는 기본 권한은 호출 WithHostStorage() 여부에 따라 달라집니다. 추가 WithHostStorage() 하면 스토리지 계정 기여자 할당이 제거됩니다. 다음 표에서는 .NET Aspire가 호스트 스토리지 연결에 대해 설정하는 기본 사용 권한을 나열합니다.

호스트 스토리지 연결	기본 역할
호출 없음 `WithHostStorage()`	Storage Blob 데이터 기여자, Storage 큐 데이터 기여자, 스토리지 테이블 데이터 기여자 스토리지 계정 기여자
호출 `WithHostStorage()`	Storage Blob 데이터 기여자, Storage 큐 데이터 기여자, 스토리지 테이블 데이터 기여자

다음 예제에서는 호스트 스토리지를 대체하고 역할 할당을 지정하는 앱 호스트 프로젝트에 대한 최소 Program.cs 파일을 보여 줍니다.

using Azure.Provisioning.Storage;

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureContainerAppEnvironment("myEnv");

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

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithHostStorage(myHostStorage)
    .WithRoleAssignments(myHostStorage, StorageBuiltInRole.StorageBlobDataOwner);

builder.Build().Run();

비고

스토리지 Blob 데이터 소유자는 호스트 스토리지 연결의 기본 요구 사항에 권장되는 역할입니다. Blob 서비스에 대한 연결이 .NET Aspire의 기본 제공 Storage Blob Data Contributor 설정만으로 이루어져 있는 경우, 앱에 문제가 발생할 수 있습니다.

프로덕션 시나리오의 경우 둘 다 WithHostStorage() 및 WithRoleAssignments().에 대한 호출을 포함합니다. 그런 다음 필요한 다른 역할과 함께 이 역할을 명시적으로 설정할 수 있습니다.

트리거 및 바인딩 연결

트리거 및 바인딩은 이름으로 연결을 참조합니다. 다음 .NET Aspire 통합은 WithReference()에 대한 호출을 통해 프로젝트 리소스에서 이러한 연결을 제공합니다.

.NET Aspire 통합	기본 역할
Azure Blob Storage	Storage Blob 데이터 기여자, Storage 큐 데이터 기여자, 스토리지 테이블 데이터 기여자
Azure Queue Storage	Storage Blob 데이터 기여자, Storage 큐 데이터 기여자, 스토리지 테이블 데이터 기여자
Azure Event Hubs	Azure Event Hubs 데이터 소유자
Azure Service Bus	Azure Service Bus 데이터 소유자

다음 예제에서는 큐 트리거를 구성하는 앱 호스트 프로젝트에 대한 최소 Program.cs 파일을 보여 줍니다. 이 예제에서는 해당 큐 트리거의 속성이 Connection으로 설정되므로, MyQueueTriggerConnection 호출에서 이름을 지정합니다.

var builder = DistributedApplication.CreateBuilder(args);

var myAppStorage = builder.AddAzureStorage("myAppStorage").RunAsEmulator();
var queues = myAppStorage.AddQueues("queues");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithReference(queues, "MyQueueTriggerConnection");

builder.Build().Run();

다른 통합의 경우 다른 방식으로 구성을 설정하기 위한 WithReference 호출입니다. .NET Aspire 클라이언트 통합에서는 구성을 사용할 수 있지만, 트리거 및 바인딩에는 사용할 수 없습니다. 이러한 통합의 경우 트리거 또는 바인딩을 해결할 연결 정보를 전달하도록 WithEnvironment()를 호출합니다.

다음 예제에서는 연결 문자열 식을 노출하는 리소스에 대한 환경 변수 MyBindingConnection 를 설정하는 방법을 보여 줍니다.

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection", otherIntegration.Resource.ConnectionStringExpression);

.NET Aspire 클라이언트 통합과 트리거 및 바인딩 시스템이 모두 연결을 사용하도록 하려면, WithReference() 및 WithEnvironment() 둘 다 구성할 수 있습니다.

일부 리소스의 경우 로컬로 실행할 때와 Azure에 게시할 때의 연결 구조가 다를 수 있습니다. 이전 예제 otherIntegration 에서는 에뮬레이터로 실행되는 리소스일 수 있으므로 ConnectionStringExpression 에뮬레이터 연결 문자열 반환합니다. 그러나 리소스가 게시되면 .NET Aspire가 ID 기반 연결을 ConnectionStringExpression 설정하고 서비스의 URI를 반환할 수 있습니다. 이 경우 Azure Functions에 대한 ID 기반 연결을 설정하려면 다른 환경 변수 이름을 제공해야 할 수 있습니다.

다음 예제에서는 필요한 접미사를 조건부로 추가하는 데 사용합니다 builder.ExecutionContext.IsPublishMode .

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection" + (builder.ExecutionContext.IsPublishMode ? "__serviceUri" : ""), otherIntegration.Resource.ConnectionStringExpression);

각 바인딩에서 지원하는 연결 형식 및 해당 형식에 필요한 사용 권한에 대한 자세한 내용은 바인딩의 참조 페이지를 참조하세요.

애플리케이션 호스팅

기본적으로 Azure Functions 프로젝트를 Azure에 게시하면 Azure Container Apps에 배포됩니다.

미리 보기 기간 동안 컨테이너 앱 리소스는 이벤트 기반 크기 조정을 지원하지 않습니다. 이 모드에서 배포된 앱에는 Azure Functions 지원을 사용할 수 없습니다. 지원 티켓을 열어야 하는 경우 Azure Container Apps 리소스 유형을 선택합니다.

고려 사항 및 모범 사례

.NET Aspire와 Azure Functions의 통합을 평가할 때 다음 사항을 고려합니다.

통합에 대한 지원은 현재 미리 보기로 제공됩니다.
.NET Aspire를 통한 트리거 및 바인딩 구성은 현재 특정 통합으로 제한됩니다. 자세한 내용은 이 문서에서 .NET Aspire를 사용한 연결 구성 을 참조하세요.
파일은 Program.cs가 포함된 IHostApplicationBuilder 버전의 호스트 인스턴스 시작을 사용해야 합니다. IHostApplicationBuilder를 사용하면 함수 프로젝트에 builder.AddServiceDefaults() 추가하도록 호출 할 수 있습니다.
.NET Aspire는 모니터링에 OpenTelemetry를 사용합니다. 서비스 기본 프로젝트를 통해 Azure Monitor로 데이터를 내보내도록 .NET Aspire를 구성할 수 있습니다.

다른 많은 Azure Functions 컨텍스트에서는 작업자 서비스를 등록하여 Application Insights와의 직접 통합을 포함할 수 있습니다. .NET Aspire에서는 이러한 종류의 통합을 권장하지 않습니다. 버전 2.22.0에서는 Microsoft.ApplicationInsights.WorkerService 관련 런타임 오류가 발생할 수 있지만, 버전 2.23.0에서는 이 문제가 해결됩니다. .NET Aspire를 사용하는 경우 Functions 프로젝트에서 직접 Application Insights 통합을 제거합니다.
.NET Aspire 오케스트레이션에 참여하는 Functions 프로젝트의 경우 대부분의 애플리케이션 구성은 .NET Aspire 앱 호스트 프로젝트에서 제공됩니다. local.settings.json 설정을 제외하고 FUNCTIONS_WORKER_RUNTIME 설정은 피하십시오. .NET Aspire에서 동일한 환경 변수 local.settings.json 를 설정하는 경우 시스템에서 .NET Aspire 버전을 사용합니다.
local.settings.json에서 연결에 대해 Azure Storage 에뮬레이터를 구성하지 마세요. 많은 Functions 시작 템플릿에는 에뮬레이터가 기본값 AzureWebJobsStorage으로 포함됩니다. 그러나 에뮬레이터 구성은 일부 개발자 도구에서 .NET Aspire에서 사용하는 버전과 충돌할 수 있는 에뮬레이터 버전을 시작하라는 메시지를 표시할 수 있습니다.