Partilhar via

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

Importante

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

Funções do Azure versão 4.x é altamente retrocompatível com a 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 mais informações sobre as versões em tempo de execução das funções, consulte Funções do Azure visão geral das versões em tempo de execução.

Importante

As aplicações funcionais que ainda estão a correr o runtime final de vida v3 no Linux num plano de Consumo deixam de funcionar após 30 de setembro de 2026. Para evitar interrupções no serviço, migre a sua aplicação para o runtime da v4.

A opção de alojar aplicações funcionais no Linux num plano Consumption será retirada a 30 de setembro de 2028. O plano Linux Consumption não está a receber novas funcionalidades nem versões de linguagem. As aplicações a correr no Windows num plano de Consumo não estão atualmente afetadas. Migre as suas aplicações para o plano Flex Consumption antes da data de reforma.

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 a versão .NET do seu destino

Na versão 3.x do runtime Functions, a sua aplicação de funções C# direciona-se ao .NET Core 3.1 usando o modelo em processo ou ao .NET 5 usando o modelo worker isolado.

Quando migra a sua aplicação de funções, tem a oportunidade de escolher a versão alvo do .NET. Pode atualizar o seu projeto C# para uma das seguintes versões de .NET suportadas pela versão 4.x das Functions:

Versão .NET .NET Política Oficial de Suporte tipo de lançamento Modelo de funções de processo1,2
.NET 10 LTS (fim do suporte em 14 de novembro de 2028) Modelo de trabalhador isolado
.NET 9 STS (fim do suporte em 10 de novembro de 2026)3 Modelo de trabalhador isolado
.NET 8 LTS (fim do suporte em 10 de novembro de 2026) Modelo de trabalhador isolado,
Modelo em desenvolvimento2
.NET Framework 4.8 Ver política Modelo de trabalhador isolado

1 O modelo trabalhador isolado suporta versões de Suporte a Longo Prazo (LTS) e Suporte a Prazo Padrão (STS) do .NET, bem como .NET Framework. O modelo em processo apenas suporta versões LTS de .NET, terminando com .NET 8. Para uma comparação completa das funcionalidades entre os dois modelos, veja Diferenças entre processos de trabalho no local e isolados .NET Funções do Azure.

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

3 .NET 9 tinha anteriormente uma data prevista de fim de suporte para 12 de maio de 2026. Durante a janela de serviço do .NET 9, a equipa do .NET estendeu o suporte para versões STS até 24 meses, começando pelo .NET 9. Para obter mais informações, consulte a postagem do blog.

Gorjeta

Recomendamos atualizar para .NET 8 no modelo de trabalhador isolado. .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, não recomendamos essa abordagem se puder evitá-la. 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 enquanto migra para a versão 4.x diminuirá o esforço total necessário, e o modelo de trabalhador isolado dará à sua aplicação benefícios adicionais, incluindo a capacidade de direcionar versões futuras de .NET mais facilmente. Se estiver a migrar para o modelo de trabalhador isolado, o Assistente de Atualização .NET também pode tratar de muitas das alterações necessárias ao código para si.

Este guia não apresenta exemplos específicos para .NET 10 (pré-visualização) ou .NET 9. Se precisares de escolher uma dessas versões, podes adaptar os exemplos do .NET 8.

Prepare para a migração

Se ainda não o fez, identifique a lista de aplicações que precisam de ser migradas na sua subscrição 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 o seu projeto, teste completamente a aplicação localmente usando a versão 4.x do Core Tools Funções do Azure Core Tools.
  4. Execute o validador pré-atualização na aplicação alojada em Azure e resolva quaisquer problemas identificados.
  5. Atualize a sua aplicação de funções no Azure para a nova versão. Se precisares de minimizar o tempo de inatividade, considera usar um slot staging para testar e verificar a tua aplicação migrada em Azure na nova versão de runtime. 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 usa o Visual Studio para publicar um projeto da versão 4.x numa aplicação de funções existente numa versão inferior, é solicitado a deixar o Visual Studio atualizar a aplicação de funções para a versão 4.x durante a implementaçã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 o separador que corresponda à sua versão alvo do .NET e ao modelo de processo desejado (processo em processo ou processo de trabalho isolado).

Gorjeta

Se estiver a migrar para uma versão LTS ou STS do .NET usando o modelo de trabalhador isolado, o Assistente de Atualização .NET pode ser usado para fazer automaticamente muitas das alterações mencionadas nas secções seguintes.

Ficheiro de Projeto

O exemplo seguinte é um ficheiro de projeto .csproj que utiliza .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; se, em vez disso, seu aplicativo usar 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 OutputType elemento ao PropertyGroup:

    <OutputType>Exe</OutputType>

  4. No .ItemGroup PackageReference list, substitua a referência do pacote para 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 quaisquer referências a outros pacotes nos espaços de nomes Microsoft.Azure.WebJobs.*. Você substituirá esses pacotes em uma etapa posterior.

  5. Adicionar 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 adotardes os pacotes de destino, precisareis atualizar o namespace das instruções using e alguns tipos aos quais fazeis 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 Cronómetro Adicionar
Microsoft.Azure. Functions.Worker.Extensions.Timer
Ligações de armazenamento Substituir
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
Ligações de blob Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
com a última versão do
Microsoft.Azure. Functions.Worker.Extensions.Storage.Blobs
Ligações de fila Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Ligações de tabelas Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.Tables
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.Tables
Vínculos 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
Fixações de 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 do Event Grid Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.EventGrid
com a última versão do
Microsoft.Azure. Functions.Worker.Extensions.EventGrid
Ligações SignalR Service Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.SignalRService
com a última versão do
Microsoft.Azure. Functions.Worker.Extensions.SignalRService
Durable Functions Substitua as referências a
Microsoft.Azure.WebJobs.Extensions.DurableTask
com a última versão do
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Durable Functions
(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
Durable Functions
(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
Ligações 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 dos pacotes que pretende utilizar.

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 Service Bus apresenta alterações significativas na estrutura entre as versões 4.x e 5.x. Para mais informações, consulte ligações do Azure Service Bus para Funções do Azure.

A sua aplicação de modelo de trabalhador isolado não deve referenciar nenhum pacote nos namespaces Microsoft.Azure.WebJobs.* ou Microsoft.Azure.Functions.Extensions. Se você tiver quaisquer referências restantes a estes, eles devem ser removidos.

Gorjeta

A tua aplicação também pode depender dos tipos de SDK do Azure, seja como parte dos teus triggers e bindings, seja como uma dependência autónoma. Você deve aproveitar esta oportunidade para atualizá-los também. As versões mais recentes das extensões Functions funcionam com as versões mais recentes do SDK do Azure para .NET, quase todos os pacotes para os quais são da forma Azure.*.

arquivo Program.cs

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 integração ASP.NET Core para melhorar o desempenho e fornecer um modelo de programação familiar quando a sua aplicação usa triggers HTTP. Se você não pretende usar gatilhos HTTP, pode substituir a chamada para ConfigureFunctionsWebApplication por uma chamada para ConfigureFunctionsWorkerDefaults. Se o fizeres, podes remover a referência a Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore do teu ficheiro de projeto. No entanto, para o melhor desempenho, mesmo para funções com outros tipos de gatilho, deve manter o FrameworkReference em o ASP.NET Core.

O arquivo Program.cs substitui qualquer arquivo que tenha o FunctionsStartup atributo, que normalmente é um arquivo Startup.cs . Em locais onde o seu FunctionsStartup código faria referência a IFunctionsHostBuilder.Services, pode adicionar instruções dentro do método .ConfigureServices() do HostBuilder no ficheiro Program.cs. Para saber mais sobre como trabalhar com Program.cs, consulte Inicialização e configuração no guia de modelo de trabalhador isolado.

Os exemplos de Program.cs padrão descritos anteriormente incluem a configuração do Application Insights. Em seu Program.cs, você também deve configurar qualquer filtragem de log que deve ser aplicada a logs provenientes de código em seu projeto. No modelo de trabalho isolado, o arquivo host.json controla 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, elas também se aplicam apenas ao código em seu projeto. A plataforma também necessita de configuração de ativadores e ligações, que deve ser fornecida através das funcionalidades de "definições de aplicação," "referências do Key Vault" ou "referências de configuração da aplicação."

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

arquivo local.settings.json

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

arquivo host.json

Não são necessárias alterações ao seu host.json ficheiro. No entanto, se a configuração do Application Insights neste ficheiro for proveniente do seu projeto em execução, poderá querer fazer outras alterações no ficheiro 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 Gestão de níveis de registo no modelo de trabalhador isolado para obter detalhes sobre como filtrar esses registos.

Alterações no nome da classe

Algumas classes chave mudaram de nome entre versões. Estas alterações resultam tanto de alterações nas APIs .NET como de diferenças entre processos em processo e processos de trabalhadores isolados. A tabela seguinte indica as principais classes .NET usadas pelas Funções que podem mudar 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 integração ASP.NET Core)
IActionResult HttpResponseData HttpResponseData, IActionResult (usando 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 nos nomes das classes 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 verificar Alterações significativas entre 3.x e 4.x para outras alterações que possa precisar fazer no seu projeto.

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar opções de serializador ou mudar para JSON.NET (Newtonsoft.Json), consulte Personalização da serialização JSON.

Estruturas de log e filtração no 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ê precisa configurar regras de filtragem como parte do seu Program.cs. Consulte Gestão de níveis de registo no modelo de trabalhador isolado para obter detalhes sobre como filtrar esses registos.

Modelo de acionador HTTP

As diferenças entre o processo em execução e o processo de trabalho isolado podem ser observadas 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 o seu projeto para Funções do Azure 4.x:

  1. Atualize a sua instalação local do Funções do Azure Core Tools para a versão 4.x.

  2. Atualize o pacote de extensões Funções do Azure da sua app para 2.x ou superior. Para obter mais informações, consulte alterações significativas.

  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 estiveres a usar Python 3.6, muda para uma das versões c0.

Execute o validador de pré-atualização

O Funções do Azure fornece um validador pré-atualização para ajudar a identificar potenciais problemas ao migrar a sua aplicação de funções para a 4.x. Para executar o validador de pré-atualização:

  1. No portal Azure, navegue até à sua aplicação de funções.

  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 precisares de fazer alterações à tua aplicação, certifica-te de validar as alterações com a versão 4.x do runtime das Funções, seja localmente usando Funções do Azure Core Tools v4 ou usando um slot de staging.

Atualize a sua aplicação de funções no Azure

Precisas de atualizar o tempo de execução do host da aplicação de funções no Azure para a versão 4.x antes de publicares o teu 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 forma mais simples de atualizar para a v4.x é definir a definição FUNCTIONS_EXTENSION_VERSION da aplicação para ~4 na tua aplicação de funções 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>

Também tens de definir outra definição, que difere entre Windows e Linux.

Ao correr no Windows, também é necessário ativar o .NET 8.0, que é exigido pela versão 4.x do runtime.

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

.NET 6 é necessário para aplicações de funções em qualquer linguagem a correr 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 implementação é uma boa maneira de atualizar a sua aplicação de função para o runtime v4.x de uma versão anterior. Usando um slot de preparação, pode executar a sua aplicação na nova versão do runtime no slot de preparação e alternar para 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 a sua aplicação de funções com slots ativados puder lidar com o tempo de inatividade de um rearranque completo, pode 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 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, o cmdlet do PowerShell Update-AzFunctionAppSetting não oferece suporte a slots. Deve usar o 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 modificar FUNCTIONS_EXTENSION_VERSION e atualizar o slot de preparação 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 runtime Functions requer .NET 6 no Windows. No Linux, as aplicações .NET também têm de ser atualizadas para .NET 6. Use o seguinte comando para que o runtime possa correr em .NET 6:

    Ao correr no Windows, também é necessário ativar o .NET 8.0, que é exigido pela versão 4.x do runtime.

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

    .NET 6 é necessário para aplicações de funções em qualquer linguagem a correr 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 necessitou atualizações para ser executado na versão 4.x, implemente essas atualizações no slot de teste 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 preparação atualizado para o ambiente de 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, pode trocar pela versão atualizada de um slot de preparação previamente 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 no ambiente de preparação durante o intervalo entre a troca e a restauração da versão de runtime nesse ambiente. 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. Utilize o seguinte comando para voltar a definir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 na ranhura 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 têm WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 definidos.

  4. Use o seguinte comando para modificar FUNCTIONS_EXTENSION_VERSION e atualizar o slot de preparação 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 runtime Functions requer .NET 6 no Windows. No Linux, as aplicações .NET também têm de ser atualizadas para .NET 6. Use o seguinte comando para que o runtime possa correr em .NET 6:

    Ao correr no Windows, também é necessário ativar o .NET 8.0, que é exigido pela versão 4.x do runtime.

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

    .NET 6 é necessário para aplicações de funções em qualquer linguagem a correr 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 necessitou atualizações para ser executado na versão 4.x, implemente essas atualizações no slot de teste 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 uma lista completa, veja Funções do Azure GitHub questões rotuladas Breaking Change: Aprovado.

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

Tempo de execução

  • Funções do Azure Proxies foi uma funcionalidade nas versões 1.x a 3.x do runtime Funções do Azure. Este recurso não é suportado na versão 4.x. Para mais informações, consulte Serverless REST APIs usando Funções do Azure.

  • O login em Armazenamento do Azure usando AzureWebJobsDashboard já não é suportado na versão 4.x. Em vez disso, você deve usar o Application Insights. (#1923)

  • Funções do Azure 4.x agora aplica 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 a versão 2.x ou posterior do bundle 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)

  • Funções do Azure 4.x utiliza Azure.Identity e Azure.Security.KeyVault.Secrets para o fornecedor Key Vault e descontinuou a utilização da Microsoft.Azure. KeyVault. Para mais informações sobre como configurar as definições da function app, consulte a opção Key Vault em Gerir armazenamento de chaves. (#2048)

  • As aplicações de funções que partilham contas de armazenamento agora não conseguem iniciar quando os seus IDs de host são os mesmos. Para obter mais informações, consulte Considerações sobre o ID do host. (#2049)

  • Funções do Azure 4.x suporta versões mais recentes do .NET. Consulte Linguagens suportadas em Funções do Azure para uma lista completa de versões.

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

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

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

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

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

  • Node.js versões 10 e 12 não são suportadas na Funções do Azure 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 Funções do Azure 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

  • Last updated on