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

  • Artikel

Belangrijk

Java wordt niet ondersteund door versie 1.x van de Azure Functions-runtime. Misschien wilt u in plaats daarvan uw Java-app migreren van versie 3.x naar versie 4.x. Als u een functie-app van versie 1.x migreert, selecteert u C# of JavaScript hierboven.

Belangrijk

TypeScript wordt niet ondersteund door versie 1.x van de Azure Functions-runtime. Misschien wilt u in plaats daarvan uw TypeScript-app migreren van versie 3.x naar versie 4.x. Als u een functie-app van versie 1.x migreert, selecteert u C# of JavaScript hierboven.

Belangrijk

PowerShell wordt niet ondersteund door versie 1.x van de Azure Functions-runtime. Misschien wilt u in plaats daarvan uw PowerShell-app migreren van versie 3.x naar versie 4.x. Als u een functie-app van versie 1.x migreert, selecteert u C# of JavaScript hierboven.

Belangrijk

Python wordt niet ondersteund door versie 1.x van de Azure Functions-runtime. Misschien wilt u in plaats daarvan uw Python-app migreren van versie 3.x naar versie 4.x. Als u een functie-app van versie 1.x migreert, selecteert u C# of JavaScript hierboven.

Belangrijk

De ondersteuning wordt beëindigd voor versie 1.x van de Azure Functions-runtime op 14 september 2026. We raden u ten zeerste aan uw apps te migreren naar versie 4.x door de instructies in dit artikel te volgen.

In dit artikel wordt uitgelegd hoe u uw functie-app veilig kunt migreren om uit te voeren op versie 4.x van de Functions-runtime. Omdat de instructies voor projectmigratie afhankelijk zijn van taal, moet u uw ontwikkeltaal kiezen in de selector bovenaan het artikel.

Als u versie 1.x van de runtime in Azure Stack Hub uitvoert, raadpleegt u eerst Overwegingen voor Azure Stack Hub .

Functie-apps identificeren die moeten worden gemigreerd

Gebruik het volgende PowerShell-script om een lijst met functie-apps te genereren in uw abonnement die momenteel gericht zijn op versie 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

Kies uw .NET-doelversie

Op versie 1.x van de Functions-runtime is uw C#-functie-app gericht op .NET Framework.

Wanneer u uw functie-app migreert, hebt u de mogelijkheid om de doelversie van .NET te kiezen. U kunt uw C#-project bijwerken naar een van de volgende versies van .NET die worden ondersteund door Functions versie 4.x:

.NET-versie Releasetype voor .NET Official Support Policy Functions-procesmodel1,3
.NET 82 LTS Geïsoleerde werkrolmodel
.NET 7 STS (einde van ondersteuning 14 mei 2024) Geïsoleerde werkrolmodel
.NET 6 LTS (einde van ondersteuning 12 november 2024) Geïsoleerde werkrolmodel,
In-process model3
.NET Framework 4.8 Beleid weergeven Geïsoleerde werkrolmodel

1 Het geïsoleerde werkrolmodel ondersteunt LTS-versies (Long Term Support) en STS-versies (Standard Term Support) van .NET, evenals .NET Framework. Het in-process model ondersteunt alleen LTS-releases van .NET. Zie Verschillen tussen proces- en isoleerproces .NET Azure Functions voor een volledige functie en functionaliteitsvergelijking tussen de twee modellen.

2 .NET 8 wordt nog niet ondersteund in het procesmodel, hoewel deze beschikbaar is in het geïsoleerde werkrolmodel. Zie het bericht Azure Functions Roadmap Update voor meer informatie over .NET 8-abonnementen, inclusief toekomstige opties voor het in-process model.

3 Ondersteuning eindigt op 10 november 2026 voor het in-procesmodel. Zie deze ondersteuningsaankondiging voor meer informatie. Voor continue volledige ondersteuning moet u uw apps migreren naar het geïsoleerde werkrolmodel.

Tip

Tenzij uw app afhankelijk is van een bibliotheek of API die alleen beschikbaar is voor .NET Framework, raden we u aan bij te werken naar .NET 8 op het geïsoleerde werkrolmodel. Veel apps op versie 1.x-doel .NET Framework zijn alleen beschikbaar omdat dat is wat beschikbaar was toen ze werden gemaakt. Er zijn extra mogelijkheden beschikbaar voor recentere versies van .NET. Als uw app niet wordt gedwongen om op .NET Framework te blijven vanwege een afhankelijkheid, moet u zich richten op een recentere versie. .NET 8 is de volledig uitgebrachte versie met het langste ondersteuningsvenster van .NET.

Hoewel u ervoor kunt kiezen om in plaats daarvan het in-procesmodel te gebruiken, wordt dit niet aanbevolen als dit kan worden vermeden. De ondersteuning voor het in-procesmodel eindigt op 10 november 2026, dus u moet eerst naar het geïsoleerde werkrolmodel gaan. Als u dit doet terwijl u migreert naar versie 4.x, neemt de totale inspanning af en biedt het geïsoleerde werkrolmodel uw app extra voordelen, waaronder de mogelijkheid om zich gemakkelijker te richten op toekomstige versies van .NET. Als u overstapt op het geïsoleerde werkrolmodel, kan de .NET-upgradeassistent ook veel van de benodigde codewijzigingen voor u afhandelen.

Deze handleiding bevat geen specifieke voorbeelden voor .NET 7 of .NET 6 op het geïsoleerde werkrolmodel. Als u deze versies wilt toepassen, kunt u de voorbeelden van het geïsoleerde werkrolmodel van .NET 8 aanpassen.

Voorbereiden op migratie

Als u dat nog niet hebt gedaan, identificeert u de lijst met apps die moeten worden gemigreerd in uw huidige Azure-abonnement met behulp van Azure PowerShell.

Voordat u een app migreert naar versie 4.x van de Functions-runtime, moet u de volgende taken uitvoeren:

  1. Bekijk de lijst met gedragswijzigingen na versie 1.x. Migreren van versie 1.x naar versie 4.x kan ook van invloed zijn op bindingen.
  2. Voer de stappen uit in Uw lokale project migreren om uw lokale project te migreren naar versie 4.x.
  3. Nadat u uw project hebt gemigreerd, test u de app volledig lokaal met versie 4.x van de Azure Functions Core Tools.
  4. Werk uw functie-app in Azure bij naar de nieuwe versie. Als u downtime wilt minimaliseren, kunt u overwegen om een staging-site te gebruiken om uw gemigreerde app in Azure te testen en te controleren op de nieuwe runtimeversie. Vervolgens kunt u uw app implementeren met de bijgewerkte versie-instellingen naar de productiesite. Zie Update met behulp van sites voor meer informatie.
  5. Publiceer uw gemigreerde project naar de bijgewerkte functie-app.

Wanneer u Visual Studio gebruikt om een versie 4.x-project te publiceren naar een bestaande functie-app met een lagere versie, wordt u gevraagd om Visual Studio de functie-app tijdens de implementatie bij te werken naar versie 4.x. Deze update maakt gebruik van hetzelfde proces dat is gedefinieerd in Update zonder sleuven.

Uw lokale project migreren

In de volgende secties worden de updates beschreven die u moet aanbrengen in uw C#-projectbestanden om te kunnen worden uitgevoerd op een van de ondersteunde versies van .NET in Functions versie 4.x. De weergegeven updates zijn gebruikelijk voor de meeste projecten. Uw projectcode kan updates vereisen die niet in dit artikel worden vermeld, met name wanneer u aangepaste NuGet-pakketten gebruikt.

Als u een C#-functie-app migreert van versie 1.x naar versie 4.x van de Functions-runtime, moet u wijzigingen aanbrengen in uw projectcode. Veel van deze wijzigingen zijn het gevolg van wijzigingen in de C#-taal en .NET-API's.

Kies het tabblad dat overeenkomt met uw doelversie van .NET en het gewenste procesmodel (in-process of geïsoleerd werkproces).

Tip

Als u overstapt op een LTS- of STS-versie van .NET met behulp van het geïsoleerde werkrolmodel, kan de .NET-upgradeassistent worden gebruikt om automatisch veel van de wijzigingen in de volgende secties aan te brengen.

Projectbestand

Het volgende voorbeeld is een .csproj projectbestand dat wordt uitgevoerd op versie 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>

Gebruik een van de volgende procedures om dit XML-bestand bij te werken voor uitvoering in Functions versie 4.x:

Bij deze stappen wordt uitgegaan van een lokaal C#-project en 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 .csproj XML-projectbestand:

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

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

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

    <OutputType>Exe</OutputType>

  4. In de ItemGroup.PackageReference vervang de pakketverwijzing door Microsoft.NET.Sdk.Functions 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>

Wijzigingen in pakket- en naamruimte

Op basis van het model waarnaar u migreert, moet u de pakketten waarnaar u migreert mogelijk bijwerken of wijzigen. Wanneer u de doelpakketten gebruikt, moet u vervolgens de naamruimte bijwerken van het gebruik van instructies en enkele typen waarnaar u verwijst. U kunt het effect van deze naamruimtewijzigingen zien op using instructies in de voorbeelden van http-triggersjablonen verderop in dit artikel.

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

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:

Scenario Wijzigingen in pakketverwijzingen
Timertrigger Toevoegen
Microsoft.Azure.Functions.Worker.Extensions.Timer
Storage-bindingen Replace
Microsoft.Azure.WebJobs.Extensions.Storage
wordt uitgevoerd met
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues en
Microsoft.Azure.Functions.Worker.Extensions.Tables
Blob-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Wachtrijbindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Tabelbindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.Tables
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.Tables
Cosmos DB-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.CosmosDB
Of
Microsoft.Azure.WebJobs.Extensions.DocumentDB
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Service Bus-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.ServiceBus
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Event Hubs-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.EventHubs
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Event Grid-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.EventGrid
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
SignalR Service-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.SignalRService
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Durable Functions Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.DurableTask
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Durable Functions
(SQL Storage-provider)		 Verwijzingen vervangen naar
Microsoft.DurableTask.SqlServer.AzureFunctions
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Durable Functions
(Netherite-opslagprovider)		 Verwijzingen vervangen naar
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
SendGrid-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.SendGrid
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Kafka-bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.Kafka
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.Kafka
RabbitMQ bindingen Verwijzingen vervangen naar
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
met de nieuwste versie van
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Afhankelijkheidsinjectie
en opstartconfiguratie		 Verwijzingen verwijderen naar
Microsoft.Azure.Functions.Extensions
(Het geïsoleerde werkrolmodel biedt deze functionaliteit standaard.)

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.

Tip

Voor eventuele wijzigingen in extensieversies tijdens dit proces moet u het host.json bestand mogelijk ook bijwerken. Lees de documentatie van elke extensie die u gebruikt. De Service Bus-extensie heeft bijvoorbeeld belangrijke wijzigingen in de structuur tussen versie 4.x en 5.x. Zie Azure Service Bus-bindingen voor Azure Functions voor meer informatie.

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.

Tip

Uw app kan ook afhankelijk zijn van Azure SDK-typen, hetzij als onderdeel van uw triggers en bindingen of als zelfstandige afhankelijkheid. U kunt deze ook bijwerken. De nieuwste versies van de Functions-extensies werken met de nieuwste versies van de Azure SDK voor .NET, bijna alle pakketten waarvoor het formulier Azure.*is.

De Notification Hubs - en Mobile Apps-bindingen worden alleen ondersteund in versie 1.x van de runtime. Wanneer u een upgrade uitvoert naar versie 4.x van de runtime, moet u deze bindingen verwijderen ten gunste van het rechtstreeks werken met deze services met behulp van hun SDK's.

bestand Program.cs

In de meeste gevallen moet u voor het migreren het volgende program.cs-bestand toevoegen aan uw project:

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 vervangen door ConfigureFunctionsWebApplication een aanroep naar ConfigureFunctionsWorkerDefaults. Als u dit doet, kunt u de verwijzing Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore uit het projectbestand verwijderen. Voor de beste prestaties, zelfs voor functies met andere triggertypen, moet u echter de FrameworkReference to-ASP.NET Core behouden.

Het Program.cs bestand vervangt elk bestand dat het FunctionsStartup kenmerk heeft. Dit is meestal een Startup.cs bestand. Op plaatsen waarnaar uw FunctionsStartup code zou verwijzen IFunctionsHostBuilder.Services, kunt u in plaats daarvan instructies toevoegen binnen de .ConfigureServices() methode van de in uw HostBuilderProgram.cs. Voor meer informatie over het werken met Program.cs, raadpleegt u Opstart- en configuratiehandleiding in de handleiding voor geïsoleerde werkrollen.

De bovenstaande standaardvoorbeelden Program.cs omvatten het instellen van Application Insights-integratie voor het geïsoleerde werkrolmodel. Program.csU moet 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 Program.csconfigureert, 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, moet u er rekening mee houden dat deze op dezelfde manier van toepassing zijn op code in uw project. De trigger- en bindingsconfiguratie is ook nodig voor het platform. Dit moet worden opgegeven via de functies voor toepassingsinstellingen, Key Vault-verwijzingen of App Configuration-verwijzingen .

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.

host.json bestand

Instellingen in het bestand host.json gelden op het niveau van de functie-app, zowel lokaal als in Azure. In versie 1.x is uw host.json bestand leeg of bevat het enkele instellingen die van toepassing zijn op alle functies in de functie-app. Zie Host.json v1 voor meer informatie. Als uw host.json bestand waarden heeft ingesteld, controleert u de host.json v2-indeling op eventuele wijzigingen.

Als u wilt uitvoeren op versie 4.x, moet u toevoegen "version": "2.0" aan het host.json-bestand. U moet ook overwegen om aan uw configuratie toe te voegen logging , zoals in de volgende voorbeelden:

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

Het host.json bestand beheert alleen logboekregistratie van de Functions-hostruntime en in het geïsoleerde werkrolmodel zijn sommige van deze logboeken rechtstreeks afkomstig van uw toepassing, zodat u meer controle hebt. Zie Logboekniveaus beheren in het geïsoleerde werkrolmodel voor meer informatie over het filteren van deze logboeken.

local.settings.json-bestand

Het local.settings.json-bestand wordt alleen gebruikt wanneer het lokaal wordt uitgevoerd. Zie het bestand Met lokale instellingen voor meer informatie. In versie 1.x heeft het bestand local.settings.json slechts twee vereiste waarden:

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

Wanneer u migreert naar versie 4.x, moet u ervoor zorgen dat uw local.settings.json bestand ten minste de volgende elementen bevat:

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

Notitie

Wanneer u migreert van in-proces naar uitvoering in een geïsoleerd werkproces, moet u de FUNCTIONS_WORKER_RUNTIME waarde wijzigen in 'dotnet-isolated'.

Wijzigingen in klassenaam

Sommige sleutelklassen hebben namen gewijzigd tussen versie 1.x en versie 4.x. Deze wijzigingen zijn het gevolg van wijzigingen in .NET-API's of in verschillen tussen het proces en het geïsoleerde werkproces. De volgende tabel geeft de belangrijkste .NET-klassen aan die worden gebruikt door Functions die kunnen worden gewijzigd tijdens de migratie:

Versie 1.x .NET 8
FunctionName (kenmerk) Function (kenmerk)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (met ASP.NET Core-integratie)
HttpResponseMessage HttpResponseData, IActionResult (met ASP.NET Core-integratie)

Er zijn mogelijk ook verschillen in klassenamen in bindingen. Zie de naslagartikelen voor de specifieke bindingen voor meer informatie.

Andere codewijzigingen

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

Standaard wordt het geïsoleerde werkrolmodel gebruikt System.Text.Json voor JSON-serialisatie. Als u serialisatieopties wilt aanpassen of wilt overschakelen naar JSON.NET (Newtonsoft.Json), raadpleegt u deze instructies.

Application Insights-logboekniveaus en -filters

Logboeken kunnen vanuit zowel de Functions-hostruntime als code in uw project naar Application Insights worden verzonden. Hiermee host.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.

HTTP-triggersjabloon

De meeste codewijzigingen tussen versie 1.x en versie 4.x zijn te zien in door HTTP geactiveerde functies. De HTTP-triggersjabloon voor versie 1.x ziet er als volgt uit:

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

In versie 4.x ziet de HTTP-triggersjabloon eruit als in het volgende voorbeeld:

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"]}!");
        }
    }
}

Uw project bijwerken naar Azure Functions 4.x:

  1. Werk uw lokale installatie van Azure Functions Core Tools bij naar versie 4.x.

  2. Ga naar een van de Node.js versies die worden ondersteund op versie 4.x.

  3. Voeg zowel als versionextensionBundle elementen toe aan het host.json, zodat deze eruitziet als in het volgende voorbeeld:

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

    Het extensionBundle element is vereist omdat bindingen na versie 1.x worden onderhouden als externe pakketten. Zie Uitbreidingsbundels voor meer informatie.

  4. Werk uw local.settings.json-bestand zo bij dat het ten minste de volgende elementen bevat:

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

    De AzureWebJobsStorage instelling kan de Azurite-opslagemulator of een werkelijk Azure-opslagaccount zijn. Zie Lokale opslagemulator voor meer informatie.

Uw functie-app bijwerken in Azure

U moet de runtime van de host van de functie-app in Azure bijwerken naar versie 4.x voordat u het gemigreerde project publiceert. De runtimeversie die door de Functions-host wordt gebruikt, wordt beheerd door de FUNCTIONS_EXTENSION_VERSION toepassingsinstelling, maar in sommige gevallen moeten andere instellingen ook worden bijgewerkt. Voor zowel codewijzigingen als wijzigingen in toepassingsinstellingen moet uw functie-app opnieuw worden opgestart.

De eenvoudigste manier is om zonder sites bij te werken en vervolgens uw app-project opnieuw te publiceren. U kunt ook de downtime in uw app minimaliseren en terugdraaien vereenvoudigen door het bijwerken met behulp van sites.

Bijwerken zonder sites

De eenvoudigste manier om bij te werken naar v4.x is door de FUNCTIONS_EXTENSION_VERSION toepassingsinstelling ~4 in te stellen op uw functie-app in Azure. U moet een andere procedure volgen op een site met sites.

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

U moet ook een andere instelling instellen, die verschilt tussen Windows en Linux.

Wanneer u windows gebruikt, moet u ook .NET 6.0 inschakelen. Dit is vereist voor versie 4.x van de runtime.

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

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

Vervang in dit voorbeeld door <APP_NAME> de naam van uw functie-app en <RESOURCE_GROUP_NAME> door de naam van de resourcegroep.

U kunt uw app-project dat is gemigreerd, nu opnieuw publiceren om te worden uitgevoerd op versie 4.x.

Bijwerken met behulp van sites

Het gebruik van implementatiesites is een goede manier om uw functie-app bij te werken naar de v4.x-runtime van een vorige versie. Met behulp van een staging-site kunt u uw app uitvoeren op de nieuwe runtimeversie in de staging-site en na verificatie overschakelen naar productie. Sites bieden ook een manier om downtime tijdens de update te minimaliseren. Als u downtime wilt minimaliseren, volgt u de stappen in Minimale downtime-update.

Nadat u uw app in de bijgewerkte site hebt geverifieerd, kunt u de app en de nieuwe versie-instellingen in productie wisselen. Voor deze wissel is instelling WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 in de productiesite vereist. Hoe u deze instelling toevoegt, is van invloed op de hoeveelheid downtime die nodig is voor de update.

Standard-update

Als uw functie-app met sleuf de downtime van een volledig opnieuw opstarten kan afhandelen, kunt u de WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS instelling rechtstreeks in de productiesite bijwerken. Omdat het rechtstreeks wijzigen van deze instelling in de productiesite een herstart veroorzaakt die van invloed is op de beschikbaarheid, kunt u overwegen deze wijziging uit te voeren op een moment van minder verkeer. U kunt vervolgens wisselen in de bijgewerkte versie van de staging-site.

De Update-AzFunctionAppSetting PowerShell-cmdlet biedt momenteel geen ondersteuning voor sites. U moet Azure CLI of Azure Portal gebruiken.

  1. Gebruik de volgende opdracht om in de productiesite in te stellen WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 :

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    Vervang in dit voorbeeld door <APP_NAME> de naam van uw functie-app en <RESOURCE_GROUP_NAME> door de naam van de resourcegroep. Met deze opdracht wordt de app die in de productiesite wordt uitgevoerd, opnieuw gestart.

  2. Gebruik de volgende opdracht om ook in de staging-site in te stellen WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS :

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. Gebruik de volgende opdracht om de staging-site te wijzigen FUNCTIONS_EXTENSION_VERSION en bij te werken naar de nieuwe runtimeversie:

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

  4. Voor versie 4.x van de Functions-runtime is .NET 6 in Windows vereist. In Linux moeten .NET-apps ook worden bijgewerkt naar .NET 6. Gebruik de volgende opdracht zodat de runtime kan worden uitgevoerd op .NET 6:

    Wanneer u windows gebruikt, moet u ook .NET 6.0 inschakelen. Dit is vereist voor versie 4.x van de runtime.

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

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

    Vervang in dit voorbeeld door <APP_NAME> de naam van uw functie-app en <RESOURCE_GROUP_NAME> door de naam van de resourcegroep.

  5. Als voor uw codeproject updates zijn vereist om te worden uitgevoerd op versie 4.x, implementeert u deze updates nu in de staging-site.

  6. Controleer of uw functie-app correct wordt uitgevoerd in de bijgewerkte faseringsomgeving voordat u wisselt.

  7. Gebruik de volgende opdracht om de bijgewerkte staging-site om te wisselen naar productie:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Minimale downtime-update

Als u de downtime in uw productie-app wilt minimaliseren, kunt u de WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS instelling van de staging-site omzetten in productie. Daarna kunt u wisselen in de bijgewerkte versie van een vooraf inwarmende staging-site.

  1. Gebruik de volgende opdracht om in de staging-site in te stellen WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 :

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  2. Gebruik de volgende opdrachten om de site om te wisselen met de nieuwe instelling in productie en herstel tegelijkertijd de versie-instelling in de staging-site.

    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>

    Mogelijk ziet u fouten van de staging-site tijdens de tijd tussen de wissel en de runtimeversie die wordt hersteld tijdens fasering. Deze fout kan optreden omdat tijdens WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 het wisselen alleen fasering de FUNCTIONS_EXTENSION_VERSION instelling in fasering verwijdert. Zonder de versie-instelling heeft uw site een slechte status. Als u de versie in de staging-site direct na de wissel bijwerkt, wordt de site weer in een goede staat geplaatst en wordt u de wijzigingen teruggedraaid, indien nodig. Voor elke terugdraaibewerking van de swap moet u echter ook rechtstreeks uit de productie verwijderen WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 voordat de wissel teruggaat om te voorkomen dat dezelfde fouten in de productie in de fasering worden gezien. Deze wijziging in de productie-instelling veroorzaakt dan opnieuw opstarten.

  3. Gebruik de volgende opdracht om opnieuw in te stellen WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 in de staging-site:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    Op dit moment zijn WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 beide sleuven ingesteld.

  4. Gebruik de volgende opdracht om de staging-site te wijzigen FUNCTIONS_EXTENSION_VERSION en bij te werken naar de nieuwe runtimeversie:

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

  5. Voor versie 4.x van de Functions-runtime is .NET 6 in Windows vereist. In Linux moeten .NET-apps ook worden bijgewerkt naar .NET 6. Gebruik de volgende opdracht zodat de runtime kan worden uitgevoerd op .NET 6:

    Wanneer u windows gebruikt, moet u ook .NET 6.0 inschakelen. Dit is vereist voor versie 4.x van de runtime.

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

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

    Vervang in dit voorbeeld door <APP_NAME> de naam van uw functie-app en <RESOURCE_GROUP_NAME> door de naam van de resourcegroep.

  6. Als voor uw codeproject updates zijn vereist om te worden uitgevoerd op versie 4.x, implementeert u deze updates nu in de staging-site.

  7. Controleer of uw functie-app correct wordt uitgevoerd in de bijgewerkte faseringsomgeving voordat u wisselt.

  8. Gebruik de volgende opdracht om de bijgewerkte en voorverwarmde staging-site om te wisselen naar productie:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Gedrag wordt gewijzigd na versie 1.x

In deze sectie worden wijzigingen beschreven die zijn aangebracht na versie 1.x in zowel trigger- als bindingsgedrag, evenals in kernfuncties en -gedrag.

Wijzigingen in triggers en bindingen

Vanaf versie 2.x moet u de extensies installeren voor specifieke triggers en bindingen die worden gebruikt door de functies in uw app. De enige uitzondering voor deze HTTP- en timertriggers, waarvoor geen extensie is vereist. Zie Bindingsextensies registreren en installeren voor meer informatie.

Er zijn ook enkele wijzigingen in de function.json of kenmerken van de functie tussen versies. De eigenschap Event Hubs path is nu bijvoorbeeld.eventHubName Zie de bestaande bindingstabel voor koppelingen naar documentatie voor elke binding.

Wijzigingen in functies en functionaliteit

Enkele functies zijn verwijderd, bijgewerkt of vervangen na versie 1.x. In deze sectie worden de wijzigingen in latere versies beschreven nadat u versie 1.x hebt gebruikt.

In versie 2.x zijn de volgende wijzigingen aangebracht:

  • Sleutels voor het aanroepen van HTTP-eindpunten worden altijd versleuteld opgeslagen in Azure Blob Storage. In versie 1.x zijn sleutels standaard opgeslagen in Azure Files. Wanneer u een app migreert van versie 1.x naar versie 2.x, worden bestaande geheimen die zich in Azure Files bevinden, opnieuw ingesteld.

  • De runtime van versie 2.x bevat geen ingebouwde ondersteuning voor webhookproviders. Deze wijziging is aangebracht om de prestaties te verbeteren. U kunt nog steeds HTTP-triggers gebruiken als eindpunten voor webhooks.

  • Om de bewaking te verbeteren, wordt het WebJobs-dashboard in de portal, dat de AzureWebJobsDashboard instelling heeft gebruikt, vervangen door Azure-toepassing Insights, die gebruikmaakt van de APPINSIGHTS_INSTRUMENTATIONKEY instelling. Zie Monitor Azure Functions (Azure Functions bewaken) voor meer informatie.

  • Alle functies in een functie-app moeten dezelfde taal delen. Wanneer u een functie-app maakt, moet u een runtimestack voor de app kiezen. De runtimestack wordt opgegeven door de FUNCTIONS_WORKER_RUNTIME waarde in toepassingsinstellingen. Deze vereiste is toegevoegd om de footprint en opstarttijd te verbeteren. Wanneer u lokaal ontwikkelt, moet u deze instelling ook opnemen in het local.settings.json-bestand.

  • De standaardtime-out voor functies in een App Service-plan wordt gewijzigd in 30 minuten. U kunt de time-out handmatig wijzigen in onbeperkt met behulp van de instelling functionTimeout in host.json.

  • HTTP-gelijktijdigheidsbeperkingen worden standaard geïmplementeerd voor verbruiksabonnementsfuncties, met een standaardwaarde van 100 gelijktijdige aanvragen per exemplaar. U kunt dit gedrag wijzigen in de maxConcurrentRequests instelling in het host.json-bestand.

  • Vanwege .NET Core-beperkingen is ondersteuning voor F#-scriptfuncties (.fsxbestanden) verwijderd. Gecompileerde F#-functies (.fs) worden nog steeds ondersteund.

  • De URL-indeling van event grid-triggerwebhooks is gewijzigd om dit patroon te volgen: https://{app}/runtime/webhooks/{triggerName}

  • De namen van enkele vooraf gedefinieerde aangepaste metrische gegevens zijn gewijzigd na versie 1.x. Duration is vervangen door MaxDurationMs, MinDurationMsen AvgDurationMs. Success Rate is ook gewijzigd in Success Rate.

Overwegingen voor Azure Stack Hub

App Service in Azure Stack Hub biedt geen ondersteuning voor versie 4.x van Azure Functions. Wanneer u een migratie van versie 1.x in Azure Stack Hub plant, kunt u een van de volgende opties kiezen:

  • Migreren naar versie 4.x die wordt gehost in openbare cloud Azure Functions met behulp van de instructies in dit artikel. In plaats van uw bestaande app te upgraden, maakt u een nieuwe app met versie 4.x en implementeert u vervolgens het gewijzigde project.
  • Schakel over naar WebJobs die worden gehost in een App Service-plan in Azure Stack Hub.

Volgende stappen

Meer informatie over Functions-versies