Azure Functions 버전 3.x에서 버전 4.x로 앱 마이그레이션

  • 아티클

Azure Functions 버전 4.x는 이전 버전 3.x와 호환됩니다. 대부분의 앱은 중요한 코드 변경 없이 4.x로 안전하게 마이그레이션되어야 합니다. Functions 런타임 버전에 대한 자세한 내용은 Azure Functions 런타임 버전 개요를 참조하세요.

Important

2022년 12월 13일부터 Azure Functions 런타임 버전 2.x 및 3.x에서 실행되는 함수 앱의 추가 지원이 종료되었습니다. 자세한 내용은 사용 중지된 버전을 참조하세요.

이 문서에서는 Functions 런타임 버전 4.x에서 실행되도록 함수 앱을 안전하게 마이그레이션하는 프로세스를 안내합니다. 프로젝트 마이그레이션 지침은 언어에 따라 다르므로 문서 상단의 선택기에서 개발 언어를 선택해야 합니다.

마이그레이션할 함수 앱 식별

다음 PowerShell 스크립트를 사용하여 구독에서 현재 버전 2.x 또는 3.x를 대상으로 하는 함수 앱 목록을 생성합니다.

$Subscription = '<YOUR SUBSCRIPTION ID>' 
 
Set-AzContext -Subscription $Subscription | Out-Null

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"] -like '*3*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

대상 .NET 버전 선택

Functions 런타임 버전 3.x에서 C# 함수 앱은 격리된 작업자 모델을 사용하여 In Process 모델 또는 .NET 5를 사용하여 .NET Core 3.1을 대상으로 합니다.

함수 앱을 마이그레이션할 때 .NET의 대상 버전을 선택할 수 있습니다. Functions 버전 4.x에서 지원되는 다음 버전의 .NET 중 하나로 C# 프로젝트를 업데이트할 수 있습니다.

.NET 버전 .NET 공식 지원 정책 릴리스 유형 Functions 프로세스 모델1,3
.NET 82 LTS 격리된 작업자 모델
.NET 7 STS(2024년 5월 14일 지원 종료) 격리된 작업자 모델
.NET 6 LTS(2024년 11월 12일 지원 종료) 격리된 작업자 모델,
In Process 모델3
.NET Framework 4.8 정책 참조 격리된 작업자 모델

1격리된 작업자 모델은 .NET Framework뿐만 아니라 LTS(장기 지원) 및 STS(표준 기간 지원) 버전의 .NET을 지원합니다. In Process 모델은 .NET의 LTS 릴리스만 지원합니다. 두 모델 간의 전체 기능 비교는 In Process 및 격리 작업자 프로세스 .NET Azure Functions의 차이점을 참조하세요.

2 .NET 8은 격리된 작업자 모델에서 사용할 수 있지만 In-Process 모델에서는 아직 지원되지 않습니다. 진행 중인 모델에 대한 향후 옵션을 포함하여 .NET 8 계획에 대한 자세한 내용은 Azure Functions 로드맵 업데이트 게시물을 참조하세요.

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

팁

격리된 작업자 모델에서는 .NET 8로 업데이트하는 것이 좋습니다. .NET 8은 .NET에서 지원 기간이 가장 긴 완전 릴리스 버전입니다.

대신 In Process 모델을 사용하도록 선택할 수도 있지만 피할 수 없다면 권장되지 않습니다. In Process 모델에 대한 지원이 2026년 11월 10일에 종료되므로 그 전에 격리된 작업자 모델로 전환해야 합니다. 버전 4.x로 마이그레이션하는 동안 이렇게 하면 필요한 총 활동이 줄어들고, 격리된 작업자 모델에서 향후 버전의 .NET을 더욱 쉽게 대상 지정할 수 있는 기능을 포함하여 앱에 추가적인 이점이 제공됩니다. 격리된 작업자 모델로 전환하는 경우 .NET 업그레이드 도우미가 필요한 여러 코드 변경 내용을 자동으로 처리할 수도 있습니다.

이 가이드에서는 격리된 작업자 모델의 .NET 7 또는 .NET 6에 대한 구체적인 예제를 제시하지 않습니다. 이러한 버전을 대상으로 지정해야 하는 경우 .NET 8 격리 작업자 모델 예제를 적용할 수 있습니다.

마이그레이션 준비

아직 하지 않은 경우 Azure PowerShell을 사용하여 현재 Azure 구독에서 마이그레이션해야 하는 앱 목록을 식별합니다.

앱을 Functions 런타임 버전 4.x로 마이그레이션하기 전에 다음 작업을 수행해야 합니다.

  1. 3.x와 4.x 사이의 호환성이 손상되는 변경 목록을 검토합니다.
  2. 로컬 프로젝트를 버전 4.x로 마이그레이션하려면 로컬 프로젝트 마이그레이션의 단계를 완료합니다.
  3. 프로젝트를 마이그레이션한 후 Azure Functions Core Tools 버전 4.x를 사용하여 앱을 로컬로 완전히 테스트합니다.
  4. Azure에서 호스트되는 앱에서 업그레이드 전 유효성 검사기를 실행하고 식별된 문제를 해결합니다.
  5. Azure에서 함수 앱을 새 버전으로 업데이트합니다. 가동 중지 시간을 최소화해야 하는 경우 스테이징 슬롯을 사용하여 새 런타임 버전에서 Azure의 마이그레이션된 앱을 테스트하고 확인하는 것이 좋습니다. 그런 다음, 업데이트된 버전 설정을 사용하여 앱을 프로덕션 슬롯에 배포할 수 있습니다. 자세한 내용은 슬롯을 사용하여 업데이트를 참조하세요.
  6. 마이그레이션된 프로젝트를 업데이트된 함수 앱에 게시합니다.

Visual Studio를 사용하여 버전 4.x 프로젝트를 더 낮은 버전의 기존 함수 앱에 게시하는 경우 배포하는 동안 Visual Studio에서 함수 앱을 버전 4.x로 업데이트하도록 요구하는 메시지가 표시됩니다. 이 업데이트는 슬롯 없는 업데이트에 정의된 것과 동일한 프로세스를 사용합니다.

로컬 프로젝트 마이그레이션

업그레이드 지침은 언어에 따라 다릅니다. 해당 언어가 표시되지 않으면 문서 상단의 선택기에서 선택합니다.

.NET의 대상 버전 및 원하는 프로세스 모델(In Process 또는 격리된 작업자 프로세스)과 일치하는 탭을 선택합니다.

팁

격리된 작업자 모델을 사용하여 .NET의 LTS 또는 STS 버전으로 이동하는 경우 .NET 업그레이드 도우미를 사용하여 다음 섹션에서 언급한 많은 변경 내용을 자동으로 수행할 수 있습니다.

프로젝트 파일

다음 예제는 버전 3.x에서 .NET Core 3.1을 사용하는 .csproj 프로젝트 파일입니다.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="3.0.13" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

다음 프로시저 중 하나를 사용하여 Functions 버전 4.x에서 실행되도록 이 XML 파일을 업데이트합니다.

이러한 단계에서는 로컬 C# 프로젝트를 가정하고, 앱이 C# 스크립트(.csx 파일)를 대신 사용하는 경우 계속하기 전에 프로젝트 모델로 변환해야 합니다.

.csproj XML 프로젝트 파일에는 다음 변경이 필요합니다.

  1. PropertyGroup 값을 설정합니다.TargetFramework가 net8.0로 변경되었습니다.

  2. PropertyGroup 값을 설정합니다.AzureFunctionsVersion가 v4로 변경되었습니다.

  3. 다음 OutputType 요소를 PropertyGroup에 추가합니다.

    <OutputType>Exe</OutputType>

  4. ItemGroup에서PackageReference 목록에서 Microsoft.NET.Sdk.Functions에 대한 패키지 참조를 다음 참조로 바꿉니다.

      <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
  <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />

    Microsoft.Azure.WebJobs.* 네임스페이스의 다른 패키지에 대한 참조를 기록해 둡니다. 이후 단계에서 이러한 패키지를 대체합니다.

  5. 다음 새 ItemGroup을 추가합니다.

    <ItemGroup>
  <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
</ItemGroup>

이러한 변경을 수행한 후 업데이트된 프로젝트는 다음 예제와 같아야 합니다.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <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.17.2" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

패키지 및 네임스페이스 변경 내용

마이그레이션하는 모델에 따라 애플리케이션에서 참조하는 패키지를 업데이트하거나 변경해야 할 수 있습니다. 대상 패키지를 채택할 때 문을 사용하는 네임스페이스 및 참조하는 일부 형식을 업데이트해야 합니다. 이 문서 뒷부분에 나오는 HTTP 트리거 템플릿 예에서 이러한 네임스페이스 변경이 using 문에 미치는 영향을 확인할 수 있습니다.

아직 업데이트하지 않은 경우 다음의 최신 안정 버전을 참조하도록 프로젝트를 업데이트합니다.

앱에서 사용하는 트리거 및 바인딩에 따라 앱은 다른 패키지 세트를 참조해야 할 수 있습니다. 다음 표에서는 가장 일반적으로 사용되는 일부 확장에 대한 대체를 보여 줍니다.

시나리오 패키지 참조에 대한 변경 내용
타이머 트리거 추가
Microsoft.Azure.Functions.Worker.Extensions.Timer
스토리지 바인딩 바꾸기
Microsoft.Azure.WebJobs.Extensions.Storage
다음과 같이 바꿉니다.
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 및
Microsoft.Azure.Functions.Worker.Extensions.Tables
Blob 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
큐 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
테이블 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.Tables
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.Tables
Cosmos DB 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.CosmosDB
및/또는
Microsoft.Azure.WebJobs.Extensions.DocumentDB
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Service Bus 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.ServiceBus
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Event Hubs 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.EventHubs
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Event Grid 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.EventGrid
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
SignalR Service 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.SignalRService
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
지속성 함수 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.DurableTask
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
지속성 함수
(SQL 스토리지 공급자)		 참조를 다음으로 바꾸기
Microsoft.DurableTask.SqlServer.AzureFunctions
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
지속성 함수
(Netherite 스토리지 공급자)		 참조를 다음으로 바꾸기
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
SendGrid 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.SendGrid
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Kafka 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.Kafka
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.Kafka
RabbitMQ 바인딩 참조를 다음으로 바꾸기
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
최신 버전의
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
종속성 주입
및 시작 구성		 다음에 대한 참조 제거
Microsoft.Azure.Functions.Extensions
(격리된 작업자 모델은 기본적으로 이 기능을 제공합니다.)

고려할 확장의 전체 목록은 지원되는 바인딩을 참조하고 격리된 프로세스 모델에 대한 전체 설치 지침은 각 확장 설명서를 참조하세요. 대상으로 하는 패키지의 안정적인 최신 버전을 설치해야 합니다.

팁

이 프로세스 중에 확장 버전을 변경하려면 host.json 파일도 업데이트해야 할 수 있습니다. 사용하는 각 확장의 설명서를 꼭 참조하세요. 예를 들어, Service Bus 확장에는 버전 4.x와 5.x 사이의 구조가 크게 변경되었습니다. 자세한 내용은 Azure Functions용 Azure Service Bus 바인딩을 참조하세요.

격리된 작업자 모델 애플리케이션은 Microsoft.Azure.WebJobs.* 네임스페이스 또는 Microsoft.Azure.Functions.Extensions의 패키지를 참조해서는 안 됩니다. 이에 대한 나머지 참조가 있는 경우 제거해야 합니다.

팁

앱은 트리거 및 바인딩의 일부 또는 독립 실행형 종속성으로 Azure SDK 형식에 의존할 수도 있습니다. 이 기회에 이러한 모델도 업데이트해야 합니다. 최신 버전의 Functions 확장은 최신 버전의 .NET용 Azure SDK에서 작동하며, 거의 모든 패키지는 형식 Azure.*입니다.

Program.cs 파일

격리된 작업자 프로세스에서 실행되도록 마이그레이션하는 경우 프로젝트에 다음 program.cs 파일을 추가해야 합니다.

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

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

host.Run();

이 예에는 앱이 HTTP 트리거를 사용할 때 성능을 개선하고 친숙한 프로그래밍 모델을 제공하기 위한 ASP.NET Core 통합이 포함되어 있습니다. HTTP 트리거를 사용하지 않으려면 ConfigureFunctionsWebApplication 호출을 ConfigureFunctionsWorkerDefaults 호출로 바꿀 수 있습니다. 그렇게 하면 프로젝트 파일에서 Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore에 대한 참조를 제거할 수 있습니다. 그러나 최상의 성능을 위해서는 다른 트리거 형식을 사용하는 함수의 경우에도 FrameworkReference를 ASP.NET Core로 유지해야 합니다.

Program.cs 파일은 일반적으로 Startup.cs 파일인 FunctionsStartup 특성을 가진 모든 파일을 대체합니다. FunctionsStartup 코드가 IFunctionsHostBuilder.Services를 참조하는 위치에서는 Program.cs에서 HostBuilder의 .ConfigureServices() 메서드 내에 명령문을 추가할 수 있습니다. Program.cs 작업에 대한 자세한 내용은 격리된 작업자 모델 가이드의 시작 및 구성을 참조하세요.

위의 기본 Program.cs 예에는 격리된 작업자 모델을 위한 Application Insights 통합 설정이 포함되어 있습니다. Program.cs에서는 프로젝트의 코드에서 들어오는 로그에 적용해야 하는 로그 필터링도 구성해야 합니다. 격리된 작업자 모델에서 host.json 파일은 Functions 호스트 런타임에서 내보낸 이벤트만 제어합니다. Program.cs에서 필터링 규칙을 구성하지 않으면 원격 분석의 다양한 범주에 대한 로그 수준에 차이가 나타날 수 있습니다.

HostBuilder의 일부로 사용자 지정 구성 원본을 등록할 수 있지만 이는 프로젝트의 코드에만 유사하게 적용된다는 점에 유의해야 합니다. 트리거 및 바인딩 구성도 플랫폼에 필요하며 이는 애플리케이션 설정, Key Vault 참조 또는 App Configuration 참조 기능을 통해 제공되어야 합니다.

기존 FunctionsStartup의 모든 항목을 Program.cs 파일로 이동한 후에는 FunctionsStartup 특성 및 적용된 클래스를 삭제할 수 있습니다.

local.settings.json 파일

local.settings.json 파일은 로컬로 실행할 때만 사용됩니다. 자세한 내용은 로컬 설정 파일을 참조하세요.

버전 4.x로 마이그레이션할 때 local.settings.json 파일에 적어도 다음 요소가 있는지 확인합니다.

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

참고 항목

실행 중인 프로세스에서 격리된 작업자 프로세스에서 실행으로 마이그레이션할 때 FUNCTIONS_WORKER_RUNTIME 값을 "dotnet-isolated"로 변경해야 합니다.

host.json 파일

host.json 파일을 변경할 필요가 없습니다. 그러나 In Process 모델 프로젝트의 이 파일에 Application Insights를 구성한 경우 Program.cs 파일을 추가로 변경해야 할 수도 있습니다. host.json 파일은 Functions 호스트 런타임의 로깅만 제어하며 격리된 작업자 모델에서는 이러한 로그 중 일부가 애플리케이션에서 직접 제공되므로 더 많이 제어할 수 있습니다. 이러한 로그를 필터링하는 방법에 대한 자세한 내용은 격리된 작업자 모델에서 로그 수준 관리를 참조하세요.

클래스 이름 변경

일부 키 클래스는 버전 사이에 이름을 변경했습니다. 이 변경 내용은 .NET API의 변경 결과이거나 In Process와 격리된 작업자 프로세스 간 차이의 변경 결과입니다. 다음 표는 마이그레이션할 때 변경될 수 있는 Functions에서 사용되는 주요 .NET 클래스를 나타냅니다.

.NET Core 3.1 .NET 5 .NET 8
FunctionName(특성) Function(특성) Function(특성)
ILogger ILogger ILogger, ILogger<T>
HttpRequest HttpRequestData HttpRequestData, HttpRequest(ASP.NET Core 통합 사용)
IActionResult HttpResponseData HttpResponseData, IActionResult(ASP.NET Core 통합 사용)
FunctionsStartup(특성) 대신 Program.cs 사용 대신 Program.cs 사용

바인딩에 클래스 이름의 차이가 있을 수도 있습니다. 자세한 내용은 특정 바인딩에 대한 참조 문서를 참조하세요.

기타 코드 변경

이 섹션에서는 마이그레이션을 진행하면서 고려해야 할 기타 코드 변경 내용을 강조 표시합니다. 이러한 변경 내용은 모든 애플리케이션에 필요한 것은 아니지만 시나리오와 관련이 있는지 평가해야 합니다. 프로젝트에 추가로 변경해야 할 수 있는 내용은 3.x와 4.x 간의 호환성이 손상되는 변경을 확인합니다.

JSON 직렬화

기본적으로 격리된 작업자 모델은 JSON serialization에 System.Text.Json을 사용합니다. 직렬 변환기 옵션을 사용자 지정하거나 JSON.NET(Newtonsoft.Json)으로 전환하려면 이 지침을 참조하세요.

Application Insights 로그 수준 및 필터링

프로젝트의 Functions 호스트 런타임과 코드 모두에서 로그를 Application Insights로 보낼 수 있습니다. host.json을 사용하면 호스트 로깅 규칙을 구성할 수 있지만 코드에서 들어오는 로그를 제어하려면 Program.cs의 일부로 필터링 규칙을 구성해야 합니다. 이러한 로그를 필터링하는 방법에 대한 자세한 내용은 격리된 작업자 모델에서 로그 수준 관리를 참조하세요.

HTTP 트리거 템플릿

프로세스 내 프로세스와 격리된 작업자 프로세스 간의 차이점은 HTTP 트리거 함수에서 확인할 수 있습니다. 버전 3.x(In Process)용 HTTP 트리거 템플릿은 다음 예와 같습니다.

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.AuthLevelValue, "get", "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

마이그레이션된 버전의 HTTP 트리거 템플릿은 다음 예와 같습니다.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

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

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

프로젝트를 Azure Functions 4.x로 업데이트하려면 다음을 수행합니다.

  1. Azure Functions Core Tools의 로컬 설치를 버전 4.x로 업데이트합니다.

  2. 앱의 Azure Functions 확장 번들을 2.x 이상으로 업데이트합니다. 자세한 내용은 호환성이 손상되는 변경을 참조하세요.

  1. 필요한 경우 버전 4.x에서 지원되는 Java 버전 중 하나로 이동합니다.

  2. 다음 예와 같이 앱의 POM.xml 파일을 업데이트하여 FUNCTIONS_EXTENSION_VERSION 설정을 ~4로 수정합니다.

    <configuration>
    <resourceGroup>${functionResourceGroup}</resourceGroup>
    <appName>${functionAppName}</appName>
    <region>${functionAppRegion}</region>
    <appSettings>
        <property>
            <name>WEBSITE_RUN_FROM_PACKAGE</name>
            <value>1</value>
        </property>
        <property>
            <name>FUNCTIONS_EXTENSION_VERSION</name>
            <value>~4</value>
        </property>
    </appSettings>
</configuration>
  1. 필요한 경우 버전 4.x에서 지원되는 Node.js 버전 중 하나로 이동합니다.
  1. 이 기회에 권장되는 PowerShell 7.2로 업그레이드합니다. 자세한 내용은 PowerShell 버전을 참조하세요.
  1. Python 3.6을 사용하는 경우 지원되는 버전 중 하나로 이동합니다.

업그레이드 전 유효성 검사기 실행

Azure Functions는 함수 앱을 4.x로 마이그레이션할 때 발생할 수 있는 문제를 식별하는 데 도움이 되는 업그레이드 전 유효성 검사기를 제공합니다. 업그레이드 전 유효성 검사기를 실행하려면 다음을 수행합니다.

  1. Azure Portal에서 함수 앱으로 이동합니다.

  2. 문제 진단 및 해결 페이지를 엽니다.

  3. 함수 앱 진단에서 Functions 4.x Pre-Upgrade Validator 입력을 시작한 다음, 목록에서 선택합니다.

  4. 유효성 검사가 완료되면 권장 사항을 검토하고 앱의 모든 문제를 해결합니다. 앱을 변경해야 하는 경우 Azure Functions Core Tools v4를 로컬로 사용하거나 스테이징 슬롯을 사용하여 Functions 런타임 버전 4.x에 대한 변경 내용의 유효성을 검사해야 합니다.

Azure에서 함수 앱 업데이트

마이그레이션된 프로젝트를 게시하기 전에 Azure에서 함수 앱 호스트의 런타임을 버전 4.x로 업데이트해야 합니다. Functions 호스트에서 사용하는 런타임 버전은 FUNCTIONS_EXTENSION_VERSION 애플리케이션 설정에 의해 제어되지만 경우에 따라 다른 설정도 업데이트해야 합니다. 코드 변경과 애플리케이션 설정 변경을 모두 적용하려면 함수 앱을 다시 시작해야 합니다.

가장 쉬운 방법은 슬롯 없이 업데이트한 다음 앱 프로젝트를 다시 게시하는 것입니다. 또한 슬롯을 사용하여 업데이트하여 앱의 가동 중지 시간을 최소화하고 롤백을 간소화할 수 있습니다.

슬롯을 사용하지 않고 업데이트

v4.x로 업데이트하는 가장 간단한 방법은 Azure의 함수 앱에서 FUNCTIONS_EXTENSION_VERSION 애플리케이션 설정을 ~4로 설정하는 것입니다. 슬롯을 사용하는 사이트에서는 다른 절차를 수행해야 합니다.

az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

Windows와 Linux 간에 다른 설정도 지정해야 합니다.

Windows에서 실행되는 경우 런타임 버전 4.x에 필요한 .NET 6.0도 사용하도록 설정해야 합니다.

az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

.NET 6은 Windows에서 실행되는 모든 언어의 함수 앱에 필요합니다.

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

이제 버전 4.x에서 실행되도록 마이그레이션된 앱 프로젝트를 다시 게시할 수 있습니다.

슬롯을 사용하여 업데이트

배포 슬롯을 사용하는 것은 함수 앱을 이전 버전에서 v4.x 런타임으로 업데이트하는 좋은 방법입니다. 스테이징 슬롯을 사용하면 스테이징 슬롯의 새 런타임 버전에서 앱을 실행하고, 확인 후에 프로덕션으로 전환할 수 있습니다. 슬롯은 업데이트 중 가동 중지 시간을 최소화하는 방법도 제공합니다. 가동 중지 시간을 최소화해야 하는 경우 최소 가동 중지 시간 업데이트의 단계를 수행합니다.

업데이트된 슬롯에서 앱이 확인되면 앱 및 새 버전 설정을 프로덕션으로 교환할 수 있습니다. 이 교환을 사용하려면 프로덕션 슬롯에서 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0을 설정해야 합니다. 이 설정을 추가하는 방법은 업데이트에 필요한 가동 중지 시간의 양에 영향을 줍니다.

표준 업데이트

슬롯 사용 함수 앱에서 전체 다시 시작의 가동 중지 시간을 처리할 수 있는 경우 프로덕션 슬롯에서 직접 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS 설정을 업데이트할 수 있습니다. 프로덕션 슬롯에서 이 설정을 직접 변경하면 가용성에 영향을 주는 다시 시작이 발생하므로 트래픽이 감소할 때 이 변경을 수행하는 것이 좋습니다. 그런 다음 스테이징 슬롯에서 업데이트된 버전으로 교환할 수 있습니다.

Update-AzFunctionAppSetting PowerShell cmdlet은 현재 슬롯을 지원하지 않습니다. Azure CLI 또는 Azure Portal을 사용해야 합니다.

  1. 다음 명령을 사용하여 프로덕션 슬롯에서 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0을 설정합니다.

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    이 예제에서 <APP_NAME>을 함수 앱의 이름으로 바꾸고 <RESOURCE_GROUP_NAME>을 리소스 그룹의 이름으로 바꿉니다. 이 명령을 사용하면 프로덕션 슬롯에서 실행 중인 앱이 다시 시작됩니다.

  2. 다음 명령을 사용하여 스테이징 슬롯에서 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS도 설정합니다.

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. 다음 명령을 사용하여 FUNCTIONS_EXTENSION_VERSION을 변경하고 스테이징 슬롯을 새 런타임 버전으로 업데이트합니다.

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  4. Functions 런타임 버전 4.x에는 Windows에서 .NET 6이 필요합니다. Linux에서는 .NET 앱도 .NET 6으로 업데이트해야 합니다. 런타임이 .NET 6에서 실행될 수 있도록 다음 명령을 사용합니다.

    Windows에서 실행되는 경우 런타임 버전 4.x에 필요한 .NET 6.0도 사용하도록 설정해야 합니다.

    az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6은 Windows에서 실행되는 모든 언어의 함수 앱에 필요합니다.

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

  5. 버전 4.x에서 실행하기 위해 코드 프로젝트에 업데이트가 필요한 경우 지금 해당 업데이트를 스테이징 슬롯에 배포합니다.

  6. 교환하기 전에 업데이트된 스테이징 환경에서 함수 앱이 올바르게 실행되는지 확인합니다.

  7. 업데이트된 스테이징 슬롯을 프로덕션으로 바꾸려면 다음 명령을 사용합니다.

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

최소 가동 중지 시간 업데이트

프로덕션 앱에서 가동 중지 시간을 최소화하기 위해 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS 설정을 스테이징 슬롯에서 프로덕션으로 교환할 수 있습니다. 그 후에는 미리 준비된 스테이징 슬롯에서 업데이트된 버전으로 교환할 수 있습니다.

  1. 다음 명령을 사용하여 스테이징 슬롯에서 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0을 설정합니다.

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  2. 다음 명령을 사용하여 새 설정이 있는 슬롯을 프로덕션으로 교환하고 동시에 스테이징 슬롯에서 버전 설정을 복원합니다.

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production
az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~3 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    교환과 스테이징에서 복원되는 런타임 버전 사이의 시간 동안 스테이징 슬롯에서 오류가 표시될 수 있습니다. 이 오류는 교환 도중 준비 프로세스에만 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0이 있으면 준비 프로세스에서 FUNCTIONS_EXTENSION_VERSION 설정이 제거되기 때문에 발생할 수 있습니다. 버전 설정이 없으면 슬롯이 잘못된 상태에 있습니다. 교환 직후 스테이징 슬롯의 버전을 업데이트하면 슬롯이 다시 양호한 상태로 전환되고, 필요한 경우 변경 내용 롤백을 호출합니다. 그러나 교환을 롤백하려면 스테이징에 표시되는 프로덕션의 동일한 오류를 방지하기 위해 다시 교환하기 전에 프로덕션에서 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0도 직접 제거해야 합니다. 프로덕션 설정의 이러한 변경으로 인해 다시 시작됩니다.

  3. 다음 명령을 사용하여 스테이징 슬롯에서 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0을 다시 설정합니다.

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    이 시점에서 두 슬롯 모두에 WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0이 설정되어 있습니다.

  4. 다음 명령을 사용하여 FUNCTIONS_EXTENSION_VERSION을 변경하고 스테이징 슬롯을 새 런타임 버전으로 업데이트합니다.

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  5. Functions 런타임 버전 4.x에는 Windows에서 .NET 6이 필요합니다. Linux에서는 .NET 앱도 .NET 6으로 업데이트해야 합니다. 런타임이 .NET 6에서 실행될 수 있도록 다음 명령을 사용합니다.

    Windows에서 실행되는 경우 런타임 버전 4.x에 필요한 .NET 6.0도 사용하도록 설정해야 합니다.

    az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6은 Windows에서 실행되는 모든 언어의 함수 앱에 필요합니다.

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

  6. 버전 4.x에서 실행하기 위해 코드 프로젝트에 업데이트가 필요한 경우 지금 해당 업데이트를 스테이징 슬롯에 배포합니다.

  7. 교환하기 전에 업데이트된 스테이징 환경에서 함수 앱이 올바르게 실행되는지 확인합니다.

  8. 업데이트되고 미리 준비된 스테이징 슬롯을 프로덕션으로 바꾸려면 다음 명령을 사용합니다.

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

3.x와 4.x 사이의 호환성이 손상되는 변경

다음은 언어별 호환성이 손상되는 변경 내용을 포함하여 3.x 앱을 4.x로 업그레이드하기 전에 알아야 할 주요 변경 내용입니다. 전체 목록은 Breaking Change: Approved(호환성이 손상되는 변경: 승인됨)라는 레이블이 지정된 Azure Functions GitHub 문제를 참조하세요.

해당하는 프로그래밍 언어가 없으면 페이지 맨 위에서 선택합니다.

런타임

  • Azure Functions 프록시는 Azure Functions 런타임 버전 1.x~3.x의 레거시 함수입니다. 함수 앱을 최신 런타임 버전으로 업데이트할 수 있도록 버전 4.x에서 Functions 프록시에 대한 지원을 다시 사용하도록 설정할 수 있습니다. 가능한 한 빨리 함수 앱을 Azure API Management와 통합하도록 전환해야 합니다. API Management를 사용하면 Functions 기반 API를 정의, 보호, 관리 및 수익화하기 위한 보다 완전한 기능 집합을 활용할 수 있습니다. 자세한 내용은 API Management 통합을 참조하세요. Functions 버전 4.x에서 프록시 지원을 다시 사용하도록 설정하는 방법을 알아보려면 Functions v4.x에서 프록시 다시 사용하도록 설정를 참조하세요.

  • AzureWebJobsDashboard를 사용하여 Azure Storage에 로그인하는 것은 4.x에서 더 이상 지원되지 않습니다. 대신 Application Insights를 사용해야 합니다. (#1923)

  • Azure Functions 4.x는 이제 확장에 최소 버전 요구 사항을 적용합니다. 영향을 받는 확장을 최신 버전으로 업데이트합니다. .NET 언어가 아닌 경우 확장 번들 버전 2.x 이상으로 업데이트합니다. (#1987)

  • 이제 사용 계획의 Linux에서 실행되는 함수 앱의 경우 기본 및 최대 시간 제한이 4.x로 적용됩니다. (#1915)

  • Azure Functions 4.x는 Key Vault 공급자에 Azure.Identity 및 Azure.Security.KeyVault.Secrets를 사용하며 Microsoft.Azure.KeyVault는 더 이상 사용되지 않습니다. 함수 앱 설정을 구성하는 방법에 대한 자세한 내용은 비밀 리포지토리의 Key Vault 옵션을 참조하세요. (#2048)

  • 스토리지 계정을 공유하는 함수 앱은 이제 호스트 ID가 같을 경우 시작되지 않습니다. 자세한 내용은 호스트 ID 고려 사항을 참조하세요. (#2049)

  • Azure Functions 4.x는 .NET 6 in-process 및 격리된 앱을 지원합니다.

  • InvalidHostServicesException은 이제 치명적인 오류입니다. (#2045)

  • EnableEnhancedScopes는 기본적으로 사용하도록 설정됩니다. (#1954)

  • HttpClient가 등록된 서비스에서 제거되었습니다. (#1911)

  • Java 11에서 단일 클래스 로더를 사용합니다. (#1997)

  • Java 8에서 작업자 jar 로드가 중지됩니다. (#1991)

  • Node.js 버전 10 및 12는 Azure Functions 4.x에서 지원되지 않습니다. (#1999)

  • 이전 불일치를 해결하기 위해 Node.js 앱의 출력 serialization이 업데이트되었습니다. (#2007)

  • 기본 스레드 수가 업데이트되었습니다. 스레드로부터 안전하지 않거나 메모리 사용량이 많은 함수는 영향을 받을 수 있습니다. (#1962)

  • Python 3.6은 Azure Functions 4.x에서 지원되지 않습니다. (#1999)

  • 공유 메모리 전송은 기본적으로 사용하도록 설정됩니다. (#1973)

  • 기본 스레드 수가 업데이트되었습니다. 스레드로부터 안전하지 않거나 메모리 사용량이 많은 함수는 영향을 받을 수 있습니다. (#1962)

다음 단계

Functions 버전에 대해 자세히 알아보기