Partilhar via

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

Importante

O Java não é suportado pela versão 1.x do tempo de execução do Azure Functions. Talvez você esteja procurando migrar seu aplicativo Java da versão 3.x para a versão 4.x. Se você estiver migrando um aplicativo de função da versão 1.x, selecione C# ou JavaScript acima.

Importante

O TypeScript não é suportado pela versão 1.x do tempo de execução do Azure Functions. Talvez você esteja procurando migrar seu aplicativo TypeScript da versão 3.x para a versão 4.x. Se você estiver migrando um aplicativo de função da versão 1.x, selecione C# ou JavaScript acima.

Importante

O PowerShell não é suportado pela versão 1.x do tempo de execução do Azure Functions. Talvez você esteja procurando migrar seu aplicativo PowerShell da versão 3.x para a versão 4.x. Se você estiver migrando um aplicativo de função da versão 1.x, selecione C# ou JavaScript acima.

Importante

Python não é suportado pela versão 1.x do tempo de execução do Azure Functions. Talvez você esteja procurando migrar seu aplicativo Python da versão 3.x para a versão 4.x. Se você estiver migrando um aplicativo de função da versão 1.x, selecione C# ou JavaScript acima.

Importante

O suporte terminará para a versão 1.x do tempo de execução do Azure Functions em 14 de setembro de 2026. É altamente recomendável que você migre seus aplicativos para a versão 4.x seguindo as instruções neste artigo.

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.

Se você estiver executando a versão 1.x do tempo de execução no Azure Stack Hub, consulte Considerações para o Azure Stack Hub primeiro.

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 a versão 1.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 '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

Escolha sua versão .NET de destino

Na versão 1.x do tempo de execução do Functions, seu aplicativo de função C# tem como alvo o .NET Framework.

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 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 processo2
.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, terminando com .NET 8. 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 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 O .NET 9 tinha anteriormente uma data de fim de suporte esperada para 12 de maio de 2026. Durante a janela de serviço do .NET 9, a equipe do .NET estendeu o suporte para versões do STS para 24 meses, começando com o .NET 9. Para obter mais informações, consulte a postagem do blog.

Gorjeta

A menos que seu aplicativo dependa de uma biblioteca ou API disponível apenas para o .NET Framework, recomendamos atualizar para o .NET 8 no modelo de trabalho isolado. Muitos aplicativos na versão 1.x destinam-se ao .NET Framework apenas porque era isso que estava disponível quando foram criados. Recursos adicionais estão disponíveis para versões mais recentes do .NET e, se seu aplicativo não for forçado a permanecer no .NET Framework devido a uma dependência, você deverá direcionar uma versão mais recente. O .NET 8 é a versão totalmente lançada com a janela de suporte mais longa do .NET.

Embora se possa optar por usar o modelo em execução, isto deve ser evitado, se possível. 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 10 (visualização) ou .NET 9. Se você precisar direcionar uma dessas versões, poderá adaptar os exemplos 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. Revise a lista de alterações de comportamento após a versão 1.x. A migração da versão 1.x para a versão 4.x também pode afetar as associações.
  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 das Ferramentas Principais do Azure Functions.
  4. Atualize seu aplicativo de função no Azure para a nova versão. Se precisar minimizar o tempo de inatividade, considere usar um slot de preparação para testar e verificar a sua aplicação migrada no Azure na nova versão de runtime. Em seguida, poderá implantar a sua aplicação com as definições de versão atualizadas no ambiente de produção. Para obter mais informações, consulte Atualização utilizando slots.
  5. 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 seções a seguir descrevem as atualizações que você deve fazer em seus arquivos de projeto C# para poder executar em uma das versões suportadas do .NET no Functions versão 4.x. As atualizações mostradas são comuns à maioria dos projetos. O código do seu projeto pode exigir atualizações não mencionadas neste artigo, especialmente ao usar pacotes NuGet personalizados.

A migração de um aplicativo de função C# da versão 1.x para a versão 4.x do tempo de execução do Functions exige que você faça alterações no código do projeto. Muitas dessas alterações são resultado de alterações na linguagem C# e nas APIs .NET.

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 .csproj projeto que é executado na versão 1.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </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.na lista PackageReference, substitua a referência do pacote 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 Microsoft.Azure.WebJobs.* namespaces. 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 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 instruções using 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 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
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
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
As ligações 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
Ligações 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
Ligações 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
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 do 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 ligações do Barramento de Serviço do Azure para Funções do Azure.

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 tiver quaisquer referências restantes a estes, deve removê-las.

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 últimas versões do SDK do Azure para .NET, sendo que quase todos os pacotes estão no formato Azure.*.

Os Hubs de Notificação e Aplicativos Móveis são suportados somente na versão 1.x do tempo de execução. Ao atualizar para a versão 4.x do tempo de execução, você precisa remover essas associações em favor de trabalhar com esses serviços diretamente usando seus SDKs.

Program.cs arquivo

Na maioria dos casos, a migração requer que você adicione 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 um melhor desempenho, mesmo para funções com outros tipos de gatilho, deve-se manter o FrameworkReference em ASP.NET Core.

O arquivo Program.cs substitui qualquer arquivo que tenha o FunctionsStartup atributo, que normalmente é um arquivo Startup.cs . 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.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 precisa de configuração dos acionadores e ligações, e isso deve ser fornecido por meio das configurações da aplicação, referências do Cofre de Chaves ou referências da Configuração do Aplicativo.

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 host.json

As configurações no arquivo host.json se aplicam no nível do aplicativo de função, tanto localmente quanto no Azure. Na versão 1.x, o arquivo host.json está vazio ou contém algumas configurações que se aplicam a todas as funções no aplicativo de função. Para obter mais informações, consulte Host.json v1. Se o arquivo host.json tiver valores de configuração, revise o formato host.json v2 para verificar se há alterações.

Para executar na versão 4.x, você deve adicionar "version": "2.0" ao arquivo host.json. Você também deve considerar adicionar logging à sua configuração, como nos seguintes exemplos:

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

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.

local.settings.json ficheiro

O arquivo local.settings.json só é usado quando executado localmente. Para obter informações, consulte Arquivo de configurações locais. Na versão 1.x, o arquivo local.settings.json tem apenas dois valores necessários:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "AzureWebJobsDashboard": "AzureWebJobsStorageConnectionStringValue"
    }
}

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 num processo de trabalho isolado, você precisa alterar o valor FUNCTIONS_WORKER_RUNTIME para "dotnet-isolated".

Alterações no nome da classe

Algumas classes de chave mudaram nomes entre a versão 1.x e a versão 4.x. Essas alterações são resultado de mudanças nas APIs do .NET ou de diferenças entre o processo de trabalho isolado e o processo em execução. A tabela a seguir indica as principais classes .NET usadas pelo Functions que podem ser alteradas durante a migração:

Versão 1.x .NET 8
FunctionName (atributo) Function (atributo)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (usando a integração de ASP.NET Core)
HttpResponseMessage HttpResponseData, IActionResult (usando a integração de ASP.NET Core)

Também pode haver diferenças nos nomes das classes em ligações. Para obter mais informações, consulte os artigos de referência para os vínculos específicos.

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 de comportamento após a versão 1.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 Personalizando a serialização JSON.

Níveis de log e filtragem do Application Insights

Os logs podem ser enviados para o Application Insights a partir do host de execução do Functions e do código no 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 Gerenciando níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

Modelo de acionador HTTP

A maioria das alterações de código entre a versão 1.x e a versão 4.x pode ser vista em funções acionadas por HTTP. O modelo de gatilho HTTP para a versão 1.x se parece com o exemplo a seguir:

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static async Task<HttpResponseMessage> 
            Run([HttpTrigger(AuthorizationLevel.AuthLevelValue, "get", "post", 
            Route = null)]HttpRequestMessage req, TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

Na versão 4.x, o modelo de gatilho HTTP 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 a sua instalação local das Ferramentas Core do Azure Functions para a versão 4.x.

  2. Mude para uma das versões Node.js suportadas na versão 4.x.

  3. Adicione ambos os elementos version e extensionBundle ao host.json, para que ele se pareça com o exemplo a seguir:

    {
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

    O extensionBundle elemento é necessário porque após a versão 1.x, as ligações são mantidas como pacotes externos. Para obter mais informações, consulte Pacotes de extensão.

  4. Atualize seu arquivo local.settings.json para que ele tenha pelo menos os seguintes elementos:

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    A AzureWebJobsStorage configuração pode ser o emulador de armazenamento Azurite ou uma conta de armazenamento real do Azure. Para obter mais informações, consulte Emulador de armazenamento local.

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 8.0, que é exigido pela versão 4.x do tempo de execução.

az functionapp config set --net-framework-version v8.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. Pode-se usar um slot de preparação para executar o seu aplicativo na nova versão de ambiente de execução nesse slot e transitar 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 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 8.0, que é exigido pela versão 4.x do tempo de execução.

    az functionapp config set --net-framework-version v8.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 que a sua aplicação de funções está a funcionar corretamente no ambiente de ensaio atualizado antes de proceder à troca.

  7. Use o seguinte comando para trocar o slot de preparação atualizado para 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, poderá trocar para a versão atualizada de um slot de preparação pré-configurado.

  1. Use o seguinte comando para configurar WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 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>

  2. Use os comandos a seguir para substituir o slot pela nova configuração na 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. Este erro pode ocorrer porque ter WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 apenas no ambiente de staging durante uma troca remove a configuração FUNCTIONS_EXTENSION_VERSION no ambiente de staging. Sem a configuração de versão, seu slot está em mau estado. Atualizar a versão no slot de ensaio logo após a troca deve colocar o slot de volta em um bom estado, e pode reverter as suas alterações, se necessário. No entanto, qualquer reversão da alteração também requer que o utilizador remova diretamente WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 do ambiente de produção antes de reverter a alteração para prevenir os mesmos erros no ambiente de produção que foram observados no ambiente de teste. Essa alteração na configuração de produção causaria uma reinicialização.

  3. Use o seguinte comando para voltar a definir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 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 definidos em WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0.

  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 8.0, que é exigido pela versão 4.x do tempo de execução.

    az functionapp config set --net-framework-version v8.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 que a sua aplicação de funções está a funcionar corretamente no ambiente de ensaio atualizado antes de proceder à troca.

  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 comportamento após a versão 1.x

Esta seção detalha as alterações feitas após a versão 1.x nos comportamentos de gatilho e ligação, bem como nos principais recursos e comportamentos das Funções.

Alterações nos gatilhos e ligações

A partir da versão 2.x, você deve instalar as extensões para gatilhos e associações específicos usados pelas funções em seu aplicativo. A única exceção são os gatilhos HTTP e de temporizador, que não requerem uma extensão. Para obter mais informações, consulte Registrar e instalar extensões de vinculação.

Há também algumas mudanças no function.json ou atributos da função entre as versões. Por exemplo, a propriedade do path Event Hubs agora é eventHubName. Consulte a tabela de vinculação existente para obter links para a documentação de cada ligação.

Alterações nos recursos e funcionalidades

Alguns recursos foram removidos, atualizados ou substituídos após a versão 1.x. Esta seção detalha as alterações que você vê em versões posteriores depois de ter usado a versão 1.x.

Na versão 2.x, foram feitas as seguintes alterações:

  • As chaves para chamar pontos de extremidade HTTP são sempre armazenadas criptografadas no armazenamento de Blob do Azure. Na versão 1.x, as chaves eram armazenadas nos Arquivos do Azure por padrão. Quando você migra um aplicativo da versão 1.x para a versão 2.x, os segredos existentes que estão nos Arquivos do Azure são redefinidos.

  • O runtime da versão 2.x não inclui suporte embutido para provedores de webhook. Esta alteração foi feita para melhorar o desempenho. Você ainda pode usar gatilhos HTTP como pontos de extremidade para webhooks.

  • Para melhorar o monitoramento, o painel WebJobs no portal, que usava a AzureWebJobsDashboard configuração, é substituído pelo Azure Application Insights, que usa a APPINSIGHTS_INSTRUMENTATIONKEY configuração. Para obter mais informações, consulte Monitorizar Azure Functions.

  • Todas as funções em um aplicativo de função devem compartilhar o mesmo idioma. Ao criar uma aplicação de funções, é necessário escolher um stack de runtime para a aplicação. A pilha de tempo de execução é especificada pelo valor FUNCTIONS_WORKER_RUNTIME nas configurações do aplicativo. Este requisito foi adicionado para melhorar a pegada ecológica e o tempo de inicialização. Ao desenvolver localmente, você também deve incluir essa configuração no arquivo local.settings.json.

  • O tempo limite padrão para funções em um plano do Serviço de Aplicativo é alterado para 30 minutos. Você pode alterar manualmente o tempo limite de volta para ilimitado usando a configuração functionTimeout no host.json.

  • As limitações de simultaneidade HTTP são implementadas por padrão para funções do plano de consumo, com um padrão de 100 solicitações simultâneas por instância. Você pode alterar esse comportamento na maxConcurrentRequests configuração no arquivo host.json.

  • Devido às limitações do .NET Core, o suporte para funções de script F# (.fsxarquivos) foi removido. As funções F# compiladas (.fs) ainda são suportadas.

  • O formato de URL dos webhooks de gatilho do Event Grid foi alterado para seguir este padrão: https://{app}/runtime/webhooks/{triggerName}.

  • Os nomes de algumas métricas personalizadas predefinidas foram alterados após a versão 1.x. Duration foi substituído por MaxDurationMs, MinDurationMse AvgDurationMs. Success Rate também foi renomeado para Success Rate.

Considerações para o Azure Stack Hub

O Serviço de Aplicativo no Azure Stack Hub não oferece suporte à versão 4.x do Azure Functions. Ao planejar uma migração da versão 1.x no Azure Stack Hub, você pode escolher uma das seguintes opções:

  • Migre para a versão 4.x hospedada no Azure Functions de nuvem pública usando as instruções neste artigo. Em vez de atualizar seu aplicativo existente, você criaria um novo aplicativo usando a versão 4.x e, em seguida, implantaria seu projeto modificado nele.
  • Mude para WebJobs alojados num plano de Serviço de Aplicações no Azure Stack Hub.

Próximos passos

Saiba mais sobre as versões do Functions

  • Last updated on