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

  • Artikel

Wichtig

Java wird nicht von Version 1.x der Azure Functions-Runtime unterstützt. Vielleicht möchten Sie stattdessen Ihre Java-App von Version 3.x auf Version 4.x migrieren. Wenn Sie eine Funktions-App der Version 1.x migrieren, wählen Sie oben C# oder JavaScript aus.

Wichtig

TypeScript wird nicht von Version 1.x der Azure Functions-Runtime unterstützt. Vielleicht möchten Sie stattdessen Ihre TypeScript-App von Version 3.x auf Version 4.x migrieren. Wenn Sie eine Funktions-App der Version 1.x migrieren, wählen Sie oben C# oder JavaScript aus.

Wichtig

PowerShell wird nicht von Version 1.x der Azure Functions-Runtime unterstützt. Vielleicht möchten Sie stattdessen Ihre PowerShell-App von Version 3.x auf Version 4.x migrieren. Wenn Sie eine Funktions-App der Version 1.x migrieren, wählen Sie oben C# oder JavaScript aus.

Wichtig

Python wird nicht von Version 1.x der Azure Functions-Runtime unterstützt. Vielleicht möchten Sie stattdessen Ihre Python-App von Version 3.x auf Version 4.x migrieren. Wenn Sie eine Funktions-App der Version 1.x migrieren, wählen Sie oben C# oder JavaScript aus.

Wichtig

Der Support für Version 1.x der Azure Functions-Laufzeit endet am 14. September 2026. Wir empfehlen Ihnen dringend, Ihre Apps mithilfe der Anweisungen in diesem Artikel zu Version 4.x zu migrieren.

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.

Wenn Sie Version 1.x der Runtime in Azure Stack Hub ausführen, lesen Sie zunächst Überlegungen zu Azure Stack Hub.

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

$AppInfo

Auswählen der .NET-Zielversion

In Version 1.x der Functions-Runtime zielt Ihre C#-Funktions-App auf .NET Framework ab.

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

Sofern Ihre App nicht von einer Bibliothek oder API abhängt, die nur für .NET Framework verfügbar ist, empfehlen wir für das isolierte Workermodell ein Upgrade auf .NET 8. Viele Apps in Version 1.x haben nur deswegen .NET Framework als Ziel, weil bei der Erstellung nichts anderes verfügbar war. Für neuere Versionen von .NET stehen zusätzliche Funktionen zur Verfügung. Wenn Ihre App nicht gezwungen ist, aufgrund einer Abhängigkeit weiterhin .NET Framework zu verwenden, sollten Sie eine neuere Version verwenden. .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 Behavior Changes nach Version 1.x. Die Migration von Version 1.x zu Version 4.x kann sich auch auf Bindungen auswirken.
  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. 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.
  5. 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

In den folgenden Abschnitten werden die Updates beschrieben, die Sie an Ihren C#-Projektdateien vornehmen müssen, um unter einer der unterstützten Versionen von .NET in Functions-Version 4.x ausgeführt werden zu können. Die angezeigten Updates sind für die meisten Projekte üblich. Ihr Projektcode erfordert möglicherweise Updates, die in diesem Artikel nicht erwähnt werden – insbesondere bei Verwendung benutzerdefinierter NuGet-Pakete.

Zum Migrieren einer C#-Funktions-App von Version 1.x zu Version 4.x der Functions-Runtime müssen Sie Änderungen am Projektcode vornehmen. Viele dieser Änderungen sind das Ergebnis von Änderungen in der C#-Sprache und .NET-APIs.

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 unter der Version 1.x ausgeführt wird:

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

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.

Die Bindungen für Notification Hubs und Mobile Apps werden nur in Version 1.x der Runtime unterstützt. Beim Upgrade auf Version 4.x der Runtime müssen Sie diese Bindungen entfernen, um über die entsprechenden SDKs direkt mit diesen Diensten zu arbeiten.

Datei „program.cs“

In den meisten Fällen erfordert die Migration, dass 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 „host.json“

Die Einstellungen in der Datei „host.json“ gelten sowohl lokal als auch in Azure auf Funktions-App-Ebene. In Version 1.x ist die Datei „host.json“ entweder leer oder enthält einige Einstellungen, die für alle Funktionen in der Funktions-App gelten. Weitere Informationen finden Sie unter Host.json v1. Wenn Ihre Datei „host.json“ Einstellungswerte enthält, überprüfen Sie das Format „host.json v2“ auf Änderungen.

Zur Ausführung in Version 4.x müssen Sie "version": "2.0" zur Datei „host.json“ hinzufügen. Sie sollten auch erwägen, Ihrer Konfiguration logging hinzuzufügen, wie in den folgenden Beispielen:

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

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.

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. In Version 1.x weist die Datei „local.settings.json“ nur zwei erforderliche Werte auf:

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

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.

Änderungen von Klassennamen

Einige Schlüsselklassen haben die Namen zwischen Version 1.x und Version 4.x 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:

Version 1.x .NET 8
FunctionName (Attribut) Function (Attribut)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (unter Verwendung der ASP.NET Core-Integration)
HttpResponseMessage HttpResponseData, IActionResult (unter Verwendung der ASP.NET Core-Integration)

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 die Verhaltensänderungen nach Version 1.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 meisten Codeänderungen zwischen Version 1.x und Version 4.x sind in durch HTTP ausgelösten Funktionen sichtbar. Die HTTP-Triggervorlage für Version 1.x sieht wie im folgenden Beispiel aus:

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

Die HTTP-Triggervorlage in Version 4.x 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. Wechseln Sie zu einer der Node.js-Versionen, die in Version 4.x unterstützt werden.

  3. Fügen Sie beide Elemente version und extensionBundle zu host.json hinzu, sodass sie wie im folgenden Beispiel aussieht:

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

    Das Element extensionBundle ist erforderlich, da Bindungen nach Version 1.x als externe Pakete verwaltet werden. Weitere Informationen finden Sie unter Erweiterungspakete.

  4. Aktualisieren Sie die Datei „local.settings.json“, sodass sie mindestens die folgenden Elemente enthält:

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

    Die Einstellung AzureWebJobsStorage kann entweder der Azurite-Speicheremulator oder ein tatsächliches Azure-Speicherkonto sein. Weitere Informationen finden Sie unter Emulator für lokalen Speicher.

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

Behavior Changes nach Version 1.x

In diesem Abschnitt werden Änderungen beschrieben, die nach Version 1.x im Trigger- und Bindungsverhalten sowie in den wichtigsten Funktionen und Verhaltensweisen vorgenommen wurden.

Änderungen an Triggern und Bindungen

Ab der Version 2.x müssen die Erweiterungen für bestimmte Trigger und Bindungen installiert werden, die von den Funktionen in Ihrer App verwendet werden. Die einzigen Ausnahmen sind HTTP- und Timertrigger, für die keine Erweiterung erforderlich ist. Weitere Informationen finden Sie unter Registrieren und Installieren von Bindungserweiterungen.

Zwischen den Versionen gibt es auch einige Änderungen an der Datei function.json sowie an Attributen der Funktion. Beispielsweise lautet die Event Hubs-Eigenschaft path jetzt eventHubName. Links zur Dokumentation für die einzelnen Bindungen finden Sie in der Tabelle der vorhandenen Bindungen.

Änderungen bei Features und Funktionalität

Einige Features wurden nach der Version 1.x entfernt, aktualisiert oder ersetzt. In diesem Abschnitt werden die Änderungen nach der Version 1.x erläutert.

In Version 2.x wurden die folgenden Änderungen vorgenommen:

  • Schlüssel für aufrufende HTTP-Endpunkte werden immer verschlüsselt in Azure Blob Storage gespeichert. In Version 1.x wurden Schlüssel standardmäßig in Azure Files gespeichert. Bei einer App-Migration von Version 1.x zu Version 2.x werden in Azure Files vorhandene Geheimnisse zurückgesetzt.

  • Version 2.x der Runtime umfasst keine integrierte Unterstützung für Webhookanbieter. Diese Änderung wurde vorgenommen, um die Leistung zu verbessern. Sie können weiterhin HTTP-Trigger als Endpunkte für Webhooks verwenden.

  • Zur Verbesserung der Überwachung wurde das WebJobs-Dashboard im Portal, das die Einstellung AzureWebJobsDashboard verwendete, durch Azure Application Insights ersetzt – hierbei wird die Einstellung APPINSIGHTS_INSTRUMENTATIONKEY verwendet. Weitere Informationen finden Sie unter Überwachen von Azure Functions.

  • Alle Funktionen in einer Funktions-App müssen die gleiche Sprache verwenden. Wenn Sie eine Funktions-App erstellen, müssen Sie einen Runtimestapel für die App auswählen. Der Runtimestapel wird durch den FUNCTIONS_WORKER_RUNTIME-Wert in den Anwendungseinstellungen angegeben. Diese Anforderung wurde hinzugefügt, um den Speicherbedarf und die Startzeit zu verbessern. Bei der lokalen Entwicklung müssen Sie diese Einstellung auch in die Datei „local.settings.json“ einschließen.

  • Das Standardzeitlimit für Funktionen in einem App Service-Plan wurde zu 30 Minuten geändert. Sie können das Zeitlimit mit der functionTimeout-Einstellung in der host.json-Datei manuell wieder zu „unbegrenzt“ ändern.

  • HTTP-Parallelitätsdrosselungen sind standardmäßig für Verbrauchsplanfunktionen implementiert. Der Standardwert beträgt 100 gleichzeitige Anforderungen pro Instanz. Sie können dieses Verhalten in der maxConcurrentRequests-Einstellung in der host.json-Datei ändern.

  • Aufgrund der Einschränkungen von .NET Core wurde die Unterstützung von F#-Skriptfunktionen (Dateien vom Typ .fsx) entfernt. Kompilierte F#-Funktionen (FS) werden weiterhin unterstützt.

  • Das URL-Format von Event Grid-Triggerwebhooks wurde geändert und hat nun das folgende Muster: https://{app}/runtime/webhooks/{triggerName}.

  • Die Namen einiger vordefinierter benutzerdefinierter Metriken wurden nach Version 1.x geändert. Duration wurde durch MaxDurationMs, MinDurationMsund AvgDurationMs ersetzt. Success Rate wurde auch in Success Rate umbenannt.

Überlegungen zu Azure Stack Hub

App Service in Azure Stack Hub unterstützt Version 4.x von Azure Functions nicht. Wenn Sie eine Migration von Version 1.x in Azure Stack Hub planen, können Sie eine der folgenden Optionen auswählen:

  • Migrieren Sie gemäß der Anleitung in diesem Artikel zu Version 4.x, die in einer öffentlichen Cloud Azure Functions gehostet wird. Anstatt Ihre vorhandene App zu aktualisieren, erstellen Sie eine neue App mit Version 4.x und stellen dann Ihr geändertes Projekt darin bereit.
  • Wechseln Sie zu WebJobs, die in einem App Service-Plan in Azure Stack Hub gehostet werden.

Nächste Schritte

Weitere Informationen zu Functions-Versionen