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

Bei diesen Schritten wird ein lokales C#-Projekt vorausgesetzt; Wenn Ihre App stattdessen C#-Skript (CSX-Dateien ) verwendet, sollten Sie in das Projektmodell konvertieren , bevor Sie fortfahren.

Die folgenden Ä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 das folgende OutputType-Element PropertyGroup hinzu:

   <OutputType>Exe</OutputType>
   

4. Ersetzen Sie in der Liste ItemGroup.Ersetzen Sie in der PackageReference-Liste den Paketverweis auf Microsoft.NET.Sdk.Functions durch die folgenden Verweise:

     <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 Namespaces Microsoft.Azure.WebJobs.*. Diese Pakete werden in einem späteren Schritt ersetzt.

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>

Bei diesen Schritten wird ein lokales C#-Projekt vorausgesetzt; Wenn Ihre App stattdessen C#-Skript (CSX-Dateien ) verwendet, sollten Sie in das Projektmodell konvertieren , bevor Sie fortfahren.

Die folgenden Änderungen sind in der CSPROJ-XML-Projektdatei erforderlich:

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

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

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

   <OutputType>Exe</OutputType>
   

4. Ersetzen Sie in der Liste ItemGroup.Ersetzen Sie in der PackageReference-Liste die Paketreferenz auf Microsoft.NET.Sdk.Functions durch die folgenden Verweise:

     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
     <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
   

   Notieren Sie sich alle Verweise auf andere Pakete in den Namespaces Microsoft.Azure.WebJobs.*. Diese Pakete werden in einem späteren Schritt ersetzt.

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

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

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
      <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
      <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Folder Include="Properties\" />
  </ItemGroup>
</Project>

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. Ersetzen Sie die vorhandene ItemGroup. PackageReference-Liste mit folgender ItemGroup:

   <ItemGroup>
     <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
   </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>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

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

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

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:

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.

Ihre isolierte Workermodellanwendung sollte nicht auf Pakete in den namespaces Microsoft.Azure.WebJobs.* oder Microsoft.Azure.Functions.Extensions verweisen. Wenn noch Verweise auf diese vorhanden sind, sollten Sie sie entfernen.

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

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

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:

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.

Ihre isolierte Workermodellanwendung sollte nicht auf Pakete in den namespaces Microsoft.Azure.WebJobs.* oder Microsoft.Azure.Functions.Extensions verweisen. Wenn noch Verweise auf diese vorhanden sind, sollten Sie sie entfernen.

Aktualisieren Sie Ihr Projekt, um auf die neueste stabile Version von Microsoft.NET zu verweisen. Sdk.Functions.

Abhängig von den Triggern und Bindungen, die Ihre App verwendet, muss Ihre App möglicherweise auf zusätzliche Pakete verweisen. Eine Liste der zu berücksichtigenden Erweiterungen finden Sie unter Unterstützte Bindungen, und vollständige Installationsanweisungen für das In-Process-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.

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 enthält 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 ConfigureFunctionsWebApplication durch einen Aufruf ConfigureFunctionsWorkerDefaultsersetzen. In diesem Rahmen 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 FrameworkReference in ASP.NET Core beibehalten.

Die Datei Program.cs ersetzt jede Datei mit dem Attribut FunctionsStartup. Diese ist in der Regel eine Datei vom Typ Startup.cs. An den Stellen, an denen Ihr FunctionsStartup Code auf IFunctionsHostBuilder.Services verweisen würde, können Sie stattdessen Anweisungen innerhalb der .ConfigureServices()-Methode der HostBuilder in Ihrer Program.cs hinzufügen. Weitere Informationen zum Arbeiten mit Program.cs finden Sie unter "Start- und Konfiguration " im Leitfaden zum isolierten Arbeitsmodell.

Die zuvor beschriebenen Standardbeispiele Program.cs umfassen das Einrichten von Application Insights. In Ihrem Program.cs müssen Sie auch alle Protokollfilter konfigurieren, die für Protokolle gelten sollten, die aus Code in Ihrem Projekt stammen. Im isolierten Workermodell steuert die dateihost.json nur Ereignisse, die von der Hostlaufzeit der Funktionen 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.

Obwohl Sie benutzerdefinierte Konfigurationsquellen als Teil des HostBuilderProjekts registrieren können, gelten diese in ähnlicher Weise nur für Code in Ihrem Projekt. Die Plattform benötigt außerdem Trigger- und Bindungskonfigurationen, die über die Anwendungseinstellungen, Key Vault-Referenzen oder App-Konfigurationsreferenzen bereitgestellt werden sollten.

Nachdem Sie alles von einer beliebigen vorhandenen FunctionsStartup in die Program.cs Datei verschoben haben, können Sie das FunctionsStartup Attribut und die Klasse löschen, auf die sie angewendet wurde.

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

namespace Company.FunctionApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

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

Die Datei Program.cs ersetzt jede Datei mit dem Attribut FunctionsStartup. Diese ist in der Regel eine Datei vom Typ Startup.cs. An den Stellen, an denen Ihr FunctionsStartup Code auf IFunctionsHostBuilder.Services verweisen würde, können Sie stattdessen Anweisungen innerhalb der .ConfigureServices()-Methode der HostBuilder in Ihrer Program.cs hinzufügen. Weitere Informationen zum Arbeiten mit Program.cs finden Sie unter "Start- und Konfiguration " im Leitfaden zum isolierten Arbeitsmodell.

Die zuvor beschriebenen Standardbeispiele Program.cs umfassen das Einrichten von Application Insights. In Ihrem Program.cs müssen Sie auch alle Protokollfilter konfigurieren, die für Protokolle gelten sollten, die aus Code in Ihrem Projekt stammen. Im isolierten Workermodell steuert die dateihost.json nur Ereignisse, die von der Hostlaufzeit der Funktionen 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.

Obwohl Sie benutzerdefinierte Konfigurationsquellen als Teil des HostBuilderProjekts registrieren können, gelten diese in ähnlicher Weise nur für Code in Ihrem Projekt. Die Plattform benötigt außerdem eine Trigger- und Bindungskonfiguration, die über die Einstellungen für Application, Key Vault-Verweise oder App Configuration-Verweise bereitgestellt werden sollte.

Nachdem Sie alles von einer beliebigen vorhandenen FunctionsStartup in die Program.cs Datei verschoben haben, können Sie das FunctionsStartup Attribut und die Klasse löschen, auf die sie angewendet wurde.

Eine Program.cs Datei ist nicht erforderlich, wenn Sie das In-Process-Modell verwenden.

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

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

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "FUNCTIONS_INPROC_NET8_ENABLED": "1"
    }
}

In Ihrer Datei host.json sind keine Änderungen erforderlich. Wenn Ihre Application Insights-Konfiguration in dieser Datei jedoch aus Ihrem Prozessmodellprojekt stammt, möchten Sie möglicherweise andere Änderungen an Ihrer Program.cs Datei 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.

In Ihrer Datei host.json sind keine Änderungen erforderlich. Wenn Ihre Application Insights-Konfiguration in dieser Datei jedoch aus Ihrem Prozessmodellprojekt stammt, möchten Sie möglicherweise andere Änderungen an Ihrer Program.cs Datei 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.

In Ihrer Datei host.json sind keine Änderungen erforderlich.

In diesem Abschnitt werden weitere Codeänderungen genannt, die während der Migration berücksichtigt werden müssen. Diese Änderungen werden von allen Anwendungen nicht benötigt, aber Sie sollten bewerten, 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 verwendet das isolierte Workermodell System.Text.Json für die JSON-Serialisierung . Informationen zum Anpassen von Serialisierungsoptionen oder zum Wechseln zu JSON.NET (Newtonsoft.Json) finden Sie unter Customizing JSON serialization.

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. Mit demhost.json können Sie Regeln für die Hostprotokollierung konfigurieren, aber um Protokolle aus Ihrem Code zu steuern, müssen Sie Filterregeln als Teil Ihrer Program.cs konfigurieren. Ausführliche Informationen zum Filtern dieser Protokolle finden Sie unter Verwalten von Protokollebenen im Modell mit isolierten Workern.

In diesem Abschnitt werden weitere Codeänderungen genannt, die während der Migration berücksichtigt werden müssen. Diese Änderungen werden von allen Anwendungen nicht benötigt, aber Sie sollten bewerten, 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 verwendet das isolierte Workermodell System.Text.Json für die JSON-Serialisierung . Informationen zum Anpassen von Serialisierungsoptionen oder zum Wechseln zu JSON.NET (Newtonsoft.Json) finden Sie unter Customizing JSON serialization.

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. Mit demhost.json können Sie Regeln für die Hostprotokollierung konfigurieren, aber um Protokolle aus Ihrem Code zu steuern, müssen Sie Filterregeln als Teil Ihrer Program.cs konfigurieren. Ausführliche Informationen zum Filtern dieser Protokolle finden Sie unter Verwalten von Protokollebenen im Modell mit isolierten Workern.

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequestData req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

Identisch mit Version 3.x (prozessintern).