Migrar aplicações da versão 3.x das Funções do Azure para a versão 4.x

  • Artigo

O Azure Functions versão 4.x é altamente compatível com versões anteriores da versão 3.x. A maioria dos aplicativos deve migrar com segurança para o 4.x sem exigir alterações significativas no código. Para obter mais informações sobre versões de tempo de execução do Functions, consulte Visão geral das versões de tempo de execução do Azure Functions.

Importante

A partir de 13 de dezembro de 2022, as aplicações de funções executadas nas versões 2.x e 3.x do runtime das Funções do Azure chegaram ao fim do suporte alargado. Para obter mais informações, consulte Versões desativadas.

Este artigo orienta você pelo processo de migração segura do aplicativo de função para ser executado na versão 4.x do tempo de execução do Functions. Como as instruções de migração do projeto dependem do idioma, certifique-se de escolher sua linguagem de desenvolvimento no seletor na parte superior do artigo.

Identificar aplicativos de função a serem migrados

Use o seguinte script do PowerShell para gerar uma lista de aplicativos de função em sua assinatura que atualmente visam as 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

Escolha sua versão .NET de destino

Na versão 3.x do tempo de execução do Functions, seu aplicativo de função C# tem como alvo 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ção, 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 são suportadas pelo Functions versão 4.x:

Versão .NET Tipo de versão da Política de Suporte Oficial do .NET Funções modelode processo 1,3
.NET 82 LTS Modelo de trabalhador isolado
.NET 7 STS (fim do suporte em 14 de maio de 2024) Modelo de trabalhador isolado
.NET 6 LTS (fim do suporte em 12 de novembro de 2024) Modelo de trabalhador isolado,
Modeloem processo 3
.NET Framework 4.8 Ver política Modelo de trabalhador isolado

1 O modelo de trabalho isolado suporta as versões LTS (Long Term Support) e STS (Standard Term Support) do .NET, bem como do .NET Framework. O modelo em processo suporta apenas versões LTS do .NET. Para obter uma comparação completa de recursos e funcionalidades entre os dois modelos, consulte Diferenças entre o processo de trabalho em processo e o processo de trabalho isolado .NET Azure Functions.

2 O .NET 8 ainda não é suportado no modelo em processo, embora esteja disponível no modelo de trabalhador isolado. Para obter informações sobre planos do .NET 8, incluindo opções futuras para o modelo em processo, consulte a publicação Atualização do Roteiro do Azure Functions.

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

Gorjeta

Recomendamos 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 puder ser evitado. O suporte para o modelo em processo terminará em 10 de novembro de 2026, portanto, você precisará mudar para o modelo de trabalhador 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 trabalho isolado dará ao seu aplicativo benefícios adicionais, incluindo a capacidade de direcionar mais facilmente versões futuras do .NET. Se você estiver mudando para o modelo de trabalho isolado, o Assistente de Atualização do .NET também pode 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ê precisar direcionar essas versões, poderá adaptar os exemplos de modelo de trabalho isolado do .NET 8.

Prepare para a migração

Se ainda não o fez, identifique a lista de aplicativos que precisam ser migrados em sua Assinatura do Azure atual usando o Azure PowerShell.

Antes de migrar um aplicativo para a versão 4.x do tempo de execução do Functions, você deve executar as seguintes tarefas:

  1. Analise a lista de alterações significativas 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. Depois de migrar seu projeto, teste totalmente o aplicativo localmente usando a versão 4.x das Ferramentas Principais do Azure Functions.
  4. Execute o validador de pré-atualização no aplicativo hospedado no Azure e resolva quaisquer problemas identificados.
  5. Atualize seu aplicativo de função no Azure para a nova versão. Se você precisar minimizar o tempo de inatividade, considere usar um slot de preparo para testar e verificar seu aplicativo migrado no Azure na nova versão de tempo de execução. Em seguida, você pode implantar seu aplicativo com as configurações de versão atualizadas no slot de produção. Para obter mais informações, consulte Atualizar usando slots.
  6. Publique seu projeto migrado no aplicativo de função atualizado.

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

Migre seu projeto local

As instruções de atualização dependem do idioma. Se não vir o seu idioma, escolha-o no seletor na parte superior do artigo.

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

Gorjeta

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

Ficheiro de projeto

O exemplo a seguir é um arquivo de projeto que usa o .csproj .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 para ser executado no Functions versão 4.x:

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

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

  1. Defina o valor de PropertyGroup.TargetFramework a net8.0.

  2. Defina o valor de PropertyGroup.AzureFunctionsVersion a v4.

  3. Adicione o seguinte OutputType elemento ao PropertyGroup:

    <OutputType>Exe</OutputType>

  4. No .ItemGroupPackageReference substitua a referência do pacote pelas Microsoft.NET.Sdk.Functions 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 quaisquer referências a outros pacotes nos Microsoft.Azure.WebJobs.* namespaces. Você substituirá esses pacotes em uma etapa posterior.

  5. Aditar o seguinte novo ItemGroup:

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

Depois de fazer essas alterações, seu projeto atualizado deve se parecer com o exemplo a seguir:

<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 seu aplicativo faz referência. Ao adotar os pacotes de destino, você precisará atualizar o namespace de instruções using e alguns tipos aos quais você faz referência. Você pode ver o efeito dessas alterações de namespace nas using instruções nos exemplos de modelo de gatilho HTTP mais adiante neste artigo.

Se ainda não o fez, atualize o seu projeto para fazer referência às versões estáveis mais recentes de:

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

Cenário Alterações nas referências do pacote
Acionador de temporizador Adicionar
Microsoft.Azure.Functions.Worker.Extensions.Timer
Enlaces de armazenamento Replace
Microsoft.Azure.WebJobs.Extensions.Storage
com o
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues e
Microsoft.Azure.Functions.Worker.Extensions.Tables
Enlaces de blobs Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Enlaces de filas Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Enlaces de tabelas Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Tables
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.Tables
Enlaces do Cosmos DB Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.CosmosDB
e/ou
Microsoft.Azure.WebJobs.Extensions.DocumentDB
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Enlaces do Service Bus Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.ServiceBus
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Ligações de Hubs de Eventos Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.EventHubs
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Ligações de grade de eventos Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.EventGrid
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Enlaces do SignalR Service Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.SignalRService
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Funções Duráveis Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.DurableTask
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Funções Duráveis
(Provedor de armazenamento SQL)		 Substitua as referências a
Microsoft.DurableTask.SqlServer.AzureFunctions
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Funções Duráveis
(Provedor de armazenamento Netherite)		 Substitua as referências a
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Enlaces do SendGrid Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.SendGrid
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Ligações Kafka Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Kafka
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Ligações RabbitMQ Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
com a última versão do
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.)

Consulte Ligações suportadas para obter uma lista completa de extensões a serem consideradas e consulte a documentação de cada extensão para obter instruções de instalação completas para o modelo de processo isolado. Certifique-se de instalar a versão estável mais recente de todos os pacotes que você está segmentando.

Gorjeta

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

Seu aplicativo de modelo de trabalho isolado não deve fazer referência a nenhum pacote nos Microsoft.Azure.WebJobs.* namespaces ou Microsoft.Azure.Functions.Extensions. Se você tiver quaisquer referências restantes a estes, eles devem ser removidos.

Gorjeta

Seu aplicativo também pode depender dos tipos de SDK do Azure, como parte de seus gatilhos e associações ou como uma dependência autônoma. Você deve aproveitar esta oportunidade para atualizá-los também. 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 para os quais são o formulário Azure.*.

Program.cs arquivo

Ao migrar para ser executado em um processo de trabalho isolado, você deve adicionar o seguinte arquivo de program.cs ao seu 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 ASP.NET Core para melhorar o desempenho e fornecer um modelo de programação familiar quando seu aplicativo usa gatilhos HTTP. Se você não pretende usar gatilhos HTTP, você pode substituir a chamada para ConfigureFunctionsWebApplication por uma chamada para ConfigureFunctionsWorkerDefaults. Se você fizer isso, você pode remover a referência a Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore do seu arquivo de projeto. No entanto, para o melhor desempenho, mesmo para funções com outros tipos de gatilho, você deve manter o FrameworkReference ASP.NET Core.

O Program.cs arquivo substituirá qualquer arquivo que tenha o FunctionsStartup atributo, que normalmente é um Startup.cs arquivo. Em locais onde seu FunctionsStartup código faria referência IFunctionsHostBuilder.Services, você pode, em vez disso, adicionar instruções dentro do .ConfigureServices() método do HostBuilder em seu Program.cs. Para saber mais sobre como trabalhar com Program.cso , consulte Inicialização e configuração no guia de modelo de trabalhador 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.csvocê também deve configurar qualquer filtragem de log que deve ser aplicada a logs provenientes do código em seu projeto. No modelo de trabalho isolado, o arquivo controla host.json apenas os eventos emitidos pelo tempo de execução do host 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 em sua telemetria.

Embora você possa registrar fontes de configuração personalizadas como parte do HostBuilder, observe que elas também se aplicam apenas ao código em seu projeto. A configuração de acionamento e vinculação também é necessária para a plataforma, e isso deve ser fornecido por meio das configurações do aplicativo, referências do Cofre da Chave ou recursos de referências de Configuração do Aplicativo.

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

local.settings.json arquivo

O arquivo local.settings.json só é usado quando executado localmente. Para obter informações, consulte Arquivo de configurações locais.

Ao migrar para a versão 4.x, certifique-se de que o arquivo local.settings.json tenha pelo menos os seguintes elementos:

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

Nota

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

host.json arquivo

Não são necessárias alterações ao seu host.json ficheiro. No entanto, se a configuração do Application Insights neste arquivo for do seu projeto de modelo em processo, convém fazer alterações adicionais no arquivo Program.cs . O host.json arquivo controla apenas o log do tempo de execução do host do Functions e, no modelo de trabalho isolado, alguns desses logs vêm diretamente do seu aplicativo, oferecendo mais controle. Consulte Gerenciando níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

Alterações no nome da classe

Algumas classes chave mudaram de nome entre versões. Essas alterações são resultado de alterações nas APIs do .NET ou das diferenças entre o processo de trabalho isolado e em processo. A tabela a seguir indica as principais classes .NET usadas pelo Functions que podem ser alteradas durante a 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) Usa Program.cs em vez disso Usa Program.cs em vez disso

Também pode haver diferenças de nome de classe em associações. Para obter mais informações, consulte os artigos de referência para as ligações específicas.

Outras alterações de código

Esta seção destaca outras alterações de código a serem consideradas ao trabalhar na 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. Certifique-se de marcar Alterações significativas entre 3.x e 4.x para alterações adicionais que você pode precisar 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 para o Application Insights a partir do tempo de execução do host do Functions e do código em seu projeto. O host.json permite que você configure regras para registro em log do host, mas para controlar logs provenientes do seu código, você precisará configurar regras de filtragem como parte do seu Program.cs. Consulte Gerenciando níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

Modelo de acionador HTTP

As diferenças entre o processo de trabalho em processo e o processo de trabalho isolado podem ser vistas em funções acionadas por HTTP. O modelo de gatilho HTTP para a versão 3.x (em processo) se parece com o exemplo a seguir:

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 se parece com o exemplo a seguir:

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 seu projeto para o Azure Functions 4.x:

  1. Atualize sua instalação local das Ferramentas Principais do Azure Functions para a versão 4.x.

  2. Atualize o pacote de extensões do Azure Functions do seu aplicativo para 2.x ou superior. Para obter mais informações, consulte Alterações de quebra.

  1. Se necessário, mude para uma das versões Java suportadas na versão 4.x.

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

    <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, mude para uma das versões Node.js suportadas na versão 4.x.
  1. Aproveite esta oportunidade para atualizar para o PowerShell 7.2, que é recomendado. Para obter mais informações, consulte Versões do PowerShell.
  1. Se você estiver usando o Python 3.6, mude para uma das versões suportadas.

Execute o validador de pré-atualização

As Funções do Azure disponibilizam um validador de pré-atualização, que ajuda a identificar potenciais problemas ao migrar a sua aplicação de funções para a versão 4.x. Para executar o validador de pré-atualização:

  1. No portal do Azure, navegue até seu aplicativo de função.

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

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

  4. Após a conclusão da validação, revise as recomendações e resolva quaisquer problemas em seu aplicativo. Se você precisar fazer alterações em seu aplicativo, certifique-se de validar as alterações em relação à versão 4.x do tempo de execução do Functions, localmente usando o Azure Functions Core Tools v4 ou usando um slot de preparo.

Atualizar seu aplicativo de função no Azure

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

A maneira mais fácil é atualizar sem slots e, em seguida, publicar novamente seu projeto de aplicativo. Você também pode minimizar o tempo de inatividade em seu aplicativo e simplificar a reversão atualizando usando slots.

Atualizar sem slots

A maneira mais simples de atualizar para v4.x é definir a configuração do FUNCTIONS_EXTENSION_VERSION aplicativo para ~4 em seu aplicativo de função no Azure. Você deve seguir 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 deve definir outra configuração, que difere entre Windows e Linux.

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

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

O .NET 6 é necessário para aplicativos funcionais em qualquer idioma em execução no Windows.

Neste exemplo, substitua <APP_NAME> pelo nome do seu aplicativo de função 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ção para o tempo de execução v4.x de uma versão anterior. Usando um slot de preparo, você pode executar seu aplicativo na nova versão de tempo de execução 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 do tempo mínimo de inatividade.

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

Atualização padrão

Se o seu aplicativo de função habilitado para slot puder lidar com o tempo de inatividade de uma reinicialização completa, você poderá atualizar a WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS configuração 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 essa alteração em um momento de tráfego reduzido. Em seguida, você pode trocar a versão atualizada a partir do slot de preparação.

Atualmente Update-AzFunctionAppSetting , o cmdlet do PowerShell não oferece suporte a slots. Você deve 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 seu aplicativo de função 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 preparação:

    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 de tempo de execução:

    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 tempo de execução do Functions requer o .NET 6 no Windows. No Linux, os aplicativos .NET também devem ser atualizados para o .NET 6. Use o seguinte comando para que o tempo de execução 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 tempo de execução.

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

    O .NET 6 é necessário para aplicativos funcionais em qualquer idioma em execução no Windows.

    Neste exemplo, substitua <APP_NAME> pelo nome do seu aplicativo de função e <RESOURCE_GROUP_NAME> pelo nome do grupo de recursos.

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

  6. Confirme se seu aplicativo de função é executado corretamente no ambiente de preparo atualizado antes de trocar.

  7. Use o seguinte comando para trocar o slot de preparo atualizado para a produção:

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

Atualização do tempo de inatividade mínimo

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

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

    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 trocar o slot com a nova configuração em produção e, ao mesmo tempo, restaurar a configuração de versão no slot de preparação.

    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ê pode ver erros do slot de preparo durante o tempo entre a troca e a versão de tempo de execução sendo restaurada no preparo. Esse erro pode acontecer porque ter WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 apenas no preparo durante uma troca remove a FUNCTIONS_EXTENSION_VERSION configuração no preparo. Sem a configuração de versão, seu slot está em mau estado. Atualizar a versão no slot de preparo logo após a troca deve colocar o slot de volta em um bom estado, e você chama reverter suas alterações, se necessário. No entanto, qualquer reversão da troca também requer que você remova WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 diretamente da produção antes da troca 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 preparação:

    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 estão WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 definidos.

  4. Use o seguinte comando para alterar FUNCTIONS_EXTENSION_VERSION e atualizar o slot de preparo para a nova versão de tempo de execução:

    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 tempo de execução do Functions requer o .NET 6 no Windows. No Linux, os aplicativos .NET também devem ser atualizados para o .NET 6. Use o seguinte comando para que o tempo de execução 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 tempo de execução.

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

    O .NET 6 é necessário para aplicativos funcionais em qualquer idioma em execução no Windows.

    Neste exemplo, substitua <APP_NAME> pelo nome do seu aplicativo de função e <RESOURCE_GROUP_NAME> pelo nome do grupo de recursos.

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

  7. Confirme se seu aplicativo de função é executado corretamente no ambiente de preparo atualizado antes de trocar.

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

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

Alterações de quebra entre 3.x e 4.x

A seguir estão as principais alterações de quebra a serem observadas antes de atualizar um aplicativo 3.x para 4.x, incluindo alterações de quebra específicas do idioma. Para obter uma lista completa, consulte Problemas do GitHub do Azure Functions rotulados como Alteração de rutura: aprovado.

Se você não vir sua 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 tempo de execução do Azure Functions. O suporte para proxies de funções pode ser reativado na versão 4.x para que você possa atualizar com êxito seus aplicativos de função para a versão de tempo de execução mais recente. Assim que possível, você deve alternar para integrar seus aplicativos de função com o Gerenciamento de API do Azure. O API Management permite-lhe tirar partido de um conjunto de funcionalidades mais completo para definir, proteger, gerir e rentabilizar as suas APIs baseadas em Funções. Para obter mais informações, consulte Integração de gerenciamento de API. Para saber como reativar o suporte a proxies no Functions versão 4.x, consulte Reativar proxies no Functions v4.x.

  • O registro em log no Armazenamento do Azure usando AzureWebJobsDashboard não é mais suportado no 4.x. Em vez disso, você deve usar o Application Insights. (#1923)

  • O Azure Functions 4.x agora impõe requisitos mínimos de versão para extensões. Atualize para a versão mais recente das extensões afetadas. Para non-.NET idiomas, atualize para a versão 2.x ou posterior do pacote de extensão. (#1987)

  • Os tempos limite padrão e máximo agora são impostos em 4.x para aplicativos de função executados 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 Cofre da Chave e preteriu o uso do Microsoft.Azure.KeyVault. Para obter mais informações sobre como definir as configurações do aplicativo de função, consulte a opção Cofre da chave em Repositórios secretos. (#2048)

  • Os aplicativos de função que compartilham contas de armazenamento agora não são iniciados quando seus IDs de host são os mesmos. Para obter mais informações, consulte Considerações sobre o ID do host. (#2049)

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

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

  • EnableEnhancedScopes está ativado por predefinição. (#1954)

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

  • Use um carregador de classe única em Java 11. (#1997)

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

  • Node.js versões 10 e 12 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. Funções que não são thread-safe ou têm alto uso de memória podem ser afetadas. (#1962)

  • Python 3.6 não é suportado no Azure Functions 4.x. (#1999)

  • A transferência de memória partilhada está ativada por predefinição. (#1973)

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

Próximos passos

Saiba mais sobre as versões do Functions