Apps migreren van Azure Functions versie 1.x naar versie 4.x

Bij deze stappen wordt uitgegaan van een lokaal C#-project; als uw app in plaats daarvan C#-script (.csx-bestanden ) gebruikt, moet u converteren naar het projectmodel voordat u doorgaat.

De volgende wijzigingen zijn vereist in het XML-projectbestand .csproj :

1. Stel de waarde van PropertyGroup. TargetFramework aan net8.0.

2. Stel de waarde van PropertyGroup. AzureFunctionsVersion aan v4.

3. Voeg het volgende OutputType element toe aan het PropertyGroup element:

   <OutputType>Exe</OutputType>
   

4. In de ItemGroup. PackageReference lijst, vervang de pakketverwijzing naar Microsoft.NET.Sdk.Functions door de volgende verwijzingen:

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

   Noteer eventuele verwijzingen naar andere pakketten in de Microsoft.Azure.WebJobs.* naamruimten. U vervangt deze pakketten in een latere stap.

5. Voeg de volgende nieuwe ItemGrouptoe:

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

Nadat u deze wijzigingen hebt aangebracht, ziet het bijgewerkte project eruit als in het volgende voorbeeld:

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

Bij deze stappen wordt uitgegaan van een lokaal C#-project; als uw app in plaats daarvan C#-script (.csx-bestanden ) gebruikt, moet u converteren naar het projectmodel voordat u doorgaat.

De volgende wijzigingen zijn vereist in het XML-projectbestand .csproj :

1. Stel de waarde van PropertyGroup. TargetFramework aan net48.

2. Stel de waarde van PropertyGroup. AzureFunctionsVersion aan v4.

3. Voeg het volgende OutputType element toe aan het PropertyGroup element:

   <OutputType>Exe</OutputType>
   

4. In de ItemGroup. PackageReference lijst, vervang de pakketverwijzing naar Microsoft.NET.Sdk.Functions door de volgende verwijzingen:

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

   Noteer eventuele verwijzingen naar andere pakketten in de Microsoft.Azure.WebJobs.* naamruimten. U vervangt deze pakketten in een latere stap.

5. Voeg de volgende nieuwe ItemGrouptoe:

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

Nadat u deze wijzigingen hebt aangebracht, ziet het bijgewerkte project eruit als in het volgende voorbeeld:

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

De volgende wijzigingen zijn vereist in het .csproj XML-projectbestand:

1. Stel de waarde van PropertyGroup. TargetFramework aan net8.0.

2. Stel de waarde van PropertyGroup. AzureFunctionsVersion aan v4.

3. Vervang de bestaande ItemGroup. PackageReference lijst met de volgende ItemGroup:

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

Nadat u deze wijzigingen hebt aangebracht, ziet het bijgewerkte project eruit als in het volgende voorbeeld:

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

Als u dat nog niet hebt gedaan, werkt u uw project bij om te verwijzen naar de nieuwste stabiele versies van:

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

Afhankelijk van de triggers en bindingen die uw app gebruikt, moet uw app mogelijk verwijzen naar een andere set pakketten. In de volgende tabel ziet u de vervangingen voor enkele van de meest gebruikte extensies:

Zie Ondersteunde bindingen voor een volledige lijst met extensies die u kunt overwegen en raadpleeg de documentatie van elke extensie voor volledige installatie-instructies voor het geïsoleerde procesmodel. Zorg ervoor dat u de nieuwste stabiele versie installeert van alle pakketten die u wilt gebruiken.

Uw geïsoleerde werkrolmodeltoepassing mag niet verwijzen naar pakketten in de Microsoft.Azure.WebJobs.*-naamruimten of Microsoft.Azure.Functions.Extensions. Als u nog verwijzingen naar deze referenties hebt, moeten ze worden verwijderd.

Als u dat nog niet hebt gedaan, werkt u uw project bij om te verwijzen naar de nieuwste stabiele versies van:

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

Afhankelijk van de triggers en bindingen die uw app gebruikt, moet uw app mogelijk verwijzen naar een andere set pakketten. In de volgende tabel ziet u de vervangingen voor enkele van de meest gebruikte extensies:

Zie Ondersteunde bindingen voor een volledige lijst met extensies die u kunt overwegen en raadpleeg de documentatie van elke extensie voor volledige installatie-instructies voor het geïsoleerde procesmodel. Zorg ervoor dat u de nieuwste stabiele versie installeert van alle pakketten die u wilt gebruiken.

Uw geïsoleerde werkrolmodeltoepassing mag niet verwijzen naar pakketten in de Microsoft.Azure.WebJobs.*-naamruimten of Microsoft.Azure.Functions.Extensions. Als u nog verwijzingen naar deze referenties hebt, moeten ze worden verwijderd.

Werk uw project bij om te verwijzen naar de nieuwste stabiele versie van Microsoft.NET. Sdk.Functions.

Afhankelijk van de triggers en bindingen die uw app gebruikt, moet uw app mogelijk verwijzen naar een extra set pakketten. Zie Ondersteunde bindingen voor een lijst met extensies die u kunt overwegen en raadpleeg de documentatie van elke extensie voor volledige installatie-instructies voor het procesmodel in proces. Zorg ervoor dat u de nieuwste stabiele versie installeert van alle pakketten die u wilt gebruiken.

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();

Dit voorbeeld omvat ASP.NET Core-integratie om de prestaties te verbeteren en een vertrouwd programmeermodel te bieden wanneer uw app HTTP-triggers gebruikt. Als u geen HTTP-triggers wilt gebruiken, kunt u de aanroep naar ConfigureFunctionsWebApplication vervangen door een aanroep naar ConfigureFunctionsWorkerDefaults. Als u dit doet, kunt u de verwijzing naar Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore uit het projectbestand verwijderen. Voor de beste prestaties, zelfs voor functies met andere triggertypen, moet u echter bij ASP.NET Core blijven voor de FrameworkReference.

Het bestand Program.cs vervangt elk bestand dat het FunctionsStartup kenmerk heeft. Dit is meestal een Startup.cs bestand. Op plaatsen waar uw FunctionsStartup code IFunctionsHostBuilder.Services zou verwijzen, kun je in plaats daarvan instructies toevoegen in de .ConfigureServices() methode van de HostBuilder in je Program.cs. Zie de handleiding voor het opstarten en configureren van het geïsoleerde werkmodel voor meer informatie over het werken met Program.cs.

De standaard Program.cs voorbeelden die eerder zijn beschreven, omvatten de installatie van Application Insights. In uw Program.cs moet u ook logboekfilters configureren die van toepassing moeten zijn op logboeken die afkomstig zijn van code in uw project. In het geïsoleerde werkrolmodel beheert het host.json bestand alleen gebeurtenissen die worden verzonden door de Functions-hostruntime. Als u geen filterregels configureert in Program.cs, ziet u mogelijk verschillen in de logboekniveaus die aanwezig zijn voor verschillende categorieën in uw telemetrie.

Hoewel u aangepaste configuratiebronnen kunt registreren als onderdeel van de HostBuilderconfiguratie, zijn deze ook alleen van toepassing op code in uw project. Het platform heeft ook trigger- en bindingsconfiguratie nodig. Dit moet worden opgegeven via de toepassingsinstellingen, Key Vault verwijzingen of App-configuratieverwijzingen functies.

Nadat u alles van een bestaand FunctionsStartup naar het Program.cs-bestand hebt verplaatst, kunt u het FunctionsStartup kenmerk en de klasse waarop het is toegepast, verwijderen.

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

Het bestand Program.cs vervangt elk bestand dat het FunctionsStartup kenmerk heeft. Dit is meestal een Startup.cs bestand. Op plaatsen waar uw FunctionsStartup code IFunctionsHostBuilder.Services zou verwijzen, kun je in plaats daarvan instructies toevoegen in de .ConfigureServices() methode van de HostBuilder in je Program.cs. Zie de handleiding voor het opstarten en configureren van het geïsoleerde werkmodel voor meer informatie over het werken met Program.cs.

De standaard Program.cs voorbeelden die eerder zijn beschreven, omvatten de installatie van Application Insights. In uw Program.cs moet u ook logboekfilters configureren die van toepassing moeten zijn op logboeken die afkomstig zijn van code in uw project. In het geïsoleerde werkrolmodel beheert het host.json bestand alleen gebeurtenissen die worden verzonden door de Functions-hostruntime. Als u geen filterregels configureert in Program.cs, ziet u mogelijk verschillen in de logboekniveaus die aanwezig zijn voor verschillende categorieën in uw telemetrie.

Hoewel u aangepaste configuratiebronnen kunt registreren als onderdeel van de HostBuilderconfiguratie, zijn deze ook alleen van toepassing op code in uw project. Het platform heeft ook trigger- en bindingsconfiguratie nodig. Dit moet worden opgegeven via de toepassingsinstellingen, Key Vault verwijzingen of App-configuratieverwijzingen functies.

Nadat u alles van een bestaand FunctionsStartup naar het Program.cs-bestand hebt verplaatst, kunt u het FunctionsStartup kenmerk en de klasse waarop het is toegepast, verwijderen.

Een program.cs-bestand is niet vereist bij het uitvoeren van het proces.

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

Het host.json bestand beheert alleen logging vanuit de Functions host runtime-omgeving. In het geïsoleerde werkermodel zijn sommige van deze logberichten rechtstreeks afkomstig van uw toepassing, wat u meer controle geeft. Zie Logboekniveaus beheren in het geïsoleerde werkrolmodel voor meer informatie over het filteren van deze logboeken.

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

Het host.json bestand beheert alleen logging vanuit de Functions host runtime-omgeving. In het geïsoleerde werkermodel zijn sommige van deze logberichten rechtstreeks afkomstig van uw toepassing, wat u meer controle geeft. Zie Logboekniveaus beheren in het geïsoleerde werkrolmodel voor meer informatie over het filteren van deze logboeken.

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

In deze sectie worden andere codewijzigingen gemarkeerd die u kunt overwegen tijdens het uitvoeren van de migratie. Deze wijzigingen zijn niet nodig voor alle toepassingen, maar u moet evalueren of deze relevant zijn voor uw scenario's. Controleer de gedragswijzigingen na versie 1.x op aanvullende wijzigingen die u mogelijk moet aanbrengen in uw project.

JSON-serialisatie

Het geïsoleerde werkrolmodel maakt standaard gebruik van System.Text.Json voor JSON-serialisatie. Zie JSON-serialisatie aanpassen om serialisatieopties aan te passen of om over te schakelen naar JSON.NET (Newtonsoft.Json).

De niveaus en filters van Application Insights-logboeken

Logboeken kunnen vanuit zowel de Functions-hostruntime als code in uw project naar Application Insights worden verzonden. Met dehost.json kunt u regels voor hostlogboekregistratie configureren, maar om logboeken te beheren die afkomstig zijn van uw code, moet u filterregels configureren als onderdeel van uw Program.cs. Zie Logboekniveaus beheren in het geïsoleerde werkrolmodel voor meer informatie over het filteren van deze logboeken.

Controleer de gedragswijzigingen na versie 1.x op aanvullende wijzigingen die u mogelijk moet aanbrengen in uw project.

In deze sectie worden andere codewijzigingen gemarkeerd die u kunt overwegen tijdens het uitvoeren van de migratie. Deze wijzigingen zijn niet nodig voor alle toepassingen, maar u moet evalueren of deze relevant zijn voor uw scenario's. Controleer de gedragswijzigingen na versie 1.x op aanvullende wijzigingen die u mogelijk moet aanbrengen in uw project.

JSON-serialisatie

Het geïsoleerde werkrolmodel maakt standaard gebruik van System.Text.Json voor JSON-serialisatie. Zie JSON-serialisatie aanpassen om serialisatieopties aan te passen of om over te schakelen naar JSON.NET (Newtonsoft.Json).

De niveaus en filters van Application Insights-logboeken

Logboeken kunnen vanuit zowel de Functions-hostruntime als code in uw project naar Application Insights worden verzonden. Met dehost.json kunt u regels voor hostlogboekregistratie configureren, maar om logboeken te beheren die afkomstig zijn van uw code, moet u filterregels configureren als onderdeel van uw Program.cs. Zie Logboekniveaus beheren in het geïsoleerde werkrolmodel voor meer informatie over het filteren van deze logboeken.

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

Wanneer u op Windows uitvoert, moet u ook .NET 8.0 inschakelen. Dit is vereist voor versie 4.x van de runtime.

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

.NET 6 is vereist voor functie-apps in elke taal die wordt uitgevoerd op Windows.

Wanneer u op Windows uitvoert, moet u ook .NET 8.0 inschakelen. Dit is vereist voor versie 4.x van de runtime.

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

.NET 6 is vereist voor functie-apps in elke taal die wordt uitgevoerd op Windows.

Wanneer u .NET-apps uitvoert op Linux, moet u ook de site-instelling linuxFxVersion bijwerken. Helaas kan Azure PowerShell momenteel niet worden gebruikt om de linuxFxVersion in te stellen. Gebruik in plaats daarvan de Azure CLI.