Handleiding voor het uitvoeren van C# Azure Functions in het geïsoleerde werkrolmodel

In dit artikel maakt u kennis met het werken met Azure Functions in .NET met behulp van het geïsoleerde werkrolmodel. Met dit model kunnen uw projectdoelversies van .NET onafhankelijk van andere runtime-onderdelen worden gebruikt. Zie de ondersteunde versie voor informatie over specifieke ondersteunde .NET-versies.

Gebruik de volgende koppelingen om meteen aan de slag te gaan met het bouwen van .NET geïsoleerde werkrolmodelfuncties.

Zie Implementeren in Azure Functions voor meer informatie over het implementeren van een geïsoleerd werkmodelproject in Azure.

Voordelen van het geïsoleerde werkrolmodel

U kunt uw .NET-klassebibliotheekfuncties in twee modi uitvoeren: in hetzelfde proces als de Functions-hostruntime (in-process) of in een geïsoleerd werkproces. Wanneer uw .NET-functies worden uitgevoerd in een geïsoleerd werkproces, kunt u profiteren van de volgende voordelen:

• Minder conflicten: Omdat uw functies in een afzonderlijk proces worden uitgevoerd, conflicteren assembly's die in uw app worden gebruikt niet met verschillende versies van dezelfde assembly's die door het hostproces worden gebruikt.
• Volledig beheer van het proces: u beheert het opstarten van de app, wat betekent dat u de gebruikte configuraties en de middleware kunt beheren.
• Standaardinjectie van afhankelijkheid: Omdat u volledige controle over het proces hebt, kunt u huidig .NET-gedrag gebruiken voor afhankelijkheidsinjectie en middleware opnemen in uw functie-app.
• Flexibiliteit van .NET-versie: Het uitvoeren buiten het hostproces betekent dat uw functies kunnen draaien op versies van .NET die niet native door de Functions-runtime worden ondersteund, waaronder het .NET Framework.

Als u een bestaande C#-functie-app hebt die in het proces wordt uitgevoerd, moet u uw app migreren om te profiteren van deze voordelen. Zie .NET-apps van het procesmodel migreren naar het geïsoleerde werkrolmodel voor meer informatie.

Zie Verschillen tussen in-proces en isolate werkproces .NET Azure Functions voor een uitgebreide vergelijking tussen de twee modi.

Ondersteunde versies

Versies van de Functions-runtime ondersteunen specifieke versies van .NET. Zie het overzicht van runtimeversies van Azure Functions voor meer informatie over Functions-versies. Versieondersteuning is ook afhankelijk van of uw functies in proces of geïsoleerd werkproces worden uitgevoerd.

In de volgende tabel ziet u het hoogste niveau van .NET of .NET Framework dat kan worden gebruikt met een specifieke versie van Functions.

¹ .NET 6 werd eerder ondersteund op beide modellen, maar bereikte het einde van de officiële ondersteuning op 12 november 2024. .NET 7 werd eerder ondersteund op het geïsoleerde werkrolmodel, maar bereikte het einde van de officiële ondersteuning op 14 mei 2024.

² Voor het buildproces is ook de .NET SDK vereist.

³ Ondersteuning eindigt op versie 1.x van de Azure Functions-runtime op 14 september 2026. Zie deze ondersteuningsaankondiging voor meer informatie. Voor continue volledige ondersteuning moet u uw apps migreren naar versie 4.x.

⁴ Ondersteuning eindigt op het procesmodel op 10 november 2026. Zie deze ondersteuningsaankondiging voor meer informatie. Voor voortdurende volledige ondersteuning dient u uw apps te migreren naar het geïsoleerde werkermodel.

⁵ U kunt .NET 10-apps niet uitvoeren in Linux in het verbruiksabonnement. Als u linux wilt uitvoeren, moet u in plaats daarvan het Flex Consumption-abonnement gebruiken. Zie Verbruiksabonnement-apps migreren naar het Flex Consumption-abonnement voor stapsgewijze instructies voor migratie.

Voor het laatste nieuws over Azure Functions-releases, waaronder het verwijderen van specifieke oudere versies, controleert u de Azure App Service-aankondigingen.

Projectstructuur

Een .NET-project voor Azure Functions dat gebruikmaakt van het geïsoleerde werkrolmodel is in feite een .NET-console-appproject dat is gericht op een ondersteunde .NET-runtime. De volgende bestanden zijn de basisbestanden die vereist zijn in een .NET-geïsoleerd project:

• C#-projectbestand (.csproj) dat het project en de afhankelijkheden definieert.
• Program.cs bestand dat het toegangspunt voor de app is.
• Codebestanden die uw functies definiëren.
• host.json bestand dat de configuratie definieert die wordt gedeeld door functies in uw project.
• local.settings.json bestand waarmee omgevingsvariabelen worden gedefinieerd die door uw project worden gebruikt wanneer ze lokaal op uw computer worden uitgevoerd.

Zie het .NET 8-voorbeeldproject en het .NET Framework 4.8-voorbeeldproject voor volledige voorbeelden.

Softwarepakketverwijzingen

Een .NET-project voor Azure Functions dat gebruikmaakt van het geïsoleerde werkrolmodel, maakt gebruik van een unieke set pakketten voor zowel kernfunctionaliteit als bindingsextensies.

Kernpakketten

Als u uw .NET-functies wilt uitvoeren in een geïsoleerd werkproces, hebt u de volgende pakketten nodig:

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

De minimale versies van deze pakketten zijn afhankelijk van uw .NET-doelversie:

Versie 2.x

De 2.x-versies van de kernpakketten veranderen de ondersteunde frameworks en bieden ondersteuning voor nieuwe .NET-API's uit deze latere versies. Let op de volgende wijzigingen bij het bijwerken naar de 2.x-versies:

• Vanaf versie 2.0.0 van Microsoft.Azure.Functions.Worker.Sdk:
  • De SDK bevat standaardconfiguraties voor SDK-container-builds.
  • De SDK bevat ondersteuning voor dotnet run wanneer de Azure Functions Core Tools is geïnstalleerd. Installeer de Core Tools in Windows via een ander mechanisme dan NPM.
• Vanaf versie 2.0.0 van Microsoft.Azure.Functions.Worker:
  • Met deze versie wordt ondersteuning toegevoegd voor IHostApplicationBuilder. Enkele voorbeelden in deze handleiding zijn tabbladen om alternatieven weer te geven met behulp van IHostApplicationBuilder. Voor deze voorbeelden zijn de 2.x-versies vereist.
  • Bereikvalidatie van serviceproviders wordt standaard opgenomen als deze wordt uitgevoerd in een ontwikkelomgeving. Dit gedrag komt overeen met ASP.NET Core.
  • De EnableUserCodeException optie is standaard ingeschakeld. De eigenschap is nu aangemerkt als overbodig.
  • De IncludeEmptyEntriesInMessagePayload optie is standaard ingeschakeld. Als deze optie is ingeschakeld, bevatten payloads die verzamelingen vertegenwoordigen altijd lege vermeldingen. Als een bericht bijvoorbeeld zonder hoofdtekst wordt verzonden, is er nog steeds een lege vermelding aanwezig string[] voor de triggergegevens. Het opnemen van lege vermeldingen vergemakkelijkt kruisverwijzingen met metagegevensmatrices waarnaar de functie ook kan verwijzen. U kunt dit gedrag uitschakelen door IncludeEmptyEntriesInMessagePayload op false in te stellen in de serviceconfiguratie WorkerOptions.
  • De naam van de ILoggerExtensions klasse wordt gewijzigd in FunctionsLoggerExtensions. De naamswijziging voorkomt een dubbelzinnige aanroepfout bij het gebruik van LogMetric() op een ILogger exemplaar.
  • Voor apps die gebruikmaken HttpResponseDatavan de WriteAsJsonAsync() methode wordt de statuscode niet meer ingesteld op 200 OK. In 1.x overschrijft dit gedrag andere foutcodes die u instelt.
• De 2.x-versies verwijderen .NET 5 TFM-ondersteuning.

Uitbreidingspakketten

Omdat .NET geïsoleerde werkprocesfuncties verschillende bindingstypen gebruiken, hebben ze een unieke set bindingsuitbreidingspakketten nodig.

U vindt deze extensiepakketten onder Microsoft.Azure.Functions.Worker.Extensions.

Opstarten en configureren

Wanneer u het geïsoleerde werkrolmodel gebruikt, hebt u toegang tot het opstarten van uw functie-app, meestal in Program.cs. U bent verantwoordelijk voor het maken en starten van uw eigen hostexemplaren. Als zodanig hebt u ook directe toegang tot de configuratiepijplijn voor uw app. Met het geïsoleerde werkproces van .NET Functions kunt u eenvoudiger configuraties toevoegen, afhankelijkheden injecteren en uw eigen middleware uitvoeren.

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

Configuratie

Het type opbouwfunctie dat u gebruikt, bepaalt hoe u de toepassing configureert.

.ConfigureFunctionsWorkerDefaults()

Deze configuraties zijn alleen van toepassing op de worker-code die u schrijft. Ze zijn niet rechtstreeks van invloed op de configuratie van de Functions-host of triggers en bindingen. Als u wijzigingen wilt aanbrengen in de configuratie van de functieshost of trigger en binding, gebruikt u het host.json-bestand.

Afhankelijkheidsinjectie

Het geïsoleerde werkrolmodel maakt gebruik van standaard .NET-mechanismen voor het injecteren van services.

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

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

Voor deze code is vereist using Microsoft.Extensions.DependencyInjection;. Zie Afhankelijkheidsinjectie in ASP.NET Core voor meer informatie.

Azure-clients registreren

Gebruik afhankelijkheidsinjectie om te communiceren met andere Azure-services. U kunt clients uit de Azure SDK voor .NET injecteren met behulp van het pakket Microsoft.Extensions.Azure . Nadat u het pakket hebt geïnstalleerd, registreert u de clients door AddAzureClients() aan te roepen op de servicecollectie in Program.cs. In het volgende voorbeeld wordt een benoemde client geconfigureerd voor Azure Blobs:

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

In het volgende voorbeeld ziet u hoe u deze registratie- en SDK-typen kunt gebruiken om blob-inhoud te kopiëren als een stream van de ene container naar de andere met behulp van een geïnjecteerde client:

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

    }
}

Het ILogger<T> in dit voorbeeld wordt ook verkregen via afhankelijkheidsinjectie, dus deze wordt automatisch geregistreerd. Zie Logboekregistratie voor meer informatie over configuratieopties voor logboekregistratie.

Middleware

Het geïsoleerde werkrolmodel ondersteunt ook middlewareregistratie, opnieuw met behulp van een model dat lijkt op wat er in ASP.NET bestaat. Dit model biedt u de mogelijkheid om logica in de aanroepketen te injecteren en voor en nadat functies worden uitgevoerd.

De extensiemethode ConfigureFunctionsWorkerDefaults heeft een overbelasting waarmee u uw eigen middleware kunt registreren, zoals u in het volgende voorbeeld ziet.

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

De UseWhen extensiemethode registreert een middleware die voorwaardelijk wordt uitgevoerd. U moet een predicaat doorgeven dat een Booleaanse waarde retourneert aan deze methode. De middleware neemt deel aan de aanroepverwerkingspijplijn wanneer het predicaat terugkeert true.

Met de volgende uitbreidingsmethoden in FunctionContext kunt u eenvoudiger werken met middleware in het geïsoleerde model.

In dit voorbeeld ziet u een middleware-implementatie die het HttpRequestData exemplaar leest en het exemplaar bijwerkt tijdens de uitvoering van de HttpResponseData functie:

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

Met deze middleware wordt gecontroleerd op de aanwezigheid van een specifieke aanvraagheader (x-correlationId). Wanneer de koptekst aanwezig is, gebruikt de middleware de headerwaarde om een antwoordheader te stempelen. Anders wordt er een nieuwe GUID-waarde gegenereerd en wordt die waarde gebruikt voor het stempelen van de antwoordheader.

Zie het voorbeeld van een aangepaste middleware in uw functie-app voor een volledig voorbeeld van het gebruik van aangepaste middleware.

JSON-serialisatie aanpassen

Het geïsoleerde werkrolmodel gebruikt System.Text.Json standaard. U kunt het gedrag van de serializer aanpassen door services te configureren als onderdeel van uw Program.cs bestand. Deze sectie heeft betrekking op serialisatie voor algemeen gebruik en heeft geen invloed op JSON-serialisatie van HTTP-triggers met ASP.NET Core-integratie, die u afzonderlijk moet configureren.

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

Als u JSON.NET (Newtonsoft.Json) wilt gebruiken voor serialisatie, installeert u het Microsoft.Azure.Core.NewtonsoftJson pakket. Wijs vervolgens in uw serviceregistratie de Serializer eigenschap opnieuw toe aan de WorkerOptions configuratie. In het volgende voorbeeld ziet u deze configuratie met behulp van ConfigureFunctionsWebApplication, maar het werkt ook voor 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 worden herkend als functies

Een functiemethode is een openbare methode van een openbare klasse met een Function kenmerk dat is toegepast op de methode en een triggerkenmerk dat is toegepast op een invoerparameter, zoals wordt weergegeven in het volgende voorbeeld:

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

Het triggerkenmerk geeft het triggertype op en koppelt invoergegevens aan een methodeparameter. De voorgaande voorbeeldfunctie wordt geactiveerd door een wachtrijbericht en het wachtrijbericht wordt doorgegeven aan de methode in de myQueueItem parameter.

Het Function kenmerk markeert de methode als een functieinvoerpunt. De naam moet uniek zijn binnen een project, beginnen met een letter en mag alleen letters, cijfers _en -maximaal 127 tekens lang zijn. Projectsjablonen maken vaak een methode met de naam Run, maar de naam van de methode kan elke geldige C#-methodenaam zijn. De methode moet een openbaar lid van een openbare klasse zijn. Het moet over het algemeen een instantiemethode zijn, zodat services kunnen worden doorgegeven via afhankelijkheidsinjectie.

Functieparameters

Hier volgen enkele parameters die u kunt opnemen als onderdeel van een functiemethodehandtekening:

• Bindingen, die als zodanig worden gemarkeerd door de parameters als kenmerken te decoreren. De functie moet precies één triggerparameter bevatten.
• Een uitvoeringscontextobject dat informatie biedt over de huidige aanroep.
• Een annuleringstoken dat wordt gebruikt voor een probleemloos afsluiten.

Uitvoeringscontext

In het geïsoleerde werkrolmodel geeft het werkproces een FunctionContext-object door aan uw functiemethoden. Met dit object kunt u een ILogger exemplaar ophalen om naar de logboeken te schrijven door de GetLogger-methode aan te roepen en een categoryName tekenreeks op te geven. U kunt deze context gebruiken om een ILogger te verkrijgen zonder afhankelijkheidsinjectie te gebruiken. Zie Logboekregistratievoor meer informatie.

Annuleringstokens

Een functie kan een cancellationToken-parameter accepteren, waardoor het besturingssysteem uw code kan melden wanneer de functie op het punt staat te worden beëindigd. U kunt deze melding gebruiken om ervoor te zorgen dat de functie niet onverwacht wordt beëindigd op een manier die gegevens in een inconsistente status laat.

.NET-functies die worden uitgevoerd in een geïsoleerd werkproces ondersteunen annuleringstokens. In het volgende voorbeeld wordt een uitzondering gegenereerd wanneer een annuleringsaanvraag wordt ontvangen:

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

In het volgende voorbeeld worden opschoonacties uitgevoerd wanneer een annuleringsaanvraag wordt ontvangen:

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

Scenario's die leiden tot annulering

Het annuleringstoken wordt gesignaleerd wanneer de aanroep van de functie wordt geannuleerd. Verschillende redenen kunnen leiden tot een annulering en deze redenen variëren, afhankelijk van het triggertype dat wordt gebruikt. Enkele veelvoorkomende redenen zijn:

• De verbinding met de client wordt verbroken: de client die uw functie aanroept, wordt verbroken. Deze reden is waarschijnlijk voor HTTP-triggerfuncties.
• Functie-app wordt opnieuw opgestart: u of het platform start de functie-app opnieuw of stopt deze rond het moment dat een aanroep wordt aangevraagd. Een herstart kan optreden als gevolg van werkexemplaarverplaatsingen, werkexemplaarupdates of opschalen.

Overwegingen bij annulering

• Tijdens een herstart kunnen aanroepen opnieuw worden uitgevoerd, afhankelijk van hoe ze zijn geactiveerd. Zie de documentatie voor opnieuw proberen voor meer informatie.

• De host verzendt de aanroep naar de werknemer zelfs als het annuleringstoken wordt geannuleerd voordat de host de aanvraag naar de werknemer kan verzenden.

• Als u niet wilt dat vooraf geannuleerde aanroepen naar de worker worden verzonden, voegt u de SendCanceledInvocationsToWorker eigenschap toe aan uw host.json bestand om dit gedrag uit te schakelen.

  In dit voorbeeld ziet u een host.json bestand dat gebruikmaakt van deze eigenschap:

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

• Het instellen van SendCanceledInvocationsToWorker op false kan leiden tot een FunctionInvocationCanceled-uitzondering met de volgende log:

  Annulering is aangevraagd. De aanroepverzoek met id {invocationId} wordt geannuleerd en zal niet naar de werker worden verzonden.

  Deze uitzondering treedt op wanneer het annuleringstoken wordt geannuleerd (als gevolg van een van de eerder beschreven gebeurtenissen) voordat de host een binnenkomende aanroepaanvraag naar de worker verzendt. Deze uitzondering kan veilig worden genegeerd en wordt verwacht indien SendCanceledInvocationsToWorkerfalse is.

Verbindingen

Bindingen definiëren met behulp van kenmerken voor methoden, parameters en retourtypen. Bindingen kunnen gegevens bieden als tekenreeksen, matrices en serialiseerbare typen, zoals gewone oude klasseobjecten (POCO's). Voor sommige bindingsextensies kunt u ook verbinding maken met servicespecifieke typen die zijn gedefinieerd in service-SDK's.

Zie de sectie HTTP-trigger voor HTTP-triggers.

Zie het referentievoorbeeld voor bindingsextensies voor een volledige set referentievoorbeelden die gebruikmaken van triggers en bindingen met geïsoleerde werkprocesfuncties.

Invoerbindingen

Een functie kan nul of meer invoerbindingen hebben die gegevens doorgeven aan de functie. Net als triggers definieert u invoerbindingen door een bindingskenmerk toe te passen op een invoerparameter. Wanneer de functie wordt uitgevoerd, probeert de runtime gegevens op te halen die zijn opgegeven in de binding. De aangevraagde gegevens zijn vaak afhankelijk van informatie die door de trigger wordt verstrekt via bindingsparameters.

Uitvoerbindingen

Als u naar een uitvoerbinding wilt schrijven, moet u een uitvoerbindingskenmerk toepassen op de functiemethode. Met dit kenmerk wordt gedefinieerd hoe u naar de afhankelijke service schrijft. De retourwaarde van de methode wordt naar de uitvoerbinding geschreven. In het volgende voorbeeld wordt een tekenreekswaarde naar een berichtenwachtrij met de naam output-queue geschreven, gebruikmakend van een uitvoerbinding.

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

Meerdere uitvoerbindingen

De gegevens die naar een uitvoerbinding worden geschreven, zijn altijd de retourwaarde van de functie. Als u naar meer dan één uitvoerbinding moet schrijven, moet u een aangepast retourtype maken. Dit retourtype moet het uitvoerbindingskenmerk hebben toegepast op een of meer eigenschappen van de klasse. Het volgende voorbeeld is een HTTP-getriggerde functie die gebruikmaakt van ASP.NET Core-integratie en schrijft naar zowel het HTTP-antwoord als een wachtrijuitvoerbinding.

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

Wanneer u aangepaste retourtypen gebruikt voor meerdere uitvoerbindingen met ASP.NET Core-integratie, moet u het [HttpResult] kenmerk toevoegen aan de eigenschap die het resultaat levert. Het HttpResult kenmerk is beschikbaar wanneer u SDK 1.17.3-preview2 of hoger gebruikt, samen met versie 3.2.0 of hoger van de HTTP-extensie en versie 1.3.0 of hoger van de ASP.NET Core-extensie.

SDK-typen

Voor sommige servicespecifieke bindingstypen kunt u bindingsgegevens opgeven met behulp van typen van service-SDK's en frameworks. Deze typen bieden mogelijkheden die verder gaan dan wat een geserialiseerde tekenreeks of een eenvoudig oud CLR-object (POCO) kan bieden. Als u de nieuwere typen wilt gebruiken, werkt u uw project bij om nieuwere versies van kernafhankelijkheden te gebruiken.

Wanneer u SDK-typen lokaal op uw computer test, moet u ook Azure Functions Core Tools, versie 4.0.5000 of hoger gebruiken. U kunt uw huidige versie controleren met behulp van de func --version opdracht.

Elke bindingsextensie heeft ook een eigen minimale versievereiste, die wordt beschreven in de naslagartikelen voor extensies. Deze bindingsextensies ondersteunen momenteel SDK-typen:

Overwegingen voor SDK-typen:

• Wanneer u bindingexpressies gebruikt die afhankelijk zijn van triggergegevens, kunnen SDK-typen voor de trigger zelf niet worden gebruikt.
• Voor uitvoerscenario's waarbij u een SDK-type kunt gebruiken, maakt en werkt u rechtstreeks met SDK-clients in plaats van een uitvoerbinding.
• De Azure Cosmos DB-trigger maakt gebruik van de Azure Cosmos DB-wijzigingenfeed en maakt wijzigingenfeeditems beschikbaar als JSON-serialiseerbare typen. Hierdoor worden SDK-typen niet ondersteund voor deze trigger.

HTTP-trigger

Met HTTP-triggers kan een functie worden aangeroepen door een HTTP-aanvraag. U kunt twee verschillende benaderingen gebruiken:

• Een ASP.NET Core-integratiemodel dat gebruikmaakt van concepten die bekend zijn bij ASP.NET Core-ontwikkelaars
• Een ingebouwd model, waarvoor geen extra afhankelijkheden nodig zijn en aangepaste typen worden gebruikt voor HTTP-aanvragen en -antwoorden. Deze benadering wordt gehandhaafd voor compatibiliteit met oudere versies van eerdere .NET geïsoleerde apps.

ASP.NET Core-integratie

In deze sectie wordt beschreven hoe u met de onderliggende HTTP-aanvraag- en antwoordobjecten kunt werken met behulp van typen uit ASP.NET Core, waaronder HttpRequest, HttpResponse en IActionResult. Dit model is niet beschikbaar voor apps die gericht zijn op .NET Framework. In plaats daarvan moet het ingebouwde model worden gebruikt.

ASP.NET Core-integratie inschakelen voor HTTP:

1. Voeg een verwijzing in uw project toe aan het pakket Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore , versie 1.0.0 of hoger.

2. Werk uw project bij om deze specifieke pakketversies te gebruiken:

   • Microsoft.Azure.Functions.Worker.Sdk, versie 1.11.0. of hoger
   • Microsoft.Azure.Functions.Worker, versie 1.16.0 of hoger.

3. Werk in uw Program.cs bestand de configuratie van de hostbouwer bij om aan te roepen ConfigureFunctionsWebApplication(). Deze methode vervangt ConfigureFunctionsWorkerDefaults() als u die methode anders zou gebruiken. In het volgende voorbeeld ziet u een minimale installatie zonder andere aanpassingen:

   • IHostBuilder
   • IHostApplicationBuilder

   Opmerking

   Uw toepassing moet verwijzen naar versie 2.0.0 of hoger van Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore om ASP.NET Core-integratie met dit pakket te gebruiken.

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

4. Werk alle bestaande door HTTP geactiveerde functies bij om de ASP.NET Core-typen te gebruiken. In dit voorbeeld ziet u de standaard HttpRequest en een IActionResult functie die wordt gebruikt voor een eenvoudige 'hallo, wereld'-functie:

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

JSON-serialisatie met ASP.NET Core-integratie

ASP.NET Core een eigen serialisatielaag heeft en dit wordt niet beïnvloed door het aanpassen van de algemene serialisatieconfiguratie. Als u het serialisatiegedrag wilt aanpassen dat wordt gebruikt voor uw HTTP-triggers, moet u een .AddMvc() aanroep opnemen als onderdeel van de serviceregistratie. Het geretourneerde IMvcBuilder kan worden gebruikt om de JSON-serialisatie-instellingen van ASP.NET Core te wijzigen.

U kunt HttpRequestData en HttpResponseData blijven gebruiken in combinatie met ASP.NET-integratie, maar voor de meeste apps is het beter om in plaats daarvan HttpRequest en IActionResult te gebruiken. Het gebruik HttpRequestData/HttpResponseData roept de ASP.NET Core-serialisatielaag niet aan en is in plaats daarvan afhankelijk van de configuratie van de algemene werkrolserialisatie voor de app. Wanneer ASP.NET Core-integratie is ingeschakeld, moet u mogelijk nog steeds configuratie toevoegen. Het standaardgedrag van ASP.NET Core is om synchrone IO niet toe te staan. Als u een aangepaste serializer wilt gebruiken die geen asynchrone IO ondersteunt, zoals NewtonsoftJsonObjectSerializer, moet u synchrone IO voor uw toepassing inschakelen door KestrelServerOptions te configureren.

In het volgende voorbeeld ziet u hoe u JSON.NET (Newtonsoft.Json) en het NuGet-pakket Microsoft.AspNetCore.Mvc.NewtonsoftJson configureert voor serialisatie met behulp van deze methode:

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

Ingebouwd HTTP-model

In het ingebouwde model vertaalt het systeem het binnenkomende HTTP-aanvraagbericht in een HttpRequestData-object dat wordt doorgegeven aan de functie. Dit object biedt gegevens uit de aanvraag, waaronder Headers, Cookies, Identities, , en URLoptioneel een bericht Body. Dit object vertegenwoordigt de HTTP-aanvraag, maar is niet rechtstreeks verbonden met de onderliggende HTTP-listener of het ontvangen bericht.

Op dezelfde manier retourneert de functie een HttpResponseData-object , dat gegevens levert die worden gebruikt voor het maken van het HTTP-antwoord, inclusief bericht StatusCode, Headersen optioneel een bericht Body.

In het volgende voorbeeld ziet u het gebruik van HttpRequestData en 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;
}

Loggen

U kunt schrijven naar logboeken met behulp van een ILogger<T> of ILogger instantie. U kunt de logger ophalen via afhankelijkheidsinjectie van een ILogger<T> of van een ILoggerFactory:

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

}

U kunt de logboekregistratie ook ophalen uit een FunctionContext-object dat aan uw functie is doorgegeven. Roep de methode GetLogger<T> of GetLogger aan, waarbij een tekenreekswaarde wordt doorgegeven die de naam is voor de categorie waarin de logboeken worden geschreven. De categorie is meestal de naam van de specifieke functie waaruit de logboeken worden geschreven. Zie het bewakingsartikel voor meer informatie over categorieën.

Gebruik de methoden van ILogger<T> en ILogger om verschillende logboekniveaus te schrijven, zoals LogWarning of LogError. Zie het bewakingsartikel voor meer informatie over logboekniveaus. U kunt de logboekniveaus aanpassen voor onderdelen die aan uw code zijn toegevoegd door filters te registreren:

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

Als onderdeel van het configureren van uw app in Program.cs, kunt u ook het gedrag definiëren voor hoe fouten worden weergegeven in uw logboeken. Het standaardgedrag is afhankelijk van het type opbouwfunctie dat u gebruikt.

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

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

host.Run();

Analyses van toepassingen

U kunt uw geïsoleerde procestoepassing configureren om logboeken rechtstreeks naar Application Insights te verzenden. Deze configuratie vervangt het standaardgedrag van het doorsturen van logboeken via de host. Tenzij u Aspire gebruikt, configureert u directe Application Insights-integratie, omdat u hiermee kunt bepalen hoe deze logboeken worden verzonden.

Application Insights-integratie is niet standaard ingeschakeld in alle installatie-ervaringen. Sommige sjablonen maken Functions-projecten met de benodigde pakketten en de opstartcode uitgecommentarieerd. Als u Application Insights-integratie wilt gebruiken, moet u de commentaartags bij deze regels verwijderen in het Program.cs-bestand en het .csproj-bestand van het project. In de instructies in de rest van deze sectie wordt ook beschreven hoe u de integratie kunt inschakelen.

Als uw project deel uitmaakt van een Aspire-indeling, wordt in plaats daarvan OpenTelemetry gebruikt voor bewaking. Schakel directe Application Insights-integratie niet in binnen Aspire-projecten. Configureer in plaats daarvan de Azure Monitor OpenTelemetry-exporteur als onderdeel van het standaardproject van de service. Als uw Functions-project gebruikmaakt van Application Insights-integratie in een Aspire-context, treden er toepassingsfouten op bij het opstarten.

Pakketten installeren

Als u logboeken rechtstreeks vanuit uw code naar Application Insights wilt schrijven, voegt u verwijzingen toe naar deze pakketten in uw project:

• Microsoft.Azure.Functions.Worker.ApplicationInsights, versie 1.0.0 of hoger.
• Microsoft.ApplicationInsights.WorkerService.

Voer de volgende opdrachten uit om deze verwijzingen toe te voegen aan uw project:

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

Opstarten configureren

Nadat u de pakketten hebt geïnstalleerd, roept u AddApplicationInsightsTelemetryWorkerService() en ConfigureFunctionsApplicationInsights() aan tijdens de serviceconfiguratie in uw Program.cs bestand zoals wordt weergegeven in het volgende voorbeeld.

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

De aanroep naar ConfigureFunctionsApplicationInsights() voegt een ITelemetryModule toe die luistert naar een door Functions gedefinieerde ActivitySource. Met deze module maakt u de afhankelijkheidstelemetrie die is vereist ter ondersteuning van gedistribueerde tracering. Raadpleeg AddApplicationInsightsTelemetryWorkerService() voor meer informatie over en hoe u deze kunt gebruiken.

Logboekniveaus beheren

De rest van uw toepassing blijft werken met ILogger en ILogger<T>. Application Insights SDK voegt echter standaard een logboekregistratiefilter toe waarmee de logger alleen waarschuwingen en ernstigere logboeken vastlegt. U kunt logboekniveaus configureren in het geïsoleerde werkproces op een van de volgende manieren:

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

Zie Logboekregistratie in .NET en Application Insights voor Werkservicetoepassingen voor meer informatie over het configureren van logboekregistratie.

Prestatieoptimalisaties

In deze sectie vindt u een overzicht van de opties die u kunt inschakelen om de prestaties rond koude start te verbeteren.

Over het algemeen moet uw app gebruikmaken van de nieuwste versies van de belangrijkste afhankelijkheden. Werk uw project minimaal als volgt bij:

1. Upgrade Microsoft.Azure.Functions.Worker naar versie 1.19.0 of hoger.
2. Upgrade Microsoft.Azure.Functions.Worker.Sdk naar versie 1.16.4 of hoger.
3. Voeg een frameworkreferentie toe aan Microsoft.AspNetCore.App, tenzij uw app is gericht op .NET Framework.

In het volgende fragment ziet u deze configuratie in de context van een projectbestand:

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

Plaatsaanduidingen

Placeholders zijn een platformfunctie die de koude start verbetert voor apps die gericht zijn op .NET 6 of hoger. Als u deze optimalisatie wilt gebruiken, moet u tijdelijke aanduidingen expliciet inschakelen door de volgende stappen uit te voeren:

1. Werk de projectconfiguratie bij om de nieuwste afhankelijkheidsversies te gebruiken, zoals beschreven in de vorige sectie.

2. Stel de WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED toepassingsinstelling in op 1. Gebruik deze opdracht az functionapp config appsettings set :

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

   Vervang in dit voorbeeld door <groupName> de naam van de resourcegroep en vervang deze door <appName> de naam van uw functie-app.

3. Zorg ervoor dat de netFrameworkVersion eigenschap van de functie-app overeenkomt met het doelframework van uw project. Dit moet .NET 6 of hoger zijn. Gebruik deze opdracht az functionapp config set :

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

   Vervang in dit voorbeeld ook <framework> door de juiste versietekenreeks, zoals v8.0, volgens uw doel .NET-versie.

4. Zorg ervoor dat uw functie-app is geconfigureerd voor het gebruik van een 64-bits proces. Gebruik deze opdracht az functionapp config set :

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

Geoptimaliseerde uitvoerder

De functie-uitvoerder is een onderdeel van het platform dat ervoor zorgt dat aanroepen worden uitgevoerd. Een geoptimaliseerde versie van dit onderdeel is standaard ingeschakeld vanaf versie 1.16.2 van de SDK. Er is geen andere configuratie vereist.

ReadyToRun

U kunt uw functie-app compileren als binaire readyToRun-bestanden. ReadyToRun is een vorm van vooraf compilatie die de opstartprestaties kan verbeteren om het effect van koude starts te verminderen bij het uitvoeren in een Verbruiksabonnement. ReadyToRun is beschikbaar in .NET 6 en hoger en vereist versie 4.0 of hoger van de Azure Functions-runtime.

ReadyToRun vereist dat u het project bouwt op basis van de runtime-architectuur van de hosting-app. Wanneer deze architecturen niet zijn uitgelijnd, krijgt uw app een fout bij het opstarten. Selecteer uw runtime-id in deze tabel:

¹ Slechts 64-bits apps komen in aanmerking voor enkele andere prestatieoptimalisaties.

Als u wilt controleren of uw Windows-app 32-bits of 64-bits is, voert u de volgende CLI-opdracht uit en vervangt u <group_name> door de naam van uw resourcegroep en <app_name> door de naam van uw toepassing. Een uitvoer van 'true' geeft aan dat de app 32-bits is en 'false' 64-bits aangeeft.

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

U kunt uw toepassing wijzigen in 64-bits met de volgende opdracht, met dezelfde vervangingen:

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

Als u uw project wilt compileren als ReadyToRun, werkt u het projectbestand bij door de <PublishReadyToRun> en <RuntimeIdentifier> elementen toe te voegen. In het volgende voorbeeld ziet u een configuratie voor het publiceren naar een Windows 64-bits functie-app.

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

Als u het <RuntimeIdentifier> niet wilt instellen als onderdeel van het projectbestand, kunt u deze instelling ook configureren als onderdeel van de publicatieactie zelf. Met een Windows 64-bits functie-app is de .NET CLI-opdracht bijvoorbeeld:

dotnet publish --runtime win-x64

Stel in Visual Studio de optie Target Runtime in het publicatieprofiel in op de juiste runtime-id. Wanneer deze is ingesteld op de standaardwaarde portable, wordt ReadyToRun niet gebruikt.

Implementeren in Azure Functions

Wanneer u uw functiecodeproject in Azure implementeert, moet het worden uitgevoerd in een functie-app of in een Linux-container. U moet de functie-app en andere vereiste Azure-resources maken voordat u uw code implementeert.

U kunt uw functie-app ook implementeren in een Linux-container. Zie Werken met containers en Azure Functions voor meer informatie.

Azure-resources maken

U kunt uw functie-app en andere vereiste resources in Azure maken met behulp van een van de volgende methoden:

• Visual Studio: Visual Studio kan resources voor u maken tijdens het publicatieproces van code.
• Visual Studio Code: Visual Studio Code kan verbinding maken met uw abonnement, de benodigde resources voor uw app maken en vervolgens uw code publiceren.
• Azure CLI: Gebruik de Azure CLI om de vereiste resources in Azure te maken.
• Azure PowerShell: Gebruik Azure PowerShell om de vereiste resources in Azure te maken.
• Implementatiesjablonen: GEBRUIK ARM-sjablonen en Bicep-bestanden om de implementatie van de vereiste resources in Azure te automatiseren. Zorg ervoor dat uw sjabloon alle vereiste instellingen bevat.
• Azure Portal: Maak de vereiste resources in Azure Portal.

Uw toepassing publiceren

Nadat u uw functie-app en andere vereiste resources in Azure hebt gemaakt, implementeert u het codeproject in Azure met behulp van een van de volgende methoden:

• Visual Studio: Eenvoudige handmatige implementatie tijdens de ontwikkeling.
• Visual Studio Code: Eenvoudige handmatige implementatie tijdens de ontwikkeling.
• Azure Functions Core Tools: Projectbestand implementeren vanaf de opdrachtregel.
• Continue implementatie: handig voor doorlopend onderhoud, vaak naar een staging-site.
• Implementatiesjablonen: U kunt ARM-sjablonen of Bicep-bestanden gebruiken om pakketimplementaties te automatiseren.

Zie Implementatietechnologieën in Azure Functions voor meer informatie.

Nettolading van implementatie

Veel van de implementatiemethoden maken gebruik van een zip-archief. Als u het zip-archief zelf maakt, moet het de structuur volgen die in deze sectie wordt beschreven. Als dat niet het geval is, kan uw app bij het opstarten fouten ervaren.

De payload van de implementatie moet overeenkomen met de uitvoer van een dotnet publish commando, maar zonder de bovenliggende map. Het zip-archief moet worden gemaakt uit de volgende bestanden:

• .azurefunctions/
• extensions.json
• functions.metadata
• host.json
• worker.config.json
• Het uitvoerbare bestand van uw project (een console-app)
• Andere ondersteunende bestanden en mappen zijn gekoppeld aan dat uitvoerbare bestand

Het buildproces genereert deze bestanden en u moet ze niet rechtstreeks bewerken.

Bij het voorbereiden van een zip-archief voor implementatie comprimeert u alleen de inhoud van de uitvoermap, niet de map zelf. Wanneer het archief wordt geëxtraheerd in de huidige werkmap, moeten de eerder vermelde bestanden onmiddellijk zichtbaar zijn.

Implementatievereisten

Als u .NET-functies wilt uitvoeren in het geïsoleerde werkrolmodel in Azure, moet u aan een aantal vereisten voldoen. De vereisten zijn afhankelijk van het besturingssysteem:

Wanneer u uw functie-app in Azure maakt met behulp van de methoden in de vorige sectie, worden deze vereiste instellingen voor u toegevoegd. Wanneer u deze resources maakt met behulp van ARM-sjablonen of Bicep-bestanden voor automatisering, moet u deze instellen in de sjabloon.

Ambiëren

Aspire is een stack met een duidelijke visie die de ontwikkeling van gedistribueerde toepassingen in de cloud vereenvoudigt. U kunt geïsoleerde werkprojectmodellen opnemen in Aspire 13-orkestraties. Zie Azure Functions met Aspire voor meer informatie.

Fouten opsporen

Wanneer u lokaal werkt met Visual Studio of Visual Studio Code, kunt u fouten opsporen in uw geïsoleerde .NET-werkproject zoals normaal. Er zijn echter twee foutopsporingsscenario's die niet werken zoals verwacht.

Externe foutopsporing met Visual Studio

Omdat uw geïsoleerde werkproces-app buiten de Functions-runtime wordt uitgevoerd, moet u het externe foutopsporingsprogramma koppelen aan een afzonderlijk proces. Zie Externe foutopsporing voor meer informatie over foutopsporing met Visual Studio.

Foutopsporing bij het richten van .NET Framework

Als uw geïsoleerde project is gericht op .NET Framework 4.8, moet u handmatige stappen uitvoeren om foutopsporing in te schakelen. Deze stappen zijn niet vereist als u een ander doelframework gebruikt.

Uw app moet beginnen met een aanroep naar FunctionsDebugger.Enable(); als eerste bewerking. Dit gebeurt in de Main() methode voordat u een HostBuilder initialiseert. Uw Program.cs bestand moet er ongeveer als volgt uitzien:

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

Vervolgens moet u handmatig aan het proces koppelen met behulp van een .NET Framework-foutopsporingsprogramma. Visual Studio doet dit nog niet automatisch voor geïsoleerde werkproces .NET Framework-apps en de bewerking Foutopsporing starten moet worden vermeden.

Voer in uw projectmap (of de builduitvoermap) het volgende uit:

func host start --dotnet-isolated-debug

Hiermee start u uw werkproces, en het proces stopt met het volgende bericht:

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

Waar <process id> is de id voor uw werkproces. U kunt Visual Studio nu gebruiken om handmatig aan het proces te koppelen. Zie voor instructies over deze bewerking Hoe aan te sluiten op een actief proces.

Nadat het foutopsporingsprogramma is gekoppeld, wordt de procesuitvoering hervat en kunt u fouten opsporen.

Preview van .NET-versies

Voordat een algemeen beschikbare release wordt uitgebracht, kan een .NET-versie worden uitgebracht in een preview- of Go-live-status. Zie het officiële ondersteuningsbeleid van .NET voor meer informatie over deze statussen.

Hoewel het mogelijk is om een bepaalde release van een lokaal Functions-project te gebruiken, hebben functie-apps die in Azure worden gehost, die release mogelijk niet beschikbaar. Azure Functions kan alleen worden gebruikt met preview- of go-live-releases die in deze sectie worden vermeld.

Azure Functions werkt momenteel niet met 'Preview' of 'Go-live' .NET-releases. Zie Ondersteunde versies voor een lijst met algemeen beschikbare releases die u kunt gebruiken.

Een preview van .NET SDK gebruiken

Als u Azure Functions wilt gebruiken met een preview-versie van .NET, moet u uw project bijwerken door:

1. De relevante .NET SDK-versie installeren in uw ontwikkeling
2. TargetFramework De instelling in uw .csproj bestand wijzigen

Wanneer u implementeert in uw functie-app in Azure, moet u er ook voor zorgen dat het framework beschikbaar wordt gesteld voor de app. Tijdens de preview-periode kunnen sommige hulpprogramma's en ervaringen de nieuwe preview-versie mogelijk niet als optie weergeven. Als u de preview-versie niet ziet die is opgenomen in Azure Portal, kunt u bijvoorbeeld de REST API, Bicep-bestanden of de Azure CLI gebruiken om de versie handmatig te configureren.

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

Overwegingen voor het gebruik van .NET Preview-versies

Houd rekening met deze overwegingen bij het gebruik van Functions met preview-versies van .NET:

• Wanneer u uw functies in Visual Studio ontwerpt, moet u Visual Studio Insiders gebruiken, die ondersteuning biedt voor het bouwen van Azure Functions-projecten met .NET Preview SDK's.

• Zorg ervoor dat u beschikt over de nieuwste Functies-hulpprogramma's en -sjablonen. Uw hulpprogramma's bijwerken:

  1. Navigeer naar Extra>Opties, kies Azure Functions onder Projecten en Oplossingen>Meer Instellingen.
  2. Selecteer Controleren op updates en installeer updates zoals hierom wordt gevraagd.

• Tijdens een preview-periode heeft uw ontwikkelomgeving mogelijk een recentere versie van de .NET-preview dan de gehoste service. Dit kan ertoe leiden dat uw functie-app mislukt wanneer deze wordt geïmplementeerd. U kunt dit oplossen door de versie van de SDK op te geven die moet worden gebruikt in global.json.

  1. Voer de dotnet --list-sdks opdracht uit en noteer de preview-versie die u momenteel gebruikt tijdens lokale ontwikkeling.
  2. Voer de dotnet new globaljson --sdk-version <SDK_VERSION> --force opdracht uit, waar <SDK_VERSION> de versie is die u lokaal gebruikt. Zorgt er bijvoorbeeld dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force voor dat het systeem de .NET 10 Preview 5 SDK gebruikt bij het bouwen van uw project.

Volgende stappen