다음을 통해 공유

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

  • 아티클

Important

Java는 Azure Functions 런타임 버전 1.x에서 지원되지 않습니다. 대신, Java 앱을 버전 3.x에서 버전 4.x로 마이그레이션할 것을 기대할 수 있습니다. 버전 1.x 함수 앱을 마이그레이션하는 경우 위의 C# 또는 JavaScript를 선택합니다.

Important

TypeScript는 Azure Functions 런타임 버전 1.x에서 지원되지 않습니다. 대신, TypeScript 앱을 버전 3.x에서 버전 4.x로 마이그레이션할 것을 기대할 수 있습니다. 버전 1.x 함수 앱을 마이그레이션하는 경우 위의 C# 또는 JavaScript를 선택합니다.

Important

PowerShell은 Azure Functions 런타임 버전 1.x에서 지원되지 않습니다. 대신, PowerShell 앱을 버전 3.x에서 버전 4.x로 마이그레이션할 것을 기대할 수 있습니다. 버전 1.x 함수 앱을 마이그레이션하는 경우 위의 C# 또는 JavaScript를 선택합니다.

Important

Python은 Azure Functions 런타임 버전 1.x에서 지원되지 않습니다. 대신, Python 앱을 버전 3.x에서 버전 4.x로 마이그레이션할 것을 기대할 수 있습니다. 버전 1.x 함수 앱을 마이그레이션하는 경우 위의 C# 또는 JavaScript를 선택합니다.

Important

2026년 9월 14일에 Azure Functions 런타임 버전 1.x에 대한 지원이 종료됩니다. 이 문서의 지침에 따라 앱을 버전 4.x로 마이그레이션하는 것이 좋습니다.

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

Azure Stack Hub에서 런타임 버전 1.x를 실행하는 경우 먼저 Azure Stack Hub에 대한 고려 사항을 참조하세요.

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

다음 PowerShell 스크립트를 사용하여 구독에서 현재 버전 1.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 '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

대상 .NET 버전 선택

Functions 런타임 버전 1.x에서 C# 함수 앱은 .NET Framework를 대상으로 합니다.

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

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

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

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

팁

앱이 .NET Framework에서만 사용할 수 있는 라이브러리나 API에 의존하지 않는 한 격리된 작업자 모델에서 .NET 8로 업데이트하는 것이 좋습니다. 버전 1.x의 많은 앱은 .NET Framework를 만들 때 사용할 수 있었던 것이므로 .NET Framework만 대상으로 합니다. 추가 기능은 최신 버전의 .NET에서 사용할 수 있으며 종속성으로 인해 앱이 .NET Framework에 유지되도록 강제되지 않는 경우 최신 버전을 대상으로 해야 합니다. .NET 8은 .NET에서 지원 기간이 가장 긴 완전 릴리스 버전입니다.

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

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

마이그레이션 준비

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

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

  1. 버전 1.x 이후의 동작 변경 목록을 검토합니다. 버전 1.x에서 버전 4.x로 마이그레이션하는 것은 바인딩에도 영향을 줄 수 있습니다.
  2. 로컬 프로젝트를 버전 4.x로 마이그레이션하려면 로컬 프로젝트 마이그레이션의 단계를 완료합니다.
  3. 프로젝트를 마이그레이션한 후 Azure Functions Core Tools 버전 4.x를 사용하여 앱을 로컬로 완전히 테스트합니다.
  4. Azure에서 함수 앱을 새 버전으로 업데이트합니다. 가동 중지 시간을 최소화해야 하는 경우 스테이징 슬롯을 사용하여 새 런타임 버전에서 Azure의 마이그레이션된 앱을 테스트하고 확인하는 것이 좋습니다. 그런 다음, 업데이트된 버전 설정을 사용하여 앱을 프로덕션 슬롯에 배포할 수 있습니다. 자세한 내용은 슬롯을 사용하여 업데이트를 참조하세요.
  5. 마이그레이션된 프로젝트를 업데이트된 함수 앱에 게시합니다.

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

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

다음 섹션에서는 Functions 버전 4.x에서 지원되는 .NET 버전 중 하나에서 실행할 수 있도록 C# 프로젝트 파일에 대해 수행해야 하는 업데이트를 설명합니다. 표시된 업데이트는 대부분의 프로젝트에 공통된 업데이트입니다. 특히 사용자 지정 NuGet 패키지를 사용하는 경우 이 문서에 언급되지 않은 업데이트가 프로젝트 코드에 필요할 수 있습니다.

C# 함수 앱을 Functions 런타임 버전 1.x에서 버전 4.x로 마이그레이션하려면 프로젝트 코드를 변경해야 합니다. 이 변경 내용은 대부분 C# 언어 및 .NET API의 변경 결과입니다.

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

팁

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

프로젝트 파일

다음 예제는 버전 1.x에서 실행되는 .csproj 프로젝트 파일입니다.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </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.*입니다.

Notification Hubs 및 Mobile Apps 바인딩은 런타임 버전 1.x에서만 지원됩니다. 런타임 버전 4.x로 업그레이드하는 경우 SDK를 사용하여 직접 이러한 서비스로 작업하려면 해당 바인딩을 제거해야 합니다.

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 특성 및 적용된 클래스를 삭제할 수 있습니다.

host.json 파일

host.json 파일의 설정은 로컬 및 Azure의 함수 앱 수준에서 적용됩니다. 버전 1.x에서 host.json 파일은 비어 있거나 함수 앱의 모든 함수에 적용되는 일부 설정을 포함합니다. 자세한 내용은 Host.json v1을 참조하세요. host.json 파일에 설정 값이 있는 경우 변경 내용은 host.json v2 형식을 검토합니다.

버전 4.x에서 실행하려면 host.json 파일에 "version": "2.0"를 추가해야 합니다. 다음 예제와 같이 구성에 logging을 추가하는 것도 고려해야 합니다.

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

host.json 파일은 Functions 호스트 런타임의 로깅만 제어하며 격리된 작업자 모델에서는 이러한 로그 중 일부가 애플리케이션에서 직접 제공되므로 더 많이 제어할 수 있습니다. 이러한 로그를 필터링하는 방법에 대한 자세한 내용은 격리된 작업자 모델에서 로그 수준 관리를 참조하세요.

local.settings.json 파일

local.settings.json 파일은 로컬로 실행할 때만 사용됩니다. 자세한 내용은 로컬 설정 파일을 참조하세요. 버전 1.x에서 local.settings.json 파일에는 두 개의 필수 값만 있습니다.

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "AzureWebJobsDashboard": "AzureWebJobsStorageConnectionStringValue"
    }
}

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

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

참고 항목

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

클래스 이름 변경

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

버전 1.x .NET 8
FunctionName(특성) Function(특성)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest(ASP.NET Core 통합 사용)
HttpResponseMessage HttpResponseData, IActionResult(ASP.NET Core 통합 사용)

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

기타 코드 변경

이 섹션에서는 마이그레이션을 진행하면서 고려해야 할 기타 코드 변경 내용을 강조 표시합니다. 이러한 변경 내용은 모든 애플리케이션에 필요한 것은 아니지만 시나리오와 관련이 있는지 평가해야 합니다. 프로젝트에 추가로 변경해야 할 수 있는 사항은 버전 1.x 이후 동작 변경 내용을 확인합니다.

JSON 직렬화

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

Application Insights 로그 수준 및 필터링

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

HTTP 트리거 템플릿

버전 1.x와 버전 4.x 간 대부분의 코드 변경은 HTTP 트리거 함수에서 확인할 수 있습니다. 버전 1.x에 대한 HTTP 트리거 템플릿은 다음 예제와 같습니다.

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

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

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

버전 4.x에서 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. 버전 4.x에서 지원되는 Node.js 버전 중 하나로 이동합니다.

  3. host.json에 version 및 extensionBundle 요소를 모두 추가하면 다음 예제와 같이 표시됩니다.

    {
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

    버전 1.x 이후 바인딩은 외부 패키지로 유지 관리되므로 extensionBundle 요소가 필요합니다. 자세한 내용은 확장 번들을 참조하세요.

  4. 적어도 다음 요소를 포함하도록 local.settings.json 파일을 업데이트합니다.

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    AzureWebJobsStorage 설정은 Azure Storage 에뮬레이터 또는 실제 Azure Storage 계정일 수 있습니다. 자세한 내용은 로컬 스토리지 에뮬레이터를 참조하세요.

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

버전 1.x 이후 동작 변경

이 섹션에서는 트리거 및 바인딩 동작과 핵심 Functions 기능 및 동작 모두에서 버전 1.x 이후 변경 내용을 자세히 설명합니다.

트리거 및 바인딩의 변경 내용

버전 2.x부터 앱의 함수에 사용되는 특정 트리거 및 바인딩에 대한 확장을 설치해야 합니다. 유일한 예외는 확장이 필요 없는 이 HTTP 및 타이머 트리거입니다. 자세한 내용은 바인딩 확장 등록 및 설치를 참조하세요.

버전 간에 function.json 또는 함수의 특성에도 몇 가지 변경 사항이 있습니다. 예를 들어, Event Hubs path 속성은 이제 eventHubName입니다. 각 바인딩의 설명서에 대한 링크는 기존 바인딩 테이블을 참조하세요.

기능 변경

버전 1.x 이후에 몇 가지 기능이 제거, 업데이트 또는 교체되었습니다. 이 섹션에서는 버전 1.x를 사용한 후 이후 버전에서 볼 수 있는 변경 사항에 대해 자세히 설명합니다.

버전 2.x에서 다음과 같은 사항이 변경되었습니다.

  • HTTP 엔드포인트를 호출하기 위한 키는 항상 Azure Blob Storage에 암호화된 상태로 저장됩니다. 버전 1.x에서는 키가 기본적으로 Azure Files에 저장되었습니다. 버전 1.x에서 버전 2.x로 앱을 마이그레이션하면 Azure Files에 있는 기존 비밀이 다시 설정됩니다.

  • 버전 2.x 런타임에서는 웹후크 공급자가 기본적으로 지원되지 않습니다. 성능 향상을 위해 이렇게 변경되었습니다. HTTP 트리거를 여전히 웹후크에 대한 엔드포인트로 사용할 수 있습니다.

  • 모니터링을 향상시키기 위해 AzureWebJobsDashboard 설정을 사용하는 포털의 WebJobs 대시보드가 APPINSIGHTS_INSTRUMENTATIONKEY 설정을 사용하는 Azure Application Insights로 바뀌었습니다. 자세한 내용은 Azure Functions 모니터링을 참조하세요.

  • 함수 앱의 모든 함수가 동일한 언어를 공유해야 합니다. 함수 앱을 만들 때 앱의 런타임 스택을 선택해야 합니다. 런타임 스택은 애플리케이션 설정의 FUNCTIONS_WORKER_RUNTIME 값으로 지정됩니다. 이 요구 사항은 공간 효율성 및 시작 시간을 개선하기 위해 추가되었습니다. 로컬로 개발하는 경우 local.settings.json 파일에 이 설정을 포함해야 합니다.

  • App Service 계획의 함수에 대한 기본 시간 제한은 30분으로 변경되었습니다. host.json에서 functionTimeout 설정을 사용하여 수동으로 제한 시간을 다시 무제한으로 변경할 수 있습니다.

  • HTTP 동시성 제한은 기본값으로 인스턴스당 동시 요청 수 100개를 갖는 사용 플랜 함수에 대해 기본적으로 구현됩니다. 이 동작은 host.json 파일의 maxConcurrentRequests 설정에서 변경할 수 있습니다.

  • .NET Core 제한으로 인해 F# 스크립트(.fsx 파일) 함수에 대한 지원이 제거되었습니다. 컴파일된 F# 함수(.fs)는 계속 지원됩니다.

  • Event Grid 트리거 webhook의 URL 형식은 https://{app}/runtime/webhooks/{triggerName} 패턴을 따라 변경되었습니다.

  • 일부 사전 정의된 사용자 지정 메트릭의 이름은 버전 1.x 이후에 변경되었습니다. Duration이 MaxDurationMs, MinDurationMs, AvgDurationMs로 바뀌었습니다. Success Rate의 이름도 Success Rate로 바뀌었습니다.

Azure Stack Hub에 대한 고려 사항

Azure Stack Hub의 App Service는 Azure Functions 버전 4.x를 지원하지 않습니다. Azure Stack Hub에서 버전 1.x에서 마이그레이션을 계획하는 경우 다음 옵션 중 하나를 선택할 수 있습니다.

  • 이 문서의 지침을 사용하여 퍼블릭 클라우드 Azure Functions에서 호스트되는 버전 4.x로 마이그레이션하세요. 기존 앱을 업그레이드하는 대신 버전 4.x를 사용하여 새 앱을 만든 다음 수정된 프로젝트를 여기에 배포합니다.
  • Azure Stack Hub의 App Service 요금제에서 호스트되는 WebJobs로 전환하세요.

다음 단계

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