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

이러한 단계에서는 로컬 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>

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

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

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

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

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

   <OutputType>Exe</OutputType>
   

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

     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
     <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>
     <Folder Include="Properties\" />
   </ItemGroup>
   

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
      <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
      <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>
    <Folder Include="Properties\" />
  </ItemGroup>
</Project>

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

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

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

3. 기존 ItemGroup. PackageReference 목록을 다음 ItemGroup으로 바꿉니다.

   <ItemGroup>
     <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
   </ItemGroup>
   

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

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

• Microsoft.Azure. Functions.Worker
• Microsoft.Azure. Functions.Worker.Sdk

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

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

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

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

• Microsoft.Azure. Functions.Worker
• Microsoft.Azure. Functions.Worker.Sdk

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

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

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

안정적인 최신 버전의 Microsoft.NET.Sdk.Functions을 참조하도록 프로젝트를 업데이트하세요.

앱에서 사용하는 트리거 및 바인딩에 따라 앱은 추가 패키지 집합을 참조해야 할 수 있습니다. 고려할 확장 목록은 지원되는 바인딩 을 참조하고 In Process 모델에 대한 전체 설치 지침은 각 확장 설명서를 참조하세요. 대상으로 하는 패키지의 안정적인 최신 버전을 설치해야 합니다.

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 대한 참조를 제거할 수 있습니다. 그러나 최상의 성능을 위해 다른 트리거 형식을 사용하는 함수의 경우에도 ASP.NET Core FrameworkReference 유지해야 합니다.

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

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

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

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

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

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

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

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

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

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

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

Program.cs 파일은 인프로세스 모델을 사용할 때 필요하지 않습니다.

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

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

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "FUNCTIONS_INPROC_NET8_ENABLED": "1"
    }
}

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

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

host.json 파일을 변경할 필요가 없습니다.

이 섹션에서는 마이그레이션을 진행하면서 고려해야 할 기타 코드 변경 내용을 강조 표시합니다. 이러한 변경 내용은 모든 애플리케이션에서 필요하지 않지만 시나리오와 관련된 변경 내용이 있는지 평가해야 합니다. 3.x와 4.x 사이의 호환성에 영향을 미치는 변경 사항 항목을 확인하여 프로젝트에 적용해야 할 수 있는 추가 변경 사항을 살펴보십시오.

JSON 직렬화

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

Application Insights 로그 수준 및 필터링

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

이 섹션에서는 마이그레이션을 진행하면서 고려해야 할 기타 코드 변경 내용을 강조 표시합니다. 이러한 변경 내용은 모든 애플리케이션에서 필요하지 않지만 시나리오와 관련된 변경 내용이 있는지 평가해야 합니다. 3.x와 4.x 사이의 호환성에 영향을 미치는 변경 사항 항목을 확인하여 프로젝트에 적용해야 할 수 있는 추가 변경 사항을 살펴보십시오.

JSON 직렬화

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

Application Insights 로그 수준 및 필터링

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

3.x와 4.x 사이의 호환성에 영향을 미치는 변경 사항 항목을 확인하여 프로젝트에 적용해야 할 수 있는 추가 변경 사항을 살펴보십시오.

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"]}!");
        }
    }
}

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

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

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

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

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

버전 3.x(In Process)와 동일합니다.