Průvodce spuštěním funkcí jazyka C# pro Azure v izolovaném pracovním modelu

Tento článek představuje práci s Azure Functions v .NET pomocí izolovaného modelu pracovního procesu. Tento model umožňuje cílové verze projektu .NET nezávisle na ostatních komponentách modulu runtime. Informace o podporovaných konkrétních verzích .NET najdete v tématu supported version.

Následující odkazy vám pomůžou začít hned vytvářet .NET funkce izolovaného pracovního modelu.

Začínáme Koncepty Ukázky

Další informace o nasazení projektu izolovaného modelu pracovního procesu do Azure najdete v tématu Deploy do Azure Functions.

Výhody izolovaného modelu pracovního procesu

Funkce knihovny tříd .NET můžete spustit ve dvou režimech: buď ve stejném procesu jako modul runtime hostitele služby Functions (in-process) nebo v izolovaném pracovním procesu. Když .NET funkce běží v izolovaném pracovním procesu, můžete využít následující výhody:

  • Méně konfliktů: Vzhledem k tomu, že vaše funkce běží v samostatném procesu, sestavení použitá v aplikaci nejsou v konfliktu s různými verzemi stejných sestavení používaných hostitelským procesem.
  • Úplné řízení procesu: Řídíte spuštění aplikace, což znamená, že můžete spravovat použité konfigurace a spustit middleware.
  • Standard dependency injection: Protože máte úplnou kontrolu nad procesem, můžete použít aktuální chování .NET pro injektáž závislostí a začlenění middlewaru do vaší aplikace funkcí.
  • Flexibilita verzí .NET: Spuštění mimo hostitelský proces znamená, že vaše funkce se mohou spouštět ve verzích .NET, které nejsou nativně podporovány prostředím funkcí, včetně rozhraní .NET Framework.

Pokud máte existující aplikaci funkcí jazyka C#, která běží v procesu, musíte aplikaci migrovat, abyste mohli tyto výhody využít. Další informace najdete v tématu Migrace .NET aplikací z modelu v procesu do izolovaného modelu pracovního procesu.

Komplexní porovnání mezi těmito dvěma režimy najdete v tématu Difference mezi procesem a izolovaným pracovním procesem .NET Azure Functions.

Podporované verze

Verze prostředí runtime Azure Functions podporují konkrétní verze .NET. Další informace o verzích služby Functions najdete v tématu Azure Functions přehled verzí modulu runtime. Podpora verzí také závisí na tom, zda vaše funkce běží v procesu nebo izolovaném pracovním procesu.

Poznámka:

Informace o tom, jak změnit verzi modulu runtime funkcí používanou vaší funkční aplikací, vizte v části zobrazit a aktualizovat aktuální verzi modulu runtime.

Následující tabulka ukazuje nejvyšší úroveň .NET nebo rozhraní .NET Framework, které lze použít s konkrétní verzí funkcí.

Verze modulu runtime služby Functions Izolovaný model pracovního procesu Model v procesu4
Funkce 4.x1 .NET 105
.NET 9,0
.NET 8.0
.NET Framework 4.82		 .NET 8.0
Funkce 1.x3 Není k dispozici .NET Framework 4.8

1 .NET 6 bylo dříve podporováno na obou modelech, ale dosáhlo konce oficiální podpory 12. listopadu 2024. .NET 7 byl dříve podporován v izolovaném modelu pracovních procesů, ale dosáhl konce oficiální podpory 14. května 2024.

2 Proces sestavení také vyžaduje .NET SDK.

3 Podpora končí pro verzi 1.x modulu runtime Azure Functions 14. září 2026. Pro více informací si přečtěte toto oznámení podpory. Pokud chcete pokračovat v plné podpoře, měli byste migrovat aplikace na verzi 4.x.

4 Podpora modelu v procesu končí 10. listopadu 2026. Pro více informací si přečtěte toto oznámení podpory. Pokud chcete pokračovat v plné podpoře, měli byste své aplikace migrovat do izolovaného pracovního modelu.

5 V plánu Consumption nemůžete spouštět .NET 10 aplikací v Linuxu. Pokud chcete spustit v Linuxu, měli byste místo toho použít plán Flex Consumption. Podrobné pokyny k migraci najdete v tématu Migrace aplikací plánu Consumption do plánu Flex Consumption.

Pro nejnovější zprávy o verzích Azure Functions, včetně odebrání konkrétních starších podverzí, sledujte oznámení Azure App Service.

Struktura projektu

Projekt .NET pro Azure Functions, který používá izolovaný model pracovního procesu, je v podstatě projekt konzolové aplikace .NET, který cílí na podporovaný modul runtime .NET. Následující soubory jsou základní soubory vyžadované v jakémkoli .NET izolovaném projektu:

  • Soubor project jazyka C# (.csproj), který definuje project a závislosti.
  • Program.cs soubor, který je vstupním bodem aplikace.
  • Všechny soubory kódu definující vaše funkce.
  • host.json soubor, který definuje konfiguraci sdílenou funkcemi ve vašem project.
  • local.settings.json soubor, který definuje proměnné prostředí používané project při místním spuštění na vašem počítači.

Kompletní příklady najdete v ukázkovém projektu .NET 8 a ukázkovém projektu .NET Framework 4.8.

Odkazy na balíčky

Projekt .NET pro Azure Functions, který používá izolovaný model pracovního procesu, používá jedinečnou sadu balíčků pro základní funkce i rozšíření vazeb.

Základní balíčky

Ke spuštění funkcí .NET v izolovaném pracovním procesu potřebujete následující balíčky:

Minimální verze těchto balíčků závisí na vaší cílové verzi .NET:

verze .NET Microsoft.Azure.Functions.Worker Microsoft.Azure.Functions.Worker.Sdk
.NET 10 2.50.0 nebo novější 2.0.5 nebo novější
.NET 9 2.0.0 nebo novější 2.0.0 nebo novější
.NET 8 1.16.0 nebo novější 1.11.0 nebo novější
.NET Framework 1.16.0 nebo novější 1.11.0 nebo novější

Verze 2.x

Verze 2.x základních balíčků mění podporované architektury a přinášejí podporu nových rozhraní API .NET z těchto novějších verzí. Při aktualizaci na verze 2.x mějte na paměti následující změny:

  • Počínaje verzí 2.0.0 Microsoft.Azure. Functions.Worker.Sdk:
    • Sada SDK obsahuje výchozí konfigurace pro sestavení kontejnerů sady SDK.
    • Sada SDK zahrnuje podporu pro dotnet run při instalaci nástrojů Azure Functions Core Tools. Na Windows nainstalujte nástroje Core Tools prostřednictvím jiného mechanismu než NPM.
  • Počínaje verzí 2.0.0 Microsoft.Azure. Functions.Worker:
    • Tato verze přidává podporu pro IHostApplicationBuilder. Mezi příklady v tomto průvodci patří karty, které ukazují alternativy pomocí IHostApplicationBuilder. Tyto příklady vyžadují verze 2.x.
    • Ověření rozsahu poskytovatele služeb je ve výchozím nastavení zahrnuté, pokud běží ve vývojovém prostředí. Toto chování odpovídá ASP.NET Core.
    • Tato EnableUserCodeException možnost je ve výchozím nastavení povolená. Vlastnost je nyní označena jako zastaralá.
    • Tato IncludeEmptyEntriesInMessagePayload možnost je ve výchozím nastavení povolená. Pokud je tato možnost povolena, spouštěcí datové pakety, které představují kolekce, vždy obsahují prázdné položky. Například, pokud je zpráva odeslána bez obsahu, v string[] pro údaje spouštěče se stále nachází prázdná položka. Zahrnutí prázdných položek usnadňuje křížový odkaz s poli metadat, na která může funkce odkazovat. Toto chování můžete zakázat nastavením IncludeEmptyEntriesInMessagePayload na false v WorkerOptions konfiguraci služby.
    • Třída ILoggerExtensions je přejmenována na FunctionsLoggerExtensions. Přejmenování zabraňuje nejednoznačné chybě volání při použití LogMetric() v ILogger instanci.
    • U aplikací, které používají HttpResponseData, WriteAsJsonAsync() už metoda nenastaví stavový kód na 200 OK. V 1.x toto chování přerodí další kódy chyb, které jste nastavili.
  • Verze 2.x ukončí podporu TFM .NET 5.

Balíčky rozšíření

Vzhledem k tomu, že .NET izolované funkce pracovních procesů používají různé typy vazeb, vyžadují jedinečnou sadu balíčků rozšíření vazeb.

Tyto balíčky rozšíření najdete v části Microsoft.Azure. Functions.Worker.Extensions.

Spuštění a konfigurace

Při použití izolovaného modelu pracovníka máte přístup ke spuštění vaší funkční aplikace, která je obvykle v Program.cs. Zodpovídáte za vytváření a spouštění vlastní instance hostitele. V takovém případě máte také přímý přístup do konfiguračního kanálu vaší aplikace. S izolovaným pracovním procesem .NET Functions můžete mnohem snadněji přidávat konfigurace, vkládat závislosti a spouštět vlastní middleware.

Aby bylo možné použít vaši aplikaci IHostApplicationBuilder, musí používat verzi 2.x nebo novější základních balíčků.

Následující kód ukazuje příklad pipeline IHostApplicationBuilder:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

var host = builder.Build();

Před voláním Build() na tomto objektu IHostApplicationBuilder byste měli:

  • Pokud chcete použít integraci ASP.NET Core, zavolejte builder.ConfigureFunctionsWebApplication().
  • Pokud píšete aplikaci pomocí jazyka F#, možná budete muset zaregistrovat některá rozšíření vazeb. Informace o instalaci najdete v dokumentaci k rozšířeníBlobs, rozšíření Tables a rozšíření Cosmos DB při plánování použití těchto rozšíření v aplikaci F#.
  • Nakonfigurujte všechny služby nebo konfiguraci aplikace, které váš projekt vyžaduje. Podrobnosti najdete v části Konfigurace .
  • Pokud plánujete používat Application Insights, musíte volat AddOpenTelemetry().UseFunctionsWorkerDefaults() a AddOpenTelemetry().UseAzureMonitorExporter() proti vlastnosti tvůrce Services . Podrobnosti najdete v Application Insights .

Pokud váš projekt cílí na .NET Framework 4.8, musíte před vytvořením nástroje HostBuilder přidat také FunctionsDebugger.Enable();. Měl by to být první řádek vaší Main() metody. Další informace najdete v tématu Ladění při cílení na .NET Framework.

IHostApplicationBuilder se používá k sestavení a vrácení plně inicializované IHost instance, kterou spustíte asynchronně pro spuštění aplikace funkcí.

await host.RunAsync();

Konfigurace

Typ používaného tvůrce určuje způsob konfigurace aplikace.

FunctionsApplication.CreateBuilder() Pomocí této metody přidejte nastavení potřebná ke spuštění aplikace funkcí. Tato metoda zahrnuje následující funkce:

  • Výchozí sada převaděčů
  • Nastavte výchozí JsonSerializerOptions tak, aby ignorovala velikost písmen u názvů vlastností.
  • Integrujte se s protokolováním Azure Functions.
  • Middleware a funkce výstupní vazby
  • Middleware pro vykonávání funkcí
  • Výchozí podpora gRPC
  • Použijte jiné výchozí hodnoty z Host.CreateDefaultBuilder().

Máte přístup do sestavovacího kanálu, takže během inicializace můžete nastavit libovolné konfigurace specifické pro aplikaci. Metody rozšíření můžete volat u vlastnosti buildera Configuration a přidat tak všechny zdroje konfigurace vyžadované vaším kódem. Další informace o konfiguraci aplikace najdete v tématu Konfigurace v ASP.NET Core.

Tyto konfigurace se vztahují pouze na vytvořený pracovní kód. Nemají přímý vliv na konfiguraci hostitele nebo triggerů a vazeb Functions. Pokud chcete provést změny hostitele funkcí nebo konfigurace triggeru a vazby, použijte souborhost.json.

Poznámka:

Vlastní zdroje konfigurace se nedají použít pro konfiguraci aktivačních událostí a vazeb. Konfigurace triggeru a vazby musí být dostupná pro platformu Functions, a ne jenom kód aplikace. Tuto konfiguraci můžete poskytnout prostřednictvím nastavení aplikace, odkazů na Key Vault nebo odkazů na konfiguraci aplikace.

Injektáž závislostí

Model izolovaného pracovního procesu používá standardní mechanismy .NET pro vkládání služeb.

Při použití IHostApplicationBuilder použijte jeho vlastnost Services pro přístup k IServiceCollection. Následující příklad injektuje závislost singletonové služby:

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

Tento kód vyžaduje using Microsoft.Extensions.DependencyInjection;. Další informace najdete v Injektáž závislostí v ASP.NET Core.

Registrace klientů Azure

Použijte injektování závislostí pro interakci s jinými službami Azure. Klienty můžete vložit z Azure SDK pro .NET pomocí balíčku Microsoft.Extensions.Azure. Po instalaci balíčku registrujte klienty voláním AddAzureClients() v kolekci služeb v Program.cs. Následující příklad nakonfiguruje klienta named client pro objekty blob Azure:

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

Následující příklad ukazuje, jak můžete pomocí této registrace a typů sad SDK zkopírovat obsah objektů blob jako datový proud z jednoho kontejneru do druhého pomocí injektovaného klienta:

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

    }
}

V tomto příkladu se ILogger<T> získá také prostřednictvím injektování závislostí, takže se zaregistruje automaticky. Další informace o možnostech konfigurace pro protokolování najdete v tématu Protokolování.

Návod

Příklad používá textový řetězec pro název klienta v Program.cs i ve funkci. Místo toho zvažte použití sdíleného konstantního řetězce definovaného ve třídě funkce. Můžete například přidat public const string CopyStorageClientName = nameof(_copyContainerClient); a potom odkazovat na BlobCopier.CopyStorageClientName na obou místech. Podobným způsobem můžete definovat název oddílu konfigurace s funkcí místo v Program.cs.

Middleware

Izolovaný pracovní model také podporuje registraci middlewaru, a to znovu pomocí modelu podobného tomu, co existuje v ASP.NET. Tento model umožňuje vložit logiku do kanálu vyvolání a před a po spuštění funkcí.

Metoda rozšíření ConfigureFunctionsWorkerDefaults má přetížení, které vám umožní zaregistrovat vlastní middleware, jak vidíte v následujícím příkladu.

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

Metoda UseWhen rozšíření zaregistruje middleware, který se spouští podmíněně. Je nutné předat predikát, který této metodě vrátí logickou hodnotu. Middleware se účastní kanálu zpracování vyvolání, když predikát vrátí true.

Následující metody rozšíření na FunctionContext usnadňují práci s middlewarem v izolovaném modelu.

metoda Popis
GetHttpRequestDataAsync Získá instanci HttpRequestData když je vyvolán HTTP triggerem. Tato metoda vrátí instanci ValueTask<HttpRequestData?>, která je užitečná, když chcete číst data zpráv, jako jsou hlavičky požadavku a soubory cookie.
GetHttpResponseData Získá instanci HttpResponseData když je vyvolán HTTP triggerem.
GetInvocationResult Získá instanci InvocationResult, která představuje výsledek aktuálního spuštění funkce. Value Pomocí vlastnosti získejte nebo nastavte hodnotu podle potřeby.
GetOutputBindings Získá položky výstupních vazeb pro aktuální spuštění funkce. Každá položka v výsledku této metody je typu OutputBindingData. Vlastnost můžete použít Value k získání nebo nastavení hodnoty podle potřeby.
BindInputAsync Vytvoří vazbu pro položku vstupní vazby požadované instance BindingMetadata. Tuto metodu použijte například v případě, že máte funkci se vstupní vazbou BlobInput , kterou musí váš middleware použít.

Tento příklad ukazuje implementaci middlewaru HttpRequestData , která čte instanci a aktualizuje HttpResponseData instanci během provádění funkce:

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

Tento middleware kontroluje přítomnost konkrétní hlavičky požadavku (x-correlationId). Pokud je hlavička přítomná, middleware použije hodnotu hlavičky k nastavení hlavičky odpovědi. V opačném případě vygeneruje novou hodnotu GUID a použije tuto hodnotu pro razítko hlavičky odpovědi.

Návod

Vzor zobrazený dříve, kdy se nastavují hlavičky odpovědí po await next(context), nemusí spolehlivě fungovat ve všech scénářích. Tento problém platí zejména v případě, že používáte integraci ASP.NET Core nebo v určitých konfiguracích modulu runtime, ve kterých už byl stream odpovědí odeslán. Pokud chcete zajistit správné nastavení hlaviček, zvažte načtení odpovědi z context.GetInvocationResult().Value a nastavení hlaviček před vrácením odpovědi z funkce, místo abyste se pokoušeli je upravovat v middlewaru po dokončení provádění funkce.

Pro úplnější příklad použití vlastního middlewaru ve vaší aplikaci funkcí si prohlédněte referenční ukázku pro vlastní middleware custom middleware reference sample.

Přizpůsobení serializace JSON

Model izolovaného pracovníka používá System.Text.Json ve výchozím nastavení. Chování serializátoru můžete přizpůsobit konfigurací služeb v rámci souboru Program.cs . Tato část se věnuje serializaci pro obecné účely a nemá vliv na serializaci JSON triggeru HTTP s integrací ASP.NET Core, kterou musíte nakonfigurovat samostatně.

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

Pokud chcete k serializaci použít JSON.NET (Newtonsoft.Json), nainstalujte balíček Microsoft.Azure.Core.NewtonsoftJson. Potom v registraci služby znovu přiřaďte Serializer vlastnost ke WorkerOptions konfiguraci. Následující příklad ukazuje tuto konfiguraci pomocí ConfigureFunctionsWebApplication, ale funguje také pro 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();

Metody rozpoznané jako funkce

Metoda funkce je veřejná metoda veřejné třídy s atributem Function použitým na metodu a atribut trigger použitý na vstupní parametr, jak je znázorněno v následujícím příkladu:

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

Atribut triggeru určuje typ triggeru a vytvoří vazbu vstupních dat na parametr metody. Předchozí ukázková funkce se aktivuje pomocí zprávy fronty a zpráva fronty se předá metodě v parametru myQueueItem.

Atribut Function označuje metodu jako vstupní bod funkce. Název musí být jedinečný v rámci project, musí začínat písmenem a obsahovat jenom písmena, číslice, _ a -, délku až 127 znaků. Project šablony často vytvářejí metodu s názvem Run, ale název metody může být libovolný platný název metody jazyka C#. Metoda musí být veřejným členem veřejné třídy. Obecně by to měla být instanční metoda, aby služby mohly být předány prostřednictvím injekce závislostí.

Parametry funkce

Tady jsou některé parametry, které můžete zahrnout jako součást podpisu metody funkce:

  • Vazby, které jsou označené jako takové dekorací parametrů jako atributy. Funkce musí obsahovat přesně jeden parametr triggeru.
  • Objekt kontextu spuštění, který poskytuje informace o aktuálním vyvolání.
  • Příznak pro zrušení, který se používá k plynulému vypnutí.

Kontext spuštění

V izolovaném modelu pracovního procesu předává pracovní proces objektu FunctionContext do vašich metod funkce. Tento objekt umožňuje získat instanci ILogger pro zápis do protokolů voláním metody GetLogger a zadáním řetězce categoryName. Tento kontext můžete použít k získání ILogger bez nutnosti použití vkládání závislostí. Další informace naleznete v tématu Protokoly.

** Tokeny pro zrušení

Funkce může přijmout parametr cancellationToken , který umožňuje operačnímu systému upozornit váš kód, když se funkce chystá ukončit. Pomocí tohoto oznámení můžete zajistit, aby se funkce neočekávaně neukončila způsobem, který ponechá data v nekonzistentním stavu.

.NET funkce, které běží v izolovaném pracovním procesu, podporují tokeny zrušení. Následující příklad vyvolá výjimku při přijetí požadavku na zrušení:

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

Následující příklad provádí akce vyčištění při přijetí žádosti o zrušení:

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

Scénáře, které vedou ke zrušení

Token zrušení se signalizuje, když je vyvolání funkce zrušeno. Zrušení může vést k několika důvodům a tyto důvody se liší v závislosti na použitém typu triggeru. Mezi běžné důvody patří:

  • Odpojení klienta: Klient, který vyvolá vaši funkci, se odpojí. Tento důvod je nejpravděpodobnější pro funkce triggeru HTTP.
  • Restartování aplikace funkcí: Vy nebo platforma restartujete (nebo zastavíte) aplikaci funkcí přibližně ve stejnou dobu, kdy je vyžadováno vyvolání. K restartování může dojít kvůli přesunům instancí pracovního procesu, aktualizacím instance pracovního procesu nebo škálování.

Aspekty zrušení

  • Vyvolání během události restartování se může opakovat v závislosti na tom, jak se aktivovaly. Další informace najdete v dokumentaci k opakovaným pokusům.

  • Hostitel odešle vyvolání pracovnímu procesu , i když je token zrušení zrušen před tím, než hostitel dokáže odeslat žádost o vyvolání pracovnímu procesu.

  • Pokud nechcete, aby se pracovníkovi odesílala předem zrušená volání, přidejte do souboru SendCanceledInvocationsToWorker vlastnost host.json, která toto chování zakáže.

    Tento příklad ukazuje host.json soubor, který používá tuto vlastnost:

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

  • Nastavení SendCanceledInvocationsToWorker na false může vést k výjimce s následujícím záznamem: FunctionInvocationCanceled

    Bylo požadováno zrušení. Žádost o vyvolání s ID {invocationId} je zrušená a nebude odeslána pracovníkovi.

    K této výjimce dochází, když je storno token zneplatněn (v důsledku jedné z událostí popsaných výše) před tím, než host odešle příchozí žádost o vyvolání pracovníkovi. Tuto výjimku lze bezpečně ignorovat a očekává se, pokud SendCanceledInvocationsToWorker je false.

Asynchronní programování

Izolovaný pracovní proces .NET nenastaví uživatelsky definovaný SynchronizationContext. To znamená, že SynchronizationContext.Current je null během provádění funkce. Po await jsou pokračování naplánována ve fondu vláken, což je standardní chování .NET.

Vzhledem k tomu, že není nic SynchronizationContext, co by se dalo potlačit, nemá použití ConfigureAwait(false) ve vašem kódu funkce žádný praktický účinek. Izolovaný pracovní proces běží jako standardní .NET generický hostitel (konzolová aplikace), takže stejné asynchronní a očekávané chování, jaké byste očekávali v libovolné ASP.NET Core nebo konzolové aplikaci, platí i zde. To platí také pro izolované pracovní aplikace .NET Framework (net48), protože pracovní proces je vždy spustitelný soubor konzoly pomocí HostBuilder.

Poznámka:

orchestrátory Durable Functions mají vlastní omezení dělení na vlákna. Vlákno opakování orchestrátoru musí spouštět pokračování, takže použití ConfigureAwait(false) ve funkcích orchestrátoru nebo middlewaru orchestrátoru může kolidovat s prováděním orchestrace. Další informace najdete v omezeních kódu Durable Functions.

Vazby

Definujte vazby pomocí atributů pro metody, parametry a návratové typy. Vazby mohou poskytovat data jako řetězce, pole a serializovatelné typy, jako jsou jednoduché objekty tříd (POCOs). U některých rozšíření vazeb můžete také vytvořit vazbu na typy specifické pro službu, které jsou definovány v SDK služby.

Pro informace o HTTP triggeru viz část HTTP trigger.

Kompletní sadu referenčních ukázek, které používají triggery a vazby s izolovanými funkcemi pracovního procesu, najdete v referenční ukázce rozšíření pro vazby.

Vstupní vazby

Funkce může mít nulové nebo více vstupních vazeb, které funkci předávají data. Podobně jako triggery definujete vstupní vazby použitím atributu vazby na vstupní parametr. Při spuštění funkce se modul runtime pokusí získat data zadaná v vazbě. Požadovaná data často závisí na informacích poskytovaných triggerem prostřednictvím parametrů vazby.

Výstupní vazby

Chcete-li zapisovat do výstupní vazby, musíte použít atribut výstupní vazby pro metodu funkce. Tento atribut definuje, jak zapisovat do vázané služby. Návratová hodnota metody je zapsána do výstupní vazby. Následující příklad například zapíše řetězcovou hodnotu do fronty zpráv pojmenované output-queue pomocí výstupní vazby:

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

Více výstupních vazeb

Data zapsaná do výstupní vazby jsou vždy návratovou hodnotou funkce. Pokud potřebujete zapisovat do více než jedné výstupní vazby, musíte vytvořit vlastní návratový typ. Tento návratový typ musí mít atribut výstupní vazby použitý na jednu nebo více vlastností třídy. Následující příklad je funkce aktivovaná protokolem HTTP, která používá integraci ASP.NET Core a zapisuje se do výstupní vazby HTTP i do výstupní vazby fronty:

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

Pokud používáte vlastní návratové typy pro více výstupních vazeb s integrací ASP.NET Core, musíte do vlastnosti, která poskytuje výsledek, přidat atribut [HttpResult]. Atribut HttpResult je k dispozici při použití SDK 1.17.3-preview2 nebo novější spolu s version 3.2.0 nebo novější rozšíření HTTP a version 1.3.0 nebo novější rozšíření ASP.NET Core.

Typů SDK

U některých typů vazeb specifických pro službu můžete data vazby poskytnout pomocí typů ze sad SDK a architektur služby. Tyto typy nabízejí možnosti nad rámec toho, co serializovaný řetězec nebo prostý objekt CLR (POCO) může poskytnout. Pokud chcete použít novější typy, aktualizujte project tak, aby používaly novější verze základních závislostí.

Závislost Požadavek na verzi
Microsoft.Azure. Functions.Worker 1.18.0 nebo novější
Microsoft.Azure. Functions.Worker.Sdk 1.13.0 nebo novější

Při místním testování typů sad SDK na vašem počítači je také potřeba použít Azure Functions Core Tools verze 4.0.5000 nebo novější. Aktuální verzi můžete zkontrolovat pomocí func --version příkazu.

Každé vazební rozšíření má také požadovanou minimální verzi, která je popsána v odkazujících článcích o rozšíření. Vazební rozšíření v současné době podporují typy SDK:

Extension Types Úroveň podpory
Azure Blob Storage BlobClient
BlobContainerClient
BlockBlobClient
PageBlobClient
AppendBlobClient		 Aktivační událost: GA
Vstup: GA
Azure Cosmos DB CosmosClient
Database
Container		 Vstup: GA
Azure Event Grid CloudEvent
EventGridEvent		 Aktivační událost: GA
Azure Event Hubs EventData
EventHubProducerClient		 Aktivační událost: GA
Azure Queue Storage QueueClient
QueueMessage		 Aktivační událost: GA
Azure Service Bus ServiceBusClient
ServiceBusReceiver
ServiceBusSender
ServiceBusMessage		 Aktivační událost: GA
Azure Table Storage TableClient
TableEntity		 Vstup: GA

Úvahy o typech SDK:

  • Pokud používáte vazbové výrazy, které spoléhají na data triggeru , nelze použít typy sad SDK pro samotný trigger.
  • Ve výstupních scénářích, ve kterých můžete použít typ sady SDK, můžete vytvářet klienty sady SDK a pracovat s klienty sady SDK přímo místo použití výstupní vazby.
  • Trigger Azure Cosmos DB používá kanál změn Azure Cosmos DB a zveřejňuje položky kanálu změn jako serializovatelné typy JSON. V důsledku toho nejsou typy SDK podporované pro tento spouštěč.

HTTP spouštěč

Spouštěče HTTP umožňují, aby byla funkce vyvolána požadavkem HTTP. Můžete použít dva různé přístupy:

  • Model integrace ASP.NET Core, který používá koncepty známé ASP.NET Core vývojářům
  • Integrovaný model, který nevyžaduje další závislosti a používá vlastní typy pro požadavky a odpovědi HTTP. Tento přístup se udržuje kvůli zpětné kompatibilitě s předchozími .NET izolovanými pracovními aplikacemi.

integrace ASP.NET Core

Tato část ukazuje, jak pracovat s podkladovými objekty požadavků HTTP a odpovědí pomocí typů z ASP.NET Core, včetně HttpRequest, HttpResponse a IActionResult. Tento model není dostupný pro apps, jejichž cílem je .NET Framework, který by měl místo toho používat built-in model.

Poznámka:

Tento model nezpřístupňuje všechny funkce ASP.NET Core. Konkrétně neposkytuje přístup k ASP.NET Core kanálům middlewaru a možnostem směrování. ASP.NET Core integrace vyžaduje použití aktualizovaných balíčků.

Povolení integrace ASP.NET Core pro PROTOKOL HTTP:

  1. Přidejte do projektu odkaz na Microsoft.Azure. Functions.Worker.Extensions.Http.AspNetCore balíček verze 1.0.0 nebo novější.

  2. Aktualizujte project tak, aby používaly tyto konkrétní verze balíčků:

  3. Ve vašem Program.cs souboru aktualizujte konfiguraci tvůrce hostitelů pro zavolání ConfigureFunctionsWebApplication(). Tato metoda nahradí ConfigureFunctionsWorkerDefaults() , pokud byste tuto metodu použili jinak. Následující příklad ukazuje minimální nastavení bez dalších přizpůsobení:

    Poznámka:

    Aplikace musí odkazovat na verzi 2.0.0 nebo novější Microsoft.Azure. Functions.Worker.Extensions.Http.AspNetCore pro použití integrace ASP.NET Core s IHostApplicationBuilder.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();    

builder.Build().Run();

  4. Aktualizujte všechny existující funkce aktivované protokolem HTTP tak, aby používaly typy ASP.NET Core. Tento příklad ukazuje standard HttpRequest a IActionResult používá se pro jednoduchou funkci "hello, world":

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

Serializace JSON s integrací ASP.NET Core

ASP.NET Core má vlastní vrstvu serializace a není ovlivněn úpravami obecné konfigurace serializace. Chcete-li přizpůsobit chování serializace používané pro triggery HTTP, musíte zahrnout .AddMvc() volání jako součást registrace služby. Vrácenou IMvcBuilder můžete využít k úpravě nastavení serializace JSON v ASP.NET Core.

Při použití integrace ASP.NET můžete dál používat HttpRequestData a HttpResponseData, i když pro většinu aplikací je lepší místo toho použít HttpRequest a IActionResult. Použití HttpRequestData/HttpResponseData nevyvolá vrstvu serializace ASP.NET Core a místo toho spoléhá na konfiguraci serializace generální serializace pracovních procesů aplikace. Pokud je ale ASP.NET Core integrace povolená, možná budete muset přidat konfiguraci. Výchozí chování z ASP.NET Core je zakázat synchronní vstupně-výstupní operace. Pokud chcete použít vlastní serializátor, který nepodporuje asynchronní vstupně-výstupní operace, například NewtonsoftJsonObjectSerializermusíte pro aplikaci povolit synchronní vstupně-výstupní operace konfigurací KestrelServerOptions.

Následující příklad ukazuje, jak nakonfigurovat JSON.NET (Newtonsoft.Json) a Microsoft. Balíček NuGet AspNetCore.Mvc.NewtonsoftJson pro serializaci pomocí tohoto přístupu:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

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

Integrovaný model HTTP

V integrovaném modelu systém přeloží příchozí zprávu požadavku HTTP do objektu HttpRequestData, který předává funkci. Tento objekt poskytuje data z požadavku, včetně Headers, Cookies, Identities, URLa volitelně zprávy Body. Tento objekt představuje požadavek HTTP, ale není přímo připojený k podkladovému naslouchacímu procesu HTTP nebo přijaté zprávě.

Důležité

Pokud použijete HttpRequestData, text požadavku HTTP nemůže být datový proud. Pokud má například požadavek hlavičku Transfer-Encoding: chunked a žádnou hlavičku Content-Length, vlastnost objektu HttpRequestDataBody bude null stream. Pokud potřebujete pracovat se streamovanými požadavky HTTP, zvažte místo toho použití modelu integrace ASP.NET Core.

Podobně vrátí funkce objekt HttpResponseData, který poskytuje data použitá k vytvoření odpovědi HTTP, včetně zprávy StatusCode, Headers a volitelně zprávy Body.

Následující příklad ukazuje použití HttpRequestData a 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;
}

Protokolování

Do protokolů můžete zapisovat pomocí instance ILogger<T> nebo ILogger. Logger můžete získat injektováním závislostíILogger<T> nebo 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}");
    }

}

Poznámka:

Když do konstruktoru třídy vložíte ILogger<T>, jako v předchozím příkladu, kategorie záznamu se automaticky nastaví na plně kvalifikovaný název této třídy, například MyFunctionApp.MyFunction. Tyto názvy kategorií obsahují . (tečkové) znaky. Když hostujete funkční aplikaci na Linuxu, nemůžete použít proměnné prostředí pro přepsání úrovní protokolování u kategorií, které obsahují tečky. Pokud chcete toto omezení obejít, můžete místo toho nakonfigurovat úrovně protokolu v kódu nebo v appsettings.json souboru.

Protokolovací nástroj můžete získat také z objektu FunctionContext předaného vaší funkci. Zavolejte metodu GetLogger<T> nebo GetLogger a předejte jí řetězcovou hodnotu, která určuje název kategorie, do které se protokoly zapisují. Kategorie je obvykle název konkrétní funkce, ze které se protokoly zapisují. Další informace o kategoriích najdete v článku monitorování.

Použijte metody ILogger<T> a ILogger ke zápisu různých úrovní protokolu, například LogWarning nebo LogError. Další informace o úrovních protokolů najdete v článku monitorování. Úrovně protokolů pro komponenty přidané do kódu můžete přizpůsobit registrací filtrů:

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

V rámci konfigurace vaší aplikace v Program.cs můžete také definovat, jak se chyby zobrazují v protokolech. Výchozí chování závisí na typu tvůrce, který používáte.

Při použití IHostApplicationBuilder výjimky vyvolané vaším kódem procházejí systémem beze změn. Nepotřebujete žádnou jinou konfiguraci.

Application Insights

Aplikaci izolovaného procesu můžete nakonfigurovat tak, aby odesílala protokoly přímo do Application Insights. Tato konfigurace nahrazuje výchozí chování předávání protokolů prostřednictvím hostitele. Pokud nepoužíváte Aspire, nakonfigurujte přímou integraci Application Insights, abyste měli kontrolu nad tím, jak jsou tyto protokoly zaznamenávány.

Integrace Application Insights není ve výchozím nastavení ve všech prostředích nastavení povolená. Některé šablony vytvářejí projekty Functions s potřebnými balíčky a zakomentovaným spouštěcím kódem. Pokud chcete použít integraci Application Insights, odkomentujte tyto řádky v souboru Program.cs a project .csproj. Pokyny ve zbývající části této části také popisují, jak povolit integraci.

Pokud je váš project součástí orchestrace Aspire, používá k monitorování metodu OpenTelemetry. Nepovolujte přímou integraci Application Insights v projektech Aspire. Místo toho nakonfigurujte exportér Azure Monitor OpenTelemetry jako součást výchozího projektu služby. Pokud váš projekt Functions používá integraci s "Application Insights" v kontextu Aspire, dochází k chybám aplikace při spuštění.

Aktualizace host.json

Pokud chcete povolit výstup OpenTelemetry z hostitele Functions, aktualizujte soubor host.json v projektu kódu a přidejte "telemetryMode": "OpenTelemetry" do kořenové kolekce prvek. Když je povolený OpenTelemetry, může váš soubor host.json vypadat takto:

{
    "version": "2.0",
    "telemetryMode": "OpenTelemetry",
    ...
}

Instalace balíčků

Pokud chcete zapisovat protokoly přímo do Application Insights z kódu, přidejte do project odkazy na tyto balíčky:

Spuštěním následujících příkazů přidejte tyto odkazy do svého project:

dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

Konfigurace spuštění

Po instalaci balíčků zavolejte AddOpenTelemetry().UseFunctionsWorkerDefaults() a AddOpenTelemetry().UseAzureMonitorExporter() během konfigurace služby ve vašem souboru Program.cs, jak je znázorněno v následujícím příkladu.

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

builder.ConfigureFunctionsWebApplication();
builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Build().Run();

Další informace najdete v tématu Use OpenTelemetry with Azure Functions.

Správa úrovní protokolů

Důležité

Host Functions a izolovaný pracovní proces mají samostatnou konfiguraci pro úrovně protokolu. Jakákoli konfigurace v host.json nemá vliv na protokolování od pracovního procesu a podobně konfigurace v kódu pracovního procesu nemá vliv na protokolování z hostitele. Pokud váš scénář vyžaduje přizpůsobení v obou vrstvách, použijte změny na obou místech.

Úrovně protokolů můžete v izolovaném pracovním procesu nakonfigurovat jedním z těchto způsobů:

Metoda konfigurace Výhody
V kódu Podporuje jasnější oddělení mezi konfiguracemi na straně hostitele a na straně pracovního procesu.
Použití appsettings.json Užitečné, když chcete nastavit různé úrovně protokolů pro různé kategorie, aniž byste museli upravovat kód.

FunctionsApplication.CreateBuilder() automaticky načte konfiguraci ze appsettings.json souborů. Do souboru můžete přidat konfiguraci appsettings.json protokolování:

{
  "logging": {
    "logLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.Azure.Functions.Worker": "Information"
    }
  }
}

Tato konfigurace se automaticky použije při vytvoření sestavovače. Nejsou vyžadovány žádné další změny kódu v Program.cs:

using Azure.Monitor.OpenTelemetry.Exporter;
using Microsoft.Azure.Functions.Worker.Builder;
using Microsoft.Azure.Functions.Worker.OpenTelemetry;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

builder.Build().Run();

Další informace o konfiguraci protokolování najdete v tématu Logging v .NET a Application Insights pro aplikace pracovních služeb.

Optimalizace výkonu

Tato část popisuje možnosti, které umožňují zvýšit výkon při studeném startu.

Obecně platí, že vaše aplikace by měla používat nejnovější verze základních závislostí. Minimálně aktualizujte project následujícím způsobem:

  1. Upgradujte Microsoft.Azure. Functions.Worker verze 1.19.0 nebo novější.
  2. Upgradujte Microsoft.Azure. Functions.Worker.Sdk verze 1.16.4 nebo novější.
  3. Pokud vaše aplikace necílí na .NET Framework, přidejte odkaz na framework Microsoft.AspNetCore.App.

Následující fragment kódu ukazuje tuto konfiguraci v kontextu souboru project:

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

Zástupné symboly

Zástupné prvky jsou možnost platformy, která zlepšuje studený start pro aplikace cílící na .NET 6 nebo novější verze. Pokud chcete tuto optimalizaci použít, musíte zástupné symboly explicitně povolit pomocí následujících kroků:

  1. Aktualizujte konfiguraci project tak, aby používala nejnovější verze závislostí, jak je podrobně popsáno v předchozí části.

  2. Nastavte WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED nastavení aplikace na 1. Použijte tento příkaz az functionapp config appsettings set:

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

    V tomto příkladu nahraďte <groupName> názvem skupiny prostředků a nahraďte <appName> názvem vaší aplikace funkcí.

  3. Ujistěte se, že vlastnost netFrameworkVersion aplikace funkcí odpovídá cílovému rozhraní projektu, které musí být .NET 6 nebo novější. Použijte tento příkaz az functionapp config set:

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

    V tomto příkladu nahraďte také <framework> odpovídajícím řetězcem verze, například v8.0 podle cílové verze .NET.

  4. Ujistěte se, že je vaše aplikace funkcí nakonfigurovaná tak, aby používala 64bitový proces. Použijte tento příkaz az functionapp config set:

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

Důležité

Při nastavování WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED na 1 hodnotu musíte správně nastavit všechny ostatní konfigurace funkční aplikace. Jinak se aplikace funkcí nemusí spustit.

Optimalizovaný exekutor

Vykonavatel funkcí je komponenta platformy, která spouští vyvolání. Optimalizovaná verze této komponenty je ve výchozím nastavení povolená od verze 1.16.2 sady SDK. Nevyžaduje se žádná jiná konfigurace.

ReadyToRun

Aplikaci funkcí můžete zkompilovat jako binární soubory ReadyToRun. ReadyToRun je forma předběžné kompilace, která může zlepšit výkon při spouštění, čímž se pomáhá snížit účinek studených startů při běhu v plánu Consumption. ReadyToRun je k dispozici v .NET 6 a novějších verzích a vyžaduje version 4.0 nebo novější modulu runtime Azure Functions.

ReadyToRun vyžaduje, abyste projekt vytvořili pro runtime architekturu hostitelské aplikace. Pokud tyto architektury nejsou zarovnané, aplikace při spuštění narazí na chybu. Vyberte z této tabulky identifikátor runtime.

Operační systém Aplikace je 32bitová 1. Identifikátor modulu runtime
Windows Pravda win-x86
Windows Nepravda win-x64
Operační systém Linux Pravda Není k dispozici (nepodporuje se)
Operační systém Linux Nepravda linux-x64

1 Pouze 64bitové aplikace mají nárok na některé další optimalizace výkonu.

Pokud chcete zkontrolovat, jestli je aplikace Windows 32bitová nebo 64bitová, spusťte následující příkaz rozhraní příkazového řádku a nahraďte <group_name> názvem vaší skupiny prostředků a <app_name> názvem vaší aplikace. Výstup "true" označuje, že aplikace je 32bitová a "false" označuje 64bitovou verzi.

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

Aplikaci můžete změnit na 64bitovou verzi pomocí následujícího příkazu, a to pomocí stejných nahrazení:

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

Pokud chcete zkompilovat project jako ReadyToRun, aktualizujte soubor project přidáním elementů <PublishReadyToRun> a <RuntimeIdentifier>. Následující příklad ukazuje konfiguraci pro nasazení do funkční aplikace ve Windows 64bitové verzi.

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

Pokud nechcete nastavit <RuntimeIdentifier> jako součást souboru project, můžete toto nastavení nakonfigurovat také jako součást samotného gesta publikování. Například s funkční aplikací pro Windows 64bit je příkaz CLI .NET:

dotnet publish --runtime win-x64

V Visual Studio nastavte v profilu publikování možnost Target Runtime na správný identifikátor modulu runtime. Pokud je nastavena výchozí hodnota Portable, ReadyToRun se nepoužívá.

Nasazení do Azure Functions

Když nasadíte projekt kódu funkce do Azure, musí se spustit v aplikaci funkcí nebo v kontejneru Linuxu. Před nasazením kódu musíte vytvořit aplikaci funkcí a další požadované prostředky Azure.

Aplikaci funkcí můžete také nasadit v kontejneru Linuxu. Další informace najdete v tématu Pracování s kontejnery a Azure Functions.

Vytvoření Azure prostředků

Aplikaci funkcí a další požadované prostředky můžete vytvořit v Azure pomocí jedné z těchto metod:

  • Visual Studio: Visual Studio může během procesu publikování kódu vytvořit prostředky.
  • Visual Studio Code: Visual Studio Code se může připojit k vašemu předplatnému, vytvořit prostředky potřebné vaší aplikací a pak publikovat kód.
  • Azure CLI: Pomocí Azure CLI vytvořte požadované prostředky v Azure.
  • Azure PowerShell: Pomocí Azure PowerShell vytvořte požadované prostředky v Azure.
  • Deployment templates: K automatizaci nasazení požadovaných prostředků do Azure použijte šablony ARM a Bicep soubory. Ujistěte se, že vaše šablona obsahuje všechna požadovaná nastavení.
  • Azure portal: Vytvořte požadované prostředky na portálu Azure.

Publikování aplikace

Po vytvoření aplikace funkcí a dalších požadovaných prostředků v Azure nasaďte projekt kódu do Azure pomocí jedné z těchto metod:

Další informace najdete v tématu Odployment technologie v Azure Functions.

Nasazovací balíček

Řada metod nasazení používá archiv zip. Pokud archiv zip vytvoříte sami, musí se řídit strukturou popsanou v této části. Pokud tomu tak není, může u vaší aplikace dojít k chybám při spuštění.

Datová část nasazení by se měla shodovat s výstupem dotnet publish příkazu, i když bez nadřazené složky. Archiv zip by měl být vytvořen z následujících souborů:

  • .azurefunctions/
  • extensions.json
  • functions.metadata
  • host.json
  • worker.config.json
  • Spustitelný soubor projektu (konzolová aplikace)
  • Další podpůrné soubory a adresáře jsou na stejné úrovni jako tento spustitelný soubor.

Proces sestavení tyto soubory vygeneruje a neměli byste je upravovat přímo.

Návod

Příkaz v func pack nástrojích Core Tools můžete použít k správnému vygenerování archivu zip pro nasazení. Podpora pro func pack je aktuálně ve verzi Preview.

Při přípravě archivu zip pro nasazení komprimujte pouze obsah výstupního adresáře, nikoli samotný nadřazený adresář. Když se archiv extrahuje do aktuálního pracovního adresáře, musí být soubory uvedené dříve okamžitě viditelné.

Požadavky na nasazení

Pokud chcete spustit .NET funkce v izolovaném pracovním modelu v Azure, musíte splnit několik požadavků. Požadavky závisí na operačním systému:

Když vytvoříte aplikaci funkcí v Azure pomocí metod v předchozí části, tato požadovaná nastavení se za vás přidají. Při vytváření těchto prostředků pomocí šablon ARM nebo Bicep souborů pro automatizaci je nutné je nastavit v šabloně.

'Aspire'

Aspire je názorově zaměřený stack, který zjednodušuje vývoj distribuovaných aplikací v cloudu. Projekty izolovaného modelu pracovních procesů můžete zahrnout do orchestrací Aspire 13. Další informace najdete v tématu Azure Functions s Aspire.

Ladění

Při místním spuštění pomocí Visual Studio nebo Visual Studio Code můžete ladit .NET izolovaný pracovní projekt jako obvykle. Existují však dva scénáře ladění, které nefungují podle očekávání.

Vzdálené ladění pomocí Visual Studio

Vzhledem k tomu, že aplikace izolovaného pracovního procesu běží vně prostředí Functions runtime, musíte vzdálený debugger připojit k samostatnému procesu. Další informace o ladění pomocí Visual Studio viz Vzdálené ladění.

Ladění aplikací na platformě .NET Framework

Pokud váš izolovaný projekt cílí na .NET Framework 4.8, musíte provést ruční kroky pro povolení ladění. Pokud používáte jinou cílovou architekturu, tyto kroky se nevyžadují.

Aplikace by měla začínat voláním FunctionsDebugger.Enable(); jako první operace. K tomu dochází v Main() metodě před inicializací HostBuilder. Soubor Program.cs by měl vypadat nějak takto:

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

Dále je potřeba se ručně připojit k procesu pomocí debuggeru .NET Framework. Visual Studio to zatím neprovádí automaticky u izolovaných pracovních procesů .NET Framework a operace Spustit ladění by se měla vyhnout.

V adresáři projektu (nebo v adresáři s výstupy sestavení) spusťte:

func host start --dotnet-isolated-debug

Tím se spustí váš pracovní proces a proces se zastaví následující zprávou:

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

Kde <process id> je ID pracovního procesu. Teď můžete použít Visual Studio k ručnímu připojení k procesu. Pokyny k této operaci najdete v tématu Připojení ke spuštěném procesu.

Po připojení ladicího programu se provádění procesu obnoví a budete moct ladit.

Verze .NET náhled

Před obecně dostupnou verzí může být verze .NET vydána ve stavu Preview nebo Go-live. Podrobnosti o těchto státech najdete v .NET oficiální zásady podpory.

I když může být možné cílit na danou verzi z místního projektu Functions, aplikace funkcí hostované v Azure nemusí mít k dispozici danou verzi. Azure Functions je možné použít pouze s verzemi Preview nebo Go live, které jsou uvedené v této části.

Azure Functions v současné době nefunguje s žádnými verzemi Preview ani "Go-live" .NET. Seznam obecně dostupných verzí, které můžete použít, najdete v části Podporované verze .

Použití sady Preview .NET SDK

Pokud chcete použít Azure Functions s verzí Preview .NET, musíte projekt aktualizovat pomocí těchto možností:

  1. Instalace příslušné verze sady .NET SDK ve vašem vývoji
  2. Změna nastavení TargetFramework ve .csproj souboru.

Když nasadíte do aplikace funkcí v Azure, musíte také zajistit, aby byla architektura dostupná pro aplikaci. Během období náhledu nemusí některé nástroje a prostředí zobrazit novou verzi náhledu jako možnost. Pokud nevidíte verzi Preview, která je součástí portálu Azure, můžete k ruční konfiguraci verze použít rozhraní REST API, Bicep soubory nebo Azure CLI.

Pro aplikace hostované na Windows použijte následující příkaz Azure CLI. Nahraďte <groupName> názvem skupiny prostředků a nahraďte <appName> názvem vaší aplikace funkcí. Nahraďte <framework> odpovídajícím řetězcem verze, například v8.0.

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

Důležité informace o používání verzí .NET Preview

Při používání funkcí s verzemi Preview .NET mějte na paměti tyto aspekty:

  • Když vytváříte funkce v Visual Studio, musíte použít Visual Studio Insiders, což podporuje vytváření Azure Functions projektů pomocí sad SDK .NET Preview.

  • Ujistěte se, že máte nejnovější nástroje a šablony Functions. Aktualizace nástrojů:

    1. Přejděte na Nástroje>Možnosti, v části Projekty a řešení zvolte Azure Functions>Další nastavení.
    2. Podle výzvy vyberte Vyhledat aktualizace a nainstalovat aktualizace.

  • Během období Preview může mít vaše vývojové prostředí novější verzi .NET Preview než hostovaná služba. To může způsobit selhání vaší funkční aplikace při nasazení do provozu. Chcete-li to vyřešit, můžete zadat verzi sady SDK, která se má použít v global.json.

    1. dotnet --list-sdks Spusťte příkaz a poznamenejte si verzi Preview, kterou aktuálně používáte při místním vývoji.
    2. dotnet new globaljson --sdk-version <SDK_VERSION> --force Spusťte příkaz, kde <SDK_VERSION> je verze, kterou používáte místně. Například dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force způsobí, že systém při sestavování projektu použije sadu .NET 10 Preview 5 SDK.

Poznámka:

Vzhledem k načítání architektur preview za běhu můžou aplikace funkcí běžící na Windows při porovnání s dřívějšími verzemi GA zaznamenat vyšší dobu spuštění za běhu.

Další kroky

Uučte se více o osvědčených postupech pro Azure Functions

Migrace aplikací .NET do izolovaného modelu pracovního procesu

Integrace s Aspire

  • Last updated on