Migrieren von Apps von Azure Functions Version 3.x zu Version 4.x

  • Artikel

Die Azure Functions-Version 4.x bietet eine hohe Abwärtskompatibilität mit der Version 3.x. Bei den meisten Apps sollte eine Migration zu Version 4.x ohne erhebliche Codeänderungen problemlos möglich sein. Weitere Informationen zu den Functions-Runtimeversionen finden Sie unter Übersicht über die Runtimeversionen von Azure Functions.

Wichtig

Seit dem 13. Dezember 2022 haben Funktions-Apps, die in den Versionen 2.x und 3.x der Azure Functions-Runtime ausgeführt werden, das Ende des erweiterten Supports erreicht. Weitere Informationen finden Sie unter Eingestellte Versionen.

Dieser Artikel führt Sie durch den Prozess der sicheren Migration Ihrer Funktions-App zur Ausführung mit Version 4.x der Functions-Runtime. Da Projektmigrationsanweisungen sprachabhängig sind, stellen Sie sicher, dass Sie Ihre Entwicklungssprache über den Selektor oben im Artikel auswählen.

Identifizieren zu migrierender Funktions-Apps

Verwenden Sie das folgende PowerShell-Skript, um eine Liste von Funktions-Apps in Ihrem Abonnement zu generieren, die derzeit auf die Versionen 2.x oder 3.x ausgerichtet sind:

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

$AppInfo

Auswählen der .NET-Zielversion

Bei Version 3.x der Functions-Runtime hat Ihre C#-Functions-App als Zielversion .NET Core 3.1 unter Verwendung des In-Process-Modells bzw. .NET 5 unter Verwendung des isolierten Workermodells.

Wenn Sie Ihre Funktions-App migrieren, haben Sie die Möglichkeit, die Zielversion von .NET auszuwählen. Sie können Ihr C#-Projekt auf eine der folgenden Versionen von .NET aktualisieren, die von der Functions-Version 4.x unterstützt werden:

.NET-Version Releasetyp der offiziellen .NET-Supportrichtlinie Functions-Prozessmodell1,3
.NET 82 LTS Isoliertes Workermodell
.NET 7 STS (Ende des Supports 14. Mai 2024) Isoliertes Workermodell
.NET 6 LTS (Ende des Supports am 12. November 2024) Isoliertes Workermodell,
In-Process-Modell3
.NET Framework 4.8 Siehe Richtlinie Isoliertes Workermodell

1 Das isolierte Workermodell unterstützt die Versionen LTS (Long Term Support) und STS (Standard Term Support) von .NET sowie .NET Framework. Das In-Process-Modell unterstützt nur LTS-Releases von .NET. Einen umfassenden Feature- und Funktionsvergleich zwischen den beiden Modellen finden Sie unter Unterschiede zwischen einem In-Process- und einem isolierten Workerprozess in .NET-Azure Functions.

2 .NET 8 wird für das In-Process-Modell noch nicht unterstützt, obwohl es im isolierten Workermodell verfügbar ist. Informationen zu .NET 8-Plänen, einschließlich zukünftiger Optionen für das In-Process-Modell, finden Sie im Beitrag mit dem Update zur Azure Functions-Roadmap.

3 Die Unterstützung für das In-Process-Modell endet am 10. November 2026. Weitere Informationen finden Sie in dieser Supportankündigung. Um weiterhin uneingeschränkten Support zu erhalten, müssen Sie Ihre Apps zum Modell mit isolierten Workern migrieren.

Tipp

Es wird empfohlen, für das Modell mit isolierten Workern ein Update auf .NET 8 durchzuführen. .NET 8 ist die vollständig veröffentlichte Version mit dem längsten Supportfenster von .NET.

Obwohl Sie sich dafür entscheiden können, stattdessen das In-Process-Modell zu verwenden, wird dies nicht empfohlen, sofern es vermieden werden kann. Der Support für das In-Process-Modell endet am 10. November 2026, sodass Sie vorher zum Modell mit isolierten Workern wechseln sollten. Auf diese Weise verringert sich der bei der Migration zu Version 4.x erforderliche Aufwand. Außerdem bietet das Modell mit isolierten Workern Ihrer App zusätzliche Vorteile, einschließlich der Möglichkeit, zukünftige Versionen von .NET einfacher als Ziel zu nutzen. Wenn Sie auf das Modell mit isolierten Workern umstellen, kann der .NET-Upgrade-Assistent auch viele der erforderlichen Codeänderungen für Sie durchführen.

In diesem Leitfaden werden keine spezifischen Beispiele für .NET 7 oder .NET 6 für das isolierte Workermodell vorgestellt. Wenn Sie diese Versionen als Ziel verwenden müssen, können Sie die .NET 8-Beispiele für isolierte Workermodelle anpassen.

Vorbereiten der Migration

Sofern noch nicht geschehen, ermitteln Sie mithilfe von Azure PowerShell die Liste der Apps, die in Ihrem aktuellen Azure-Abonnement migriert werden müssen.

Bevor Sie eine App zu Version 4.x der Functions-Runtime migrieren, sollten Sie die folgenden Aufgaben ausführen:

  1. Überprüfen Sie die Liste der Breaking Changes zwischen 3.x und 4.x.
  2. Führen Sie die Schritte unter Migrieren Ihres lokalen Projekts aus, um Ihr lokales Projekt zu Version 4.x zu migrieren.
  3. Nachdem Sie Ihr Projekt migriert haben, testen Sie die App vollständig lokal mit Version 4.x der Azure Functions Core Tools.
  4. Führen Sie das Vorupgrade-Validierungssteuerelement für die in Azure gehostete App aus, und beheben Sie alle identifizierten Probleme.
  5. Aktualisieren Sie Ihre Funktions-App in Azure auf die neue Version. Wenn Sie Downtime minimieren müssen, sollten Sie die Verwendung eines Stagingslots in Betracht ziehen, um Ihre migrierte App in Azure mit der neuen Runtimeversion zu testen und zu überprüfen. Anschließend können Sie Ihre App mit den aktualisierten Versionseinstellungen für den Produktionsslot bereitstellen. Weitere Informationen finden Sie unter Aktualisieren mit Slots.
  6. Veröffentlichen Sie Ihr migriertes Projekt in der aktualisierten Funktions-App.

Wenn Sie Visual Studio verwenden, um ein Version 4.x-Projekt in einer vorhandenen Funktions-App in einer niedrigeren Version zu veröffentlichen, werden Sie aufgefordert, Visual Studio das Update der Funktions-App auf Version 4.x während der Bereitstellung zu ermöglichen. Dieses Update verwendet denselben Prozess, der in Aktualisieren ohne Slots definiert ist.

Migrieren Ihres lokalen Projekts

Upgradeanweisungen können sprachabhängig sein. Wenn Ihre Sprache nicht angezeigt wird, wählen Sie sie oben im Artikel aus.

Wählen Sie die Registerkarte aus, die Ihrer Zielversion von .NET und dem gewünschten Prozessmodell (prozessinterner oder isolierter Workerprozess) entspricht.

Tipp

Wenn Sie mit dem isolierten Workermodell zu einer LTS- oder STS-Version von .NET wechseln, kann der .NET-Upgrade-Assistent verwendet werden, um viele der in den folgenden Abschnitten beschriebenen Änderungen automatisch durchzuführen.

Projektdatei

Das folgende Beispiel ist eine .csproj-Projektdatei, die .NET Core 3.1 in Version 3.x verwendet:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="3.0.13" />
  </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>

Verwenden Sie eines der folgenden Verfahren, um diese XML-Datei so zu aktualisieren, dass sie in Functions-Version 4.x ausgeführt wird:

Für diese Schritte wird ein lokales C#-Projekt vorausgesetzt. Wenn Ihre App stattdessen ein C#-Skript (.csx-Dateien) verwendet, sollten Sie zum Projektmodell wechseln, bevor Sie fortfahren.

Folgende Änderungen sind in der .csproj-XML-Projektdatei erforderlich:

  1. Legen Sie den Wert von PropertyGroup fest:TargetFramework in net8.0.

  2. Legen Sie den Wert von PropertyGroup fest:AzureFunctionsVersion in v4.

  3. Fügen Sie dem das folgende OutputType-Element PropertyGroup hinzu:

    <OutputType>Exe</OutputType>

  4. Ersetzen Sie in der Liste ItemGroup.PackageReference den Paketverweis durch Microsoft.NET.Sdk.Functions mit den folgenden Verweisen:

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

    Notieren Sie sich alle Verweise auf andere Pakete in den Microsoft.Azure.WebJobs.*-Namespaces. Sie ersetzen diese Pakete in einem späteren Schritt.

  5. Fügen Sie die folgende neue ItemGroup hinzu:

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

Nachdem Sie diese Änderungen vorgenommen haben, sollte Ihr aktualisiertes Projekt wie das folgende Beispiel aussehen:

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

Paket- und Namespaceänderungen

Abhängig von dem Modell, zu dem Sie migrieren, müssen Sie ggf. die Pakete aktualisieren oder ändern, auf die Ihre Anwendung verweist. Wenn Sie die Zielpakete übernehmen, müssen Sie möglicherweise den Namespace von using-Anweisungen und einigen Typen aktualisieren, auf die Sie verweisen. Sie können die Auswirkungen dieser Namespaceänderungen in using-Anweisungen in den Beispielen für HTTP-Triggervorlagen weiter unten in diesem Artikel erkennen.

Falls noch nicht geschehen, aktualisieren Sie Ihr Projekt, um auf die neuesten stabilen Versionen der folgenden Komponenten zu verweisen:

Abhängig von den Triggern und Bindungen, die Ihre App verwendet, muss Ihre App möglicherweise auf andere Pakete verweisen. In der folgenden Tabelle sind die Ersetzungen für einige der am häufigsten verwendeten Erweiterungen aufgeführt:

Szenario Änderungen an Paketverweisen
Trigger mit Timer Hinzufügen
Microsoft.Azure.Functions.Worker.Extensions.Timer
Speicherbindungen Ersetzen von
Microsoft.Azure.WebJobs.Extensions.Storage
durch
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues und
Microsoft.Azure.Functions.Worker.Extensions.Tables
Blobbindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Warteschlangenbindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Tabellenbindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.Tables
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.Tables
Cosmos DB-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.CosmosDB
und/oder
Microsoft.Azure.WebJobs.Extensions.DocumentDB
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Service Bus-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.ServiceBus
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Event Hubs-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.EventHubs
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Event Grid-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.EventGrid
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
SignalR Service-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.SignalRService
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Langlebige Funktionen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.DurableTask
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Langlebige Funktionen
(SQL-Speicheranbieter)		 Ersetzen Sie Verweise auf
Microsoft.DurableTask.SqlServer.AzureFunctions
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Langlebige Funktionen
(Netherite-Speicheranbieter)		 Ersetzen Sie Verweise auf
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
SendGrid-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.SendGrid
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Kafka-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.Kafka
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.Kafka
RabbitMQ-Bindungen Ersetzen Sie Verweise auf
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
durch die neueste Version von
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Abhängigkeitsinjektion
und Startkonfiguration		 Entfernen Sie Verweise auf
Microsoft.Azure.Functions.Extensions
(Das isolierte Workermodell stellt diese Funktionalität standardmäßig bereit.)

Eine vollständige Liste der zu berücksichtigenden Erweiterungen finden Sie unter Unterstützte Bindungen, und vollständige Installationsanweisungen für das isolierte Prozessmodell finden Sie in der Dokumentation der jeweiligen Erweiterung. Stellen Sie sicher, dass Sie die neueste stabile Version aller Pakete installieren, die Sie als Ziel verwenden.

Tipp

Alle Änderungen an Erweiterungsversionen während dieses Vorgangs erfordern möglicherweise, dass Sie auch Ihre host.json-Datei aktualisieren. Lesen Sie unbedingt die Dokumentation der einzelnen Erweiterungen, die Sie verwenden. Bei der Service Bus-Erweiterung gibt es beispielsweise Änderungen an der Struktur zwischen den Versionen 4.x und 5.x. Weitere Informationen finden Sie unter Azure Service Bus-Bindungen für Azure Functions.

Ihre isolierte Workermodellanwendung darf auf keine Pakete in den Microsoft.Azure.WebJobs.*-Namespaces oder in Microsoft.Azure.Functions.Extensions verweisen. Wenn noch Verweise auf diese vorhanden sind, sollten Sie sie entfernen.

Tipp

Ihre App kann auch von Azure SDK-Typen abhängig sein, entweder als Teil Ihrer Trigger und Bindungen oder als eigenständige Abhängigkeit. Sie sollten die Gelegenheit nutzen, um auch diese zu aktualisieren. Die neuesten Versionen der Functions-Erweiterungen können mit den neuesten Versionen des Azure SDK für .NET verwendet werden, wobei fast alle Pakete in der Form Azure.* vorliegen.

Datei „program.cs“

Bei der Migration zur Ausführung in einem isolierten Workerprozess müssen Sie ihrem Projekt die folgende Datei „program.cs“ hinzufügen:

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

Dieses Beispiel umfasst ASP.NET Core-Integration, um die Leistung zu verbessern und ein vertrautes Programmiermodell bereitzustellen, wenn Ihre App HTTP-Trigger verwendet. Wenn Sie nicht beabsichtigen, HTTP-Trigger zu verwenden, können Sie den Aufruf von ConfigureFunctionsWebApplication durch einen Aufruf von ConfigureFunctionsWorkerDefaults ersetzen. In diesem Fall können Sie den Verweis auf Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore aus der Projektdatei entfernen. Um jedoch die beste Leistung zu erzielen, sollten Sie auch für Funktionen mit anderen Triggertypen für FrameworkReference ASP.NET Core beibehalten.

Die Program.cs-Datei ersetzt jede Datei, die das FunctionsStartup-Attribut aufweist, was in der Regel eine Startup.cs-Datei ist. An Stellen, an denen Ihr FunctionsStartup-Code IFunctionsHostBuilder.Services referenzieren würde, können Sie stattdessen Anweisungen innerhalb der .ConfigureServices()-Methode der HostBuilder in Ihrem Program.cs hinzufügen. Weitere Informationen zum Arbeiten mit Program.cs finden Sie unter Start und Konfiguration im Handbuch für isolierte Arbeitsmodelle.

Die oben genannten Standardbeispiele für Program.cs umfassen das Einrichten der Application Insights-Integration für das Modell mit isolierten Workern. Sie müssen in Ihrer Datei Program.cs auch alle Protokollfilter konfigurieren, die auf Protokolle angewandt werden sollen, die aus Code in Ihrem Projekt stammen. Im Modell mit isolierten Workern steuert die Datei host.json nur Ereignisse, die von der Functions-Hostruntime ausgegeben werden. Wenn Sie in Program.cs keine Filterregeln konfigurieren, treten möglicherweise Unterschiede auf den Protokollebenen für verschiedene Kategorien in Ihren Telemetriedaten auf.

Sie können zwar benutzerdefinierte Konfigurationsquellen als Teil von HostBuilder registrieren, sollten dabei aber beachten, dass diese ebenfalls nur für Code in Ihrem Projekt gelten. Eine Trigger- und Bindungskonfiguration wird ebenfalls für die Plattform benötigt. Sie wird über die Anwendungseinstellungen, Key Vault-Verweise oder App Configuration-Verweisfeatures bereitgestellt.

Nachdem Sie alles aus einer vorhandenen FunctionsStartup- zu einer Program.cs-Datei verschoben haben, können Sie das FunctionsStartup-Attribut und die Klasse löschen, auf die es angewendet wurde.

Datei „local.settings.json“

Die Datei „local.settings.json“ wird nur bei lokaler Ausführung verwendet. Weitere Informationen finden Sie unter Datei für lokale Einstellungen.

Stellen Sie bei der Migration zu Version 4.x sicher, dass Ihre Datei „local.settings.json“ mindestens die folgenden Elemente enthält:

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

Hinweis

Wenn Sie von der prozessinternen Ausführung zur Ausführung in einem isolierten Workerprozess migrieren, müssen Sie den FUNCTIONS_WORKER_RUNTIME-Wert in „dotnet-isolated“ ändern.

Datei „host.json“

In Ihrer Datei host.json sind keine Änderungen erforderlich. Wenn Ihre Application Insights-Konfiguration in dieser Datei jedoch von Ihrem Projekt mit In-Process-Modell stammt, sollten Sie zusätzliche Änderungen an Ihrer Datei Program.cs vornehmen. Die Datei host.json steuert nur die Protokollierung der Functions-Hostruntime, und im Modell mit isolierten Workern stammen einige dieser Protokolle direkt aus Ihrer Anwendung, sodass Sie mehr Kontrolle erhalten. Ausführliche Informationen zum Filtern dieser Protokolle finden Sie unter Verwalten von Protokollebenen im Modell mit isolierten Workern.

Änderungen von Klassennamen

Für einige wichtigen Klassen wurden die Namen zwischen den Versionen geändert. Diese Änderungen sind das Ergebnis von Änderungen in .NET-APIs oder von Unterschieden zwischen prozessinternen und isolierten Workerprozess. In der folgenden Tabelle werden die wichtigsten .NET-Klassen aufgeführt, die von Functions verwendet werden und sich bei der Migration ändern können:

.NET Core 3.1 .NET 5 .NET 8
FunctionName (Attribut) Function (Attribut) Function (Attribut)
ILogger ILogger ILogger, ILogger<T>
HttpRequest HttpRequestData HttpRequestData, HttpRequest (unter Verwendung der ASP.NET Core-Integration)
IActionResult HttpResponseData HttpResponseData, IActionResult (unter Verwendung der ASP.NET Core-Integration)
FunctionsStartup (Attribut) Verwendet stattdessen Program.cs Verwendet stattdessen Program.cs

Es kann auch Unterschiede bei Klassennamen in Bindungen geben. Weitere Informationen finden Sie im Referenzartikel für die jeweilige Bindung.

Weitere Codeänderungen

In diesem Abschnitt werden weitere Codeänderungen genannt, die während der Migration berücksichtigt werden müssen. Diese Änderungen werden nicht bei allen Anwendungen benötigt, vielmehr müssen Sie selbst einschätzen, ob sie für Ihre Szenarien relevant sind. Überprüfen Sie unbedingt die Breaking Changes zwischen 3.x und 4.x auf weitere Änderungen, die Sie möglicherweise an Ihrem Projekt vornehmen müssen.

JSON-Serialisierung

Standardmäßig wird im Modell mit isolierten Workern für die JSON-Serialisierung System.Text.Json verwendet. Informationen zum Anpassen von Serialisierungsoptionen oder zum Umstellen auf JSON.NET (Newtonsoft.Json) finden Sie in diesen Anweisungen.

Application Insights: Protokollebenen und -filterung

Protokolle können sowohl von der Functions-Hostrumtime als auch von Code in Ihrem Projekt an Application Insights gesendet werden. In der Datei host.json können Sie Regeln für die Hostprotokollierung konfigurieren, aber um Protokolle über Ihren Code zu steuern, müssen Sie Filterregeln in Ihre Datei Program.cs einfügen. Ausführliche Informationen zum Filtern dieser Protokolle finden Sie unter Verwalten von Protokollebenen im Modell mit isolierten Workern.

HTTP-Triggervorlage

Die Unterschiede zwischen prozessinternen und isolierten Workerprozessen können in durch HTTP ausgelösten Funktionen beobachtet werden. Die HTTP-Triggervorlage für Version 3.x (prozessintern) sieht wie im folgenden Beispiel aus:

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

Die HTTP-Triggervorlage für die migrierte Version sieht wie im folgenden Beispiel aus:

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

So aktualisieren Sie Ihr Projekt auf Azure Functions 4.x:

  1. Aktualisieren Sie Ihre lokale Installation der Azure Functions Core Tools auf Version 4.x.

  2. Aktualisieren Sie das Azure Functions-Erweiterungenbundle Ihrer App auf 2.x oder höher. Weitere Informationen finden Sie unter Breaking Changes.

  1. Wechseln Sie bei Bedarf zu einer der Java-Versionen, die in Version 4.x unterstützt werden.

  2. Aktualisieren Sie die Datei POM.xml der App so, dass die Einstellung FUNCTIONS_EXTENSION_VERSION in ~4 geändert wird, wie im folgenden Beispiel gezeigt:

    <configuration>
    <resourceGroup>${functionResourceGroup}</resourceGroup>
    <appName>${functionAppName}</appName>
    <region>${functionAppRegion}</region>
    <appSettings>
        <property>
            <name>WEBSITE_RUN_FROM_PACKAGE</name>
            <value>1</value>
        </property>
        <property>
            <name>FUNCTIONS_EXTENSION_VERSION</name>
            <value>~4</value>
        </property>
    </appSettings>
</configuration>
  1. Wechseln Sie bei Bedarf zu einer der Node.js-Versionen, die in Version 4.x unterstützt werden.
  1. Nutzen Sie diese Gelegenheit, um ein Upgrade auf PowerShell 7.2 durchzuführen, das empfohlen wird. Weitere Informationen finden Sie unter PowerShell-Versionen.
  1. Wenn Sie Python 3.6 verwenden, wechseln Sie zu einer der unterstützten Versionen.

Ausführen des Vorupgrade-Validierungssteuerelements

Azure Functions bietet ein Vorupgrade-Validierungssteuerelement, um potenzielle Probleme beim Migrieren der Funktions-App auf 4.x zu erkennen. So führen Sie das Vorupgrade-Validierungssteuerelement aus:

  1. Navigieren Sie im Azure-Portal zu Ihrer Funktions-App.

  2. Öffnen Sie die Seite Diagnose und Problembehandlung.

  3. Beginnen Sie in der Funktions-App-Diagnose mit der Eingabe von Functions 4.x Pre-Upgrade Validator, und wählen Sie es dann aus der Liste aus.

  4. Überprüfen Sie nach Abschluss der Überprüfung die Empfehlungen, und behandeln Sie alle Probleme in Ihrer App. Wenn Sie Änderungen an Ihrer App vornehmen müssen, überprüfen Sie die Änderungen anhand der Version 4.x der Functions-Runtime, entweder lokal mithilfe der Azure Functions Core Tools v4 oder mithilfe eines Stagingslots.

Aktualisieren Ihrer Funktions-App in Azure

Sie müssen die Runtime des Funktions-App-Hosts in Azure auf Version 4.x aktualisieren, bevor Sie Ihr migriertes Projekt veröffentlichen. Die vom Functions-Host verwendete Runtimeversion wird von der FUNCTIONS_EXTENSION_VERSION-Anwendungseinstellung gesteuert, aber in einigen Fällen müssen auch andere Einstellungen aktualisiert werden. Sowohl Codeänderungen als auch Änderungen an Anwendungseinstellungen erfordern einen Neustart Ihrer Funktions-App.

Die einfachste Möglichkeit besteht darin, ein Update ohne Slots durchzuführen und Ihr App-Projekt dann erneut zu veröffentlichen. Sie können auch die Downtime in Ihrer App minimieren und das Rollback vereinfachen, indem Sie ein Update mithilfe von Slots durchführen.

Aktualisieren ohne Slots

Die einfachste Möglichkeit zum Update auf v4.x besteht darin, die FUNCTIONS_EXTENSION_VERSION-Anwendungseinstellung in Ihrer Funktions-App in Azure auf ~4 festzulegen. Sie müssen ein anderes Verfahren an einem Standort mit Slots ausführen.

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

Sie müssen auch eine andere Einstellung festlegen, die sich für Windows und Linux unterscheidet.

Bei Ausführung unter Windows müssen Sie auch .NET 6.0 aktivieren, das für Version 4.x der Runtime erforderlich ist.

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

.NET 6 ist für Funktions-Apps in jeder Sprache erforderlich, die unter Windows ausgeführt wird.

Ersetzen Sie in diesem Beispiel <APP_NAME> durch den Namen Ihrer Funktions-App und <RESOURCE_GROUP_NAME> durch den Namen der Ressourcengruppe.

Sie können Ihr App-Projekt jetzt erneut veröffentlichen, das für die Ausführung in Version 4.x migriert wurde.

Aktualisieren mit Slots

Die Verwendung von Bereitstellungsslots ist eine gute Möglichkeit, Ihre Funktions-App von einer früheren Version auf die v4.x-Runtime zu aktualisieren. Mithilfe eines Stagingslos können Sie Ihre App auf der neuen Runtimeversion im Stagingslot ausführen und nach der Überprüfung zur Produktion wechseln. Slots bieten auch eine Möglichkeit, Downtime während des Updates zu minimieren. Wenn Sie Downtime minimieren müssen, führen Sie die Schritte unter Update mit minimaler Downtime aus.

Nachdem Sie Ihre App im aktualisierten Slot überprüft haben, können Sie die App und neue Versionseinstellungen in der Produktion übernehmen. Dieser Wechsel erfordert die Einstellung WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 im Produktionsslot. Wie Sie diese Einstellung hinzufügen, wirkt sich auf die Länge der für das Update erforderlichen Downtime aus.

Standardupdate

Wenn Ihre Funktions-App mit Slotunterstützung die Downtime eines vollständigen Neustarts verarbeiten kann, können Sie die WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS-Einstellung direkt im Produktionsslot aktualisieren. Da das Ändern dieser Einstellung direkt im Produktionsslot einen Neustart verursacht, der sich auf die Verfügbarkeit auswirkt, sollten Sie diese Änderung zu einem Zeitpunkt mit reduziertem Datenverkehr in Betracht ziehen. Anschließend können Sie die aktualisierte Version aus dem Stagingslot übernehmen.

Das Update-AzFunctionAppSetting-PowerShell-Cmdlet unterstützt derzeit keine Slots. Sie müssen Azure CLI oder das Azure-Portal verwenden.

  1. Verwenden Sie den folgenden Befehl, um im Produktionslot WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 festzulegen:

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

    Ersetzen Sie in diesem Beispiel <APP_NAME> durch den Namen Ihrer Funktions-App und <RESOURCE_GROUP_NAME> durch den Namen der Ressourcengruppe. Dieser Befehl bewirkt, dass die im Produktionslot ausgeführte App neu gestartet wird.

  2. Verwenden Sie den folgenden Befehl, um auch im Stagingslot WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS festzulegen:

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

  3. Verwenden Sie den folgenden Befehl, um FUNCTIONS_EXTENSION_VERSION zu ändern und den Stagingslot auf die neue Runtimeversion zu aktualisieren:

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

  4. Version 4.x der Functions-Runtime erfordert .NET 6 unter Windows. In Linux müssen .NET-Apps auch auf .NET 6 aktualisiert werden. Verwenden Sie den folgenden Befehl, damit die Runtime unter .NET 6 ausgeführt werden kann:

    Bei Ausführung unter Windows müssen Sie auch .NET 6.0 aktivieren, das für Version 4.x der Runtime erforderlich ist.

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

    .NET 6 ist für Funktions-Apps in jeder Sprache erforderlich, die unter Windows ausgeführt wird.

    Ersetzen Sie in diesem Beispiel <APP_NAME> durch den Namen Ihrer Funktions-App und <RESOURCE_GROUP_NAME> durch den Namen der Ressourcengruppe.

  5. Wenn für Ihr Codeprojekt Updates erforderlich sind, die auf Version 4.x ausgeführt werden sollen, stellen Sie diese Updates jetzt für den Stagingslot bereit.

  6. Vergewissern Sie sich vor dem Austausch, dass Ihre Funktions-App ordnungsgemäß in der aktualisierten Stagingumgebung ausgeführt wird.

  7. Verwenden Sie den folgenden Befehl, um den aktualisierten Stagingslot in die Produktion zu übernehmen:

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

Update mit minimaler Downtime

Um die Downtime in Ihrer Produktions-App zu minimieren, können Sie die WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS-Einstellung vom Stagingslot in die Produktion übernehmen. Danach können Sie von einem vordefinierten Stagingslot die aktualisierte Version übernehmen.

  1. Verwenden Sie den folgenden Befehl, um WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 im Stagingslot festzulegen:

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

  2. Verwenden Sie die folgenden Befehle, um den Slot mit der neuen Einstellung in die Produktion zu übernehmen und gleichzeitig die Versionseinstellung im Stagingslot wiederherzustellen.

    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>

    Während der Zeit zwischen dem Austausch und der Runtimeversion, die beim Staging wiederhergestellt wird, werden möglicherweise Fehler vom Stagingslot angezeigt. Dieser Fehler kann auftreten, weil die FUNCTIONS_EXTENSION_VERSION-Einstellung im Staging entfernt wird, wenn WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 während eines Austausches nur im Staging vorhanden ist. Ohne die Versionseinstellung befindet sich Ihr Slot in einem schlechten Zustand. Wenn Sie die Version im Stagingslot direkt nach dem Austausch aktualisieren, sollte der Slot wieder in einen guten Zustand versetzt werden, damit Sie bei Bedarf ein Rollback Ihrer Änderungen durchführen können. Ein Rollback des Austausches erfordert jedoch auch, dass Sie WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 direkt aus der Produktion entfernen, bevor der Austausch zurückgesetzt wird, um die gleichen Fehler, die im Staging auftreten, in der Produktion zu verhindern. Diese Änderung in der Produktionseinstellung würde dann einen Neustart verursachen.

  3. Verwenden Sie den folgenden Befehl, um WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 wieder im Stagingslot festzulegen:

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

    An diesem Punkt ist für beide Slots WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 festgelegt.

  4. Verwenden Sie den folgenden Befehl, um FUNCTIONS_EXTENSION_VERSION zu ändern und den Stagingslot auf die neue Runtimeversion zu aktualisieren:

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

  5. Version 4.x der Functions-Runtime erfordert .NET 6 unter Windows. In Linux müssen .NET-Apps auch auf .NET 6 aktualisiert werden. Verwenden Sie den folgenden Befehl, damit die Runtime unter .NET 6 ausgeführt werden kann:

    Bei Ausführung unter Windows müssen Sie auch .NET 6.0 aktivieren, das für Version 4.x der Runtime erforderlich ist.

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

    .NET 6 ist für Funktions-Apps in jeder Sprache erforderlich, die unter Windows ausgeführt wird.

    Ersetzen Sie in diesem Beispiel <APP_NAME> durch den Namen Ihrer Funktions-App und <RESOURCE_GROUP_NAME> durch den Namen der Ressourcengruppe.

  6. Wenn für Ihr Codeprojekt Updates erforderlich sind, die auf Version 4.x ausgeführt werden sollen, stellen Sie diese Updates jetzt für den Stagingslot bereit.

  7. Vergewissern Sie sich vor dem Austausch, dass Ihre Funktions-App ordnungsgemäß in der aktualisierten Stagingumgebung ausgeführt wird.

  8. Verwenden Sie den folgenden Befehl, um den aktualisierten und vordefinierten Stagingslot in die Produktion zu übernehmen:

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

Wichtige Unterschiede zwischen 3.x und 4.x

Nachfolgend finden Sie wichtige Breaking Changes, die vor dem Upgrade einer 3.x-App auf 4.x beachtet werden müssen, einschließlich sprachspezifischer Breaking Changes. Eine vollständige Liste finden Sie unter Azure Functions GitHub mit der Bezeichnung Breaking Change: Approved.

Wenn Ihre Programmiersprache nicht angezeigt wird, wählen Sie sie oben auf der Seite aus.

Typ

  • Azure Functions-Proxys sind ein Legacyfeature für die Versionen 1.x bis 3.x der Azure Functions-Runtime. Die Unterstützung für Functions-Proxys kann in Version 4.x wieder aktiviert werden, sodass Sie erfolgreich für Ihre Funktions-Apps ein Update auf die neueste Runtimeversion durchführen können. Wechseln Sie aber stattdessen so bald wie möglich zur Integration Ihrer Funktions-Apps in Azure API Management. Mit API Management können Sie einen umfassenderen Featuresatz für die Definition, Sicherung, Verwaltung und Monetarisierung Ihrer Functions-basierten APIs nutzen. Weitere Informationen finden Sie unter API Management-Integration. Informationen zum erneuten Aktivieren der Proxyunterstützung in der Functions-Version 4.x finden Sie unter Erneutes Aktivieren von Proxys in Functions v4.x.

  • Sich bei Azure Storage mithilfe von AzureWebJobsDashboard anzumelden, wird in 4.x nicht mehr unterstützt. Es empfiehlt sich, stattdessen Application Insights zu verwenden. (#1923)

  • Azure Functions 4.x erzwingt nun Mindestversionsanforderungen für Erweiterungen. Führen Sie ein Update auf die neueste Version der betroffenen Erweiterungen durch. Für andere Sprachen als .NET führen Sie ein Update auf Version 2.x oder höher des Erweiterungspakets durch. (#1987)

  • Standardmäßige und maximale Timeouts werden nun in Version 4.x für Funktions-Apps erzwungen, die unter Linux im Rahmen eines Verbrauchsplans ausgeführt werden. (#1915)

  • Azure Functions 4.x verwendet Azure.Identity und Azure.Security.KeyVault.Secrets für den Key Vault-Anbieter. Die Verwendung von „Microsoft.Azure.KeyVault“ ist veraltet. Weitere Informationen zum Konfigurieren der Einstellungen für Funktions-Apps finden Sie in Geheimnis-Repositorys unter der Schlüsseltresoroption. (#2048)

  • Funktions-Apps mit gemeinsam genutzten Speicherkonten können nicht mehr gestartet werden, wenn ihre Host-IDs identisch sind. Weitere Informationen finden Sie unter Überlegungen zur Host-ID. (#2049)

  • Azure Functions 4.x unterstützt .NET 6 In-Process und isolierte Apps.

  • InvalidHostServicesException ist jetzt ein schwerwiegender Fehler. (#2045)

  • EnableEnhancedScopes ist standardmäßig aktiviert. (#1954)

  • Entfernt HttpClient als registrierten Dienst. (#1911)

  • Verwenden eines Klassenladers in Java 11. (#1997)

  • Beendet das Laden von Worker-JAR-Dateien in Java 8. (#1991)

  • Die Node.js-Versionen 10 und 12 werden von Azure Functions 4.x nicht unterstützt. (#1999)

  • Die Ausgabeserialisierung in Node.js-Apps wurde aktualisiert, um frühere Inkonsistenzen zu beheben. (#2007)

  • Standardthreadanzahl wurde aktualisiert. Funktionen, die nicht threadsicher sind oder eine hohe Arbeitsspeicherauslastung mit sich bringen, können betroffen sein. (#1962)

  • Python 3.6 wird von Azure Functions 4.x nicht unterstützt. (#1999)

  • Shared Memory-Übertragung ist standardmäßig aktiviert. (#1973)

  • Standardthreadanzahl wurde aktualisiert. Funktionen, die nicht threadsicher sind oder eine hohe Arbeitsspeicherauslastung mit sich bringen, können betroffen sein. (#1962)

Nächste Schritte

Weitere Informationen zu Functions-Versionen