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

Essas etapas pressupõem um projeto em C# local; se seu aplicativo, em vez disso, usa o script C# (arquivos .csx ), você deve converter no modelo de projeto antes de continuar.

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

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

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

3. Adicione o seguinte elemento OutputType ao PropertyGroup:

   <OutputType>Exe</OutputType>
   

4. No ItemGroup. PackageReference lista, 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 todas as referências a outros pacotes nos namespaces Microsoft.Azure.WebJobs.*. Você substituirá esses pacotes em uma etapa posterior.

5. Adicione o novo ItemGroup a seguir:

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

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

Essas etapas pressupõem um projeto em C# local; se seu aplicativo, em vez disso, usa o script C# (arquivos .csx ), você deve converter no modelo de projeto antes de continuar.

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

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

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

3. Adicione o seguinte elemento OutputType ao PropertyGroup:

   <OutputType>Exe</OutputType>
   

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

     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
     <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
   

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

5. Adicione o novo ItemGroup a seguir:

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

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
      <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
      <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Folder Include="Properties\" />
  </ItemGroup>
</Project>

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

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

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

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

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

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

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

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

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

Confira as Associações com suporte para obter uma lista completa das extensões a serem consideradas, e confira a documentação de cada extensão para obter as instruções completas de instalação para o modelo de processo isolado. Certifique-se de instalar a versão estável mais recente de quaisquer pacotes que você estiver focando.

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

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

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

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

Confira as Associações com suporte para obter uma lista completa das extensões a serem consideradas, e confira a documentação de cada extensão para obter as instruções completas de instalação para o modelo de processo isolado. Certifique-se de instalar a versão estável mais recente de quaisquer pacotes que você estiver focando.

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

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

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

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 ASP.NET Core integração 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, pode substituir a chamada a ConfigureFunctionsWebApplication por uma chamada a ConfigureFunctionsWorkerDefaults. Se você fizer isso, poderá remover a referência a Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore do arquivo de projeto. No entanto, para obter o melhor desempenho, mesmo para funções com outros tipos de gatilho, você deve manter o FrameworkReference para 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 a IFunctionsHostBuilder.Services, você pode adicionar instruções dentro do método .ConfigureServices() 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 trabalho isolado.

Os exemplos de Program.cs padrão descritos anteriormente incluem a instalação do Application Insights. Em seu Program.cs, você 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 host.json controla apenas os eventos emitidos pelo runtime do host do Functions. Se você não configurar regras de filtragem em 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 da HostBuilder, elas se aplicam somente ao código em seu projeto. A plataforma também precisa de configuração de disparador e vínculo, e isso deve ser fornecido por meio das configurações do aplicativo, referências do Key Vault ou referências de App Configuration.

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.

using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;

namespace Company.FunctionApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .ConfigureServices(services => {
                    services.AddApplicationInsightsTelemetryWorkerService();
                    services.ConfigureFunctionsApplicationInsights();
                })
                .Build();
            host.Run();
        }
    }
}

O arquivo Program.cs substitui qualquer arquivo que tenha o FunctionsStartup atributo, que normalmente é um arquivo Startup.cs . Em locais onde seu FunctionsStartup código faria referência a IFunctionsHostBuilder.Services, você pode adicionar instruções dentro do método .ConfigureServices() 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 trabalho isolado.

Os exemplos de Program.cs padrão descritos anteriormente incluem a instalação do Application Insights. Em seu Program.cs, você 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 host.json controla apenas os eventos emitidos pelo runtime do host do Functions. Se você não configurar regras de filtragem em 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 da HostBuilder, elas se aplicam somente ao código em seu projeto. A plataforma também precisa de configuração de disparo e vinculação, e isso deve ser fornecido por meio das configurações do aplicativo, referências do Key Vault ou referências do App Configuration.

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.

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

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

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

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

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

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

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

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

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "FUNCTIONS_INPROC_NET8_ENABLED": "1"
    }
}

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

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar 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 ao Application Insights tanto do runtime do host das Funções quanto do código em seu projeto. O host.json permite que você configure regras para log do host, mas para controlar os logs provenientes do seu código, você precisa configurar regras de filtragem como parte do Program.cs. Confira Gerenciamento de níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

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

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

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar opções de 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 ao Application Insights do runtime do host do Functions e do código em seu projeto. O host.json permite que você configure regras para log do host, mas para controlar os logs provenientes do seu código, você precisa configurar regras de filtragem como parte do Program.cs. Confira Gerenciamento de níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequestData req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

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

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

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

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

Ao executar no Windows, você também precisa habilitar .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 aplicativos de funções em qualquer idioma em execução no Windows.

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

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

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

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