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

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

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

1. Defina o valor de PropertyGroup.TargetFramework 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 .ItemGroupPackageReference substitua a referência do pacote pelas Microsoft.NET.Sdk.Functions seguintes referências:

     <FrameworkReference Include="Microsoft.AspNetCore.App" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
     <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
   

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

5. Aditar o seguinte novo ItemGroup:

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

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

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

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

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

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

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

3. Adicione o seguinte OutputType elemento ao PropertyGroup:

   <OutputType>Exe</OutputType>
   

4. No .ItemGroupPackageReference substitua a referência do pacote pelas Microsoft.NET.Sdk.Functions seguintes referências:

     <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 quaisquer referências a outros pacotes nos Microsoft.Azure.WebJobs.* namespaces. Você substituirá esses pacotes em uma etapa posterior.

5. Aditar o seguinte novo ItemGroup:

   <ItemGroup>
     <Folder Include="Properties\" />
   </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>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 .csproj projeto XML:

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

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

3. Substitua o arquivo ItemGroup.PackageReference lista com o seguinte ItemGroup:

   <ItemGroup>
     <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
   </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>
  </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>

Se ainda não o fez, atualize o seu projeto para fazer referência às 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 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:

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.

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

Se ainda não o fez, atualize o seu projeto para fazer referência às 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 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:

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.

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

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, seu aplicativo pode precisar fazer referência a um conjunto adicional de pacotes. Consulte Ligações suportadas para obter uma lista 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 em processo. Certifique-se de instalar a versão estável mais recente de todos os pacotes que você está segmentando.

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

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

host.Run();

Este exemplo inclui a integração ASP.NET Core para melhorar o desempenho e fornecer um modelo de programação familiar quando seu aplicativo usa gatilhos HTTP. Se você não pretende usar gatilhos HTTP, você pode substituir a chamada para ConfigureFunctionsWebApplication por uma chamada para ConfigureFunctionsWorkerDefaults. Se você fizer isso, você pode remover a referência a Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore do seu arquivo de projeto. No entanto, para o melhor desempenho, mesmo para funções com outros tipos de gatilho, você deve manter o FrameworkReference ASP.NET Core.

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

Os exemplos padrão Program.cs acima incluem a configuração da integração do Application Insights para o modelo de trabalho isolado. No , Program.csvocê também deve configurar qualquer filtragem de log que deve ser aplicada a logs provenientes do código em seu projeto. No modelo de trabalho isolado, o arquivo controla host.json apenas os eventos emitidos pelo tempo de execução do host Functions. Se você não configurar regras de filtragem no Program.cs, poderá ver diferenças nos níveis de log presentes para várias categorias em sua telemetria.

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

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

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 Program.cs arquivo substituirá qualquer arquivo que tenha o FunctionsStartup atributo, que normalmente é um Startup.cs arquivo. Em locais onde seu FunctionsStartup código faria referência IFunctionsHostBuilder.Services, você pode, em vez disso, adicionar instruções dentro do .ConfigureServices() método do HostBuilder em seu Program.cs. Para saber mais sobre como trabalhar com Program.cso , consulte Inicialização e configuração no guia de modelo de trabalhador isolado.

Os exemplos padrão Program.cs acima incluem a configuração da integração do Application Insights para o modelo de trabalho isolado. No , Program.csvocê também deve configurar qualquer filtragem de log que deve ser aplicada a logs provenientes do código em seu projeto. No modelo de trabalho isolado, o arquivo controla host.json apenas os eventos emitidos pelo tempo de execução do host Functions. Se você não configurar regras de filtragem no Program.cs, poderá ver diferenças nos níveis de log presentes para várias categorias em sua telemetria.

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

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

Um Program.cs arquivo não é necessário quando você está usando o modelo em processo.

{
    "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"
    }
}

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

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

Não são necessárias alterações ao seu host.json ficheiro.

Esta seção destaca outras alterações de código a serem consideradas ao trabalhar na migração. Essas alterações não são necessárias para todos os aplicativos, mas você deve avaliar se alguma é relevante para seus cenários. Certifique-se de marcar Alterações significativas entre 3.x e 4.x para alterações adicionais que você pode precisar fazer em seu projeto.

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar as opções do serializador ou alternar para JSON.NET (Newtonsoft.Json), consulte estas instruções.

Níveis de log e filtragem do Application Insights

Os logs podem ser enviados para o Application Insights a partir do tempo de execução do host do Functions e do código em seu projeto. O host.json permite que você configure regras para registro em log do host, mas para controlar logs provenientes do seu código, você precisará configurar regras de filtragem como parte do seu Program.cs. Consulte Gerenciando níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

Esta seção destaca outras alterações de código a serem consideradas ao trabalhar na migração. Essas alterações não são necessárias para todos os aplicativos, mas você deve avaliar se alguma é relevante para seus cenários. Certifique-se de marcar Alterações significativas entre 3.x e 4.x para alterações adicionais que você pode precisar fazer em seu projeto.

Serialização JSON

Por padrão, o modelo de trabalho isolado usa System.Text.Json para serialização JSON. Para personalizar as opções do serializador ou alternar para JSON.NET (Newtonsoft.Json), consulte estas instruções.

Níveis de log e filtragem do Application Insights

Os logs podem ser enviados para o Application Insights a partir do tempo de execução do host do Functions e do código em seu projeto. O host.json permite que você configure regras para registro em log do host, mas para controlar logs provenientes do seu código, você precisará configurar regras de filtragem como parte do seu Program.cs. Consulte Gerenciando níveis de log no modelo de trabalho isolado para obter detalhes sobre como filtrar esses logs.

Certifique-se de marcar Alterações significativas entre 3.x e 4.x para alterações adicionais que você pode precisar fazer em seu projeto.

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

Sames como versão 3.x (em processo).