Delen via

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

  • Artikel

Dit artikel is een inleiding tot het werken met Azure Functions in .NET, met behulp van het geïsoleerde werkrolmodel. Met dit model kan uw project versies van .NET onafhankelijk van andere runtime-onderdelen targeten. 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.

Aan de slag Concepten Voorbeelden

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

Voordelen van het geïsoleerde werkrolmodel

Er zijn twee modi waarin u uw .NET-klassebibliotheekfuncties kunt uitvoeren: in hetzelfde proces als de Functions-hostruntime (in-proces) 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 afhankelijkheden: 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: als u buiten het hostproces wordt uitgevoerd, betekent dit dat uw functies kunnen worden uitgevoerd op versies van .NET die niet systeemeigen worden ondersteund door de Functions-runtime, met inbegrip van .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 proces- en isoleerproces .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.

Notitie

Zie de huidige runtimeversie weergeven en bijwerken voor meer informatie over het wijzigen van de runtimeversie van Functions die door uw functie-app wordt gebruikt.

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

Runtimeversie van Functions Geïsoleerde werkrolmodel In-process model4
Functions 4.x1 .NET 9.0
.NET 8.0
.NET Framework 4.82		 .NET 8.0
Functions 1.x3 n.v.t. .NET Framework 4.8

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

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

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

4 Ondersteuning eindigt op het procesmodel op 10 november 2026. Zie deze ondersteuningsaankondiging voor meer informatie. Voor continue volledige ondersteuning moet u uw apps migreren naar het geïsoleerde werkrolmodel.

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

Projectstructuur

Een .NET-project voor Azure Functions met behulp van het geïsoleerde werkrolmodel is in feite een .NET-console-appproject dat is gericht op een ondersteunde .NET-runtime. Hieronder vindt u 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.

Pakketverwijzingen

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

Kernpakketten

De volgende pakketten zijn vereist om uw .NET-functies uit te voeren in een geïsoleerd werkproces:

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. Wanneer u .NET 9 of hoger target, moet uw app verwijzen naar versie 2.0.0 of hoger van beide pakketten.

Let op de volgende wijzigingen bij het bijwerken naar de 2.x-versies:

  • Vanaf versie 2.0.0 van Microsoft.Azure.Functions.Worker.Sdk:
  • 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 gemarkeerd als verouderd.
    • De IncludeEmptyEntriesInMessagePayload optie is standaard ingeschakeld. Als deze optie is ingeschakeld, triggert u nettoladingen die verzamelingen vertegenwoordigen, altijd lege vermeldingen bevatten. 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 dit in te stellen IncludeEmptyEntriesInMessagePayload false in de WorkerOptions serviceconfiguratie.
    • De naam van de ILoggerExtensions klasse wordt gewijzigd in FunctionsLoggerExtensions. De naamswijziging voorkomt een dubbelzinnige aanroepfout bij het gebruik van LogMetric() een ILogger exemplaar.
    • Voor apps die worden gebruiktHttpResponseData, wordt de statuscode 200 OKniet meer ingesteld op de WriteAsJsonAsync() methode. In 1.x overroeed dit andere foutcodes die waren ingesteld.
  • 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.

De volgende code toont een voorbeeld van een HostBuilder-pijplijn :

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

Voor deze code is vereist using Microsoft.Extensions.DependencyInjection;.

Voordat u het aanroept Build() IHostBuilder, moet u het volgende doen:

  • Roep aan ConfigureFunctionsWebApplication() als u ASP.NET Core-integratie of ConfigureFunctionsWorkerDefaults() anderszins gebruikt. Zie de HTTP-trigger voor meer informatie over deze opties.
    Als u uw toepassing schrijft met F#, moeten sommige trigger- en bindingsextensies extra configuratie vereisen. Zie de installatiedocumentatie voor de Blobs-extensie, de extensie Tabellen en de Cosmos DB-extensie wanneer u van plan bent deze extensies in een F#-app te gebruiken.
  • Configureer services of app-configuraties die uw project nodig heeft. Zie Configuratie voor meer informatie.
    Als u van plan bent Om Application Insights te gebruiken, moet u de ConfigureServices() gemachtigde bellen AddApplicationInsightsTelemetryWorkerService() en ConfigureFunctionsApplicationInsights() opnemen. Zie Application Insights voor meer informatie.

Als uw project is gericht op .NET Framework 4.8, moet u ook toevoegen FunctionsDebugger.Enable(); voordat u De HostBuilder maakt. Dit moet de eerste regel van uw Main() methode zijn. Zie Foutopsporing bij het richten van .NET Framework voor meer informatie.

HostBuilder wordt gebruikt om een volledig geïnitialiseerd exemplaar IHost te bouwen en te retourneren, dat u asynchroon uitvoert om uw functie-app te starten.

await host.RunAsync();

Configuratie

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

De methode ConfigureFunctionsWorkerDefaults wordt gebruikt om de instellingen toe te voegen die nodig zijn om de functie-app uit te voeren. De methode bevat de volgende functionaliteit:

  • Standaardset conversieprogramma's.
  • Stel de standaard JsonSerializerOptions in om hoofdletters voor eigenschapsnamen te negeren.
  • Integreren met Azure Functions-logboekregistratie.
  • Middleware en functies voor uitvoerbinding.
  • Middleware voor het uitvoeren van functies.
  • Standaard gRPC-ondersteuning.
.ConfigureFunctionsWorkerDefaults()

Als u toegang hebt tot de host builder-pijplijn, kunt u ook app-specifieke configuraties instellen tijdens de initialisatie. U kunt de configureAppConfiguration-methode op HostBuilder een of meer keren aanroepen om configuratiebronnen toe te voegen die vereist zijn voor uw code. Zie Configuratie in ASP.NET Core voor meer informatie over app-configuratie.

Deze configuraties zijn alleen van toepassing op de werkrolcode die u maakt, en ze beïnvloeden niet rechtstreeks 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, moet u nog steeds het host.json-bestand gebruiken.

Notitie

Aangepaste configuratiebronnen kunnen niet worden gebruikt voor de configuratie van triggers en bindingen. De trigger- en bindingsconfiguratie moet beschikbaar zijn voor het Functions-platform en niet alleen uw toepassingscode. U kunt deze configuratie opgeven via de functies voor toepassingsinstellingen, Key Vault-verwijzingen of App Configuration-verwijzingen .

Afhankelijkheidsinjectie

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

Wanneer u een HostBuilderservice gebruikt, roept u ConfigureServices aan op de hostbouwer en gebruikt u de extensiemethoden op IServiceCollection om specifieke services te injecteren. In het volgende voorbeeld wordt een singleton-serviceafhankelijkheid geïnjecteerd:

.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

Afhankelijkheidsinjectie kan worden gebruikt 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 de serviceverzameling in aan Program.cste roepenAddAzureClients(). In het volgende voorbeeld wordt een benoemde client geconfigureerd voor Azure Blobs:

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 blobinhoud 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 is ook verkregen via afhankelijkheidsinjectie, dus deze wordt automatisch geregistreerd. Zie Logboekregistratie voor meer informatie over configuratieopties voor logboekregistratie.

Tip

In het voorbeeld is een letterlijke tekenreeks gebruikt voor de naam van de client in zowel Program.cs als de functie. Overweeg in plaats daarvan een gedeelde constante tekenreeks te gebruiken die is gedefinieerd in de functieklasse. U kunt bijvoorbeeld op beide locaties een verwijzing toevoegen public const string CopyStorageClientName = nameof(_copyContainerClient); en ernaar verwijzen BlobCopier.CopyStorageClientName . U kunt ook de naam van de configuratiesectie definiëren met de functie in plaats van in Program.cs.

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 aanroeppijplijn te injecteren en voor- en na de functies uit te voeren.

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

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 kan worden gebruikt om een middleware te registreren die voorwaardelijk wordt uitgevoerd. U moet aan deze methode een predicaat doorgeven dat een Booleaanse waarde retourneert en de middleware deelneemt aan de pijplijn voor aanroepverwerking wanneer de retourwaarde van het predicaat is true.

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

Wijze Description
GetHttpRequestDataAsync Hiermee haalt u het HttpRequestData exemplaar op wanneer het wordt aangeroepen door een HTTP-trigger. Deze methode retourneert een instantie van ValueTask<HttpRequestData?>, wat handig is wanneer u berichtgegevens wilt lezen, zoals aanvraagheaders en cookies.
GetHttpResponseData Hiermee haalt u het HttpResponseData exemplaar op wanneer het wordt aangeroepen door een HTTP-trigger.
GetInvocationResult Hiermee wordt een exemplaar van InvocationResult, dat het resultaat van de huidige functie-uitvoering vertegenwoordigt. Gebruik de eigenschap om de Value waarde op te halen of in te stellen indien nodig.
GetOutputBindings Haalt de uitvoerbindingvermeldingen op voor de huidige functie-uitvoering. Elke vermelding in het resultaat van deze methode is van het type OutputBindingData. U kunt de Value eigenschap gebruiken om de waarde op te halen of in te stellen indien nodig.
BindInputAsync Hiermee wordt een invoerbindingsitem voor het aangevraagde BindingMetadata exemplaar gebonden. U kunt deze methode bijvoorbeeld gebruiken wanneer u een functie hebt met een BlobInput invoerbinding die moet worden gebruikt door uw middleware.

Dit is een voorbeeld van 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) en wanneer deze aanwezig is, wordt de headerwaarde gebruikt om een antwoordheader te stempelen. Anders wordt er een nieuwe GUID-waarde gegenereerd en wordt deze 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. In deze sectie wordt de serialisatie voor algemeen gebruik behandeld en wordt de JSON-serialisatie van HTTP-triggers niet beïnvloed met ASP.NET Core-integratie, die afzonderlijk moet worden geconfigureerd.

In het volgende voorbeeld ziet u dit met behulp van ConfigureFunctionsWebApplication, maar dit werkt ook voor ConfigureFunctionsWorkerDefaults:

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

U kunt in plaats daarvan JSON.NET (Newtonsoft.Json) gebruiken voor serialisatie. Hiervoor installeert u het Microsoft.Azure.Core.NewtonsoftJson pakket. Vervolgens moet u in uw serviceregistratie de Serializer eigenschap opnieuw toewijzen aan de WorkerOptions configuratie. In het volgende voorbeeld ziet u dit met behulp van ConfigureFunctionsWebApplication, maar dit werkt ook voor ConfigureFunctionsWorkerDefaults:

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(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

Het triggerkenmerk geeft het triggertype op en koppelt invoergegevens aan een methodeparameter. De vorige 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.

Context voor uitvoering

.NET isolated geeft 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 afhankelijkheidsinjectie te verkrijgen zonder dat u afhankelijkheidsinjectie hoeft te gebruiken. Zie Logboekregistratie voor 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.

Annuleringstokens worden ondersteund in .NET-functies wanneer ze worden uitgevoerd in een geïsoleerd werkproces. 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);
    }
}

Bindingen

Bindingen worden gedefinieerd 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 met triggers en bindingen met geïsoleerde werkprocesfuncties.

Invoerbindingen

Een functie kan nul of meer invoerbindingen hebben waarmee gegevens aan een functie kunnen worden doorgegeven. Net als triggers worden invoerbindingen gedefinieerd 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 met behulp van bindingsparameters.

Uitvoerbindingen

Als u naar een uitvoerbinding wilt schrijven, moet u een uitvoerbindingskenmerk toepassen op de functiemethode, waarmee wordt gedefinieerd hoe u naar de afhankelijke service schrijft. De waarde die door de methode wordt geretourneerd, wordt naar de uitvoerbinding geschreven. In het volgende voorbeeld wordt bijvoorbeeld een tekenreekswaarde naar een berichtenwachtrij geschreven met output-queue behulp van een uitvoerbinding:

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([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 door HTTP geactiveerde functie met behulp van ASP.NET Core-integratie die 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 kunnen bindingsgegevens worden verstrekt met behulp van typen van service-SDK's en frameworks. Deze bieden meer mogelijkheden dan wat een geserialiseerde tekenreeks of een eenvoudig oud CLR-object (POCO) kan bieden. Als u de nieuwere typen wilt gebruiken, moet uw project worden bijgewerkt om nieuwere versies van kernafhankelijkheden te kunnen gebruiken.

Dependency Versievereiste
Microsoft.Azure.Functions.Worker 1.18.0 of hoger
Microsoft.Azure.Functions.Worker.Sdk 1.13.0 of hoger

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 trigger en bindingsextensie hebben ook een eigen minimale versievereiste, die wordt beschreven in de naslagartikelen voor extensies. De volgende servicespecifieke bindingen bieden SDK-typen:

Service Activator Invoerbinding Uitvoerbinding
Azure-blobs Algemeen beschikbaar Algemeen beschikbaar SDK-typen worden niet aanbevolen.1
Azure-wachtrijen Algemeen beschikbaar Invoerbinding bestaat niet SDK-typen worden niet aanbevolen.1
Azure Service Bus Algemeen beschikbaar Invoerbinding bestaat niet SDK-typen worden niet aanbevolen.1
Azure Event Hubs Algemeen beschikbaar Invoerbinding bestaat niet SDK-typen worden niet aanbevolen.1
Azure Cosmos DB SDK-typen die niet worden gebruikt2 Algemeen beschikbaar SDK-typen worden niet aanbevolen.1
Azure-tabellen Trigger bestaat niet Algemeen beschikbaar SDK-typen worden niet aanbevolen.1
Azure Event Grid Algemeen beschikbaar Invoerbinding bestaat niet SDK-typen worden niet aanbevolen.1

1 Voor uitvoerscenario's waarin u een SDK-type zou gebruiken, moet u rechtstreeks met SDK-clients maken en werken in plaats van een uitvoerbinding te gebruiken. Zie Azure-clients registreren voor een voorbeeld van afhankelijkheidsinjectie.

2 De Cosmos DB-trigger maakt gebruik van de Azure Cosmos DB-wijzigingenfeed en maakt wijzigingenfeeditems beschikbaar als JSON-serialiseerbare typen. Het ontbreken van SDK-typen is standaard voor dit scenario.

Notitie

Wanneer u bindingexpressies gebruikt die afhankelijk zijn van triggergegevens, kunnen SDK-typen voor de trigger zelf niet worden gebruikt.

HTTP-trigger

Met HTTP-triggers kan een functie worden aangeroepen door een HTTP-aanvraag. Er zijn twee verschillende benaderingen die kunnen worden gebruikt:

  • 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 achterwaartse compatibiliteit met eerdere .NET geïsoleerde werkrol-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 van 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.

Notitie

Niet alle functies van ASP.NET Core worden door dit model weergegeven. De ASP.NET Core middleware-pijplijn- en routeringsmogelijkheden zijn niet beschikbaar. ASP.NET Core-integratie vereist dat u bijgewerkte pakketten 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:

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

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

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

host.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. In het volgende voorbeeld ziet u hoe u JSON.NET (Newtonsoft.Json) configureert voor serialisatie met behulp van deze methode:

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();
    })
    .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 is een weergave van 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;
}

Logboekregistratie

U kunt schrijven naar logboeken met behulp van een ILogger<T> of ILogger exemplaar. De logger kan worden verkregen 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}");
    }

}

De logger kan ook worden verkregen van een FunctionContext-object dat aan uw functie wordt 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 artikel over bewaking 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.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.

Wanneer u een HostBuilder, standaard, uitzonderingen die door uw code worden gegenereerd, worden verpakt in een RpcException. Als u deze extra laag wilt verwijderen, stelt u de EnableUserCodeException eigenschap in op 'true' als onderdeel van het configureren van de opbouwfunctie:

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. Dit gedrag vervangt het standaardgedrag van het doorsturen van logboeken via de host. Tenzij u .NET Aspire gebruikt, wordt het configureren van directe Application Insights-integratie aanbevolen, omdat u hiermee controle hebt over 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 opstartcode als commentaar. Als u Application Insights-integratie wilt gebruiken, kunt u opmerkingen bij deze regels ongedaan Program.cs maken en het projectbestand .csproj . 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 .NET Aspire-indeling, wordt in plaats daarvan OpenTelemetry gebruikt voor bewaking. Schakel directe Application Insights-integratie binnen .NET Aspire-projecten niet in. 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 .NET Aspire-context, treedt de toepassing een fout 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:

U kunt de volgende opdrachten uitvoeren om deze verwijzingen aan uw project toe te voegen:

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

Opstarten configureren

Als de pakketten zijn geïnstalleerd, moet u de serviceconfiguratie in uw Program.cs bestand aanroepen AddApplicationInsightsTelemetryWorkerService() en ConfigureFunctionsApplicationInsights() tijdens de serviceconfiguratie, zoals in dit voorbeeld:

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 voor ConfigureFunctionsApplicationInsights() het toevoegen van een ITelemetryModule, die luistert naar een door Functions gedefinieerde ActivitySourcefunctie. Hiermee maakt u de afhankelijkheidstelemetrie die is vereist voor de ondersteuning van gedistribueerde tracering. Zie Application Insights for Worker Service-toepassingen voor meer informatie over AddApplicationInsightsTelemetryWorkerService() en hoe u deze kunt gebruiken.

Logboekniveaus beheren

Belangrijk

De Functions-host en de geïsoleerde proceswerkrol hebben een afzonderlijke configuratie voor logboekniveaus, enzovoort. Elke Application Insights-configuratie in host.json heeft geen invloed op de logboekregistratie van de werkrol. Op dezelfde manier heeft de configuratie in uw werkrolcode geen invloed op logboekregistratie van de host. U moet wijzigingen op beide plaatsen toepassen als aanpassing op beide lagen is vereist voor uw scenario.

De rest van uw toepassing blijft werken met ILogger en ILogger<T>. De Application Insights SDK voegt echter standaard een logboekregistratiefilter toe waarmee de logboekregistratie alleen waarschuwingen en ernstigere logboeken kan vastleggen. Als u dit gedrag wilt uitschakelen, verwijdert u de filterregel als onderdeel van de serviceconfiguratie:

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

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. U moet uw project minimaal als volgt bijwerken:

  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>

Tijdelijke aanduidingen

Tijdelijke aanduidingen zijn een platformmogelijkheid 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 met behulp van deze stappen:

  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 1in op, wat u kunt doen met behulp van 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. U kunt dit doen met behulp van deze opdracht az functionapp config set :

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

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

  4. Zorg ervoor dat uw functie-app is geconfigureerd voor het gebruik van een 64-bits proces, wat u kunt doen met behulp van deze opdracht az functionapp config set :

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

Belangrijk

Als u dit WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED 1instelt, moeten alle andere configuraties van de functie-app correct worden ingesteld. Anders kan uw functie-app niet worden gestart.

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 compilatie van tevoren die de opstartprestaties kan verbeteren om het effect van koude start 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. Als deze niet zijn uitgelijnd, treedt er bij het opstarten een fout op in uw app. Selecteer uw runtime-id in deze tabel:

Besturingssysteem App is 32-bits1 Runtime-id
Windows Waar win-x86
Windows Onwaar win-x64
Linux Waar N/B (niet ondersteund)
Linux Onwaar linux-x64

1 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, kunt u de volgende CLI-opdracht uitvoeren, waarbij <group_name> u de naam van uw resourcegroep en <app_name> de naam van uw toepassing vervangt. 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> projectbestand niet wilt instellen als onderdeel van het projectbestand, kunt u dit ook configureren als onderdeel van de publicatiebeweging zelf. Met een Windows 64-bits functie-app is de .NET CLI-opdracht bijvoorbeeld:

dotnet publish --runtime win-x64

In Visual Studio moet de optie Target Runtime in het publicatieprofiel worden ingesteld 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. De functie-app en andere vereiste Azure-resources moeten bestaan 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: U kunt de Azure CLI gebruiken om de vereiste resources in Azure te maken.
  • Azure PowerShell: u kunt Azure PowerShell gebruiken om de vereiste resources in Azure te maken.
  • Implementatiesjablonen: U kunt ARM-sjablonen en Bicep-bestanden gebruiken om de implementatie van de vereiste resources in Azure te automatiseren. Zorg ervoor dat uw sjabloon alle vereiste instellingen bevat.
  • Azure Portal: U kunt de vereiste resources maken in Azure Portal.

Uw toepassing publiceren

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

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 dit niet het probleem is, kan uw app fouten ondervinden bij het opstarten.

De nettolading van de implementatie moet overeenkomen met de uitvoer van een dotnet publish opdracht, 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 project (een console-app)
  • Andere ondersteunende bestanden en mappen zijn gekoppeld aan dat uitvoerbare bestand

Deze bestanden worden gegenereerd door het buildproces en ze zijn niet bedoeld om rechtstreeks te worden bewerkt.

Wanneer u een zip-archief voorbereidt voor implementatie, moet u alleen de inhoud van de uitvoermap comprimeren, niet de ingesloten map zelf. Wanneer het archief wordt geëxtraheerd in de huidige werkmap, moeten de bovenstaande bestanden onmiddellijk zichtbaar zijn.

Implementatievereisten

Er zijn enkele vereisten voor het uitvoeren van .NET-functies in het geïsoleerde werkrolmodel in Azure, afhankelijk van het besturingssysteem:

  • FUNCTIONS_WORKER_RUNTIME moet worden ingesteld op een waarde van dotnet-isolated.
  • netFrameworkVersion moet worden ingesteld op de gewenste versie.

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.

.NET Aspire (preview)

.NET Aspire is een beoordelde stack die de ontwikkeling van gedistribueerde toepassingen in de cloud vereenvoudigt. U kunt .NET 8- en .NET 9 geïsoleerde werkrolmodelprojecten in Aspire 9.0-indelingen inschakelen met behulp van preview-ondersteuning. In de sectie worden de belangrijkste vereisten voor opname beschreven.

Voor deze integratie is een specifieke installatie vereist:

  • Gebruik Aspire 9.0 of hoger en de .NET 9 SDK. Aspire 9.0 ondersteunt de .NET 8- en .NET 9-frameworks.
  • Als u Visual Studio gebruikt, werkt u bij naar versie 17.12 of hoger. U moet ook de nieuwste versie van de Functions-hulpprogramma's voor Visual Studio hebben. Als u op updates wilt controleren, gaat u naar Extra-opties>, kiest u Azure Functions onder Projecten en oplossingen. Selecteer Controleren op updates en installeer updates zoals hierom wordt gevraagd.
  • In het hostproject van de Aspire-app:
    • U moet verwijzen naar Aspire.Hosting.Azure.Functions.
    • U moet een projectverwijzing hebben naar uw Functions-project.
    • In de host van Program.csde app moet u ook het project opnemen door uw IDistributedApplicationBuilderaanroep uit te schakelenAddAzureFunctionsProject<TProject>(). Deze methode wordt gebruikt in plaats van de AddProject<TProject>() methode die u gebruikt voor andere projecttypen. Als u alleen maar gebruikt AddProject<TProject>(), wordt het Functions-project niet goed gestart.
  • In het Functions-project:
    • U moet verwijzen naar de 2.x-versies van Microsoft.Azure.Functions.Worker en Microsoft.Azure.Functions.Worker.Sdk. U moet ook verwijzingen Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore naar de versie 2.x bijwerken.
    • U Program.cs moet de opstartversie van het IHostApplicationBuilder hostexemplaren gebruiken.
    • Als u de standaardinstellingen van uw Aspire-service wilt gebruiken, moet u een projectreferentie opnemen naar het standaardproject voor de service. Voordat u uw IHostApplicationBuilder inbouwt Program.cs, moet u ook een aanroep naar builder.AddServiceDefaults().
    • U moet de configuratie niet bewaren, local.settings.jsonafgezien van de FUNCTIONS_WORKER_RUNTIME instelling, die 'dotnet-isolated' moet blijven. Andere configuratie moet worden ingesteld via het app-hostproject.
    • Verwijder alle directe Application Insights-integraties. Bewaking in Aspire wordt in plaats daarvan afgehandeld via de OpenTelemetry-ondersteuning.

In het volgende voorbeeld ziet u een minimum Program.cs voor een App Host-project:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject");

builder.Build().Run();

In het volgende voorbeeld ziet u een minimum Program.cs voor een Functions-project dat wordt gebruikt in Aspire:

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

builder.ConfigureFunctionsWebApplication();

builder.Build().Run();

Dit omvat niet de standaard Application Insights-configuratie die u in veel van de andere Program.cs voorbeelden in dit artikel ziet. In plaats daarvan wordt de OpenTelemetry-integratie van Aspire geconfigureerd via de builder.AddServiceDefaults() aanroep.

Overwegingen en best practices voor .NET Aspire-integratie

Houd rekening met de volgende punten bij het evalueren van .NET Aspire met Azure Functions:

  • Ondersteuning voor Azure Functions met .NET Aspire is momenteel in preview. Tijdens de preview-periode, wanneer u de Aspire-oplossing publiceert naar Azure, worden Functions-projecten geïmplementeerd als Azure Container Apps-resources zonder gebeurtenisgestuurd schalen. Azure Functions-ondersteuning is niet beschikbaar voor apps die in deze modus zijn geïmplementeerd.
  • De trigger- en bindingsconfiguratie via Aspire is momenteel beperkt tot specifieke integraties. Zie De verbindingsconfiguratie met Aspire voor meer informatie.
  • U Program.cs moet de opstartversie van het IHostApplicationBuilder hostexemplaren gebruiken. Hiermee kunt u aanroepen builder.AddServiceDefaults() om de standaardinstellingen van de .NET Aspire-service toe te voegen aan uw Functions-project.
  • Aspire maakt gebruik van OpenTelemetry voor bewaking. U kunt Aspire configureren voor het exporteren van telemetrie naar Azure Monitor via het standaardproject voor de service. In veel andere Azure Functions-contexten kunt u directe integratie met Application Insights opnemen door de telemetriewerkservice te registreren. Dit wordt niet aanbevolen in Aspire en kan leiden tot runtimefouten met versie 2.22.0 van Microsoft.ApplicationInsights.WorkerService. Verwijder alle directe Application Insights-integraties uit uw Functions-project wanneer u Aspire gebruikt.
  • Voor Functions-projecten die zijn opgenomen in een Aspire-indeling, moet de meeste toepassingsconfiguratie afkomstig zijn van het Hostproject van de Aspire-app. U moet meestal voorkomen dat u dingen instelt in local.settings.json, anders dan de FUNCTIONS_WORKER_RUNTIME instelling. Als dezelfde omgevingsvariabele is ingesteld door local.settings.json En Aspire, gebruikt het systeem de Aspire-versie.
  • Configureer de opslagemulator niet voor verbindingen in local.settings.json. Veel Functions-starterssjablonen bevatten de emulator als standaardinstelling voor AzureWebJobsStorage. De emulatorconfiguratie kan echter enkele IDE's vragen om een versie van de emulator te starten die kan conflicteren met de versie die Aspire gebruikt.

Verbindingsconfiguratie met Aspire

Azure Functions vereist een hostopslagverbinding (AzureWebJobsStorage) voor verschillende kerngedrag. Wanneer u uw app-hostproject aanroept AddAzureFunctionsProject<TProject>() , wordt er een standaardverbinding AzureWebJobsStorage gemaakt en aan het Functions-project verstrekt. Deze standaardverbinding maakt gebruik van de Opslagemulator voor uitvoeringen van lokale ontwikkeling en richt automatisch een opslagaccount in wanneer deze wordt geïmplementeerd. Voor extra controle kunt u deze verbinding vervangen door de Functions-projectresource aan te roepen .WithHostStorage() .

In het volgende voorbeeld ziet u een minimum Program.cs voor een app-hostproject dat de hostopslag vervangt:

var builder = DistributedApplication.CreateBuilder(args);

var myHostStorage = builder.AddAzureStorage("myHostStorage");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithHostStorage(myHostStorage);

builder.Build().Run();

Notitie

Wanneer Aspire de hostopslag in de publicatiemodus instelt, wordt standaard de roltoewijzingen gemaakt voor de rol Inzender voor opslagaccounts, Inzender voor opslagblobgegevens, Inzender voor opslagwachtrijgegevens en Inzender voor opslagtabelgegevens.

Uw triggers en bindingen verwijzen naar verbindingen op naam. Sommige Aspire-integraties kunnen deze bieden via een aanroep van WithReference() de projectresource:

Ambieer integratie Opmerkingen
Azure-blobs Wanneer Aspire de resource instelt, wordt standaard de roltoewijzingen gemaakt voor de rollen Inzender voor opslagblobgegevens, Inzender voor opslagwachtrijgegevens en Inzender voor opslagtabelgegevens.
Azure-wachtrijen Wanneer Aspire de resource instelt, wordt standaard de roltoewijzingen gemaakt voor de rollen Inzender voor opslagblobgegevens, Inzender voor opslagwachtrijgegevens en Inzender voor opslagtabelgegevens.
Azure Event Hubs Wanneer Aspire de resource in richt, wordt standaard een roltoewijzing gemaakt met behulp van de rol Azure Event Hubs-gegevenseigenaar .
Azure Service Bus Wanneer Aspire de resource in richt, wordt standaard een roltoewijzing gemaakt met behulp van de rol Azure Service Bus-gegevenseigenaar .

In het volgende voorbeeld ziet u een minimum Program.cs voor een app-hostproject waarmee een wachtrijtrigger wordt geconfigureerd. In dit voorbeeld is Connection de bijbehorende wachtrijtrigger ingesteld op 'MyQueueTriggerConnection'.

var builder = DistributedApplication.CreateBuilder(args);

var myAppStorage = builder.AddAzureStorage("myAppStorage").RunAsEmulator();
var queues = myAppStorage.AddQueues("queues");

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithReference(queues, "MyQueueTriggerConnection");

builder.Build().Run();

Voor andere integraties worden aanroepen om de configuratie op een andere manier in te WithReference stellen, zodat deze beschikbaar wordt gemaakt voor Aspire-clientintegraties, maar niet voor triggers en bindingen. Voor deze integraties moet u aanroepen WithEnvironment() om de verbindingsgegevens door te geven voor de trigger of binding die moet worden omgezet. In het volgende voorbeeld ziet u hoe u de omgevingsvariabele 'MyBindingConnection' instelt voor een resource die een verbindingsreeks-expressie weergeeft:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection", otherIntegration.Resource.ConnectionStringExpression);

U kunt zowel WithReference() configureren als WithEnvironment() als als u wilt dat een verbinding wordt gebruikt door zowel de Aspire-clientintegraties als het triggers- en bindingssysteem.

Voor sommige resources kan de structuur van een verbinding verschillen tussen wanneer u deze lokaal uitvoert en wanneer u deze publiceert naar Azure. In het vorige voorbeeld otherIntegration kan dit een resource zijn die wordt uitgevoerd als een emulator, dus ConnectionStringExpression retourneert een emulator verbindingsreeks. Wanneer de resource wordt gepubliceerd, kan Aspire echter een op identiteit gebaseerde verbinding instellen en ConnectionStringExpression de URI van de service retourneren. Als u in dit geval op identiteit gebaseerde verbindingen voor Azure Functions wilt instellen, moet u mogelijk een andere naam voor de omgevingsvariabele opgeven. In het volgende voorbeeld wordt builder.ExecutionContext.IsPublishMode het benodigde achtervoegsel voorwaardelijk toegevoegd:

builder.AddAzureFunctionsProject<Projects.MyFunctionsProject>("MyFunctionsProject")
    .WithEnvironment("MyBindingConnection" + (builder.ExecutionContext.IsPublishMode ? "__serviceUri" : ""), otherIntegration.Resource.ConnectionStringExpression);

Afhankelijk van uw scenario moet u mogelijk ook de machtigingen aanpassen die worden toegewezen voor een op identiteit gebaseerde verbinding. U kunt de ConfigureConstruct<T>() methode gebruiken om aan te passen hoe Aspire infrastructuur configureert wanneer uw project wordt gepubliceerd.

Raadpleeg de referentiepagina's van elke binding voor meer informatie over de verbindingsindelingen die worden ondersteund en de machtigingen die deze indelingen vereisen.

Foutopsporing

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 = 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 werkrol en stopt het proces 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 het koppelen aan 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 richten, hebben functie-apps die worden gehost in Azure mogelijk niet die release 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-sjablonen of de Azure CLI gebruiken om de versie handmatig te configureren.

Gebruik de volgende Azure CLI-opdracht voor apps die worden gehost in Windows. Vervang <groupName> door de naam van de resourcegroep en vervang deze door <appName> de naam van uw functie-app. Vervang <framework> door de juiste versietekenreeks, zoals v8.0.

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

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 Preview gebruiken, dat 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.
    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, waarbij de versie is die <SDK_VERSION> u lokaal gebruikt. Zorgt er bijvoorbeeld voor dotnet new globaljson --sdk-version dotnet-sdk-8.0.100-preview.7.23376.3 --force dat het systeem de .NET 8 Preview 7 SDK gebruikt bij het bouwen van uw project.

Notitie

Vanwege het Just-In-Time laden van preview-frameworks kunnen functie-apps die in Windows worden uitgevoerd, een verhoogde koude begintijd ervaren in vergelijking met eerdere GA-versies.

Volgende stappen

Meer informatie over aanbevolen procedures voor Azure Functions

.NET-apps migreren naar het geïsoleerde werkrolmodel