Leitfaden zum Ausführen von C#-Azure Functions im isolierten Arbeitsmodell

In diesem Artikel wird die Arbeit mit Azure Functions in .NET mithilfe des isolierten Arbeitsmodells eingeführt. Mit diesem Modell können Sie die Zielversionen Ihrer Projekte für .NET unabhängig von anderen Laufzeitkomponenten festlegen. Informationen zu bestimmten unterstützten .NET Versionen finden Sie unter supported version.

Verwenden Sie die folgenden Links, um sofort mit der Erstellung von .NET-Funktionen im isolierten Arbeitsmodell zu beginnen.

Um zu erfahren, wie man ein isoliertes Worker-Modell-Projekt für Azure bereitstellt, siehe Deploy to Azure Functions.

Vorteile des isolierten Workermodells

Sie können Ihre .NET Klassenbibliotheksfunktionen in zwei Modi ausführen: entweder im gleichen Prozess wie die Hostlaufzeit der Funktionen (in-process) oder in einem isolierten Arbeitsprozess. Wenn Ihre .NET Funktionen in einem isolierten Arbeitsprozess ausgeführt werden, können Sie die folgenden Vorteile nutzen:

• Weniger Konflikte: Da Ihre Funktionen in einem separaten Prozess ausgeführt werden, geraten die Assemblys Ihrer App nicht mit unterschiedlichen Versionen der gleichen Assemblys in Konflikt, die vom Hostprozess verwendet werden.
• Vollständige Kontrolle über den Prozess: Sie steuern den Start der App, können also die verwendeten Konfigurationen und die gestartete Middleware verwalten.
• Standard-Abhängigkeitsinjektion: Da Sie die vollständige Kontrolle über den Prozess haben, können Sie aktuelle .NET Verhaltensweisen für Abhängigkeitseinfügungen verwenden und Middleware in Ihre Funktions-App integrieren.
• .NET Version flexibilität: Das Ausführen außerhalb des Hostprozesses bedeutet, dass Ihre Funktionen auf Versionen von .NET ausgeführt werden können, die von der Funktionslaufzeit nicht nativ unterstützt werden, einschließlich des .NET Frameworks.

Wenn Sie bereits über eine C#-Funktions-App mit In-Process-Ausführung verfügen, müssen Sie Ihre App migrieren, um diese Vorteile nutzen zu können. Weitere Informationen finden Sie unter Migrate .NET Apps aus dem In-Process-Modell zum isolierten Workermodell.

Einen umfassenden Vergleich zwischen den beiden Betriebsmodi finden Sie unter Unterschiede zwischen In-Process- und Isolate Worker Process .NET Azure Functions.

Unterstützte Versionen

Versionen der Funktionslaufzeit unterstützen bestimmte Versionen von .NET. Weitere Informationen zu Funktionsversionen finden Sie unter Azure Functions Laufzeitversionen – Übersicht. Die Versionsunterstützung hängt auch davon ab, ob Ihre Funktionen prozessintern oder in einem isolierten Workerprozess ausgeführt werden.

Die folgende Tabelle zeigt die höchste Ebene von .NET oder .NET Framework, die mit einer bestimmten Version von Funktionen verwendet werden kann.

¹ .NET 6 wurde zuvor auf beiden Modellen unterstützt, erreichte jedoch das Ende des offiziellen Supports am 12. November 2024. .NET 7 wurde zuvor auf dem isolierten Arbeitsmodell unterstützt, erreichte aber am 14. Mai 2024 das Ende des offiziellen Supports.

² Der Buildvorgang erfordert auch das .NET SDK.

³ Der Support endet für Version 1.x der Azure Functions Laufzeit am 14. September 2026. Weitere Informationen finden Sie unter diese Supportankündigung. Um weiterhin uneingeschränkten Support zu erhalten, müssen Sie Ihre Apps zur Version  4.x migrieren.

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

⁵ Sie können nicht .NET 10 Apps unter Linux im Verbrauchsplan ausführen. Um unter Linux auszuführen, sollten Sie stattdessen den Flex-Verbrauchsplan verwenden. Schritt-für-Schritt-Migrationsanweisungen finden Sie unter Migrieren von Verbrauchsplan-Apps zum Flex-Verbrauchsplan.

Für die neuesten Nachrichten zu Azure Functions-Versionen, einschließlich der Entfernung spezifischer älterer Nebenversionen, verfolgen Sie die Ankündigungen des Azure App Service.

Projekt-Struktur

Ein .NET-Projekt für Azure Functions, das das isolierte Workermodell verwendet, ist im Grunde ein .NET-Konsolen-App-Projekt, das eine unterstützte .NET-Laufzeit anvisiert. Die folgenden Dateien sind die Grunddateien, die in jedem isolierten .NET-Projekt erforderlich sind.

• C#-Projektdatei (.csproj), die das Projekt und die Abhängigkeiten definiert.
• Program.cs, der Einstiegspunkt für die App
• Alle Codedateien, die Ihre Funktionen definieren.
• host.jsondatei, die die konfiguration definiert, die von Funktionen in Ihrem project gemeinsam genutzt wird.
• local.settings.jsondatei, die Umgebungsvariablen definiert, die von Ihrem project verwendet werden, wenn sie lokal auf Ihrem Computer ausgeführt werden.

Vollständige Beispiele finden Sie im .NET 8-Beispiel project und im .NET Framework 4.8-Beispiel project.

Paketverweise

Ein .NET-Projekt für Azure Functions, das das isolierte Workermodell nutzt, verwendet einen eindeutigen Satz von Paketen für die Kernfunktionen und Binding-Erweiterungen.

Erforderliche Pakete

Um Ihre .NET Funktionen in einem isolierten Arbeitsprozess auszuführen, benötigen Sie die folgenden Pakete:

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

Die Mindestversionen dieser Pakete hängen von Ihrer Zielversion .NET Version ab:

Version 2.x

Die 2.x-Versionen der Kernpakete ändern die unterstützten Frameworks und unterstützen neue .NET-APIs aus diesen späteren Versionen. Beachten Sie beim Aktualisieren auf die 2.x-Versionen die folgenden Änderungen:

• Ab Version 2.0.0 von Microsoft. Azure. Functions.Worker.Sdk:
  • Das SDK enthält Standardkonfigurationen für SDK-Containerbuilds.
  • Das SDK enthält Unterstützung für dotnet run, wenn die Azure Functions Core Tools installiert ist. Installieren Sie unter Windows die Core Tools über einen anderen Mechanismus als NPM.
• Ab Version 2.0.0 von Microsoft. Azure. Functions.Worker:
  • Diese Version bietet Unterstützung für IHostApplicationBuilder. Einige Beispiele in diesem Leitfaden enthalten Registerkarten mit Alternativen, die IHostApplicationBuilder verwenden. Für diese Beispiele sind 2.x-Versionen erforderlich.
  • Die Gültigkeitsprüfung des Dienstanbieterbereichs ist standardmäßig enthalten, wenn die Ausführung in einer Entwicklungsumgebung erfolgt. Dieses Verhalten entspricht ASP.NET Core.
  • Die EnableUserCodeException-Option ist standardmäßig aktiviert. Die Eigenschaft ist jetzt als veraltet markiert.
  • Die IncludeEmptyEntriesInMessagePayload-Option ist standardmäßig aktiviert. Wenn diese Option aktiviert ist, löst sie Nutzdaten aus, die Sammlungen mit stets leeren Einträge darstellen. Wenn beispielsweise eine Nachricht ohne Textkörper gesendet wird, ist für die Triggerdaten weiterhin ein leerer Eintrag vorhanden string[] . Der Einschluss leerer Einträge vereinfacht Querverweise mit Metadatenarrays, auf die die Funktion ebenfalls verweisen kann. Sie können dieses Verhalten deaktivieren, indem Sie in der IncludeEmptyEntriesInMessagePayload-Dienstkonfiguration false auf WorkerOptions festlegen.
  • Die ILoggerExtensions-Klasse wurde in FunctionsLoggerExtensions umbenannt. Die Umbenennung verhindert einen Fehler durch einen mehrdeutigen Aufruf bei Verwendung von LogMetric() in einer ILogger-Instanz.
  • Für Apps, die HttpResponseData verwenden, setzt die Methode den WriteAsJsonAsync()-Statuscode nicht mehr auf 200 OK. In 1.x überrodet dieses Verhalten andere von Ihnen festgelegte Fehlercodes.
• Die 2.x-Versionen verwerfen die Unterstützung von .NET 5 TFM.

Erweiterungspakete

Da .NET isolierten Arbeitsprozessfunktionen unterschiedliche Bindungstypen verwenden, benötigen sie einen eindeutigen Satz von Bindungserweiterungspaketen.

Diese Erweiterungspakete finden Sie unter Microsoft. Azure. Functions.Worker.Extensions.

Start und Konfiguration

Wenn Sie das isolierte Workermodell verwenden, haben Sie Zugriff auf den Start Ihrer Funktions-App, die sich in der Regel in Program.cs befindet. Sie sind dafür verantwortlich, eine eigene Hostinstanz zu erstellen und zu starten. Somit haben Sie auch direkten Zugriff zur Konfigurationspipeline für Ihre App. Mit dem isolierten Worker-Prozess von .NET Functions können Sie viel einfacher Konfigurationen hinzufügen, Abhängigkeiten injizieren und Ihre eigene Middleware ausführen.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Logging.Services.Configure<LoggerFilterOptions>(options =>
    {
        // The Application Insights SDK adds a default logging filter that instructs ILogger to capture only Warning and more severe logs. Application Insights requires an explicit override.
        // Log levels can also be configured using appsettings.json. For more information, see https://learn.microsoft.com/azure/azure-monitor/app/worker-service#ilogger-logs
        LoggerFilterRule? defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
            == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
        if (defaultRule is not null)
        {
            options.Rules.Remove(defaultRule);
        }
    });

var host = builder.Build();

await host.RunAsync();

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(s =>
    {
        s.AddApplicationInsightsTelemetryWorkerService();
        s.ConfigureFunctionsApplicationInsights();
        s.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
        s.Configure<LoggerFilterOptions>(options =>
        {
            // The Application Insights SDK adds a default logging filter that instructs ILogger to capture only Warning and more severe logs. Application Insights requires an explicit override.
            // Log levels can also be configured using appsettings.json. For more information, see https://learn.microsoft.com/en-us/azure/azure-monitor/app/worker-service#ilogger-logs
            LoggerFilterRule? toRemove = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");

            if (toRemove is not null)
            {
                options.Rules.Remove(toRemove);
            }
        });
    })
    .Build();

Konfiguration

Der Typ des verwendeten Generators bestimmt, wie Sie die Anwendung konfigurieren.

.ConfigureFunctionsWorkerDefaults()

Diese Konfigurationen gelten nur für den Arbeitscode, den Sie erstellen. Sie beeinflussen nicht direkt die Konfiguration des Functions-Hosts oder der Trigger und Bindungen. Verwenden Sie die host.json Datei, um Änderungen am Host der Funktionen vorzunehmen oder eine Trigger- und Bindungskonfiguration vorzunehmen.

Abhängigkeitsinjektion

Das isolierte Arbeitsmodell verwendet standard-.NET Mechanismen zum Einfügen von Diensten.

builder.Services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();

.ConfigureServices(services =>
{
    services.AddSingleton<IHttpResponderService, DefaultHttpResponderService>();
})

Für diesen Code ist using Microsoft.Extensions.DependencyInjection; erforderlich. Weitere Informationen finden Sie unter Dependency Injection in ASP.NET Core.

Registrieren Azure Clients

Verwenden Sie die Abhängigkeitsinjektion, um mit anderen Azure-Diensten zu interagieren. Sie können Clients aus dem Azure SDK für .NET durch mithilfe des Microsoft.Extensions.Azure-Paketes injizieren. Nach der Installation des Pakets registrieren Sie die Clients , indem Sie in der Dienstsammlung aufrufen. Im folgenden Beispiel wird ein named-Client für Azure Blobs konfiguriert:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(builder.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });

builder.Build().Run();

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices((hostContext, services) =>
    {
        services.AddAzureClients(clientBuilder =>
        {
            clientBuilder.AddBlobServiceClient(hostContext.Configuration.GetSection("MyStorageConnection"))
                .WithName("copierOutputBlob");
        });
    })
    .Build();

host.Run();

Das folgende Beispiel zeigt, wie Sie diese Registrierungs- und SDK-Typen verwenden können, um Blobinhalte mithilfe eines eingefügten Clients als Datenstrom von einem Container in einen anderen zu kopieren:

using Microsoft.Extensions.Azure;
using Microsoft.Extensions.Logging;

namespace MyFunctionApp
{
    public class BlobCopier
    {
        private readonly ILogger<BlobCopier> _logger;
        private readonly BlobContainerClient _copyContainerClient;

        public BlobCopier(ILogger<BlobCopier> logger, IAzureClientFactory<BlobServiceClient> blobClientFactory)
        {
            _logger = logger;
            _copyContainerClient = blobClientFactory.CreateClient("copierOutputBlob").GetBlobContainerClient("samples-workitems-copy");
            _copyContainerClient.CreateIfNotExists();
        }

        [Function("BlobCopier")]
        public async Task Run([BlobTrigger("samples-workitems/{name}", Connection = "MyStorageConnection")] Stream myBlob, string name)
        {
            await _copyContainerClient.UploadBlobAsync(name, myBlob);
            _logger.LogInformation($"Blob {name} copied!");
        }

    }
}

Das ILogger<T> in diesem Beispiel wird auch durch Abhängigkeitsinjektion abgerufen, sodass es automatisch registriert wird. Weitere Informationen zu den Konfigurationsoptionen für die Protokollierung finden Sie unter Protokollierung.

Middleware

Das isolierte Workermodell unterstützt auch die Middleware-Registrierung, indem ein Modell verwendet wird, das dem in ASP.NET vorhandenen Modell ähnelt. Dieses Modell bietet Ihnen die Möglichkeit, Logik in die Aufrufpipeline einzufügen, und vorher und nachher Funktionen auszuführen.

Die ConfigureFunctionsWorkerDefaults Erweiterungsmethode verfügt über eine Überladung, mit der Sie Ihre eigene Middleware registrieren können, wie im folgenden Beispiel gezeigt.

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

var builder = FunctionsApplication.CreateBuilder(args);

// Register our custom middlewares with the worker
builder
    .UseMiddleware<ExceptionHandlingMiddleware>()
    .UseMiddleware<MyCustomMiddleware>()
    .UseWhen<StampHttpHeaderMiddleware>((context) =>
    {
        // We want to use this middleware only for http trigger invocations.
        return context.FunctionDefinition.InputBindings.Values
                        .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
    });

builder.Build().Run();

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(workerApplication =>
    {
        // Register our custom middlewares with the worker

        workerApplication.UseMiddleware<ExceptionHandlingMiddleware>();

        workerApplication.UseMiddleware<MyCustomMiddleware>();

        workerApplication.UseWhen<StampHttpHeaderMiddleware>((context) =>
        {
            // We want to use this middleware only for http trigger invocations.
            return context.FunctionDefinition.InputBindings.Values
                          .First(a => a.Type.EndsWith("Trigger")).Type == "httpTrigger";
        });
    })
    .Build();

Die UseWhen Erweiterungsmethode registriert eine Middleware, die bedingt ausgeführt wird. Sie müssen ein Prädikat übergeben, das einen booleschen Wert an diese Methode zurückgibt. Die Middleware nimmt an der Aufrufverarbeitungspipeline teil, wenn das Prädikat zurückgegeben wird true.

Die folgenden Erweiterungsmethoden für FunctionContext erleichtern die Arbeit mit Middleware im isolierten Modell.

Dieses Beispiel zeigt eine Middleware-Implementierung, die die HttpRequestData Instanz liest und die Instanz während der HttpResponseData Funktionsausführung aktualisiert:

internal sealed class StampHttpHeaderMiddleware : IFunctionsWorkerMiddleware
{
    public async Task Invoke(FunctionContext context, FunctionExecutionDelegate next)
    {
        var requestData = await context.GetHttpRequestDataAsync();

        string correlationId;
        if (requestData!.Headers.TryGetValues("x-correlationId", out var values))
        {
            correlationId = values.First();
        }
        else
        {
            correlationId = Guid.NewGuid().ToString();
        }

        await next(context);

        context.GetHttpResponseData()?.Headers.Add("x-correlationId", correlationId);
    }
}

Diese Middleware sucht nach dem Vorhandensein eines bestimmten Anforderungsheaders (x-correlationId). Wenn der Header vorhanden ist, verwendet die Middleware den Headerwert, um einen Antwortheader zu stempeln. Andernfalls generiert sie einen neuen GUID-Wert und verwendet diesen Wert zum Stempeln des Antwortheaders.

Ein vollständiges Beispiel für die Verwendung von benutzerdefinierter Middleware in Ihrer Funktions-App finden Sie im Custom Middleware-Referenzbeispiel.

Anpassen der JSON-Serialisierung

Das isolierte Arbeitsmodell verwendet System.Text.Json standardmäßig. Sie können das Verhalten des Serialisierungsmoduls anpassen, indem Sie Dienste als Teil Ihrer Program.cs Datei konfigurieren. Dieser Abschnitt behandelt die allgemeine Serialisierung und beeinflusst nicht HTTP Trigger JSON Serialization mit ASP.NET Core Integration, die Sie separat konfigurieren müssen.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
    {
        jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
        jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

        // override the default value
        jsonSerializerOptions.PropertyNameCaseInsensitive = false;
    });

builder.Build().Run();

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<JsonSerializerOptions>(jsonSerializerOptions =>
        {
            jsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
            jsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
            jsonSerializerOptions.ReferenceHandler = ReferenceHandler.Preserve;

            // override the default value
            jsonSerializerOptions.PropertyNameCaseInsensitive = false;
        });
    })
    .Build();

host.Run();

Um JSON.NET (Newtonsoft.Json) für die Serialisierung zu verwenden, installieren Sie das paket Microsoft.Azure.Core.NewtonsoftJson. Weisen Sie dann in Ihrer Dienstregistrierung die Serializer Eigenschaft für die WorkerOptions Konfiguration neu zu. Das folgende Beispiel zeigt diese Konfiguration mithilfe von ConfigureFunctionsWebApplication, es funktioniert jedoch auch mit ConfigureFunctionsWorkerDefaults.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.Configure<WorkerOptions>(workerOptions =>
    {
        var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
        settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
        settings.NullValueHandling = NullValueHandling.Ignore;

        workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
    });

builder.Build().Run();

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

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication((IFunctionsWorkerApplicationBuilder builder) =>
    {
        builder.Services.Configure<WorkerOptions>(workerOptions =>
        {
            var settings = NewtonsoftJsonObjectSerializer.CreateJsonSerializerSettings();
            settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
            settings.NullValueHandling = NullValueHandling.Ignore;

            workerOptions.Serializer = new NewtonsoftJsonObjectSerializer(settings);
        });
    })
    .Build();

host.Run();

Methoden, die als Funktionen erkannt werden

Eine Funktionsmethode ist eine öffentliche Methode einer öffentlichen Klasse mit einem Function-Attribut, das auf die Methode angewendet wird, und einem Trigger-Attribut, das auf einen Ausgabeparameter angewendet wird. Dies wird im folgenden Beispiel veranschaulicht:

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Das Trigger-Attribut gibt den Triggertyp an und bindet die Eingabedaten an einen Methodenparameter. Die obige Beispielfunktion wird durch eine Warteschlangennachricht ausgelöst, und die Warteschlangennachricht wird an die Methode im myQueueItem Parameter übergeben.

Das Attribut Function kennzeichnet die Methode als Funktionseinstiegspunkt. Der Name muss innerhalb eines project eindeutig sein, mit einem Buchstaben beginnen und nur Buchstaben, Zahlen, _ und - enthalten, bis zu 127 Zeichen lang. Project Vorlagen erstellen häufig eine Methode namens Run, aber der Methodenname kann ein beliebiger gültiger C#-Methodenname sein. Die Methode muss ein öffentliches Element einer öffentlichen Klasse sein. Es sollte im Allgemeinen eine Instanzmethode sein, damit Dienste über Abhängigkeitsinjektion übergeben werden können.

Funktionsparameter

Hier sind Sie einige der Parameter, die Sie in eine Funktionsmethodensignatur einschließen können:

• Bindungen, die entsprechend gekennzeichnet werden, indem die Parameter als Attribute dargestellt werden. Die Funktion muss genau einen Triggerparameter enthalten.
• Ein Ausführungskontextobjekt, das Informationen zum aktuellen Aufruf bereitstellt.
• Ein Abbruchtoken, das für das ordnungsgemäße Herunterfahren verwendet wird.

Ausführungskontext

Im isolierten Arbeitsmodell übergibt der Arbeitsprozess ein FunctionContextobjekt an die Funktionsmethoden. Mit diesem Objekt können Sie eine ILogger-Instanz abrufen, um in die Protokolle zu schreiben, indem Sie die GetLogger-Methode aufrufen und eine categoryNamezeichenfolge bereitstellen. Sie können diesen Kontext verwenden, um eine ILogger-Instanz zu erhalten, ohne die Abhängigkeitsinjektion verwenden zu müssen. Weitere Informationen siehe Logging.

Abbruchtoken

Eine Funktion kann einen cancellationToken-Parameter akzeptieren, mit dem das Betriebssystem Ihren Code benachrichtigen kann, wenn die Funktion beendet werden soll. Sie können diese Benachrichtigung verwenden, um sicherzustellen, dass die Funktion nicht auf eine Weise unerwartet beendet wird, die die Daten in einem inkonsistenten Zustand hinterlässt.

.NET Funktionen, die in einem isolierten Arbeitsprozess ausgeführt werden, unterstützen Abbruchtoken. Im folgenden Beispiel wird eine Ausnahme ausgelöst, wenn eine Abbruchanforderung empfangen wird:

[Function(nameof(ThrowOnCancellation))]
public async Task ThrowOnCancellation(
    [EventHubTrigger("sample-workitem-1", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(ThrowOnCancellation));

    foreach (var message in messages)
    {
        cancellationToken.ThrowIfCancellationRequested();
        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

Im folgenden Beispiel werden Bereinigungsaktionen ausgeführt, wenn eine Abbruchanforderung empfangen wird:

[Function(nameof(HandleCancellationCleanup))]
public async Task HandleCancellationCleanup(
    [EventHubTrigger("sample-workitem-2", Connection = "EventHubConnection")] string[] messages,
    FunctionContext context,
    CancellationToken cancellationToken)
{
    _logger.LogInformation("C# EventHub {functionName} trigger function processing a request.", nameof(HandleCancellationCleanup));

    foreach (var message in messages)
    {
        if (cancellationToken.IsCancellationRequested)
        {
            _logger.LogInformation("A cancellation token was received, taking precautionary actions.");
            // Take precautions like noting how far along you are with processing the batch
            _logger.LogInformation("Precautionary activities complete.");
            break;
        }

        await Task.Delay(6000); // task delay to simulate message processing
        _logger.LogInformation("Message '{msg}' was processed.", message);
    }
}

Szenarien, die zu einer Stornierung führen

Das Abbruchtoken wird signalisiert, wenn der Funktionsaufruf abgebrochen wird. Mehrere Gründe können zu einem Abbruch führen, und diese Gründe variieren je nach verwendetem Triggertyp. Häufige Gründe:

• Trennung des Clients: Der Client, der Ihre Funktion aufruft, trennt die Verbindung. Dies liegt höchstwahrscheinlich an den HTTP-Triggerfunktionen.
• Funktions-App-Neustart: Sie oder die Plattform starten (oder beenden) die Funktions-App um die gleiche Zeit, wenn ein Aufruf angefordert wird. Ein Neustart kann aufgrund von Arbeitsinstanzbewegungen, Aktualisierungen der Arbeitsinstanz oder Skalierung auftreten.

Überlegungen zur Kündigung

• Aufrufe, die während eines Neustarts ausgeführt werden, können je nachdem, wie sie ausgelöst wurden, erneut ausgeführt werden. Weitere Informationen finden Sie in der Wiederholungsdokumentation.

• Der Host sendet den Aufruf an den Worker , selbst wenn das Abbruchtoken storniert wird, bevor der Host in der Lage ist, die Aufrufanforderung an den Worker zu senden.

• Wenn Sie nicht möchten, dass vorab abgebrochene Aufrufe an den Worker gesendet werden, fügen Sie Ihrer SendCanceledInvocationsToWorker-Datei die Eigenschaft host.json hinzu, um dieses Verhalten zu deaktivieren.

  Dieses Beispiel zeigt eine host.json Datei, die diese Eigenschaft verwendet:

  {
      "version": "2.0",
      "SendCanceledInvocationsToWorker": "false"
  }
  

• Das Festlegen von SendCanceledInvocationsToWorker auf false könnte zu einer FunctionInvocationCanceled Ausnahme mit dem folgenden Log führen:

  Die Stornierung wurde angefordert. Die Aufrufanforderung mit der ID "{invocationId}" wird abgebrochen und wird nicht an den Worker gesendet.

  Diese Ausnahme tritt auf, wenn das Abbruchtoken abgebrochen wird (aufgrund eines der zuvor beschriebenen Ereignisse), bevor der Host eine eingehende Aufrufanforderung an den Worker sendet. Diese Ausnahme kann sicher ignoriert werden und wird erwartet, wenn SendCanceledInvocationsToWorkerfalse ist.

Asynchrone Programmierung

Der .NET isolierte Worker legt keinen benutzerdefinierten SynchronizationContext fest. Dies bedeutet, dass SynchronizationContext.Currentnull während der Funktionsausführung ist. Nach einem await werden Fortsetzungen im Thread-Pool geplant, was dem Standardverhalten von .NET entspricht.

Da es kein SynchronizationContext zu unterdrücken gibt, hat die Verwendung von ConfigureAwait(false) in Ihrem Funktionscode keine praktische Wirkung. Der isolierte Arbeitsprozess wird als Standard-.NET generischen Host (Konsolen-App) ausgeführt, sodass hier das gleiche asynchrone/await-Verhalten wie in jeder ASP.NET Core- oder Konsolenanwendung zu erwarten ist. Dies gilt auch für isolierte Worker-Apps des .NET Framework (net48), da der Worker-Prozess immer eine Konsolenanwendung mit HostBuilder ist.

Bindungen

Definieren Sie Bindungen mithilfe von Attributen für Methoden, Parameter und Rückgabetypen. Bindungen können Daten in Form von Zeichenfolgen, Arrays und serialisierbare Typen, beispielsweise Plain Old CLR Objects (POCOs) bieten. Bei einigen Bindungserweiterungen können Sie auch eine Bindung an dienstspezifische Typen vornehmen, die in Dienst-SDKs definiert sind.

Informationen zu HTTP-Triggern finden Sie im Abschnitt HTTP-Trigger.

Eine vollständige Reihe von Referenzbeispielen, die Trigger und Bindungen mit isolierten Arbeitsprozessfunktionen verwenden, finden Sie im Referenzbeispiel für bindungserweiterungen.

Eingabebindungen

Eine Funktion kann null oder mehr Eingabebindungen aufweisen, die Daten an die Funktion übergeben. Wie Trigger definieren Sie Eingabebindungen, indem Sie ein Bindungsattribut auf einen Eingabeparameter anwenden. Wenn die Funktion ausgeführt wird, versucht die Runtime, die in der Bindung angegebenen Daten abzurufen. Die angeforderten Daten hängen häufig von Informationen ab, die vom Trigger über Bindungsparameter bereitgestellt werden.

Ausgabebindungen

Um in eine Ausgabebindung zu schreiben, müssen Sie ein Ausgabebindungsattribut auf die Funktionsmethode anwenden. Dieses Attribut definiert, wie in den gebundenen Dienst geschrieben wird. Der Rückgabewert der Methode wird in die Ausgabebindung geschrieben. Im folgenden Beispiel wird ein Zeichenfolgenwert mithilfe einer Ausgabebindung in die Nachrichtenwarteschlange output-queue geschrieben:

[Function(nameof(QueueInputOutputFunction))]
[QueueOutput("output-queue")]
public string[] QueueInputOutputFunction([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

Mehrere Ausgabebindungen

Die Daten, die in eine Ausgabebindung geschrieben werden, sind immer der Rückgabewert der Funktion. Wenn Sie in mehr als eine Ausgabebindung schreiben müssen, müssen Sie einen benutzerdefinierten Rückgabetyp erstellen. Bei diesem Rückgabetyp muss das Ausgabebindungsattribut auf eine oder mehrere Eigenschaften der Klasse angewendet werden. Das folgende Beispiel ist eine HTTP-ausgelöste Funktion, die ASP.NET Core integration verwendet und sowohl in die HTTP-Antwort als auch in eine Warteschlangenausgabebindung schreibt:

public class MultipleOutputBindings
{
    private readonly ILogger<MultipleOutputBindings> _logger;

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

    [Function("MultipleOutputBindings")]
    public MyOutputType Run([HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req)
    {
        _logger.LogInformation("C# HTTP trigger function processed a request.");
        var myObject = new MyOutputType
        {
            Result = new OkObjectResult("C# HTTP trigger function processed a request."),
            MessageText = "some output"
        };
        return myObject;
    }

    public class MyOutputType
    {
        [HttpResult]
        public IActionResult Result { get; set; }

        [QueueOutput("myQueue")]
        public string MessageText { get; set; }
    }
}

Wenn Sie benutzerdefinierte Rückgabetypen für mehrere Ausgabebindungen mit ASP.NET Core Integration verwenden, müssen Sie der Eigenschaft, die das Ergebnis bereitstellt, das attribut [HttpResult] hinzufügen. Das attribut HttpResult ist verfügbar, wenn SDK 1.17.3-preview2 oder höher verwendet wird zusammen mit version 3.2.0 oder höher der HTTP-Erweiterung und version 1.3.0 oder höher der ASP.NET Core Erweiterung.

SDK-Typen

Bei einigen dienstspezifischen Bindungstypen können Sie Bindungsdaten mithilfe von Typen von Dienst-SDKs und Frameworks bereitstellen. Diese Typen bieten Funktionen, die über das hinausgehen, was ein serialisiertes Zeichenfolgenobjekt oder ein einfaches CLR-Objekt (POCO) bereitstellen kann. Um die neueren Typen zu verwenden, aktualisieren Sie ihre project, um neuere Versionen von Kernabhängigkeiten zu verwenden.

Beim lokalen Testen von SDK-Typen auf Ihrem Computer müssen Sie auch Azure Functions Core Tools, Version 4.0.5000 oder höher, verwenden. Sie können Ihre aktuelle Version mithilfe des func --version Befehls überprüfen.

Jede Bindungserweiterung hat auch eine eigene Mindestversionsanforderung, die in den Referenzartikeln zur Erweiterung beschrieben wird. Diese Bindungserweiterungen unterstützen derzeit SDK-Typen:

Überlegungen zu SDK-Typen:

• Bei Verwendung von Bindungsausdrücken, die auf Triggerdaten basieren, können SDK-Typen für den Trigger selbst nicht verwendet werden.
• Für Ausgabeszenarien, in denen Sie möglicherweise einen SDK-Typ verwenden, erstellen und arbeiten Sie direkt mit SDK-Clients, anstatt eine Ausgabebindung zu verwenden.
• Der Azure Cosmos DB-Trigger verwendet den Azure Cosmos DB-Änderungsfeed und macht Änderungsfeedelemente als JSON-serialisierbare Typen verfügbar. Daher werden SDK-Typen für diesen Trigger nicht unterstützt.

HTTP-Trigger

HTTP-Trigger ermöglichen das Aufrufen einer Funktion durch eine HTTP-Anforderung. Sie können zwei verschiedene Ansätze verwenden:

• Ein ASP.NET Core-Integrationsmodell das für ASP.NET Core Entwickler vertraute Konzepte verwendet.
• Ein integriertes Modell, das keine zusätzlichen Abhängigkeiten erfordert und benutzerdefinierte Typen für HTTP-Anforderungen und -Antworten verwendet. Dieser Ansatz wird zur Abwärtskompatibilität mit vorherigen .NET isolierten Worker-Apps beibehalten.

ASP.NET Core-Integration

In diesem Abschnitt wird gezeigt, wie Sie mit den zugrunde liegenden HTTP-Anforderungs- und Antwortobjekten arbeiten, indem Sie Typen aus ASP.NET Core verwenden, einschließlich HttpRequest, HttpResponse und IActionResult. Dieses Modell ist nicht für Apps für .NET Framework verfügbar, die stattdessen das built-in-Modell verwenden sollte.

So aktivieren Sie ASP.NET Core Integration für HTTP:

1. Fügen Sie Ihrem Projekt einen Verweis auf das Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore Paket, Version 1.0.0 oder höher, hinzu.

2. Aktualisieren Sie Ihre project so, dass diese spezifischen Paketversionen verwendet werden:

   • Microsoft. Azure. Functions.Worker.Sdk, Version 1.11.0. oder höher.
   • Microsoft. Azure. Functions.Worker, Version 1.16.0 oder höher.

3. Aktualisieren Sie in Ihrer Datei Program.cs die Konfiguration des Host-Generators, um ConfigureFunctionsWebApplication() aufzurufen. Diese Methode ersetzt ConfigureFunctionsWorkerDefaults() , wenn Sie diese Methode andernfalls verwenden würden. Das folgende Beispiel zeigt ein minimales Setup ohne weitere Anpassungen:

   • IHostBuilder
   • IHostApplicationBuilder

   Hinweis

   Ihre Anwendung muss auf Version 2.0.0 oder höher von Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore verweisen, um die ASP.NET Core-Integration mit IHostApplicationBuilder zu verwenden.

   using Microsoft.Azure.Functions.Worker.Builder;
   using Microsoft.Extensions.Hosting;
   
   var builder = FunctionsApplication.CreateBuilder(args);
   
   builder.ConfigureFunctionsWebApplication();    
   
   builder.Build().Run();
   

4. Aktualisieren Sie alle vorhandenen http-ausgelösten Funktionen, um die ASP.NET Core Typen zu verwenden. Im folgenden Beispiel werden die standardmäßige HTTP-Anforderung (HttpRequest) sowie IActionResult für eine einfache Funktion vom Typ „hello, world“ verwendet:

   [Function("HttpFunction")]
   public IActionResult Run(
       [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
   {
       return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
   }
   

JSON-Serialisierung mit ASP.NET Core Integration

ASP.NET Core verfügt über eine eigene Serialisierungsebene und ist nicht von customizing general serialization configuration betroffen. Um das für Ihre HTTP-Trigger verwendete Serialisierungsverhalten anzupassen, müssen Sie einen .AddMvc()-Aufruf als Teil der Dienstregistrierung einschließen. Die zurückgegebene IMvcBuilder kann verwendet werden, um die Einstellungen der JSON-Serialisierung von ASP.NET Core zu ändern.

Sie können weiterhin HttpRequestData und HttpResponseData während der Verwendung der ASP.NET-Integration verwenden, obwohl es für die meisten Apps besser ist, stattdessen HttpRequest und IActionResult zu verwenden. Die Verwendung von HttpRequestData/HttpResponseData ruft nicht die ASP.NET Core Serialisierungsebene auf und basiert stattdessen auf der serialisierungskonfiguration general worker serialization für die App. Wenn ASP.NET Core Integration aktiviert ist, müssen Sie möglicherweise dennoch eine Konfiguration hinzufügen. Das Standardverhalten von ASP.NET Core besteht darin, synchrone E/A zu verbieten. ** Um einen benutzerdefinierten Serialisierer zu verwenden, der keine asynchrone E/A-Funktion unterstützt, wie zum Beispiel NewtonsoftJsonObjectSerializer, müssen Sie synchrone E/A für Ihre Anwendung aktivieren, indem Sie die Konfiguration KestrelServerOptions anpassen.

Das folgende Beispiel zeigt, wie SIE JSON.NET (Newtonsoft.Json) und das Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet-Paket für die Serialisierung mithilfe dieses Ansatzes konfigurieren:

using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Services.AddMvc().AddNewtonsoftJson();

// Only needed if using HttpRequestData/HttpResponseData and a serializer that doesn't support asynchronous IO
// builder.Services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true);

builder.Build().Run();

using Microsoft.AspNetCore.Server.Kestrel.Core;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
        services.AddMvc().AddNewtonsoftJson();

        // Only needed if using HttpRequestData/HttpResponseData and a serializer that doesn't support asynchronous IO
        // services.Configure<KestrelServerOptions>(options => options.AllowSynchronousIO = true);
    })
    .Build();
host.Run();

Integriertes HTTP-Modell

Im integrierten Modell übersetzt das System die eingehende HTTP-Anforderungsnachricht in ein HttpRequestDataobjekt, das an die Funktion übergeben wird. Dieses Objekt liefert die Anforderungsdaten wie Headers, Cookies, Identities, URL und optional eine Nachricht Body. Dieses Objekt stellt die HTTP-Anforderung dar, ist aber nicht direkt mit dem zugrunde liegenden HTTP-Listener oder der empfangenen Nachricht verbunden.

Ebenso gibt die Funktion ein HttpResponseData-Objekt zurück, das Daten bereitstellt, die zum Erstellen der HTTP-Antwort verwendet werden, einschließlich nachrichten StatusCode, Headers und optional eine Nachricht Body.

Das folgende Beispiel veranschaulicht die Verwendung von HttpRequestData und HttpResponseData:

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

Protokollierung

Sie können Protokolle mithilfe einer ILogger<T>- oder ILogger-Instanz schreiben. Sie können die Protokollierung über die Abhängigkeitsinjektion einer ILogger<T> oder eines ILoggerFactory abrufen:

public class MyFunction {
    
    private readonly ILogger<MyFunction> _logger;
    
    public MyFunction(ILogger<MyFunction> logger) {
        _logger = logger;
    }
    
    [Function(nameof(MyFunction))]
    public void Run([BlobTrigger("samples-workitems/{name}", Connection = "")] string myBlob, string name)
    {
        _logger.LogInformation($"C# Blob trigger function Processed blob\n Name: {name} \n Data: {myBlob}");
    }

}

Sie können den Logger auch aus einem FunctionContext-Objekt abrufen, das an Ihre Funktion übergeben wird. Rufen Sie GetLogger<T> oder GetLoggermethode auf, und übergeben Sie einen Zeichenfolgenwert, der den Namen für die Kategorie darstellt, in der die Protokolle geschrieben werden. Die Kategorie ist normalerweise der Name der spezifischen Funktion, aus der die Protokolle geschrieben werden. Weitere Informationen zu Kategorien finden Sie im Überwachungsartikel.

Verwenden Sie die Methoden von ILogger<T> und ILogger, um verschiedene Protokolliergrade wie LogWarning oder LogError zu schreiben. Weitere Informationen zu Protokollstufen finden Sie im Monitoring-Artikel. Sie können die Protokolliergrade für Ihrem Code hinzugefügte Komponenten anpassen, indem Sie Filter registrieren:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

// Registers IHttpClientFactory.
// By default this sends a lot of Information-level logs.
builder.Services.AddHttpClient();

// Disable IHttpClientFactory Informational logs.
// Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
builder.Logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    
builder.Build().Run();

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services =>
    {
        // Registers IHttpClientFactory.
        // By default this sends a lot of Information-level logs.
        services.AddHttpClient();
    })
    .ConfigureLogging(logging =>
    {
        // Disable IHttpClientFactory Informational logs.
        // Note -- you can also remove the handler that does the logging: https://github.com/aspnet/HttpClientFactory/issues/196#issuecomment-432755765 
        logging.AddFilter("System.Net.Http.HttpClient", LogLevel.Warning);
    })
    .Build();

Im Rahmen der Konfiguration Ihrer App in Program.cs können Sie auch definieren, auf welche Weise Fehler in Ihren Protokollen ausgelöst werden. Das Standardverhalten hängt vom Typ des verwendeten Generators ab.

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(builder => {}, options =>
    {
        options.EnableUserCodeException = true;
    })
    .Build();

host.Run();

Application Insights

Sie können Ihre isolierte Prozessanwendung so konfigurieren, dass Protokolle direkt an Application Insights gesendet werden. Diese Konfiguration ersetzt das Standardverhalten der Weiterleitung von Protokollen über den Host. Wenn Sie nicht Aspire verwenden, konfigurieren Sie die direkte Application Insights-Integration, da sie Ihnen die Kontrolle darüber gibt, wie diese Protokolle ausgegeben werden.

Die Integration von Application Insights ist in allen Setup-Umgebungen nicht standardmäßig aktiviert. Einige Vorlagen erstellen Functions Projekte mit den erforderlichen Paketen und auskommentiertem Startcode. Wenn Sie die Application Insights-Integration verwenden möchten, heben Sie die Kommentare in Program.cs und der Datei .csproj des Projekts auf. Im restlichen Abschnitt der Anleitung wird außerdem beschrieben, wie Sie die Integration aktivieren.

Wenn Ihre project Teil einer Aspire Orchestration ist, wird stattdessen OpenTelemetry für die Überwachung verwendet. Aktivieren Sie keine direkte Application Insights-Integration in Aspire-Projekte. Konfigurieren Sie stattdessen den Azure Monitor OpenTelemetry-Exporter als Teil des Service Defaults-Projekts. Wenn Ihr Funktionenprojekt die Application Insights-Integration in einem Aspire-Kontext verwendet, tritt beim Starten ein Anwendungsfehler auf.

Installieren von Paketen

Um Protokolle direkt aus Ihrem Code in Application Insights zu schreiben, fügen Sie in Ihrem project Verweise auf diese Pakete hinzu:

• Microsoft. Azure. Functions.Worker.ApplicationInsights, Version 1.0.0 oder höher.
• Microsoft.ApplicationInsights.WorkerService

Führen Sie die folgenden Befehle aus, um Ihrem Projekt diese Verweise hinzuzufügen.

dotnet add package Microsoft.ApplicationInsights.WorkerService
dotnet add package Microsoft.Azure.Functions.Worker.ApplicationInsights

Konfigurieren des Starts

Rufen Sie nach der Installation der Pakete AddApplicationInsightsTelemetryWorkerService() und ConfigureFunctionsApplicationInsights() während der Dienstkonfiguration in Ihrer Program.cs Datei auf, wie im folgenden Beispiel gezeigt:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Build().Run();

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
    
var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

Der Aufruf von ConfigureFunctionsApplicationInsights() fügt ein ITelemetryModule hinzu, das auf ein von Funktionen definiertes ActivitySource lauscht. Dieses Modul erstellt die Abhängigkeits-Telemetrie, die erforderlich ist, um verteiltes Tracing zu unterstützen. Weitere Informationen zu AddApplicationInsightsTelemetryWorkerService() und deren Verwendung finden Sie unter Application Insights for Worker Service applications.

Protokollierungsstufen verwalten

Der Rest der Anwendung funktioniert weiterhin mit ILogger und ILogger<T>. Standardmäßig fügt das Application Insights SDK jedoch einen Protokollierungsfilter hinzu, der die Protokollierung anweist, nur Warnungen und schwerwiegendere Protokolliergrade zu erfassen. Sie können Protokollstufen im isolierten Worker-Prozess auf eine der folgenden Weisen konfigurieren:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Logging.Services.Configure<LoggerFilterOptions>(options =>
    {
        LoggerFilterRule? defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
            == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
        if (defaultRule is not null)
        {
            options.Rules.Remove(defaultRule);
        }
    });

builder.Build().Run();

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

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .ConfigureLogging(logging =>
    {
        logging.Services.Configure<LoggerFilterOptions>(options =>
        {
            LoggerFilterRule? defaultRule = options.Rules.FirstOrDefault(rule => rule.ProviderName
                == "Microsoft.Extensions.Logging.ApplicationInsights.ApplicationInsightsLoggerProvider");
            if (defaultRule is not null)
            {
                options.Rules.Remove(defaultRule);
            }
        });
    })
    .Build();

host.Run();

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Azure.Functions.Worker": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.Services
    .AddApplicationInsightsTelemetryWorkerService()
    .ConfigureFunctionsApplicationInsights();

builder.Build().Run();

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

var host = new HostBuilder()
    .ConfigureAppConfiguration(config =>
    {
        config.SetBasePath(Directory.GetCurrentDirectory())
              .AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
              .AddEnvironmentVariables();
    })
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Azure.Functions.Worker": "Information"
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Weitere Informationen zum Konfigurieren der Protokollierung finden Sie unter Logging in .NET und Application Insights for Worker Service applications.

Leistungsoptimierungen

In diesem Abschnitt werden Optionen beschrieben, die Sie zum Verbessern der Leistung beim Kaltstart aktivieren können.

Im Allgemeinen sollte Ihre App die neuesten Versionen ihrer Kernabhängigkeiten verwenden. Aktualisieren Sie ihre project mindestens wie folgt:

1. Upgrade Microsoft. Azure. Functions.Worker auf Version 1.19.0 oder höher.
2. Upgrade Microsoft. Azure. Functions.Worker.Sdk auf Version 1.16.4 oder höher.
3. Fügen Sie einen Frameworkverweis auf Microsoft.AspNetCore.App hinzu, es sei denn, Ihre App zielt auf .NET Framework ab.

Der folgende Codeausschnitt zeigt diese Konfiguration im Kontext einer project Datei:

  <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.16.4" />
  </ItemGroup>

Platzhalter

Platzhalter sind eine Plattformfunktion, die den Kaltstart für Apps für .NET 6 oder höher verbessert. Um diese Optimierung zu verwenden, müssen Sie Platzhalter explizit aktivieren, indem Sie die folgenden Schritte ausführen:

1. Aktualisieren Sie Ihre project-Konfiguration so, dass die neuesten Abhängigkeitsversionen verwendet werden, wie im vorherigen Abschnitt beschrieben.

2. Legen Sie die WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED Anwendungseinstellung auf 1. Verwenden Sie diesen befehl az functionapp config appsettings set:

   az functionapp config appsettings set -g <groupName> -n <appName> --settings 'WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED=1'
   

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

3. Stellen Sie sicher, dass die eigenschaft netFrameworkVersion der Funktions-App dem Zielframework ihres project entspricht, das .NET 6 oder höher sein muss. Verwenden Sie diesen befehl az functionapp config set:

   az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>
   

   Ersetzen Sie in diesem Beispiel auch <framework> durch die entsprechende Versionszeichenfolge, z. B. v8.0, entsprechend Ihrer Zielversion von .NET.

4. Stellen Sie sicher, dass Ihre Funktions-App für die Verwendung eines 64-Bit-Prozesses konfiguriert ist. Verwenden Sie diesen befehl az functionapp config set:

   az functionapp config set -g <groupName> -n <appName> --use-32bit-worker-process false
   

Optimierter Executor

Der Funktions-Executor ist eine Komponente der Plattform, die die Ausführung von Aufrufen auslöst. Ab der Version 1.16.2 des SDK ist standardmäßig eine optimierte Version dieser Komponente aktiviert. Es ist keine weitere Konfiguration erforderlich.

ReadyToRun

Sie können ihre Funktions-App als ReadyToRun-Binärdateien kompilieren. ReadyToRun ist eine Form der Vorabkompilierung, die zur Optimierung der Startleistung beitragen und die Auswirkungen von Kaltstarts bei Ausführung in einem Verbrauchstarif reduzieren kann. ReadyToRun ist in .NET 6 und höheren Versionen verfügbar und erfordert version 4.0 oder höher der Azure Functions Laufzeit.

ReadyToRun erfordert, dass Sie das Projekt für die Laufzeitarchitektur der Hosting-App erstellen. Wenn diese Architekturen nicht übereinstimmen, tritt beim Starten deiner App ein Fehler auf. Wählen Sie Ihren Runtimebezeichner aus der folgenden Tabelle aus:

¹ Einige andere Leistungsoptimierungen sind 64-Bit-Apps vorbehalten.

Um zu überprüfen, ob ihr Windows app 32-Bit- oder 64-Bit-Version ist, führen Sie den folgenden CLI-Befehl aus, und ersetzen Sie <group_name> durch den Namen Ihrer Ressourcengruppe und <app_name> mit dem Namen Ihrer Anwendung. Die Ausgabe TRUE gibt an, dass die App eine 32-Bit-App ist, und FALSE gibt an, dass es sich um eine 64-Bit-App handelt.

 az functionapp config show -g <group_name> -n <app_name> --query "use32BitWorkerProcess"

Sie können Ihre Anwendung mit dem folgenden Befehl mit den gleichen Ersetzungen in eine 64-Bit-App ändern:

az functionapp config set -g <group_name> -n <app_name> --use-32bit-worker-process false`

Um Ihre project als ReadyToRun zu kompilieren, aktualisieren Sie die project Datei, indem Sie die Elemente <PublishReadyToRun> und <RuntimeIdentifier> hinzufügen. Das folgende Beispiel zeigt eine Konfiguration für die Veröffentlichung in einer Windows-64-Bit-Funktions-App.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
  <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  <RuntimeIdentifier>win-x64</RuntimeIdentifier>
  <PublishReadyToRun>true</PublishReadyToRun>
</PropertyGroup>

Wenn Sie die <RuntimeIdentifier> nicht als Teil der project-Datei festlegen möchten, können Sie diese Einstellung auch als Teil der Veröffentlichungsgeste selbst konfigurieren. Bei einer Windows 64-Bit-Funktions-App lautet beispielsweise der Befehl .NET CLI:

dotnet publish --runtime win-x64

Legen Sie in Visual Studio die Option Target Runtime im Veröffentlichungsprofil auf den richtigen Laufzeitbezeichner fest. Bei Verwendung des Standardwerts Portierbar wird ReadyToRun nicht verwendet.

Bereitstellen auf Azure Functions

Wenn Sie Ihr Funktionscode-Projekt auf Azure bereitstellen, muss es entweder in einer Function-App oder in einem Linux-Container ausgeführt werden. Sie müssen die Funktions-App und andere erforderliche Azure Ressourcen erstellen, bevor Sie Den Code bereitstellen.

Sie können Ihre Funktions-App auch in einem Linux-Container bereitstellen. Weitere Informationen finden Sie unter Working with containers and Azure Functions.

Erstellen Azure Ressourcen

Sie können Ihre Funktions-App und andere erforderliche Ressourcen in Azure erstellen, indem Sie eine der folgenden Methoden verwenden:

• Visual Studio: Visual Studio können während des Codeveröffentlichungsprozesses Ressourcen für Sie erstellen.
• Visual Studio Code: Visual Studio Code kann eine Verbindung mit Ihrem Abonnement herstellen, die von Ihrer App benötigten Ressourcen erstellen und dann Ihren Code veröffentlichen.
• Azure CLI: Verwenden Sie die Azure CLI, um die erforderlichen Ressourcen in Azure zu erstellen.
• Azure PowerShell: Verwenden Sie Azure PowerShell, um die erforderlichen Ressourcen in Azure zu erstellen.
• Deployment-Vorlagen: Verwenden Sie ARM-Vorlagen und Bicep-Dateien, um die Bereitstellung der erforderlichen Ressourcen für Azure zu automatisieren. Achten Sie darauf, dass Ihre Vorlage alle erforderlichen Einstellungen enthält.
• Azure portal: Erstellen Sie die erforderlichen Ressourcen im Azure portal.

Veröffentlichen der Anwendung

Nachdem Sie Ihre Funktions-App und andere erforderliche Ressourcen in Azure erstellt haben, stellen Sie das Codeprojekt mithilfe einer der folgenden Methoden in Azure bereit.

• Visual Studio: Einfache manuelle Bereitstellung während der Entwicklung.
• Visual Studio Code: Einfache manuelle Bereitstellung während der Entwicklung.
• Azure Functions Core Tools: Projektdatei über die Befehlszeile bereitstellen.
• Continuous Deployment: Nützlich für die laufende Wartung, häufig in einem Stagingslot.
• Bereitstellungsvorlagen: Sie können ARM-Vorlagen oder Bicep-Dateien verwenden, um Paketbereitstellungen zu automatisieren.

Weitere Informationen finden Sie unter Deployment-Technologien in Azure Functions.

Payload der Bereitstellung

Viele der Bereitstellungsmethoden verwenden ein ZIP-Archiv. Wenn Sie das ZIP-Archiv selbst erstellen, muss es der struktur folgen, die in diesem Abschnitt beschrieben ist. Wenn dies nicht der Fall ist, könnte Ihre App beim Start auf Fehler stoßen.

Die Payload der Bereitstellung sollte mit der Ausgabe eines dotnet publish-Befehls übereinstimmen, jedoch ohne den einschließenden übergeordneten Ordner. Das ZIP-Archiv sollte aus den folgenden Dateien erstellt werden:

• .azurefunctions/
• extensions.json
• functions.metadata
• host.json
• worker.config.json
• Ihre ausführbare Projektdatei (eine Konsolenanwendung)
• Andere unterstützende Dateien und Verzeichnisse in Peer-Konfiguration für diese ausführbare Datei

Der Buildprozess generiert diese Dateien, und Sie sollten sie nicht direkt bearbeiten.

Wenn Sie ein ZIP-Archiv für die Bereitstellung vorbereiten, komprimieren Sie nur den Inhalt des Ausgabeverzeichnisses, nicht das eingeschlossene Verzeichnis selbst. Wenn das Archiv in das aktuelle Arbeitsverzeichnis extrahiert wird, müssen die zuvor aufgeführten Dateien sofort sichtbar sein.

Bereitstellungsanforderungen

Um .NET Funktionen im isolierten Workermodell in Azure auszuführen, müssen Sie einige Anforderungen erfüllen. Die Anforderungen hängen vom Betriebssystem ab:

Wenn Sie Ihre Funktions-App in Azure mithilfe der Methoden im vorherigen Abschnitt erstellen, werden diese erforderlichen Einstellungen für Sie hinzugefügt. Wenn Sie diese Ressourcen mithilfe von ARM-Vorlagen oder Bicep-Dateien für die Automatisierung erstellen, müssen Sie sie in der Vorlage festlegen.

Aspire

Aspire ist ein vorgabebestimmter Stack, der die Entwicklung verteilter Systeme in Cloud-Systemen vereinfacht. Sie können isolierte Worker-Modellprojekte in Orchestrierungen in Aspire 13 einbeziehen. Weitere Informationen finden Sie unter Azure Functions mit Aspire.

Debuggen

Wenn Sie Visual Studio oder Visual Studio Code lokal verwenden, können Sie Ihr .NET-isoliertes Worker-Projekt wie gewohnt debuggen. Es gibt jedoch zwei Debugszenarien, die nicht wie erwartet funktionieren.

Remotedebugging mit Visual Studio

Da Ihre App mit isoliertem Workerprozess außerhalb der Functions-Runtime ausgeführt wird, müssen Sie den Remotedebugger an einen separaten Prozess anfügen. Weitere Informationen zum Debuggen mit Visual Studio finden Sie unter Remote Debugging.

Fehlersuche für .NET Framework

Wenn Ihre isolierten project auf .NET Framework 4.8 ausgerichtet sind, müssen Sie manuelle Schritte ausführen, um das Debuggen zu aktivieren. Diese Schritte sind nicht erforderlich, wenn Sie ein anderes Zielframework verwenden.

Ihre App sollte mit einem Aufruf von FunctionsDebugger.Enable(); als erster Vorgang beginnen. Dieser erfolgt in der Main()-Methode, bevor Sie einen HostBuilder initialisieren. Die Datei Program.cs sollte in etwa wie folgt aussehen:

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

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

            var host = FunctionsApplication
                .CreateBuilder(args)
                .Build();

            host.Run();
        }
    }
}

using System;
using System.Diagnostics;
using Microsoft.Extensions.Hosting;
using Microsoft.Azure.Functions.Worker;
using NetFxWorker;

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

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .Build();

            host.Run();
        }
    }
}

Als Nächstes müssen Sie sich mit einem .NET Framework-Debugger manuell an den Prozess anhängen. Visual Studio führt dies für isolierte Arbeitsprozess .NET Framework-Apps noch nicht automatisch aus, und die Operation "Debuggen starten" sollte vermieden werden.

Führen Sie im Verzeichnis Ihres Projekts (oder im Build-Ausgabeverzeichnis) Folgendes aus:

func host start --dotnet-isolated-debug

Dadurch wird Ihr Worker gestartet, und der Prozess wird mit der folgenden Meldung beendet:

Azure Functions .NET Worker (PID: <process id>) initialized in debug mode. Waiting for debugger to attach...

Dabei ist <process id> die ID für Ihren Workerprozess. Sie können jetzt Visual Studio verwenden, um sich manuell an einen Prozess anzuhängen. Anweisungen zu diesem Vorgang finden Sie unter Anfügen an einen ausgeführten Prozess.

Nachdem der Debugger angefügt wurde, wird die Prozessausführung fortgesetzt, und Sie können mit dem Debuggen beginnen.

Vorschau auf die .NET-Versionen

Vor einer allgemein verfügbaren Version kann eine .NET-Version in einem Preview- oder Go-livestatus veröffentlicht werden. Einzelheiten zu diesen Staaten finden Sie in der .NET offiziellen Supportrichtlinie.

Es könnte möglich sein, eine bestimmte Version eines lokalen Functions-Projekts als Ziel zu verwenden, aber Funktions-Apps, die in Azure gehostet werden, haben diese Version möglicherweise nicht verfügbar. Azure Functions können nur mit preview- oder Go-Live-Versionen verwendet werden, die in diesem Abschnitt aufgeführt sind.

Azure Functions funktioniert derzeit nicht mit "Preview" oder "Go-live" .NET Versionen. Eine Liste der allgemein verfügbaren Versionen, die Sie verwenden können, finden Sie unter unterstützten Versionen .

Verwenden eines .NET SDK in der Vorschauversion

Um Azure Functions mit einer Vorschauversion von .NET zu verwenden, müssen Sie Ihre project wie folgt aktualisieren:

1. Installieren der relevanten .NET SDK-Version in Ihrer Entwicklung
2. Ändern der Einstellung TargetFramework in Ihrer Datei .csproj

Wenn Sie zu Ihrer Funktions-App in Azure deployen, müssen Sie auch sicherstellen, dass das Framework der App bereitgestellt wird. Während des Vorschauzeitraums zeigen einige Tools und Erlebnisse die neue Vorschauversion möglicherweise nicht als Option. Wenn die In der Azure portal enthaltene Vorschauversion nicht angezeigt wird, können Sie beispielsweise die REST-API, Bicep-Dateien oder die Azure CLI verwenden, um die Version manuell zu konfigurieren.

az functionapp config set -g <groupName> -n <appName> --net-framework-version <framework>

az functionapp config set -g <groupName> -n <appName> --linux-fx-version "dotnet-isolated|<version>"

Überlegungen zur Verwendung von .NET Vorschauversionen

Beachten Sie diese Überlegungen bei der Verwendung von Funktionen mit Vorschauversionen von .NET:

• Wenn Sie Ihre Funktionen in Visual Studio erstellen, müssen Sie Visual Studio Insider verwenden, die das Erstellen von Azure Functions Projekten mit .NET Vorschau-SDKs unterstützt.

• Achten Sie darauf, dass Sie über die neuesten Functions-Tools und -Vorlagen verfügen. So aktualisieren Sie Ihre Tools

  1. Navigieren Sie zu Tools>Options, wählen Sie Azure Functions unter Projects and Solutions>Mehr Einstellungen aus.
  2. Wählen Sie Nach Updates suchen aus, und installieren Sie Updates, wenn Sie dazu aufgefordert werden.

• Während eines Vorschauzeitraums verfügt Ihre Entwicklungsumgebung möglicherweise über eine aktuellere Version der .NET Vorschau als der gehostete Dienst. Dies kann dazu führen, dass Ihre Funktions-App nicht funktioniert, wenn sie bereitgestellt wird. Um dieses Problem zu beheben, können Sie in global.json die zu verwendende SDK-Version angeben.

  1. Führen Sie den Befehl dotnet --list-sdks aus, und notieren Sie sich die Vorschauversion, die Sie derzeit bei der lokalen Entwicklung verwenden.
  2. Führen Sie den Befehl dotnet new globaljson --sdk-version <SDK_VERSION> --force aus. <SDK_VERSION> ist hierbei die lokal verwendete Version. Beispielsweise bewirkt dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force, dass das System beim Erstellen ihrer project das .NET 10 Preview 5 SDK verwendet.

Nächste Schritte