Migrar aplicativos do Azure Functions versão 1.x para a versão 4.x

Essas etapas pressupõem um projeto C# local. Se, em vez disso, seu aplicativo estiver usando o script C# (arquivos .csx), você deverá converter para o modelo de projeto antes de continuar.

As seguintes alterações são necessárias no arquivo de projeto XML .csproj:

1. Defina o valor de PropertyGroup:TargetFramework para net8.0.

2. Defina o valor de PropertyGroup:AzureFunctionsVersion para v4.

3. Adicione o seguinte elemento OutputType ao PropertyGroup:

   <OutputType>Exe</OutputType>
   

4. No ItemGroup.Lista PackageReference, substitua a referência de pacote de Microsoft.NET.Sdk.Functions pelas seguintes referências:

     <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" />
   

   Anote todas as referências a outros pacotes nos namespaces Microsoft.Azure.WebJobs.*. Você substituirá esses pacotes em uma etapa posterior.

5. Adicione o ItemGroup novo a seguir:

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

Depois que você fizer essas alterações, o projeto atualizado será semelhante ao seguinte exemplo:

<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>

Essas etapas pressupõem um projeto C# local. Se, em vez disso, seu aplicativo estiver usando o script C# (arquivos .csx), você deverá converter para o modelo de projeto antes de continuar.

As seguintes alterações são necessárias no arquivo de projeto XML .csproj:

1. Defina o valor de PropertyGroup:TargetFramework para net48.

2. Defina o valor de PropertyGroup:AzureFunctionsVersion para v4.

3. Adicione o seguinte elemento OutputType ao PropertyGroup:

   <OutputType>Exe</OutputType>
   

4. No ItemGroup.Lista PackageReference, substitua a referência de pacote de Microsoft.NET.Sdk.Functions pelas seguintes referências:

     <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" />
   

   Anote todas as referências a outros pacotes nos namespaces Microsoft.Azure.WebJobs.*. Você substituirá esses pacotes em uma etapa posterior.

5. Adicione o ItemGroup novo a seguir:

   <ItemGroup>
     <Folder Include="Properties\" />
   </ItemGroup>
   

Depois que você fizer essas alterações, o projeto atualizado será semelhante ao seguinte exemplo:

<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>

As seguintes alterações são necessárias no arquivo de projeto XML .csproj:

1. Defina o valor de PropertyGroup:TargetFramework para net8.0.

2. Defina o valor de PropertyGroup:AzureFunctionsVersion para v4.

3. Substituir o ItemGroup existente.Lista de PackageReference com o seguinte ItemGroup:

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

Depois que você fizer essas alterações, o projeto atualizado será semelhante ao seguinte exemplo:

<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>

Atualize seu projeto, caso ainda não tenha feito isso, para referenciar as versões estáveis mais recentes de:

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

Dependendo dos gatilhos e associações que seu aplicativo usa, talvez ele precise fazer referência a um conjunto diferente de pacotes. A seguinte tabela mostra as substituições de algumas das extensões mais usadas:

Confira as Associações com suporte para obter uma lista completa das extensões a serem consideradas, e confira a documentação de cada extensão para obter as instruções completas de instalação para o modelo de processo isolado. Instale a versão estável mais recente de todos os pacotes que você está direcionando.

Seu aplicativo de modelo de trabalho isolado não deve fazer referência a nenhum pacote nos namespaces Microsoft.Azure.WebJobs.* ou Microsoft.Azure.Functions.Extensions. Se você ainda tiver referências aos pacotes, é preciso removê-las.

Atualize seu projeto, caso ainda não tenha feito isso, para referenciar as versões estáveis mais recentes de:

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

Dependendo dos gatilhos e associações que seu aplicativo usa, talvez ele precise fazer referência a um conjunto diferente de pacotes. A seguinte tabela mostra as substituições de algumas das extensões mais usadas:

Confira as Associações com suporte para obter uma lista completa das extensões a serem consideradas, e confira a documentação de cada extensão para obter as instruções completas de instalação para o modelo de processo isolado. Instale a versão estável mais recente de todos os pacotes que você está direcionando.

Seu aplicativo de modelo de trabalho isolado não deve fazer referência a nenhum pacote nos namespaces Microsoft.Azure.WebJobs.* ou Microsoft.Azure.Functions.Extensions. Se você ainda tiver referências aos pacotes, é preciso removê-las.

Atualize seu projeto para fazer referência à versão estável mais recente do Microsoft.NET.Sdk.Functions.

Dependendo dos gatilhos e associações que seu aplicativo usa, talvez ele precise fazer referência a um conjunto adicional de pacotes. Confira as Associações com suporte para obter uma lista de extensões a serem consideradas consulte a documentação de cada extensão para obter instruções completas de instalação para o modelo de processo em processo. Instale a versão estável mais recente de todos os pacotes que você está direcionando.

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();

Este exemplo inclui a integração do ASP.NET Core para melhorar o desempenho e fornecer um modelo de programação clássica quando o aplicativo usar gatilhos HTTP. Se você não pretende usar gatilhos HTTP, pode substituir a chamada a ConfigureFunctionsWebApplication por uma chamada a ConfigureFunctionsWorkerDefaults. Se você fizer isso, poderá remover a referência ao Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore do arquivo de projeto. No entanto, para obter o melhor desempenho, mesmo para funções com outros tipos de gatilho, você deve manter a FrameworkReference ASP.NET Core.

O arquivo Program.cs substituirá todos os arquivos que tenham o atributo FunctionsStartup, que normalmente é um arquivo Startup.cs. Em locais em que o código FunctionsStartup referenciaria IFunctionsHostBuilder.Services, você pode, em vez disso, adicionar instruções dentro do método .ConfigureServices() do HostBuilder em seu Program.cs. Para saber mais sobre como trabalhar com Program.cs, confira a Configuração e inicialização no guia do modelo de trabalho isolado.

Os exemplos padrão Program.cs acima incluem a configuração da integração do Application Insights para o modelo de trabalho isolado. No Program.cs, você também deve configurar qualquer filtragem de log que deve ser aplicada aos logs provenientes do código no seu projeto. No modelo de trabalho isolado, o arquivo host.json controla apenas os eventos emitidos pelo runtime do host do Functions. Se você não configurar regras de filtragem no Program.cs, poderá ver diferenças nos níveis de log presentes para várias categorias na telemetria.

Embora você possa registrar fontes de configuração personalizadas como parte do HostBuilder, observe que elas se aplicam somente ao código no seu projeto. A configuração de gatilho e associação também é necessária para a plataforma, e ela deve ser realizada por meio dos recursos de configurações de aplicativo, referências do Key Vault ou referências da Configuração de Aplicativos.

Depois de mover tudo de qualquer FunctionsStartup existente para o arquivo Program.cs, você poderá excluir o atributo FunctionsStartup e a classe à qual ele foi aplicado.

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();
        }
    }
}

O arquivo Program.cs substituirá todos os arquivos que tenham o atributo FunctionsStartup, que normalmente é um arquivo Startup.cs. Em locais em que o código FunctionsStartup referenciaria IFunctionsHostBuilder.Services, você pode, em vez disso, adicionar instruções dentro do método .ConfigureServices() do HostBuilder em seu Program.cs. Para saber mais sobre como trabalhar com Program.cs, confira a Configuração e inicialização no guia do modelo de trabalho isolado.

Os exemplos padrão Program.cs acima incluem a configuração da integração do Application Insights para o modelo de trabalho isolado. No Program.cs, você também deve configurar qualquer filtragem de log que deve ser aplicada aos logs provenientes do código no seu projeto. No modelo de trabalho isolado, o arquivo host.json controla apenas os eventos emitidos pelo runtime do host do Functions. Se você não configurar regras de filtragem no Program.cs, poderá ver diferenças nos níveis de log presentes para várias categorias na telemetria.

Embora você possa registrar fontes de configuração personalizadas como parte do HostBuilder, observe que elas se aplicam somente ao código no seu projeto. A configuração de gatilho e associação também é necessária para a plataforma, e ela deve ser realizada por meio dos recursos de configurações de aplicativo, referências do Key Vault ou referências da Configuração de Aplicativos.

Depois de mover tudo de qualquer FunctionsStartup existente para o arquivo Program.cs, você poderá excluir o atributo FunctionsStartup e a classe à qual ele foi aplicado.

Um arquivo program.cs não é necessário durante a execução em processo.

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

O arquivo host.json controla apenas o log do runtime do host do Functions e, no modelo de trabalho isolado, alguns desses logs vêm diretamente do aplicativo, oferecendo mais controle. Confira Gerenciamento de níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

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

O arquivo host.json controla apenas o log do runtime do host do Functions e, no modelo de trabalho isolado, alguns desses logs vêm diretamente do aplicativo, oferecendo mais controle. Confira Gerenciamento de níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

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

{
    "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"
    }
}

Esta seção destaca outras alterações de código a serem consideradas à medida que você trabalha com a migração. Essas alterações não são necessárias para todos os aplicativos, mas você deve avaliar se alguma é relevante para seus cenários. Verifique se há alterações de comportamento após a versão 1.x para obter alterações adicionais que talvez seja necessário fazer ao seu projeto.

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar as opções do serializador ou alternar para JSON.NET (Newtonsoft.Json), consulte estas instruções.

Níveis de log e filtragem do Application Insights

Os logs podem ser enviados ao Application Insights do runtime do host do Functions e do código em seu projeto. O host.json permite que você configure regras para o registro do host, mas para controlar os logs provenientes do código, você precisará configurar regras de filtragem como parte do seu Program.cs. Confira Gerenciamento de níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

Verifique se há alterações de comportamento após a versão 1.x para obter alterações adicionais que talvez seja necessário fazer ao seu projeto.

Esta seção destaca outras alterações de código a serem consideradas à medida que você trabalha com a migração. Essas alterações não são necessárias para todos os aplicativos, mas você deve avaliar se alguma é relevante para seus cenários. Verifique se há alterações de comportamento após a versão 1.x para obter alterações adicionais que talvez seja necessário fazer ao seu projeto.

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar as opções do serializador ou alternar para JSON.NET (Newtonsoft.Json), consulte estas instruções.

Níveis de log e filtragem do Application Insights

Os logs podem ser enviados ao Application Insights do runtime do host do Functions e do código em seu projeto. O host.json permite que você configure regras para o registro do host, mas para controlar os logs provenientes do código, você precisará configurar regras de filtragem como parte do seu Program.cs. Confira Gerenciamento de níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

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;
        }
    }
}

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);
        }
    }
}

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

Update-AzFunctionAppSetting -AppSetting @{"FUNCTIONS_EXTENSION_VERSION" = "~4"} -Name <APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -Force

Ao executar no Windows, você também precisa habilitar o .NET 6.0, que é exigido pela versão 4.x do runtime.

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

O .NET 6 é necessário para aplicativos de funções em qualquer idioma em execução no Windows.

Ao executar no Windows, você também precisa habilitar o .NET 6.0, que é exigido pela versão 4.x do runtime.

Set-AzWebApp -NetFrameworkVersion v6.0 -Name <APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME>

O .NET 6 é necessário para aplicativos de funções em qualquer idioma em execução no Windows.

Ao executar aplicativos .NET no Linux, também é necessário atualizar a configuração do site linuxFxVersion. Infelizmente, o Azure PowerShell não pode ser usado para definir o linuxFxVersion neste momento. Em vez disso, use a CLI do Azure.