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

  • Artigo

O Azure Functions versão 4.x é compatível com versões anteriores à versão 3.x. A maioria dos aplicativos devem migrar para a 4.x com segurança e sem mudanças significativas no código. Para saber mais sobre as versões do runtime do Functions, confira Visão geral das versões do runtime do Azure Functions.

Importante

Desde 13 de dezembro de 2022, os aplicativos de funções em execução nas versões 2.x e 3.x do runtime do Azure Functions atingiram o fim do suporte estendido. Para saber mais, confira Versões desativadas.

Este artigo descreve o processo de migração segura do aplicativo de funções para execução na versão 4.x do runtime do Functions. Como as instruções de migração de projeto são dependentes de linguagem, escolha a linguagem de desenvolvimento no seletor na parte superior do artigo.

Identificar aplicativos de funções a serem migrados

Use o seguinte script do PowerShell para gerar uma lista de aplicativos de funções em sua assinatura que atualmente se destinam às versões 2.x ou 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

Escolher a versão do .NET de destino

Na versão 3.x do runtime do Functions, seu aplicativo de funções C# tem como destino o .NET Core 3.1 usando o modelo em processo ou o .NET 5 usando o modelo de trabalho isolado.

Ao migrar seu aplicativo de funções, você tem a oportunidade de escolher a versão de destino do .NET. Você pode atualizar seu projeto C# para uma das seguintes versões do .NET, que podem ser executadas na versão 4.x do Functions:

Versão do .NET Tipo de versão da política de suporte oficial do .NET Modelo de processo do Functions 1,3
.NET 82 LTS Modelo de trabalho isolado
.NET 7 STS (fim do suporte 14 de maio de 2024) Modelo de trabalho isolado
.NET 6 LTS (fim do suporte 12 de novembro de 2024) Modelo de trabalho isolado,
Modelo em processo3
.NET Framework 4.8 Consultar política Modelo de trabalho isolado

1 O modelo de trabalho isolado dá suporte às versões LTS (suporte de longo prazo) e STS (suporte de curto prazo) do .NET, bem como .NET Framework. O modelo em processo só dá suporte a versões LTS do .NET. Para obter uma comparação completa de recursos e funcionalidades entre os dois modelos, confira Diferenças entre o processo de trabalho isolado e em processo do Azure Functions no .NET.

2 .NET 8 ainda não tem suporte no modelo em processo, embora esteja disponível no modelo de trabalho isolado. Para obter informações sobre planos do .NET 8, incluindo futuras opções para o modelo em processo, confira a postagem Atualização do roteiro do Azure Functions.

3 O suporte termina para o modelo em processo em 10 de novembro de 2026. Para obter mais informações, confira este comunicado de suporte. Para obter suporte completo contínuo, você deve migrar seus aplicativos para o modelo de trabalho isolado.

Dica

É recomendável atualizar para o .NET 8 no modelo de trabalho isolado. O .NET 8 é a versão totalmente lançada com a janela de suporte mais longa do .NET.

Embora você possa optar por usar o modelo em processo, isso não é recomendado se ele puder ser evitado. O suporte terminará para o modelo em processo em 10 de novembro de 2026, portanto, você precisará migrar para o modelo de trabalho isolado antes disso. Fazer isso durante a migração para a versão 4.x diminuirá o esforço total necessário, e o modelo de trabalhado isolado fornecerá benefícios adicionais para o seu aplicativo, incluindo a capacidade de direcionar mais facilmente versões futuras do .NET. Se você estiver migrando para o modelo de trabalho isolado, o Assistente de Atualização do .NET também poderá lidar com muitas das alterações de código necessárias para você.

Este guia não apresenta exemplos específicos para .NET 7 ou .NET 6 no modelo de trabalho isolado. Se você precisa visar essas versões, poderá adaptar os exemplos de modelo de trabalho isolado do .NET 8.

Preparar para a migração

Caso ainda não tenha feito isso, identifique a lista de aplicativos que precisam ser migrados em sua assinatura atual do Azure usando o Azure PowerShell.

Antes de migrar um aplicativo para a versão 4.x do runtime do Functions, realize as seguintes tarefas:

  1. Examine a lista de alterações interruptivas entre 3.x e 4.x.
  2. Conclua as etapas em Migrar seu projeto local para migrar seu projeto local para a versão 4.x.
  3. Após migrar seu projeto, faça um teste completo do aplicativo no local usando a versão 4.x do Azure Functions Core Tools.
  4. Execute o validador de pré-atualização no aplicativo hospedado no Azure e resolva os problemas identificados.
  5. Atualize seu aplicativo de funções no Azure para a nova versão. Caso você precise minimizar o tempo de inatividade, considere o uso de um slot de preparo para testar e verificar seu aplicativo migrado no Azure na nova versão de runtime. Em seguida, você pode implantar o aplicativo com as configurações de versão atualizadas no slot de produção. Para saber mais, confira Atualizar usando slots.
  6. Publique seu projeto migrado para o aplicativo de funções atualizado.

Quando você usa o Visual Studio para publicar um projeto versão 4.x em um aplicativo de funções existente com uma versão inferior, é solicitado que você permita que o Visual Studio atualize o aplicativo de funções para a versão 4.x durante a implantação. Essa atualização usa o mesmo processo definido em Atualizar sem slots.

Migrar seu projeto local

As instruções de atualização dependem da linguagem. Se você não vir a linguagem, escolha-a no seletor na parte superior do artigo.

Escolha a guia que corresponde à versão de destino do .NET e ao modelo de processo desejado (em processo ou processo de trabalho isolado).

Dica

Se você estiver migrando para uma versão LTS ou STS do .NET usando o modelo de trabalho isolado, o Assistente de Atualização do .NET poderá ser usado para fazer automaticamente muitas das alterações mencionadas nas seções a seguir.

Arquivo de projeto

O exemplo a seguir é um arquivo de projeto .csproj que usa o .NET Core 3.1 na versão 3.x:

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

Use um dos procedimentos a seguir para atualizar esse arquivo XML a fim de executá-lo no Functions 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>

Alterações de pacote e namespace

Com base no modelo para o qual você está migrando, talvez seja necessário atualizar ou alterar os pacotes aos quais o aplicativo faz referência. Ao adotar os pacotes de destino, talvez seja necessário atualizar o namespace das instruções de uso e alguns tipos que você referencia. Veja o efeito dessas alterações de namespace nas instruções using nos exemplos de modelos de gatilho HTTP mais adiante neste artigo.

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

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:

Cenário Alterações nas referências de pacote
Gatilho de temporizador Add
Microsoft.Azure.Functions.Worker.Extensions.Timer
Associações do armazenamento Substitua
Microsoft.Azure.WebJobs.Extensions.Storage
por
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues e
Microsoft.Azure.Functions.Worker.Extensions.Tables
Associações de blob Substitua referências a
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Associações de fila Substitua referências a
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Associações de tabela Substitua referências a
Microsoft.Azure.WebJobs.Extensions.Tables
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.Tables
Associações do Cosmos DB Substitua referências a
Microsoft.Azure.WebJobs.Extensions.CosmosDB
e/ou
Microsoft.Azure.WebJobs.Extensions.DocumentDB
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Associações do barramento de serviço Substitua referências a
Microsoft.Azure.WebJobs.Extensions.ServiceBus
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Associações dos Hubs de Eventos Substitua referências a
Microsoft.Azure.WebJobs.Extensions.EventHubs
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Associações da Grade de Eventos Substitua referências a
Microsoft.Azure.WebJobs.Extensions.EventGrid
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Associações do Serviço do SignalR Substitua referências a
Microsoft.Azure.WebJobs.Extensions.SignalRService
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Funções duráveis Substitua referências a
Microsoft.Azure.WebJobs.Extensions.DurableTask
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Funções duráveis
(provedor de armazenamento SQL)		 Substitua referências a
Microsoft.DurableTask.SqlServer.AzureFunctions
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Funções duráveis
(provedor de armazenamento Netherite)		 Substitua referências a
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Associações do SendGrid Substitua referências a
Microsoft.Azure.WebJobs.Extensions.SendGrid
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Associações do Kafka Substitua referências a
Microsoft.Azure.WebJobs.Extensions.Kafka
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Associações do RabbitMQ Substitua referências a
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
pela versão mais recente de
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Injeção de dependência
e configuração de inicialização		 Remover referências a
Microsoft.Azure.Functions.Extensions
(O modelo de trabalho isolado fornece essa funcionalidade por padrão.)

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.

Dica

Quaisquer alterações nas versões de extensão durante esse processo podem exigir que você atualize seu arquivo host.json também. Certifique-se de ler a documentação de cada extensão que você usa. Por exemplo, a extensão do Barramento de Serviço apresenta alterações significativas na estrutura entre as versões 4.xe 5.x. Para obter mais informações, veja Encadernações do Barramento de Serviço do Azure para Azure Functions.

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.

Dica

Seu aplicativo também pode depender de tipos de SDK do Azure, seja como parte de seus gatilhos e associações ou como uma dependência autônoma. Você também deve aproveitar essa oportunidade para atualizá-los. As versões mais recentes das extensões do Functions funcionam com as versões mais recentes do SDK do Azure para .NET, quase todos os pacotes com o formato Azure.*.

Arquivo program.cs

Ao migrar para a execução em um processo de trabalho isolado, você precisa adicionar o seguinte arquivo program.cs ao projeto:

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.

Arquivo local.settings.json

O arquivo local.settings.json só é usado durante a execução local. Para obter mais informações, confira Arquivo de configurações local.

Ao migrar para a versão 4.x, verifique se o arquivo local.settings.json tem pelo menos os seguintes elementos:

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

Observação

Ao migrar da execução em processo para a execução em um processo de trabalho isolado, você precisa alterar o valor FUNCTIONS_WORKER_RUNTIME para "dotnet-isolated".

Arquivo host.json

Nenhuma alteração será necessária para o arquivo host.json. No entanto, se a configuração do Application Insights estiver neste arquivo do seu projeto de modelo em processo, talvez seja conveniente fazer alterações adicionais no seu arquivo Program.cs. 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.

Alterações de nome da classe

Algumas classes importantes mudaram de nome ao longo das versões. Essas alterações são resultado de alterações nas APIs do .NET ou em diferenças entre o processo de trabalho em processo e isolado. A seguinte tabela indica as principais classes .NET usadas pelo Functions que podem ser alteradas na migração:

.NET Core 3.1 .NET 5 .NET 8
FunctionName (atributo) Function (atributo) Function (atributo)
ILogger ILogger ILogger, ILogger<T>
HttpRequest HttpRequestData HttpRequestData, HttpRequest (usando a integração ASP.NET Core)
IActionResult HttpResponseData HttpResponseData, IActionResult (usando a integração ASP.NET Core)
FunctionsStartup (atributo) Em vez disso, usa Program.cs Em vez disso, usa Program.cs

Também pode haver diferenças de nome da classe nas associações. Para saber mais, confira os artigos de referência das associações específicas.

Outras alterações de código

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 os seus cenários. Verifique se há Alterações interruptivas entre 3.x e 4.x para quaisquer alterações adicionais que você precise fazer em 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.

Modelo de gatilho HTTP

As diferenças entre a execução em processo e o processo de trabalho isolado podem ser vistas nas funções disparadas por HTTP. O modelo de gatilho HTTP para a versão 3.x (em processo) é semelhante ao seguinte exemplo:

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

O modelo de gatilho HTTP para a versão migrada é semelhante ao seguinte exemplo:

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

Para atualizar o projeto para o Azure Functions 4.x:

  1. Atualize a instalação local do Azure Functions Core Tools para a versão 4.x.

  2. Atualize o pacote de extensões do Azure Functions do aplicativo para 2.x ou superior. Confira alterações interruptivas para obter mais informações.

  1. Se necessário, migre para uma das versões do Java com suporte na versão 4.x.

  2. Atualize o arquivo POM.xml do aplicativo para modificar a configuração FUNCTIONS_EXTENSION_VERSION para ~4, como no seguinte exemplo:

    <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. Se necessário, migre para uma das versões do Node.js com suporte na versão 4.x.
  1. Aproveite esta oportunidade para atualizar para o PowerShell 7.2, o que é recomendado. Para obter mais informações, confira Versões do PowerShell.
  1. Se estiver usando o Python 3.6, vá para uma das versões com suporte.

Executar o validador pré-atualização

O Azure Functions fornece um validador pré-atualização para ajudar você a identificar possíveis problemas ao migrar seu aplicativo de funções para o 4.x. Para executar o validador pré-atualização:

  1. No portal do Azure, navegue até o aplicativo de funções.

  2. Abra a página Diagnosticar e resolver problemas.

  3. No Diagnóstico do Aplicativo de Funções, comece a digitar Functions 4.x Pre-Upgrade Validator e escolha-o na lista.

  4. Após a conclusão da validação, examine as recomendações e resolva eventuais problemas no aplicativo. Se precisar fazer alterações no aplicativo, não deixe de validá-las na versão 4.x do runtime do Functions, localmente usando o Azure Functions Core Tools v4 ou usando um slot de preparo.

Atualize seu aplicativo de funções no Azure

Você precisa atualizar o runtime do host do aplicativo de funções no Azure para a versão 4.x antes de publicar seu projeto migrado. A versão de runtime usada pelo host do Functions é controlada pela configuração de aplicativo FUNCTIONS_EXTENSION_VERSION, mas em alguns casos outras configurações também precisam ser atualizadas. As alterações de código e as alterações nas configurações de aplicativo exigem que o aplicativo de funções seja reiniciado.

A maneira mais fácil é a atualização sem slots e a nova publicação do projeto de aplicativo. Minimize também o tempo de inatividade no aplicativo e simplifique a reversão com a atualização por meio de slots.

Atualizar sem slots

A maneira mais simples de atualizar para a v4.x é definir a configuração de aplicativo FUNCTIONS_EXTENSION_VERSION como ~4 em seu aplicativo de funções no Azure. Siga um procedimento diferente em um site com slots.

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

Você também precisa definir outra configuração, que é diferente entre o Windows e o Linux.

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.

Neste exemplo, substitua <APP_NAME> pelo nome do aplicativo de funções e <RESOURCE_GROUP_NAME> pelo nome do grupo de recursos.

Agora você pode publicar novamente seu projeto de aplicativo que foi migrado para ser executado na versão 4.x.

Atualizar usando slots

Usar slots de implantação é uma boa maneira de atualizar seu aplicativo de funções para o runtime v4.x de uma versão anterior. Usando um slot de preparo, você pode executar o aplicativo na nova versão do runtime no slot de preparo e alternar para a produção após a verificação. Os slots também fornecem uma maneira de minimizar o tempo de inatividade durante a atualização. Se precisar minimizar o tempo de inatividade, siga as etapas em Atualização com tempo de inatividade mínimo.

Depois de verificar o aplicativo no slot atualizado, você pode trocar o aplicativo e as novas configurações da versão para produção. Essa troca requer a configuração WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 no slot de produção. A maneira como você adiciona essa configuração afeta a quantidade de tempo de inatividade necessário para a atualização.

Atualização padrão

Se o aplicativo de funções habilitado para slots puder lidar com o tempo de inatividade de uma reinicialização completa, você poderá atualizar a configuração WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS diretamente no slot de produção. Como alterar essa configuração diretamente no slot de produção causa uma reinicialização que afeta a disponibilidade, considere fazer a alteração em um momento de tráfego reduzido. Em seguida, você pode trocar pela versão atualizada do slot de preparo.

No momento, o cmdlet do PowerShell Update-AzFunctionAppSetting não dá suporte a slots. Você precisa usar a CLI do Azure ou o portal do Azure.

  1. Use o seguinte comando para definir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 no slot de produção:

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

    Neste exemplo, substitua <APP_NAME> pelo nome do aplicativo de funções e <RESOURCE_GROUP_NAME> pelo nome do grupo de recursos. Esse comando faz com que o aplicativo em execução no slot de produção seja reiniciado.

  2. Use o seguinte comando para também definir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS no slot de preparo:

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

  3. Use o seguinte comando para alterar FUNCTIONS_EXTENSION_VERSION e atualizar o slot de preparo para a nova versão do runtime:

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

  4. A versão 4.x do runtime do Functions exige o .NET 6 no Windows. No Linux, os aplicativos .NET também devem fazer upgrade para o .NET 6. Use o comando a seguir para que o runtime possa ser executado no .NET 6:

    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.

    Neste exemplo, substitua <APP_NAME> pelo nome do aplicativo de funções e <RESOURCE_GROUP_NAME> pelo nome do grupo de recursos.

  5. Se o projeto de código exigiu alguma atualização para ser executado na versão 4.x, implante essas atualizações no slot de preparo agora.

  6. Confirme se o aplicativo de funções é executado corretamente no ambiente de preparo atualizado antes da troca.

  7. Use o seguinte comando para colocar o slot de preparo atualizado na produção:

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

Atualização com tempo de inatividade mínimo

Para minimizar o tempo de inatividade em seu aplicativo de produção, coloque a configuração WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS do slot de preparo para a produção. Depois disso, você pode trocar pela versão atualizada de um slot de preparo pré-aquecido.

  1. Use o seguinte comando para definir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 no slot de preparo:

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

  2. Use os comandos a seguir para colocar o slot com a nova configuração em produção e, ao mesmo tempo, restaurar a configuração da versão no slot de preparo.

    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>

    Você poderá ver erros do slot de preparo durante o período entre a troca e a versão do runtime que está sendo restaurada no preparo. Isso pode acontecer porque ter WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 apenas no preparo durante uma troca remove a configuração FUNCTIONS_EXTENSION_VERSION no preparo. Sem a configuração da versão, o slot fica em um estado inválido. Atualizar a versão no slot de preparo logo após a troca deve colocar o slot de volta em um estado válido e você pode chamar uma reversão das alterações se necessário. No entanto, qualquer reversão da troca também exige que você remova WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 diretamente da produção antes de trocar de volta para evitar os mesmos erros na produção vistos no preparo. Essa alteração na configuração de produção causaria uma reinicialização.

  3. Use o seguinte comando para definir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 novamente no slot de preparo:

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

    Neste ponto, ambos os slots têm WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 definido.

  4. Use o seguinte comando para alterar FUNCTIONS_EXTENSION_VERSION e atualizar o slot de preparo para a nova versão do runtime:

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

  5. A versão 4.x do runtime do Functions exige o .NET 6 no Windows. No Linux, os aplicativos .NET também devem fazer upgrade para o .NET 6. Use o comando a seguir para que o runtime possa ser executado no .NET 6:

    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.

    Neste exemplo, substitua <APP_NAME> pelo nome do aplicativo de funções e <RESOURCE_GROUP_NAME> pelo nome do grupo de recursos.

  6. Se o projeto de código exigiu alguma atualização para ser executado na versão 4.x, implante essas atualizações no slot de preparo agora.

  7. Confirme se o aplicativo de funções é executado corretamente no ambiente de preparo atualizado antes da troca.

  8. Use o seguinte comando para colocar o slot de preparo atualizado e pré-aquecido na produção:

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

Alterações interruptivas entre a 3.x e a 4.x

A seguir, são apresentadas as principais alterações interruptivas que deverão ser observadas antes de atualizar um aplicativo 3.x para 4.x, incluindo alterações interruptivas específicas da linguagem. Para obter uma lista completa, consulte Azure Functions GitHub problemas rotulados como alteração significativa: aprovado.

Se você não visualizar a linguagem de programação, selecione-a na parte superior da página.

Runtime

  • Os Proxies do Azure Functions são um recurso herdado para as versões 1.x a 3.x do runtime do Azure Functions. O suporte para os Proxies do Functions pode ser reabilitado na versão 4.x para que você possa atualizar com êxito seus aplicativos de funções para a versão mais recente do runtime. Assim que possível, você deverá alternar para integrar seus aplicativos de funções ao Gerenciamento de API do Azure. O Gerenciamento de API permite aproveitar um conjunto mais completo de recursos para definir, proteger, gerenciar e monetizar as APIs baseadas no Functions. Para obter mais informações, consulte Integração do Gerenciamento de API. Para saber como reabilitar o suporte aos Proxies do Functions versão 4.x, consulte Reabilitar os Proxies do Functions v4.x.

  • Não há mais suporte para o registro no Armazenamento do Microsoft Azure usando AzureWebJobsDashboard no 4.x. Em vez disso, você deve usar o Application Insights. (#1923)

  • Agora, o Azure Functions 4.x impõe os requisitos mínimos de versão para extensões. Atualize para a versão mais recente das extensões afetadas. Para linguagens não .NET, atualize para o pacote de extensão versão 2.x ou posterior. (#1987)

  • Agora, os tempos limite padrão e máximo são impostos na 4.x para os aplicativos de funções em execução no Linux em um plano de Consumo. (#1915)

  • O Azure Functions 4.x usa Azure.Identity e Azure.Security.KeyVault.Secrets para o provedor do Key Vault e preteriu o uso de Microsoft.Azure.KeyVault.t. Para obter mais informações sobre como definir as configurações do aplicativo de funções, consulte a opção Key Vault nos Repositórios secretos. (#2048)

  • Agora, os aplicativos de funções que compartilham contas de armazenamento falham ao serem iniciados quando as IDs do host são as mesmas. Para obter mais informações, consulte Considerações sobre a ID do host. (#2049)

  • O Azure Functions 4.x dá suporte a aplicativos .NET 6 em processo e isolados.

  • InvalidHostServicesException agora é um erro fatal. (#2045)

  • EnableEnhancedScopes está habilitado por padrão. (#1954)

  • Remova HttpClient como serviço registrado. (#1911)

  • Use o carregador de classe única no Java 11. (#1997)

  • Pare de carregar jars de trabalho no Java 8. (#1991)

  • As versões 10 e 12 do Node.js não têm suporte no Azure Functions 4.x. (#1999)

  • A serialização de saída em aplicativos Node.js foi atualizada para resolver inconsistências anteriores. (#2007)

  • A contagem de threads padrão foi atualizada. As funções que não são thread-safe ou têm alto uso de memória poderiam ser impactadas. (#1962)

  • O Python 3.6 não é compatível com o Azure Functions 4.x. (#1999)

  • A transferência de memória compartilhada é habilitada por padrão. (#1973)

  • A contagem de threads padrão foi atualizada. As funções que não são thread-safe ou têm alto uso de memória poderiam ser impactadas. (#1962)

Próximas etapas

Saiba mais sobre as versões do Functions