다음을 통해 공유

격리된 작업자 모델에서 C# Azure Functions를 실행하기 위한 가이드

  • 아티클

이 문서에서는 격리된 작업자 모델을 사용하여 .NET에서 Azure Functions를 사용하는 방법을 소개합니다. 이 모델을 사용하면 프로젝트가 다른 런타임 구성 요소와 독립적으로 .NET 버전을 대상으로 지정할 수 있습니다. 지원되는 특정 .NET 버전에 대한 자세한 내용은 지원되는 버전을 참조하세요.

.NET 격리 작업자 모델 함수 빌드를 바로 시작하려면 다음 링크를 사용합니다.

시작하기 개념 샘플

격리된 작업자 모델 프로젝트를 Azure에 배포하는 방법에 대한 자세한 내용은 Azure Functions에 배포를 참조하세요.

격리된 작업자 모델의 이점

.NET 클래스 라이브러리 함수는 Functions 호스트 런타임과 동일한 프로세스(in-process) 또는 격리된 작업자 프로세스의 두 가지 모드로 실행할 수 있습니다. .NET 함수가 격리 작업자 프로세스에서 실행되는 경우 다음과 같은 이점을 활용할 수 있습니다.

  • 충돌 감소: 함수는 별도의 프로세스에서 실행되므로 앱에서 사용되는 어셈블리는 호스트 프로세스에서 사용되는 동일한 어셈블리의 다른 버전과 충돌하지 않습니다.
  • 프로세스에 대한 완전한 제어: 앱의 시작을 제어하여 사용된 구성과 시작된 미들웨어를 관리할 수 있습니다.
  • 표준 종속성 주입: 프로세스를 완전하게 제어하므로 종속성 주입과 미들웨어와 함수 앱의 통합을 위해 현재 .NET 동작을 사용할 수 있습니다.
  • .NET 버전 유연성: 호스트 프로세스 외부에서 실행한다는 것은 .NET Framework를 포함하여 Functions 런타임에서 기본적으로 지원하지 않는 .NET 버전에서 함수를 실행할 수 있음을 의미합니다.

in-process로 실행되는 기존 C# 함수 앱이 있는 경우 이러한 이점을 활용하려면 앱을 마이그레이션해야 합니다. 자세한 내용은 In-Process 모델에서 격리된 작업자 모델로 .NET 앱 마이그레이션을 참조하세요.

두 모드 간의 포괄적인 비교는 In Process 및 격리 작업자 프로세스 .NET Azure Functions의 차이점을 참조하세요.

지원되는 버전

Functions 런타임 버전은 .NET의 특정 버전을 지원합니다. Functions 버전에 대해 자세히 알아보려면 Azure Functions 런타임 버전 개요를 참조하세요. In Process 또는 격리 작업자 프로세스 중 어떤 상태로 함수가 실행되는지에 따라 지원되는 버전이 달라집니다.

참고 항목

함수 앱에서 사용하는 Functions 런타임 버전을 변경하는 방법을 알아보려면 현재 런타임 버전 보기 및 업데이트를 참조하세요.

다음 표에서는 특정 버전의 Functions에서 사용할 수 있는 가장 높은 수준의 .NET 또는 .NET Framework를 보여 줍니다.

Functions 런타임 버전 격리된 작업자 모델 In Process 모델5
Functions 4.x1 .NET 9.0(미리 보기)
.NET 8.0
.NET 6.02
.NET Framework 4.83		 .NET 8.0
.NET 6.02
Functions 1.x4 해당 없음 .NET Framework 4.8

1.NET 7은 이전에 격리된 작업자 모델에서 지원되었지만 2024년 5월 14일에 공식 지원이 종료되었습니다.

2 .NET 6은 2024년 11월 12일에 공식 지원이 종료됩니다.

3 빌드 프로세스에는 .NET SDK도 필요합니다.

4 2026년 9월 14일에 Azure Functions 런타임 버전 1.x에 대한 지원이 종료됩니다. 자세한 내용은 이 지원 공지를 참조하세요. 지속적인 전체 지원을 위해 앱을 버전 4.x로 마이그레이션해야 합니다.

5 In Process 모델에 대한 지원은 2026년 11월 10일에 종료됩니다. 자세한 내용은 이 지원 공지를 참조하세요. 계속해서 완전한 지원을 받으려면 앱을 격리된 작업자 모델로 마이그레이션해야 합니다.

특정한 이전 부 버전의 삭제를 비롯하여 Azure Functions 릴리스에 대한 최신 소식을 보려면 Azure App Service 공지를 주기적으로 확인하세요.

프로젝트 구조

격리된 작업자 모델을 사용하는 Azure Functions용 .NET 프로젝트는 기본적으로 지원되는 .NET 런타임을 대상으로 하는 .NET 콘솔 앱 프로젝트입니다. 다음은 .NET 격리 프로젝트에 필요한 기본 파일입니다.

  • 프로젝트 및 종속성을 정의하는 C# 프로젝트 파일(.csproj)입니다.
  • 앱의 진입점인 Program.cs 파일입니다.
  • 함수를 정의하는 모든 코드 파일입니다.
  • 프로젝트의 함수에서 공유하는 구성을 정의하는 host.json 파일입니다.
  • 컴퓨터에서 로컬로 실행할 때 프로젝트에서 사용하는 환경 변수를 정의하는 local.settings.json 파일입니다.

전체 예제는 .NET 8 샘플 프로젝트 및 .NET Framework 4.8 샘플 프로젝트를 참조하세요.

패키지 참조

격리된 작업자 모델을 사용하는 Azure Functions용 .NET 프로젝트는 핵심 기능과 바인딩 확장 모두에 고유한 패키지 집합을 사용합니다.

핵심 패키지

격리 작업자 프로세스에서 .NET 함수를 실행하려면 다음 패키지가 필요합니다.

버전 2.x(미리 보기)

2.x 버전의 핵심 패키지는 지원되는 프레임워크를 변경하고 이러한 이후 버전의 새 .NET API를 지원합니다. .NET 9(미리 보기) 이상을 대상으로 하는 경우 앱은 두 패키지의 버전 2.0.0-preview1 이상을 참조해야 합니다.

최초 미리 보기 버전은 버전 1.x에서 작성된 코드와 호환됩니다. 그러나 미리 보기 기간 동안에는 새로운 버전에서 코드 작성에 영향을 줄 수 있는 동작 변경이 도입될 수 있습니다.

2.x 버전으로 업데이트하는 경우 다음과 같은 변경 내용을 확인합니다.

  • 버전 2.0.0-preview2부터 Microsoft.Azure.Functions.Worker.Sdk는 SDK 컨테이너 빌드에 대한 기본 구성을 추가합니다.
  • Microsoft.Azure.Functions.Worker 버전 2.0.0-preview2부터:
    • 이 버전은 .에 대한 지원을 추가합니다 IHostApplicationBuilder. 이 가이드의 몇 가지 예에는 을 사용하여 IHostApplicationBuilder대안을 표시하는 탭이 포함됩니다. 이러한 예제에는 2.x 버전이 필요합니다.
    • 개발 환경에서 실행되는 경우 서비스 공급자 범위 유효성 검사는 기본적으로 포함됩니다. 이 동작은 ASP.NET Core와 일치합니다.
    • 이 EnableUserCodeException 옵션은 기본적으로 사용하도록 설정되어 있습니다. 이제 속성이 사용되지 않는 것으로 표시됩니다.
    • 이 IncludeEmptyEntriesInMessagePayload 옵션은 기본적으로 사용하도록 설정되어 있습니다. 이 옵션을 사용하도록 설정하면 컬렉션을 나타내는 트리거 페이로드에 항상 빈 항목이 포함됩니다. 예를 들어 본문 없이 메시지를 보내는 경우 트리거 데이터에 대한 빈 항목이 계속 존재 string[] 합니다. 빈 항목을 포함하면 함수가 참조할 수도 있는 메타데이터 배열과 상호 참조할 수 있습니다. 서비스 구성에서 설정 IncludeEmptyEntriesInMessagePayload 하여 이 동작을 false WorkerOptions 사용하지 않도록 설정할 수 있습니다.
    • 클래스의 ILoggerExtensions 이름이 .로 FunctionsLoggerExtensions바뀝니다. 이름 바꾸기는 인스턴스에서 사용할 LogMetric() 때 모호한 호출 오류를 방지합니다 ILogger .

확장 패키지

.NET 격리 작업자 프로세스 함수는 서로 다른 바인딩 형식을 사용하므로 고유한 바인딩 확장 패키지 집합이 필요합니다.

이러한 확장 패키지는 Microsoft.Azure.Functions.Worker.Extensions에서 찾을 수 있습니다.

시작 및 구성

격리된 작업자 모델을 사용하는 경우 일반적으로 있는 함수 앱의 시작에 액세스할 수 있습니다 Program.cs. 사용자는 자신의 호스트 인스턴스를 만들고 시작해야 합니다. 따라서 앱에 대한 구성 파이프라인에 직접 액세스할 수도 있습니다. .NET Functions 격리 작업자 프로세스를 실행하면 훨씬 더 쉽게 구성을 추가하고, 종속성을 주입하고, 사용자 자신의 미들웨어를 실행할 수 있습니다.

다음 코드는 HostBuilder 파이프라인의 예를 보여 줍니다.

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(s =>
    {
        s.AddApplicationInsightsTelemetryWorkerService();
        s.ConfigureFunctionsApplicationInsights();
        s.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
        s.Configure<LoggerFilterOptions>(options =>
        {
            // The Application Insights SDK adds a default logging filter that instructs ILogger to capture only Warning and more severe logs. Application Insights requires an explicit override.
            // Log levels can also be configured using appsettings.json. For more information, see https://learn.microsoft.com/en-us/azure/azure-monitor/app/worker-service#ilogger-logs
            LoggerFilterRule toRemove = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");

            if (toRemove is not null)
            {
                options.Rules.Remove(toRemove);
            }
        });
    })
    .Build();

이 코드에는 using Microsoft.Extensions.DependencyInjection;이 필요합니다.

IHostBuilder에서 Build()를 호출하기 전에 다음을 수행해야 합니다.

  • ASP.NET Core 통합을 사용하는 경우 ConfigureFunctionsWebApplication()을 호출하고 그렇지 않은 경우 ConfigureFunctionsWorkerDefaults()를 호출합니다. 이러한 옵션에 대한 자세한 내용은 HTTP 트리거를 참조하세요.
    F#을 사용하여 애플리케이션을 작성하는 경우 일부 트리거 및 바인딩 확장에는 추가 구성이 필요합니다. F# 앱에서 이러한 확장을 사용하려는 경우 Blob 확장, 테이블 확장 및 Cosmos DB 확장에 대한 설정 설명서를 참조하세요.
  • 프로젝트에 필요한 서비스 또는 앱 구성을 구성합니다. 자세한 내용은 구성을 참조하세요.
    Application Insights를 사용하려는 경우 ConfigureServices() 대리자에서 AddApplicationInsightsTelemetryWorkerService() 및 ConfigureFunctionsApplicationInsights()를 호출해야 합니다. 자세한 내용은 Application Insights 를 참조하세요.

프로젝트가 .NET Framework 4.8을 대상으로 하는 경우 HostBuilder를 만들기 전에 FunctionsDebugger.Enable();을 추가해야 합니다. Main() 메서드의 첫 번째 줄이어야 합니다. 자세한 내용은 .NET Framework 대상으로 지정할 때 디버깅을 참조하세요.

Hostbuilder는 함수 앱을 시작하기 위해 비동기적으로 실행하는 완전히 초기화된 IHost 인스턴스를 빌드하고 반환하는 데 사용됩니다.

await host.RunAsync();

구성

사용하는 작성기 유형에 따라 애플리케이션을 구성하는 방법이 결정됩니다.

ConfigureFunctionsWorkerDefaults 메서드는 함수 앱을 실행하는 데 필요한 설정을 추가하는 데 사용됩니다. 이 메서드에는 다음 기능이 포함됩니다.

  • 기본 변환기 집합.
  • 속성 이름에서 대/소문자 구분을 무시하도록 기본 JsonSerializerOptions를 설정합니다.
  • Azure Functions 로깅과 통합.
  • 출력 바인딩 미들웨어 및 기능.
  • 함수 실행 미들웨어.
  • 기본 gRPC 지원.
.ConfigureFunctionsWorkerDefaults()

호스트 빌더 파이프라인에 대한 액세스 권한이 있으면 초기화하는 동안 앱별 구성을 설정할 수도 있습니다. HostBuilder에서 ConfigureAppConfiguration 메서드를 한 번 이상 호출하여 코드에 필요한 구성 원본을 추가할 수 있습니다. 앱 구성에 대한 자세한 정보는 ASP.NET Core의 구성을 참조하세요.

이러한 구성은 작성한 작업자 코드에만 적용되며 Functions 호스트 또는 트리거 및 바인딩의 구성에 직접적인 영향을 주지는 않습니다. 함수 호스트나 트리거 및 바인딩 구성을 변경하려면 host.json 파일을 계속 사용해야 합니다.

참고 항목

트리거 및 바인딩 구성에는 사용자 지정 구성 원본을 사용할 수 없습니다. 트리거 및 바인딩 구성은 애플리케이션 코드뿐만 아니라 Functions 플랫폼에서도 사용할 수 있어야 합니다. 애플리케이션 설정, Key Vault 참조 또는 App Configuration 참조 기능을 통해 이 구성을 제공할 수 있습니다.

종속성 주입

격리된 작업자 모델은 서비스를 주입하기 위해 표준 .NET 메커니즘을 사용합니다.

사용하는 HostBuilder경우 호스트 작성기에서 ConfigureServices를 호출하고 IServiceCollection의 확장 메서드를 사용하여 특정 서비스를 삽입합니다. 다음 예에서는 단일 서비스 종속성을 삽입합니다.

.ConfigureServices(services =>
{
    services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
})

이 코드에는 using Microsoft.Extensions.DependencyInjection;이 필요합니다. 자세히 알아보려면 ASP.NET Core의 종속성 주입을 참조하세요.

Azure 클라이언트 등록

종속성 주입을 사용하여 다른 Azure 서비스와 상호 작용할 수 있습니다. Microsoft.Extensions.Azure 패키지를 사용하여 .NET용 Azure SDK에서 클라이언트를 삽입할 수 있습니다. 패키지를 설치한 후 Program.cs의 서비스 컬렉션에서 AddAzureClients()을(를) 호출하여 클라이언트를 등록합니다. 다음 예제에서는 Azure Blob에 대해 명명된 클라이언트를 구성합니다.

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices((hostContext, services) =>
    {
        services.AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(hostContext.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });
    })
    .Build();

host.Run();

다음 예제에서는 삽입된 클라이언트와 이 등록 및 SDK 형식을 사용하여 Blob 콘텐츠를 한 컨테이너에서 다른 컨테이너로 스트림으로 복사하는 방법을 보여 줍니다.

using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Logging;

namespace MyFunctionApp
{
    public class BlobCopier
    {
        private readonly ILogger<BlobCopier> _logger;
        private readonly BlobContainerClient _copyContainerClient;

        public BlobCopier(ILogger<BlobCopier> logger, IAzureClientFactory<BlobServiceClient> blobClientFactory)
        {
            _logger = logger;
            _copyContainerClient = blobClientFactory.CreateClient("copierOutputBlob").GetBlobContainerClient("samples-workitems-copy");
            _copyContainerClient.CreateIfNotExists();
        }

        [Function("BlobCopier")]
        public async Task Run([BlobTrigger("samples-workitems/{name}", Connection = "MyStorageConnection")] Stream myBlob, string name)
        {
            await _copyContainerClient.UploadBlobAsync(name, myBlob);
            _logger.LogInformation($"Blob {name} copied!");
        }

    }
}

이 예제의 ILogger<T>는 종속성 주입을 통해 가져온 것이므로 자동으로 등록됩니다. 로깅에 대한 구성 옵션에 대한 자세한 내용은 로깅을 참조하세요.

팁

이 예제에서는 Program.cs 및 함수 모두에서 클라이언트 이름에 리터럴 문자열을 사용했습니다. 대신 함수 클래스에 정의된 공유 상수 문자열을 사용하는 것이 좋습니다. 예를 들어 두 위치에서 public const string CopyStorageClientName = nameof(_copyContainerClient);을(를) 추가한 다음 BlobCopier.CopyStorageClientName을(를) 참조할 수 있습니다. 마찬가지로 Program.cs에서가 아닌 함수를 사용하여 구성 섹션 이름을 정의할 수 있습니다.

미들웨어

격리된 작업자 모델은 ASP.NET에 있는 것과 유사한 모델을 사용하여 미들웨어 등록도 지원합니다. 이 모델은 함수 실행 전후에 호출 파이프라인으로 논리를 삽입하는 기능을 제공합니다.

ConfigureFunctionsWorkerDefaults 확장 메서드에는 다음 예에서 볼 수 있는 것처럼 사용자 자신의 미들웨어를 등록할 수 있는 오버로드가 있습니다.

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(workerApplication =>
    {
        // Register our custom middlewares with the worker

        workerApplication.UseMiddleware<ExceptionHandlingMiddleware>();

        workerApplication.UseMiddleware<MyCustomMiddleware>();

        workerApplication.UseWhen<StampHttpHeaderMiddleware>((context) =>
        {
            // We want to use this middleware only for http trigger invocations.
            return context.FunctionDefinition.InputBindings.Values
                          .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
        });
    })
    .Build();

UseWhen 확장 메서드를 사용하여 조건부로 실행되는 미들웨어를 등록할 수 있습니다. 이 메서드에 부울 값을 반환하는 조건자를 전달해야 하며 조건자의 반환 값이 true인 경우 미들웨어가 호출 처리 파이프라인에 참여합니다.

FunctionContext의 다음 확장 메서드를 사용하면 격리된 모델에서 미들웨어로 더 쉽게 작업할 수 있습니다.

메서드 설명
GetHttpRequestDataAsync HTTP 트리거에서 호출할 때 HttpRequestData 인스턴스를 가져옵니다. 이 메서드는 요청 헤더 및 쿠키와 같은 메시지 데이터를 읽으려는 경우에 유용한 ValueTask<HttpRequestData?> 인스턴스를 반환합니다.
GetHttpResponseData HTTP 트리거에서 호출할 때 HttpResponseData 인스턴스를 가져옵니다.
GetInvocationResult 현재 함수 실행의 결과를 나타내는 InvocationResult 인스턴스를 가져옵니다. 필요에 따라 Value 속성을 사용하여 값을 가져오거나 설정합니다.
GetOutputBindings 현재 함수 실행에 대한 출력 바인딩 항목을 가져옵니다. 이 메서드의 결과에 있는 각 항목은 형식 OutputBindingData입니다. 필요에 따라 Value 속성을 사용하여 값을 가져오거나 설정할 수 있습니다.
BindInputAsync 요청된 BindingMetadata 인스턴스에 대한 입력 바인딩 항목을 바인딩합니다. 예를 들어 미들웨어에서 사용해야 하는 BlobInput 입력 바인딩을 포함하는 함수가 있는 경우 이 메서드를 사용할 수 있습니다.

다음은 HttpRequestData 인스턴스를 읽고 함수 실행 중에 HttpResponseData 인스턴스를 업데이트하는 미들웨어 구현의 예입니다.

internal sealed class StampHttpHeaderMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        var requestData = await context.GetHttpRequestDataAsync();

        string correlationId;
        if (requestData!.Headers.TryGetValues("x-correlationId", out var values))
        {
            correlationId = values.First();
        }
        else
        {
            correlationId = Guid.NewGuid().ToString();
        }

        await next(context);

        context.GetHttpResponseData()?.Headers.Add("x-correlationId", correlationId);
    }
}

이 미들웨어는 특정 요청 헤더(x-correlationId)가 있는지 확인하고 헤더 값을 사용하여 응답 헤더를 스탬프합니다. 그렇지 않으면 새 GUID 값을 생성하고 응답 헤더를 스탬프하는 데 이 값을 사용합니다. 함수 앱에서 사용자 지정 미들웨어를 사용하는 방법에 대한 보다 자세한 예는 사용자 지정 미들웨어 참조 샘플을 참조하세요.

JSON serialization 사용자 지정

격리된 작업자 모델은 기본적으로 System.Text.Json을 사용합니다. Program.cs 파일의 일부로 서비스를 구성하여 직렬 변환기의 동작을 사용자 지정할 수 있습니다. 이 섹션에서는 범용 serialization에 대해 설명하며, 별도로 구성해야 하는 ASP.NET Core 통합을 사용하여 HTTP 트리거 JSON serialization에 영향을 주지 않습니다.

다음 예에서는 ConfigureFunctionsWebApplication을 사용하여 이를 보여 주지만 ConfigureFunctionsWorkerDefaults에서도 작동합니다.

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
        {
            jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
            jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
            jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

            // override the default value
            jsonSerializerOptions.PropertyNameCaseInsensitive = false;
        });
    })
    .Build();

host.Run();

대신 serialization에 JSON.NET(Newtonsoft.Json)를 사용할 수 있습니다. 이렇게 하려면 Microsoft.Azure.Core.NewtonsoftJson 패키지를 설치합니다. 그런 다음 서비스 등록에서 WorkerOptions 구성의 Serializer 속성을 다시 할당합니다. 다음 예에서는 ConfigureFunctionsWebApplication을 사용하여 이를 보여 주지만 ConfigureFunctionsWorkerDefaults에서도 작동합니다.

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<WorkerOptions>(workerOptions =>
        {
            var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
            settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
            settings.NullValueHandling = NullValueHandling.Ignore;

            workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
        });
    })
    .Build();

host.Run();

함수로 인식되는 메서드

함수 메서드는 다음 예제와 같이 Function 특성은 메서드에 적용되고 트리거 특성은 입력 매개 변수에 적용된 public 클래스의 public 메서드입니다.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

트리거 특성은 트리거 유형을 지정하고, 입력 데이터를 메서드 매개 변수에 바인딩합니다. 이전 예제 함수는 큐 메시지에 의해 트리거되며, 큐 메시지는 myQueueItem 매개 변수의 메서드에 전달됩니다.

Function 특성은 메서드를 함수 진입점으로 표시합니다. 이름은 프로젝트 내에서 고유해야 하고, 문자로 시작해야 하고, 문자, 숫자, _, -만 포함해야 하며 허용되는 최대 길이는 127자입니다. 프로젝트 템플릿에서 Run 메서드를 자주 만들지만, 유효한 C# 이름은 모두 메서드 이름이 될 수 있습니다. 이 메서드는 public 클래스의 public 멤버여야 합니다. 일반적으로 종속성 주입을 통해 서비스를 전달할 수 있도록 인스턴스 메서드여야 합니다.

함수 매개 변수

다음은 함수 메서드 서명의 일부로 포함할 수 있는 몇 가지 매개 변수입니다.

  • 바인딩 - 매개 변수를 특성으로 데코레이팅하여 표시됩니다. 함수는 정확히 하나의 트리거 매개 변수를 포함해야 합니다.
  • 실행 컨텍스트 개체 - 현재 호출에 대한 정보를 제공합니다.
  • 취소 토큰 - 정상적인 종료에 사용됩니다.

실행 컨텍스트

.NET 격리는 함수 메서드에 FunctionContext 개체를 전달합니다. 이 개체를 사용하면 GetLogger 메서드를 호출하고 categoryName 문자열을 제공하여 로그에 기록할 ILogger 인스턴스를 가져올 수 있습니다. 종속성 주입을 사용하지 않고도 이 컨텍스트를 사용하여 ILogger를 가져올 수 있습니다. 자세히 알아보려면 로깅을 참조하세요.

취소 토큰

함수는 함수가 종료될 때 운영 체제가 코드에 알릴 수 있게 해주는 CancellationToken 매개 변수를 사용할 수 있습니다. 이 알림을 통해 함수가 예기치 않게 종료되어 데이터가 일관되지 않은 상태가 되는 것을 방지할 수 있습니다.

격리 작업자 프로세스에서 실행할 때 .NET 함수에서 취소 토큰이 지원됩니다. 다음 예제에서는 취소 요청이 수신될 때 예외를 발생합니다.

[Function(nameof(ThrowOnCancellation))]
public async Task ThrowOnCancellation(
    [EventHubTrigger("sample-workitem-1", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(ThrowOnCancellation));

    foreach (var message in messages)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

다음 예제에서는 취소 요청이 수신될 때 정리 작업을 수행합니다.

[Function(nameof(HandleCancellationCleanup))]
public async Task HandleCancellationCleanup(
    [EventHubTrigger("sample-workitem-2", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(HandleCancellationCleanup));

    foreach (var message in messages)
    {
        if (cancellationToken.IsCancellationRequested)
        {
            _logger.LogInformation("A cancellation token was received, taking precautionary actions.");
            // Take precautions like noting how far along you are with processing the batch
            _logger.LogInformation("Precautionary activities complete.");
            break;
        }

        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

바인딩

바인딩은 메서드, 매개 변수 및 반환 형식에 대한 특성을 사용하여 정의됩니다. 바인딩은 문자열, 배열 및 직렬화 가능한 형식(예: POCO(Plain Old Class Object))과 같은 데이터를 제공할 수 있습니다. 일부 바인딩 확장의 경우 서비스 SDK에 정의된 서비스별 형식에 바인딩할 수도 있습니다.

HTTP 트리거의 경우 HTTP 트리거 섹션을 참조하세요.

격리 작업자 프로세스 함수를 실행할 때 트리거와 바인딩을 사용하기 위한 전체 참조 샘플 집합은 바인딩 확장 참조 샘플을 참조하세요.

입력 바인딩

함수에는 데이터를 함수에 전달할 수 있는 0개 이상의 입력 바인딩이 있을 수 있습니다. 트리거와 마찬가지로 입력 바인딩은 입력 매개 변수에 바인딩 특성을 적용하여 정의됩니다. 함수가 실행되면 런타임은 바인딩에 지정된 데이터를 가져오려고 시도합니다. 요청되는 데이터는 일반적으로 바인딩 매개 변수를 사용하여 트리거가 제공하는 정보에 따라 다릅니다.

출력 바인딩

출력 바인딩에 쓰려면 바인딩된 서비스에 쓰는 방법을 정의한 함수 메서드에 출력 바인딩 특성을 적용해야 합니다. 메서드에서 반환된 값은 출력 바인딩에 기록됩니다. 예를 들어 다음 예에서는 출력 바인딩을 사용하여 이름이 output-queue인 메시지 큐에 문자열 값을 씁니다.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

여러 출력 바인딩

출력 바인딩에 기록된 데이터는 항상 함수의 반환 값입니다. 둘 이상의 출력 바인딩에 써야 하는 경우 사용자 지정 반환 형식을 만들어야 합니다. 이 반환 형식에는 클래스의 하나 이상의 속성에 적용되는 출력 바인딩 특성이 있어야 합니다. 다음 예제는 HTTP 응답과 큐 출력 바인딩 모두에 쓰는 ASP.NET Core 통합을 사용하는 HTTP 트리거 함수입니다.

public class MultipleOutputBindings
{
    private readonly ILogger<MultipleOutputBindings> _logger;

    public MultipleOutputBindings(ILogger<MultipleOutputBindings> logger)
    {
        _logger = logger;
    }

    [Function("MultipleOutputBindings")]
    public MyOutputType Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        _logger.LogInformation("C# HTTP trigger function processed a request.");
        var myObject = new MyOutputType
        {
            Result = new OkObjectResult("C# HTTP trigger function processed a request."),
            MessageText = "some output"
        };
        return myObject;
    }

    public class MyOutputType
    {
        [HttpResult]
        public IActionResult Result { get; set; }

        [QueueOutput("myQueue")]
        public string MessageText { get; set; }
    }
}

ASP.NET Core 통합을 다양한 출력 바인딩을 위한 사용자 지정 반환 형식을 사용하는 경우, 결과를 제공하는 속성에 [HttpResult] 특성을 추가해야 합니다. HttpResult 특성은 HTTP 확장 3.2.0 이상 및 ASP.NET Core 확장 1.3.0 이상과 함께 SDK 1.17.3-preview2 이상을 이용할 때 사용할 수 있습니다.

SDK 형식

일부 서비스별 바인딩 형식의 경우 서비스 SDK 및 프레임워크의 형식을 사용하여 바인딩 데이터를 제공할 수 있습니다. 이러한 기능은 직렬화된 문자열 또는 POCO(Plain Old Class Object)가 제공할 수 있는 것 이상의 더 많은 기능을 제공합니다. 최신 형식을 사용하려면 최신 버전의 핵심 종속성을 사용하도록 프로젝트를 업데이트해야 합니다.

Dependency 버전 요구 사항
Microsoft.Azure.Functions.Worker 1.18.0 이상
Microsoft.Azure.Functions.Worker.Sdk 1.13.0 이상

컴퓨터에서 로컬로 SDK 형식을 테스트하는 경우 Azure Functions Core Tools 버전 4.0.5000 이상을 사용해야 합니다. func version 명령을 사용하여 현재 버전을 확인할 수 있습니다.

각 트리거 및 바인딩 확장에는 확장 참조 문서에 설명된 자체 최소 버전 요구 사항도 있습니다. 다음 서비스별 바인딩은 SDK 형식을 제공합니다.

서비스 트리거 입력 바인딩 출력 바인딩
Azure Blob 일반 공급 일반 공급 SDK 형식은 권장되지 않습니다.1
Azure 큐 일반 공급 입력 바인딩이 없음 SDK 형식은 권장되지 않습니다.1
Azure Service Bus 일반 공급 입력 바인딩이 없음 SDK 형식은 권장되지 않습니다.1
Azure Event Hubs 일반 공급 입력 바인딩이 없음 SDK 형식은 권장되지 않습니다.1
Azure Cosmos DB SDK 형식이 사용되지 않음2 일반 공급 SDK 형식은 권장되지 않습니다.1
Azure 테이블 트리거가 없음 일반 공급 SDK 형식은 권장되지 않습니다.1
Azure Event Grid 일반 공급 입력 바인딩이 없음 SDK 형식은 권장되지 않습니다.1

1 SDK 형식을 사용하는 출력 시나리오의 경우 출력 바인딩을 사용하는 대신 SDK 클라이언트를 직접 만들고 작업해야 합니다. 종속성 주입 예제는 Azure 클라이언트 등록을 참조하세요.

2 Cosmos DB 트리거는 Azure Cosmos DB 변경 피드를 사용하고 변경 피드 항목을 JSON 직렬화 가능 형식으로 노출합니다. 이 시나리오에서는 SDK 형식이 없습니다.

참고 항목

트리거 데이터에 의존하는 바인딩 식을 사용하는 경우 트리거 자체에 대한 SDK 형식을 사용할 수 없습니다.

HTTP 트리거

HTTP 트리거를 사용하면 HTTP 요청을 통해 함수를 호출할 수 있습니다. 사용할 수 있는 두 가지 방법이 있습니다.

  • ASP.NET Core 개발자에게 친숙한 개념을 사용하는 ASP.NET Core 통합 모델
  • 기본 제공 모델 - 추가 종속성이 필요하지 않고 HTTP 요청 및 응답에 사용자 지정 형식 사용 이 방법은 이전 .NET 격리 작업자 앱에 대해 이전 버전과의 호환성을 위해 유지 관리됩니다.

ASP.NET Core 통합

이 섹션에서는 HttpRequest, HttpResponse 및 IActionResult를 포함한 ASP.NET Core 형식을 사용하여 기본 HTTP 요청 및 응답 개체를 사용하는 방법을 보여 줍니다. 이 모델은 .NET Framework를 대상으로 하는 앱에서 사용할 수 없으므로 대신 기본 제공 모델을 활용해야 합니다.

참고 항목

ASP.NET Core의 모든 기능이 이 모델에서 노출되는 것은 아닙니다. 특히 ASP.NET Core 미들웨어 파이프라인 및 라우팅 기능은 사용할 수 없습니다. ASP.NET Core 통합을 사용하려면 업데이트된 패키지를 사용해야 합니다.

HTTP에 ASP.NET Core 통합을 사용하도록 설정하려면 다음을 수행합니다.

  1. Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore 패키지 버전 1.0.0 이상에 대한 참조를 프로젝트에 추가합니다.

  2. 이러한 특정 패키지 버전을 사용하도록 프로젝트를 업데이트합니다.

  3. Program.cs 파일에서 호출ConfigureFunctionsWebApplication()할 호스트 작성기 구성을 업데이트합니다. 그렇지 않으면 해당 메서드를 ConfigureFunctionsWorkerDefaults() 사용하는 경우 이 메서드가 대체됩니다. 다음 예제에서는 다른 사용자 지정 없이 최소 설정을 보여 줍니다.

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .Build();

host.Run();

  4. ASP.NET Core 형식을 사용하도록 기존 HTTP 트리거 함수를 업데이트합니다. 이 예제에서는 간단한 "hello, world" 함수에 사용되는 표준 HttpRequest 및 IActionResult를 보여 줍니다.

    [Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

ASP.NET Core 통합을 사용하여 JSON 직렬화

ASP.NET Core에는 자체 serialization 계층이 있으며 일반 serialization 구성을 사용자 지정하는 것에 영향을 받지 않습니다. HTTP 트리거에 사용되는 serialization 동작을 사용자 지정하려면 서비스 등록의 일부로 .AddMvc() 호출을 포함해야 합니다. 반환된 IMvcBuilder(은)는 사용하여 ASP.NET Core의 JSON serialization 설정을 수정하는데 사용할 수 있습니다. 다음 예제에서는 이 방법을 사용하여 serialization에 대한 JSON.NET(Newtonsoft.Json)를 구성하는 방법을 보여 줍니다.

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
        services.AddMvc().AddNewtonsoftJson();
    })
    .Build();
host.Run();

기본 제공 HTTP 모델

기본 제공 모델에서 시스템은 들어오는 HTTP 요청 메시지를 함수에 전달되는 HttpRequestData 개체로 변환합니다. 이 개체는 Headers, Cookies, Identities, URL 및 메시지 Body(선택 사항)을(를) 포함하여 요청의 데이터를 제공합니다. 이 개체는 HTTP 요청의 표현이지만 기본 HTTP 수신기 또는 수신된 메시지에 직접 연결되지는 않습니다.

마찬가지로 함수는 메시지 StatusCode, Headers 및 메시지 Body(선택 사항)을(를) 포함하여 HTTP 응답을 만드는 데 사용되는 데이터를 제공하는 HttpResponseData 개체를 반환합니다 .

다음 예제에서는 HttpRequestData 및 HttpResponseData의 사용을 보여 줍니다.

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

로깅

또는 ILogger 인스턴스를 사용하여 ILogger<T> 로그에 쓸 수 있습니다. 로거는 ILogger<T> 또는 ILoggerFactory의 종속성 주입을 통해 가져올 수 있습니다.

public class MyFunction {
    
    private readonly ILogger<MyFunction> _logger;
    
    public MyFunction(ILogger<MyFunction> logger) {
        _logger = logger;
    }
    
    [Function(nameof(MyFunction))]
    public void Run([BlobTrigger("samples-workitems/{name}", Connection = "")] string myBlob, string name)
    {
        _logger.LogInformation($"C# Blob trigger function Processed blob\n Name: {name} \n Data: {myBlob}");
    }

}

함수에 전달된 FunctionContext 개체에서 로거를 가져올 수도 있습니다. GetLogger<T> 또는 GetLogger 메서드를 호출하여 로그가 기록되는 범주의 이름인 문자열 값을 전달합니다. 범주는 일반적으로 로그가 기록되는 특정 함수의 이름입니다. 범주에 대해 자세히 알아보려면 모니터링 문서를 참조하세요.

ILogger<T> 및 ILogger의 메서드를 사용하여 LogWarning 또는 LogError와 같은 다양한 로그 수준을 기록합니다. 로그 수준에 대해 자세히 알아보려면 모니터링 문서를 참조하세요. 필터를 등록하여 코드에 추가된 구성 요소의 로그 수준을 사용자 지정할 수 있습니다.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services =>
    {
        // Registers IHttpClientFactory.
        // By default this sends a lot of Information-level logs.
        services.AddHttpClient();
    })
    .ConfigureLogging(logging =>
    {
        // Disable IHttpClientFactory Informational logs.
        // Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
        logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    })
    .Build();

Program.cs에서 앱을 구성하는 과정의 일환으로 오류가 로그에 표시되는 방식에 대한 동작을 정의할 수도 있습니다. 기본 동작은 사용 중인 작성기의 유형에 따라 달라집니다.

기본적으로 코드를 사용하는 HostBuilder경우 코드에서 throw된 예외가 으로 래핑될 RpcException수 있습니다. 이 추가 계층을 제거하려면 작성기 구성의 일부로 EnableUserCodeException 속성을 "true"로 설정합니다.

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(builder => {}, options =>
    {
        options.EnableUserCodeException = true;
    })
    .Build();

host.Run();

Application Insights

로그를 직접 Application Insights로 내보내도록 격리된 프로세스 애플리케이션을 구성할 수 있습니다. 이 동작은 호스트를 통해 로그를 릴레이하는 기본 동작을 대체하며, 이를 통해 로그를 내보내는 방법을 제어할 수 있으므로 권장됩니다.

패키지 설치

코드에서 Application Insights에 직접 로그를 쓰려면 프로젝트에서 이러한 패키지에 대한 참조를 추가합니다.

다음 명령을 실행하여 프로젝트에 이러한 참조를 추가할 수 있습니다.

dotnet add package Microsoft.ApplicationInsights.WorkerService
dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights

시작 구성

패키지가 설치되면 다음 예제와 같이 Program.cs 파일에서 서비스 구성 중에 AddApplicationInsightsTelemetryWorkerService() 및 ConfigureFunctionsApplicationInsights()를 호출해야 합니다.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

ConfigureFunctionsApplicationInsights()를 호출하면 Functions 정의 ActivitySource을 수신 대기하는 ITelemetryModule을 추가합니다. 이렇게 하면 분산 추적을 지원하는 데 필요한 종속성 원격 분석이 만들어집니다. AddApplicationInsightsTelemetryWorkerService()에 대한 자세한 내용과 사용 방법은 Application Insights for Worker Service 애플리케이션을 참조하세요.

로그 수준 관리

Important

Functions 호스트와 격리된 프로세스 작업자에는 로그 수준 등에 대한 별도의 구성이 있습니다. host.json의 Application Insights 구성은 작업자의 로깅에 영향을 주지 않으며, 마찬가지로 작업자 코드에서 만든 구성은 호스트의 로깅에 영향을 주지 않습니다. 시나리오에 두 계층 모두에서 사용자 지정이 필요한 경우 두 위치에서 변경 내용을 적용해야 합니다.

나머지 애플리케이션은 ILogger 및 ILogger<T>에서 계속 작동합니다. 그러나 기본적으로 Application Insights SDK는 로거에 경고 및 더 심각한 로그만 캡처하도록 지시하는 로깅 필터를 추가합니다. 이 동작을 사용하지 않도록 설정하려면 서비스 구성의 일부로 필터 규칙을 제거합니다.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .ConfigureLogging(logging =>
    {
        logging.Services.Configure<LoggerFilterOptions>(options =>
        {
            LoggerFilterRule defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
            if (defaultRule is not null)
            {
                options.Rules.Remove(defaultRule);
            }
        });
    })
    .Build();

host.Run();

성능 최적화

이 섹션에서는 콜드 부팅을 중심으로 성능을 개선하기 위해 사용하도록 설정할 수 있는 옵션을 간략하게 설명합니다.

일반적으로 앱은 최신 버전의 핵심 종속성을 사용해야 합니다. 최소한 다음과 같이 프로젝트를 업데이트해야 합니다.

  1. Microsoft.Azure.Functions.Worker를 버전 1.19.0 이상으로 업그레이드합니다.
  2. Microsoft.Azure.Functions.Worker.Sdk를 버전 1.16.4 이상으로 업그레이드합니다.
  3. 앱이 .NET Framework를 대상으로 하지 않는 한, Microsoft.AspNetCore.App에 프레임워크 참조를 추가합니다.

다음 코드 조각은 프로젝트 파일의 컨텍스트에서 이 구성을 보여 줍니다.

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
  </ItemGroup>

자리 표시자

자리 표시자는 .NET 6 이상을 대상으로 하는 앱의 콜드 부팅을 개선하는 플랫폼 기능입니다. 이 최적화를 사용하려면 다음 단계를 사용하여 자리 표시자를 명시적으로 사용하도록 설정해야 합니다.

  1. 이전 섹션에 설명된 대로 최신 종속성 버전을 사용하도록 프로젝트 구성을 업데이트합니다.

  2. WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED 애플리케이션 설정을 az functionapp config appsettings set 명령을 사용하여 수행할 수 있는 1로 설정합니다.

    az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'

    이 예제에서 <groupName>을 리소스 그룹의 이름으로 바꾸고 <appName>을 함수 앱의 이름으로 바꿉니다.

  3. 함수 앱의 netFrameworkVersion 속성이 .NET 6 이상이어야 하는 프로젝트의 대상 프레임워크와 일치하는지 확인합니다. 이 az functionapp config set 명령을 사용하여 이 작업을 수행할 수 있습니다.

    az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

    이 예제에서는 대상 .NET 버전에 따라 <framework>를 적절한 버전 문자열(예: v8.0)로 바꿉니다.

  4. az functionapp config set 명령을 사용하여 함수 앱이 64비트 프로세스를 사용하도록 구성되어 있는지 확인합니다.

    az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false

Important

WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED를 1로 설정할 때 다른 모든 함수 앱 구성을 올바르게 설정해야 합니다. 그렇지 않으면 함수 앱이 시작되지 않을 수 있습니다.

최적화된 실행기

함수 실행기는 호출이 실행되도록 하는 플랫폼의 구성 요소입니다. 이 구성 요소의 최적화된 버전은 기본적으로 SDK 버전 1.16.2부터 사용하도록 설정됩니다. 다른 구성은 필요하지 않습니다.

ReadyToRun

함수 앱을 ReadyToRun 이진 파일로 컴파일할 수 있습니다. ReadyToRun은 사용 플랜에서 실행할 때 콜드 부팅의 영향을 줄이는 데 도움이 되도록 시작 성능을 개선할 수 있는 사전 컴파일 형식입니다. ReadyToRun은 .NET 6 이상 버전에서 사용할 수 있으며 Azure Functions 런타임 버전 4.0 이상이 필요합니다.

ReadyToRun을 사용하려면 호스팅 앱의 런타임 아키텍처에 대해 프로젝트를 빌드해야 합니다. 이러한 항목이 정렬되지 않으면 시작 시 앱에 오류가 발생합니다. 다음 표에서 런타임 식별자를 선택합니다.

운영 체제 앱은 32비트1입니다. 런타임 식별자
Windows True win-x86
Windows False win-x64
Linux True 해당 없음(지원되지 않음)
Linux False linux-x64

1 64비트 앱만 다른 성능 최적화에 적합합니다.

Windows 앱이 32비트 또는 64비트인지 확인하기 위해 다음 CLI 명령을 실행하여 <group_name>을(를) 리소스 그룹의 이름으로 기리고 <app_name>을(를) 애플리케이션 이름으로 바꿉니다. "true"의 출력은 앱이 32비트이고 "false"가 64비트를 임을 나타냅니다.

 az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

다음 명령을 사용하여 동일하게 바꾼 다음, 애플리케이션을 64비트로 변경할 수 있습니다.

az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

프로젝트를 ReadyToRun으로 컴파일하려면 <PublishReadyToRun> 및 <RuntimeIdentifier> 요소를 추가하여 프로젝트 파일을 업데이트합니다. 다음 예제에서는 Windows 64비트 함수 앱에 게시하기 위한 구성을 보여 줍니다.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

<RuntimeIdentifier>을(를) 프로젝트 파일의 일부로 설정하지 않으려면 게시 제스처 자체의 일부로 구성할 수도 있습니다. 예를 들어 Windows 64비트 함수 앱을 사용하는 경우 .NET CLI 명령은 다음과 같습니다.

dotnet publish --runtime win-x64

Visual Studio에서 게시 프로필의 대상 런타임 옵션을 올바른 런타임 식별자로 설정해야 합니다. 기본값 Portable로 설정하면 ReadyToRun이 사용되지 않습니다.

Azure Functions에 배포

함수 코드 프로젝트를 Azure에 배포하는 경우 함수 앱이나 Linux 컨테이너에서 실행되어야 합니다. 코드를 배포하기 전에 함수 앱 및 기타 필요한 Azure 리소스가 있어야 합니다.

Linux 컨테이너에 함수 앱을 배포할 수도 있습니다. 자세한 내용은 컨테이너 및 Azure Functions 작업을 참조하세요.

Azure 리소스 만들기

다음 방법 중 하나를 사용하여 Azure에서 함수 앱 및 기타 필수 리소스를 만들 수 있습니다.

  • Visual Studio: Visual Studio는 코드 게시 프로세스 중에 사용자를 위해 리소스를 만들 수 있습니다.
  • Visual Studio Code: Visual Studio Code는 구독에 연결하고 앱에 필요한 리소스를 만든 다음, 코드를 게시할 수 있습니다.
  • Azure CLI: Azure CLI를 사용하여 Azure에서 필요한 리소스를 만들 수 있습니다.
  • Azure PowerShell: Azure PowerShell을 사용하여 Azure에서 필요한 리소스를 만들 수 있습니다.
  • 배포 템플릿: ARM 템플릿 및 Bicep 파일을 사용하여 Azure에 대한 필수 리소스 배포를 자동화할 수 있습니다. 템플릿에 필요한 설정이 포함되어 있는지 확인합니다.
  • Azure Portal: Azure Portal에서 필요한 리소스를 만들 수 있습니다.

애플리케이션 게시

Azure에서 함수 앱 및 기타 필수 리소스를 만든 후 다음 방법 중 하나를 사용하여 코드 프로젝트를 Azure에 배포할 수 있습니다.

자세한 내용은 Azure Functions의 배포 기술을 참조하세요.

배포 페이로드

대부분의 배포 방법에서는 zip 보관을 사용합니다. zip 보관 파일을 직접 만드는 경우 이 섹션에 설명된 구조를 따라야 합니다. 그렇지 않으면 시작 시 앱에 오류가 발생할 수 있습니다.

배포 페이로드는 포함하는 부모 폴더가 없어도 dotnet publish 명령의 출력과 일치해야 합니다. zip 보관은 다음 파일로 만들어야 합니다.

  • .azurefunctions/
  • extensions.json
  • functions.metadata
  • host.json
  • worker.config.json
  • 프로젝트 실행 파일(콘솔 앱)
  • 해당 실행 파일과 관련된 기타 지원 파일 및 디렉터리

이러한 파일은 빌드 프로세스에 의해 생성되며 직접 편집할 수 없습니다.

배포용 zip 보관을 준비할 때 포함하는 디렉터리 자체가 아닌 출력 디렉터리의 콘텐츠만 압축해야 합니다. 보관이 현재 작업 디렉터리로 추출되면 위에 나열된 파일이 즉시 표시되어야 합니다.

배포 요구 사항

운영 체제에 따라 Azure의 격리된 작업자 모델에서 .NET 함수를 실행하기 위한 몇 가지 요구 사항이 있습니다.

이전 섹션의 메서드를 사용하여 Azure에서 함수 앱을 만들 때 이러한 필수 설정이 추가됩니다. 자동화를 위해 ARM 템플릿 또는 Bicep 파일을 사용하여 이러한 리소스를 만들 때 템플릿에서 설정해야 합니다.

디버깅

Visual Studio 또는 Visual Studio Code를 사용하여 로컬로 실행하는 경우 .NET 격리 작업자 프로젝트를 정상적으로 디버그할 수 있습니다. 그러나 예상대로 작동하지 않는 두 가지 디버깅 시나리오가 있습니다.

Visual Studio를 사용하여 원격 디버깅

격리 작업자 프로세스 앱은 Functions 런타임 외부에서 실행되므로 원격 디버거를 별도의 프로세스에 연결해야 합니다. Visual Studio를 사용하여 디버그하는 방법에 대한 자세한 내용은 원격 디버깅을 참조하세요.

.NET Framework를 대상으로 지정할 때 디버깅

격리된 프로젝트가 .NET Framework 4.8을 대상으로 하는 경우 현재 미리 보기 범위에는 디버깅을 사용하도록 설정하는 수동 단계가 필요합니다. 다른 대상 프레임워크를 사용하는 경우에는 이러한 단계가 필요하지 않습니다.

앱은 먼저 첫 번째 작업으로 FunctionsDebugger.Enable();을 호출합니다. 이는 HostBuilder를 초기화하기 전에 Main() 메서드에서 발생합니다. Program.cs 파일은 다음과 유사하게 표시되어야 합니다.

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

namespace MyDotnetFrameworkProject
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .Build();

            host.Run();
        }
    }
}

다음으로, .NET Framework 디버거를 사용하여 프로세스에 수동으로 연결해야 합니다. Visual Studio는 격리 작업자 프로세스 .NET Framework 앱에 대해 자동으로 이 작업을 수행하지 않으므로 "디버깅 시작" 작업을 피해야 합니다.

프로젝트 디렉터리(또는 해당 빌드 출력 디렉터리)에서 다음을 실행합니다.

func host start --dotnet-isolated-debug

그러면 작업자가 시작되고 프로세스는 다음 메시지를 나타내며 중지됩니다.

Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...

여기서 <process id>는 작업자 프로세스의 ID입니다. 이제 Visual Studio를 사용하여 프로세스에 수동으로 연결할 수 있습니다. 이 작업에 대한 지침은 실행 중인 프로세스에 연결하는 방법을 참조하세요.

디버거가 연결되면 프로세스 실행이 다시 시작되어 디버그할 수 있게 됩니다.

.NET 버전 미리 보기

일반 공급 릴리스 전에 .NET 버전이 미리 보기 또는 게시 상태로 출시될 수 있습니다. 이러한 상태에 대한 자세한 내용은 .NET 공식 지원 정책을 참조하세요.

로컬 Functions 프로젝트에서 지정된 릴리스를 대상으로 지정할 수 있지만 Azure에서 호스트되는 함수 앱에는 해당 릴리스를 사용하지 못할 수 있습니다. Azure Functions는 이 섹션에서 설명한 미리 보기 또는 게시 릴리스에서만 사용할 수 있습니다.

Azure Functions는 현재 다음 "미리 보기" 또는 "라이브 전환" .NET 릴리스와 함께 사용할 수 있습니다.

운영 체제 .NET 미리 보기 버전
Windows .NET 9 미리 보기 61, 2
Linux .NET 9 RC21, 3

1 .NET 9를 성공적으로 대상 지정하려면 프로젝트에서 핵심 패키지의 2.x 버전을 참조해야 합니다. Visual Studio를 사용하는 경우 .NET 9에는 17.12 이상 버전이 필요합니다.

2 미리 보기 기간 동안 일부 클라이언트에는 Windows에 대한 지원이 표시되지 않을 수 있습니다.

3 .NET 9는 Flex Consumption SKU에서 아직 지원되지 않습니다.

사용할 수 있는 일반 공급 릴리스 목록은 지원되는 버전을 참조하세요.

미리 보기 .NET SDK 사용

.NET 미리 보기 버전에서 Azure Functions를 사용하려면 다음을 수행하여 프로젝트를 업데이트해야 합니다.

  1. 개발에서 관련 .NET SDK 버전 설치
  2. .csproj 파일에서 TargetFramework 설정 변경

Azure에서 함수 앱에 배포하는 경우 해당 프레임워크가 앱에서 사용 가능한지 확인해야 합니다. 미리 보기 기간 동안 일부 도구와 환경은 새로운 미리 보기 버전을 옵션으로 표시하지 않을 수 있습니다. 예를 들어 Azure Portal에 포함된 미리 보기 버전이 표시되지 않으면 REST API, Bicep 템플릿 또는 Azure CLI를 사용하여 버전을 수동으로 구성할 수 있습니다.

Windows에서 호스트되는 앱의 경우 다음 Azure CLI 명령을 사용합니다. <groupName>을(를) 리소스 그룹의 이름으로 바꾸고 <appName>을(를) 함수 앱의 이름으로 바꿉니다. <framework>를 v8.0과 같은 적절한 버전 문자열로 바꿉니다.

az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

.NET 미리 보기 버전 사용 시 고려 사항

.NET 미리 보기 버전에서 Functions를 사용할 때 다음 고려 사항을 염두에 두세요.

  • Visual Studio에서 함수를 빌드하는 경우 .NET 미리 보기 SDK를 사용하여 Azure Functions 프로젝트 빌드를 지원하는 Visual Studio Preview를 사용해야 합니다.

  • 최신 Functions 도구 및 템플릿이 있는지 확인합니다. 도구를 업데이트하려면 다음을 수행합니다.

    1. 도구>옵션으로 이동한 후 프로젝트 및 솔루션에서 Azure Functions를 선택합니다.
    2. 업데이트 확인을 선택하고 메시지가 표시되면 업데이트를 설치합니다.

  • 미리 보기 기간 동안 개발 환경에는 호스트된 서비스보다 최신 버전의 .NET 미리 보기가 있을 수 있습니다. 이로 인해 배포 시 함수 앱이 실패할 수 있습니다. 이 문제를 해결하려면 global.json에서 사용할 SDK 버전을 지정할 수 있습니다.

    1. dotnet --list-sdks 명령을 실행하고 로컬 개발 중에 현재 사용 중인 미리 보기 버전을 확인합니다.
    2. <SDK_VERSION>가 로컬에서 사용 중인 버전인 경우 dotnet new globaljson --sdk-version <SDK_VERSION> --force 명령을 실행합니다. 예를 들어, dotnet new globaljson --sdk-version dotnet-sdk-8.0.100-preview.7.23376.3 --force를 사용하면 프로젝트를 빌드할 때 시스템이 .NET 8 Preview 7 SDK를 사용하게 됩니다.

참고 항목

미리 보기 프레임워크의 Just-In-Time 로드로 인해 Windows에서 실행되는 함수 앱은 이전 GA 버전에 비해 콜드 부팅 시간이 길어질 수 있습니다.

다음 단계

Azure Functions에 대한 모범 사례에 대해 자세히 알아보기

격리된 작업자 모델로 .NET 앱 마이그레이션