Sdílet prostřednictvím


Průvodce spuštěním azure Functions v C# v izolovaném pracovním modelu

Tento článek představuje úvod do práce se službou Azure Functions v .NET pomocí izolovaného modelu pracovního procesu. Tento model umožňuje projektu cílit na verze .NET nezávisle na jiných komponentách modulu runtime. Informace o podporovaných verzích .NET najdete v části Podporované verze.

Pomocí následujících odkazů můžete hned začít vytvářet funkce izolovaného pracovního modelu .NET.

Začínáme Koncepty Ukázky

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

Výhody izolovaného modelu pracovního procesu

Existují dva režimy, ve kterých můžete spouštět funkce knihovny tříd .NET: buď ve stejném procesu jako modul runtime hostitele služby Functions (v procesu), nebo v izolovaném pracovním procesu. Když se funkce .NET spouštějí 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.
  • Standardní injektáž závislostí: Vzhledem k tomu, že máte úplnou kontrolu nad procesem, můžete použít aktuální chování .NET pro injektáž závislostí a začlenit middleware do vaší aplikace funkcí.
  • Flexibilita verze .NET: Spuštění mimo hostitelský proces znamená, že vaše funkce se můžou spouštět ve verzích .NET, které modul runtime služby Functions nativně nepodporuje, 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 aplikací .NET z modelu v procesu do izolovaného pracovního modelu.

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

Podporované verze

Verze modulu runtime Služby Functions podporují konkrétní verze rozhraní .NET. Další informace o verzích functions najdete v přehledu verzí modulu runtime Azure Functions. Podpora verzí také závisí na tom, jestli vaše funkce běží v procesu nebo izolovaný pracovní proces.

Poznámka:

Informace o tom, jak změnit verzi modulu runtime Functions používanou vaší aplikací funkcí, najdete v zobrazení a aktualizaci aktuální verze modulu runtime.

Následující tabulka ukazuje nejvyšší úroveň rozhraní .NET nebo .NET Framework, kterou je možné 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 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. Rozhraní .NET 7 bylo dříve podporováno v izolovaném modelu pracovních procesů, ale dosáhlo konce oficiální podpory 14. května 2024.

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

3 Podpora modulu runtime Azure Functions končí 1.x 14. září 2026. Další informace najdete v tomto 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. Další informace najdete v tomto oznámení podpory. Pokud chcete pokračovat v plné podpoře, měli byste své aplikace migrovat do izolovaného pracovního modelu.

Nejnovější zprávy o vydaných verzích Azure Functions, včetně odebrání konkrétních starších podverzí, monitorujte oznámení služby Aplikace Azure.

Struktura projektu

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

  • Soubor projektu jazyka C# (.csproj), který definuje projekt 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 v projektu.
  • local.settings.json soubor, který definuje proměnné prostředí používané vaším projektem při místním spuštění na 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 využívající izolovaný model pracovního procesu používá jedinečnou sadu balíčků pro základní funkce i rozšíření vazeb.

Základní balíčky

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

Verze 2.x

Verze 2.x základních balíčků mění podporované architektury a přinášejí podporu nových rozhraní .NET API z těchto novějších verzí. Když cílíte na .NET 9 nebo novější, musí vaše aplikace odkazovat na verzi 2.0.0 nebo novější obou balíčků.

Při aktualizaci na verze 2.x mějte na paměti následující změny:

  • Počínaje verzí 2.0.0 sady Microsoft.Azure.Functions.Worker.Sdk:
  • 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 povolená, aktivační datové části, které představují kolekce, vždy obsahují prázdné položky. Pokud se například zpráva odešle bez textu, bude pro data triggeru stále k dispozici string[] 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 v false 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 tento přepsal další kódy chyb, které byly nastaveny.
  • Verze 2.x odstraňte podporu TFM .NET 5.

Balíčky rozšíření

Vzhledem k tomu, že funkce izolovaného pracovního procesu .NET 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ího procesu máte přístup ke spuštění vaší aplikace funkcí, 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 ke konfiguračnímu kanálu pro vaši aplikaci. 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.

Následující kód ukazuje příklad kanálu HostBuilder :

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

Tento kód vyžaduje using Microsoft.Extensions.DependencyInjection;.

Před voláním Build() na tuto možnost IHostBuilderbyste měli:

  • Volejte buď ConfigureFunctionsWebApplication() pomocí integrace ASP.NET Core , nebo ConfigureFunctionsWorkerDefaults() jinak. Podrobnosti o těchto možnostech najdete v triggeru HTTP.
    Pokud píšete aplikaci pomocí F#, některá rozšíření triggeru a vazeb vyžadují další konfiguraci. Pokud plánujete používat tato rozšíření v aplikaci F#, podívejte se do dokumentace k nastavení rozšíření Blobs, rozšíření Tables a rozšíření Cosmos DB.
  • 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 zavolat AddApplicationInsightsTelemetryWorkerService() a ConfigureFunctionsApplicationInsights() v delegátovi ConfigureServices() . Podrobnosti najdete v Application Insights .

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

HostBuilder se používá k sestavení a vrácení plně inicializované IHost instance, kterou spustíte asynchronně, aby se spustila aplikace funkcí.

await host.RunAsync();

Konfigurace

Typ tvůrce, který použijete, určuje, jak můžete aplikaci nakonfigurovat.

Metoda ConfigureFunctionsWorkerDefaults slouží k přidání nastavení vyžadovaných pro 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í.
  • Integrace s protokolováním Azure Functions
  • Middleware a funkce výstupní vazby
  • Middleware spouštění funkcí
  • Výchozí podpora gRPC
.ConfigureFunctionsWorkerDefaults()

Přístup ke kanálu tvůrce hostitelů znamená, že během inicializace můžete také nastavit jakékoli konfigurace specifické pro aplikaci. Metodu ConfigureAppConfiguration můžete v HostBuilderu volat jednou nebo vícekrát a přidat tak jakékoli zdroje konfigurace vyžadované vaším kódem. Další informace o konfiguraci aplikací najdete v tématu Konfigurace v ASP.NET Core.

Tyto konfigurace platí jenom pro vytvořený pracovní kód a nemají přímý vliv na konfiguraci hostitele nebo triggerů a vazeb Functions. Pokud chcete provést změny hostitele nebo konfigurace triggeru a vazby funkcí, musíte stále použít soubor host.json.

Poznámka:

Vlastní zdroje konfigurace nelze 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ů služby Key Vault nebo odkazů na konfiguraci aplikací.

Injektáž závislostí

Izolovaný pracovní model používá standardní mechanismy .NET pro vkládání služeb.

Při použití HostBuilder, volání ConfigureServices v tvůrci hostitelů a použití rozšiřujících metod v IServiceCollection pro vložení konkrétních služeb. Následující příklad vloží závislost jednoúčelové služby:

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

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

Registrace klientů Azure

Injektáž závislostí se dá použít k interakci s jinými službami Azure. Klienty ze sady Azure SDK pro .NET můžete vložit pomocí balíčku Microsoft.Extensions.Azure . Po instalaci balíčku zaregistrujte klienty voláním AddAzureClients() kolekce služby v Program.cs. Následující příklad nakonfiguruje pojmenovaného klienta pro objekty blob Azure:

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

Následující příklad ukazuje, jak můžeme pomocí této registrace a typů sady 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 ILogger<T> tomto příkladu se také získal prostřednictvím injektáže závislostí, takže se automaticky zaregistruje. Další informace o možnostech konfigurace pro protokolování najdete v tématu Protokolování.

Tip

Příklad použil literálový řetězec pro název klienta v obou Program.cs i funkci. Zvažte místo toho 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 pak odkazovat BlobCopier.CopyStorageClientName na obě umístění. 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í.

ConfigureFunctionsWorkerDefaults extension metoda má přetížení, které umožňuje zaregistrovat vlastní middleware, jak je vidět v následujícím příkladu.

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

Metodu UseWhen rozšíření lze použít k registraci middlewaru, který se spustí podmíněně. Této metodě je nutné předat predikát, který vrátí logickou hodnotu, a middleware se účastní volání kanálu zpracování, pokud je truenávratová hodnota predikátu .

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

metoda Popis
GetHttpRequestDataAsync HttpRequestData Získá instanci při zavolání triggerem HTTP. 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 HttpResponseData Získá instanci při zavolání triggerem HTTP.
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á výstupní vazby položky 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 vstupní položky vazby pro požadovanou BindingMetadata instanci. Tuto metodu můžete použít například v případě, že máte funkci se vstupní vazbou BlobInput , kterou potřebuje váš middleware použít.

Toto je příklad implementace middlewaru, která čte HttpRequestData 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 zkontroluje přítomnost konkrétní hlavičky požadavku (x-correlationId) a když je k označení hlavičky odpovědi použitá hodnota hlavičky. V opačném případě vygeneruje novou hodnotu GUID a použije ji pro razítko hlavičky odpovědi. Kompletní příklad použití vlastního middlewaru v aplikaci funkcí najdete v ukázce vlastních referenčních informací k middlewaru.

Přizpůsobení serializace JSON

Model izolovaného pracovního procesu 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 zabývá serializací pro obecné účely a neovlivní serializaci JSON triggeru HTTP s integrací ASP.NET Core, která musí být nakonfigurovaná samostatně.

Následující příklad ukazuje použití ConfigureFunctionsWebApplication, ale bude fungovat také pro 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();

Místo toho můžete k serializaci použít JSON.NET (Newtonsoft.Json). Uděláte to tak, že balíček nainstalujete Microsoft.Azure.Core.NewtonsoftJson . Potom v registraci služby byste vlastnost WorkerOptions při konfiguraci znovu přiřadiliSerializer. Následující příklad ukazuje použití ConfigureFunctionsWebApplication, ale bude fungovat také pro 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();

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(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([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 zprávou 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 v rámci projektu jedinečný, musí začínat písmenem a obsahovat pouze písmena, _číslice a -až 127 znaků. Šablony projektů č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 metoda instance, aby služby mohly být předány prostřednictvím injektáže 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í.
  • Token zrušení, který se používá k řádnému vypnutí.

Kontext spuštění

Izolované rozhraní .NET předá objekt FunctionContext vašim metodám funkce. Tento objekt umožňuje získat ILogger instanci pro zápis do protokolů voláním GetLogger metody a zadáním categoryName řetězce. Tento kontext můžete použít k získání ILogger bez nutnosti použití injektáže závislostí. Další informace najdete v tématu Protokolování.

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

Tokeny zrušení jsou podporovány ve funkcích .NET při spuštění v izolovaném pracovním procesu. 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);
    }
}

Vazby

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

Informace o triggerech HTTP najdete v části triggeru HTTP.

Kompletní sadu referenčních ukázek s využitím triggerů a vazeb s funkcemi izolovaného pracovního procesu najdete v ukázce odkazů na rozšíření vazeb.

Vstupní vazby

Funkce může mít nulové nebo více vstupních vazeb, které mohou předávat data do funkce. Podobně jako triggery jsou vstupní vazby definovány 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 pomocí parametrů vazby.

Výstupní vazby

Pokud chcete zapisovat do výstupní vazby, musíte použít atribut výstupní vazby na metodu funkce, která definuje, jak zapisovat do vázané služby. Hodnota vrácená metodou 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(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;
}

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 pomocí integrace ASP.NET Core, která zapisuje jak do odpovědi HTTP, tak 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; }
    }
}

Při použití vlastních návratových typů pro více výstupních vazeb s integrací ASP.NET Core je nutné přidat [HttpResult] atribut do vlastnosti, která poskytuje výsledek. Atribut HttpResult je k dispozici při použití sady SDK 1.17.3-preview2 nebo novější společně s verzí 3.2.0 nebo novější rozšíření HTTP a verzí 1.3.0 nebo novější rozšíření ASP.NET Core.

Typy sad SDK

U některých typů vazeb specifických pro službu je možné data vazby poskytnout pomocí typů ze sad SDK a architektur služby. Poskytují další možnosti nad rámec toho, co serializovaný řetězec nebo prostý objekt CLR (POCO) může nabídnout. Pokud chcete použít novější typy, je potřeba projekt aktualizovat, aby používal novější verze základních závislostí.

Dependency 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 musíte také použít Nástroje Azure Functions Core Tools verze 4.0.5000 nebo novější. Aktuální verzi můžete zkontrolovat pomocí func version příkazu.

Každé rozšíření triggeru a vazby má také vlastní požadavek na minimální verzi, který je popsán v referenčních článcích o rozšíření. Následující vazby specifické pro službu poskytují typy sad SDK:

Služba Trigger Vstupní vazba Výstupní vazba
Objekty blob Azure Obecně dostupné Obecně dostupné Nedoporučují se typy sad SDK.1
Fronty Azure Obecně dostupné Vstupní vazba neexistuje. Nedoporučují se typy sad SDK.1
Azure Service Bus Obecně dostupné Vstupní vazba neexistuje. Nedoporučují se typy sad SDK.1
Azure Event Hubs Obecně dostupné Vstupní vazba neexistuje. Nedoporučují se typy sad SDK.1
Azure Cosmos DB Typy sad SDK se nepoužívají2 Obecně dostupné Nedoporučují se typy sad SDK.1
Tabulky Azure Aktivační událost neexistuje. Obecně dostupné Nedoporučují se typy sad SDK.1
Azure Event Grid Obecně dostupné Vstupní vazba neexistuje. Nedoporučují se typy sad SDK.1

1 Pro výstupní scénáře, ve kterých byste použili typ sady SDK, byste měli vytvořit a pracovat s klienty sady SDK přímo místo použití výstupní vazby. Příklad injektáže závislostí najdete v tématu Registrace klientů Azure.

2 Trigger služby Cosmos DB používá kanál změn služby Azure Cosmos DB a zveřejňuje položky kanálu změn jako serializovatelné typy JSON. Pro tento scénář není k dispozici typy sad SDK.

Poznámka:

Pokud používáte vazbové výrazy, které spoléhají na data triggeru , nelze použít typy sad SDK pro samotný trigger.

Trigger HTTP

Triggery HTTP umožňují vyvolání funkce požadavkem HTTP. Existují dva různé přístupy, které je možné použít:

  • Model integrace ASP.NET Core, který používá koncepty známé pro vývojáře ASP.NET Core
  • 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 izolovanými pracovními aplikacemi .NET.

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í k dispozici pro aplikace cílené na rozhraní .NET Framework, které by místo toho měly používat integrovaný model.

Poznámka:

V tomto modelu nejsou vystaveny všechny funkce ASP.NET Core. Konkrétně nejsou k dispozici možnosti ASP.NET základního middlewaru a směrování. integrace ASP.NET Core vyžaduje použití aktualizovaných balíčků.

Povolení integrace ASP.NET Core pro PROTOKOL HTTP:

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

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

  3. V souboru aktualizujte Program.cs konfiguraci tvůrce hostitelů tak, aby volala ConfigureFunctionsWebApplication(). Tím se nahradí ConfigureFunctionsWorkerDefaults() , pokud byste tuto metodu použili jinak. Následující příklad ukazuje minimální nastavení bez dalších přizpůsobení:

    using Microsoft.Azure.Functions.Worker;
    using Microsoft.Extensions.Hosting;
    
    var host = new HostBuilder()
        .ConfigureFunctionsWebApplication()
        .Build();
    
    host.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ěna přizpůsobením 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. IMvcBuilder Vrácený kód lze použít ke změně nastavení serializace JSON ASP.NET Core.

Při používání ASP.NET integrace můžete i nadále používat HttpRequestData HttpResponsedata , i když u většiny aplikací je lepší místo toho používat HttpRequest a IActionResult. Použití HttpRequestData/HttpResponseData nevyvolá vrstvu serializace ASP.NET Core a místo toho spoléhá na obecnou konfiguraci serializace pracovních procesů pro aplikaci. Pokud je ale povolená integrace ASP.NET Core, 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, jako NewtonsoftJsonObjectSerializerje například , je nutné povolit synchronní vstupně-výstupní operace pro vaši aplikaci konfigurací KestrelServerOptions.

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

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

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

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

Integrovaný model HTTP

V integrovaném modelu systém přeloží příchozí zprávu požadavku HTTP na objekt HttpRequestData , který je předán 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ě.

Podobně funkce vrátí objekt HttpResponseData , který poskytuje data použitá k vytvoření odpovědi HTTP, včetně zprávy StatusCode, Headersa 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í instanceILogger<T>.ILogger Protokolovací objekt lze získat prostřednictvím injektáže ILogger<T> závislostí 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}");
    }

}

Protokolovací objekt lze také získat z objektu FunctionContext předaného vaší funkci. Volání GetLogger<T> nebo GetLogger metoda, která předává řetězcovou hodnotu, která je název kategorie, ve které jsou protokoly zapsány. Kategorie je obvykle název konkrétní funkce, ze které se protokoly zapisují. Další informace o kategoriích najdete v článku o monitorování.

Použití metod ILogger<T> a ILogger zápisu různých úrovní protokolu, například LogWarning nebo LogError. Další informace o úrovních protokolů najdete v článku o 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.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();

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

Když ve výchozím nastavení použijete HostBuildervýjimku vyvolanou vaším kódem, můžou být zabalené do souboru RpcException. Pokud chcete tuto extra vrstvu EnableUserCodeException odebrat, nastavte vlastnost na true jako součást konfigurace tvůrce:

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

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

host.Run();

Application Insights

Aplikaci izolovaného procesu můžete nakonfigurovat tak, aby vygenerovala protokoly přímo do Application Insights. Toto chování nahrazuje výchozí chování předávání protokolů prostřednictvím hostitele. Pokud nepoužíváte .NET Aspire, doporučujeme nakonfigurovat přímou integraci Application Insights, protože vám dává kontrolu nad tím, jak se tyto protokoly vygenerují.

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

Pokud je váš projekt součástí orchestrace .NET Aspire, používá k monitorování metodu OpenTelemetry. Neměli byste povolit přímou integraci Application Insights v projektech .NET Aspire. Místo toho nakonfigurujte exportér OpenTelemetry služby Azure Monitor jako součást výchozího projektu služby. Pokud váš projekt Functions používá integraci Application Insights v kontextu .NET Aspire, aplikace se při spuštění zobrazí chyba.

Instalace balíčků

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

Spuštěním následujících příkazů můžete do projektu přidat tyto odkazy:

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

Konfigurace spuštění

S nainstalovanými balíčky musíte volat AddApplicationInsightsTelemetryWorkerService() a ConfigureFunctionsApplicationInsights() během konfigurace služby v Program.cs souboru, jak je znázorněno v tomto příkladu:

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

Volání, které ConfigureFunctionsApplicationInsights() přidá , ITelemetryModulekterý naslouchá funkcím definovaný ActivitySource. Tím se vytvoří telemetrie závislostí potřebná k podpoře distribuovaného trasování. Další informace o AddApplicationInsightsTelemetryWorkerService() aplikaci a jeho použití najdete v tématu Application Insights pro aplikace pracovních služeb.

Správa úrovní protokolů

Důležité

Hostitel služby Functions a pracovní proces izolovaného procesu mají samostatnou konfiguraci pro úrovně protokolů atd. Jakákoli konfigurace Application Insights v host.json nebude mít vliv na protokolování z pracovního procesu a podobně konfigurace provedená v kódu pracovního procesu nebude mít vliv na protokolování z hostitele. Pokud váš scénář vyžaduje přizpůsobení v obou vrstvách, musíte změny použít na obou místech.

Zbývající část aplikace nadále pracuje s ILogger aplikací a ILogger<T>. Sada Application Insights SDK ale ve výchozím nastavení přidává filtr protokolování, který protokolovacímu nástroji dává pokyn, aby zaznamenával pouze upozornění a vážnější protokoly. Pokud chcete toto chování zakázat, odeberte pravidlo filtru jako součást konfigurace služby:

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

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í. Projekt byste měli minimálně aktualizovat následujícím způsobem:

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

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

  <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é symboly jsou funkce platformy, která zlepšuje studený start pro aplikace, které cílí na .NET 6 nebo novější. Pokud chcete tuto optimalizaci použít, musíte zástupné symboly explicitně povolit pomocí následujícího postupu:

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

  2. WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED Nastavte nastavení aplikace na 1, které můžete provést pomocí tohoto příkazu 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 netFrameworkVersion vlastnost aplikace funkcí odpovídá cílové rozhraní vašeho projektu, což musí být .NET 6 nebo novější. Můžete to provést pomocí tohoto příkazu az functionapp config set :

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

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

  4. Ujistěte se, že je vaše aplikace funkcí nakonfigurovaná tak, aby používala 64bitový proces, který můžete provést pomocí tohoto příkazu 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 1hodnotu musí být správně nastaveny všechny ostatní konfigurace aplikace funkcí. Jinak se aplikace funkcí nemusí spustit.

Optimalizovaný exekutor

Exekutor funkce je komponenta platformy, která způsobuje spuštění 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ředem připravené kompilace, která může zlepšit výkon spouštění, což pomáhá snížit účinek studených startů při spuštění v plánu Consumption. ReadyToRun je k dispozici v .NET 6 a novějších verzích a vyžaduje verzi 4.0 nebo novější modulu runtime Azure Functions.

ReadyToRun vyžaduje, abyste projekt sestavili v architektuře modulu runtime hostitelské aplikace. Pokud tyto hodnoty nejsou zarovnané, aplikace při spuštění narazí na chybu. V této tabulce vyberte identifikátor modulu runtime:

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

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

Pokud chcete zkontrolovat, jestli je vaše aplikace pro Windows 32bitová nebo 64bitová, můžete spustit následující příkaz rozhraní příkazového řádku, nahradit <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 projekt zkompilovat jako ReadyToRun, aktualizujte soubor projektu přidáním <PublishReadyToRun> prvků a <RuntimeIdentifier> prvků. Následující příklad ukazuje konfiguraci pro publikování do 64bitové aplikace funkcí pro Windows.

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

Pokud nechcete nastavit <RuntimeIdentifier> soubor projektu jako součást souboru projektu, můžete ho také nakonfigurovat jako součást samotného gesta publikování. Například s 64bitovou aplikací funkcí pro Windows by příkaz .NET CLI byl:

dotnet publish --runtime win-x64

V sadě Visual Studio by měla být možnost Cílový modul runtime v profilu publikování nastavená 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 buď v aplikaci funkcí, nebo v kontejneru Linuxu. Aplikace funkcí a další požadované prostředky Azure musí existovat před nasazením kódu.

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

Vytvoření zdrojů Azure

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

Publikování aplikace

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

Další informace najdete v tématu Technologie nasazení ve službě Azure Functions.

Datová část nasazení

Řada metod nasazení využívá archiv zip. Pokud archiv zip vytváříte sami, musí se řídit strukturou popsanou v této části. Pokud ne, může se při spuštění aplikace zobrazit chyby.

Datová část nasazení by se měla shodovat s výstupem dotnet publish příkazu, i když bez nadřazené nadřazené složky. Archiv zip by měl být proveden 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 peer s tímto spustitelným souborem

Tyto soubory jsou generovány procesem sestavení a nemají být upraveny přímo.

Při přípravě archivu zip pro nasazení byste měli zkomprimovat 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 výše uvedené soubory okamžitě viditelné.

Požadavky na nasazení

V závislosti na operačním systému existuje několik požadavků na spouštění funkcí .NET v izolovaném pracovním modelu v Azure:

  • FUNCTIONS_WORKER_RUNTIME musí být nastavena na hodnotu dotnet-isolated.
  • NetFrameworkVersion musí být nastavena na požadovanou verzi.

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

.NET Aspire (Preview)

.NET Aspire je názorný zásobník, který zjednodušuje vývoj distribuovaných aplikací v cloudu. Projekty izolovaného pracovního modelu .NET 8 a .NET 9 můžete zahrnout do orchestrací Aspire 9.0 pomocí podpory preview. Tato část popisuje základní požadavky na zařazení.

Tato integrace vyžaduje konkrétní nastavení:

  • Použijte Aspire 9.0 nebo novější a sadu .NET 9 SDK. Aspire 9.0 podporuje architektury .NET 8 a .NET 9.
  • Pokud používáte Visual Studio, aktualizujte na verzi 17.12 nebo novější. Musíte mít také nejnovější verzi nástrojů Functions pro Visual Studio. Pokud chcete vyhledat aktualizace, přejděte na Možnosti nástrojů>a v části Projekty a řešení zvolte Azure Functions. Podle výzvy vyberte Vyhledat aktualizace a nainstalovat aktualizace.
  • V projektu hostitele aplikace Aspire:
    • Musíte odkazovat na Aspire.Hosting.Azure.Functions.
    • Musíte mít odkaz na projekt Functions.
    • V hostiteli Program.csaplikace musíte projekt zahrnout také voláním AddAzureFunctionsProject<TProject>() na váš IDistributedApplicationBuilder. Tato metoda se používá místo AddProject<TProject>() toho, které používáte pro jiné typy projektů. Pokud právě používáte AddProject<TProject>(), projekt Functions se nespustí správně.
  • V projektu Functions:
    • Musíte odkazovat na verze 2.x microsoft.Azure.Functions.Worker a Microsoft.Azure.Functions.Worker.Sdk. Musíte také aktualizovat všechny odkazy, které musíte mít na Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore verzi 2.x.
    • Měli byste Program.cs použít IHostApplicationBuilder verzi spuštění instance hostitele.
    • Pokud chcete použít výchozí hodnoty služby Aspire, měli byste zahrnout odkaz na projekt výchozího projektu služby. Před sestavením IHostApplicationBuilder Program.csdo , měli byste také zahrnout volání builder.AddServiceDefaults().
    • Konfiguraci byste neměli uchovávat local.settings.jsonkromě FUNCTIONS_WORKER_RUNTIME nastavení, které by mělo zůstat "izolované dotnet-izolované". Jiná konfigurace by se měla nastavit prostřednictvím hostitelského projektu aplikace.
    • Měli byste odebrat všechny přímé integrace Application Insights. Monitorování v Aspire se místo toho zpracovává prostřednictvím podpory OpenTelemetry.

Následující příklad ukazuje minimální Program.cs počet pro projekt hostitele aplikace:

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Následující příklad ukazuje minimální Program.cs využití projektu Functions použitého v 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();

Nezahrnuje výchozí konfiguraci Application Insights, kterou vidíte v mnoha dalších Program.cs příkladech v tomto článku. Místo toho je integrace OpenTelemetry pro Aspire nakonfigurovaná prostřednictvím builder.AddServiceDefaults() volání.

Důležité informace a osvědčené postupy pro integraci .NET Aspire

Při vyhodnocování služby .NET Aspire s azure Functions zvažte následující body:

  • Podpora azure Functions s .NET Aspire je aktuálně ve verzi Preview. Během období Preview se při publikování řešení Aspire do Azure nasadí projekty Functions jako prostředky Azure Container Apps bez škálování řízeného událostmi. Podpora azure Functions není dostupná pro aplikace nasazené v tomto režimu.
  • Konfigurace triggeru a vazby prostřednictvím Aspire je v současné době omezená na konkrétní integrace. Podrobnosti najdete v tématu Konfigurace připojení s Aspire .
  • Měli byste Program.cs použít IHostApplicationBuilder verzi spuštění instance hostitele. To vám umožní volat builder.AddServiceDefaults() přidání výchozích služeb .NET Aspire do projektu Functions.
  • Aspire používá k monitorování OpenTelemetry. Aspire můžete nakonfigurovat tak, aby exportoval telemetrii do služby Azure Monitor prostřednictvím výchozího projektu služby. V mnoha dalších kontextech Azure Functions můžete zahrnout přímou integraci s Application Insights registrací služby pracovního procesu telemetrie. To se nedoporučuje v Aspire a může vést k chybám za běhu ve verzi 2.22.0 z Microsoft.ApplicationInsights.WorkerService. Při použití Aspire byste měli ze svého projektu Functions odebrat všechny přímé integrace Application Insights.
  • U projektů Functions zařazených do orchestrace Aspire by většina konfigurace aplikace měla pocházet z hostitelského projektu aplikace Aspire. Obvykle byste se měli vyhnout nastavování jiných než local.settings.jsonFUNCTIONS_WORKER_RUNTIME nastavení. Pokud je stejná proměnná prostředí nastavena local.settings.json a Aspire, systém používá verzi Aspire.
  • Nekonfigurujte emulátor úložiště pro žádná připojení v local.settings.json. Mnoho úvodních šablon Functions zahrnuje emulátor jako výchozí nastavení pro AzureWebJobsStorage. Konfigurace emulátoru ale může zobrazit výzvu k spuštění verze emulátoru, která může být v konfliktu s verzí, kterou Aspire používá.

Konfigurace připojení pomocí Aspire

Azure Functions vyžaduje připojení k úložišti hostitele (AzureWebJobsStorage) pro několik základních chování. Při volání AddAzureFunctionsProject<TProject>() v hostitelském projektu aplikace se vytvoří výchozí AzureWebJobsStorage připojení a poskytne se projektu Functions. Toto výchozí připojení používá emulátor úložiště pro spuštění místního vývoje a při nasazení automaticky zřídí účet úložiště. Pro další řízení můžete toto připojení nahradit voláním .WithHostStorage() zdroje projektu Functions.

Následující příklad ukazuje minimální Program.cs velikost hostitelského projektu aplikace, který nahrazuje úložiště hostitelů:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Poznámka:

Když Aspire zřídí úložiště hostitele v režimu publikování, ve výchozím nastavení vytvoří přiřazení rolí pro přispěvatele účtu úložiště, Přispěvatel dat v objektech blob úložiště, Přispěvatel dat fronty úložiště a Přispěvatel dat tabulky úložiště.

Vaše triggery a vazby odkazují na připojení podle názvu. Některé integrace Aspire umožňují tyto integrace prostřednictvím volání WithReference() zdroje projektu:

Integrace Aspire Notes
Objekty blob Azure Když Aspire zřídí prostředek, ve výchozím nastavení vytvoří přiřazení rolí pro Přispěvatel dat v objektech blob úložiště, Přispěvatel dat fronty úložiště a Přispěvatel dat tabulky úložiště.
Fronty Azure Když Aspire zřídí prostředek, ve výchozím nastavení vytvoří přiřazení rolí pro Přispěvatel dat v objektech blob úložiště, Přispěvatel dat fronty úložiště a Přispěvatel dat tabulky úložiště.
Azure Event Hubs Když Aspire zřídí prostředek, ve výchozím nastavení vytvoří přiřazení role pomocí role Vlastník dat služby Azure Event Hubs.
Azure Service Bus Když Aspire zřídí prostředek, ve výchozím nastavení vytvoří přiřazení role pomocí role Vlastník dat služby Azure Service Bus.

Následující příklad ukazuje minimum Program.cs pro hostitelský projekt aplikace, který konfiguruje trigger fronty. V tomto příkladu má odpovídající aktivační událost fronty vlastnost Connection nastavenou na "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();

V případě jiných integrací volání, která WithReference nastaví konfiguraci jiným způsobem a zpřístupní ji integraci klientů Aspire, ale ne triggery a vazby. U těchto integrací byste měli volat WithEnvironment() předání informací o připojení pro trigger nebo vazbu, které se mají vyřešit. Následující příklad ukazuje, jak nastavit proměnnou prostředí MyBindingConnection pro prostředek, který zveřejňuje výraz připojovací řetězec:

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

Můžete nakonfigurovat obojí WithReference() a WithEnvironment() pokud chcete, aby připojení bylo použito jak integracemi klienta Aspire, tak systémem aktivačních událostí a vazeb.

U některých prostředků se struktura připojení může lišit mezi tím, kdy ho spouštíte místně a kdy ho publikujete do Azure. V předchozím příkladu může být prostředek, otherIntegration který běží jako emulátor, takže ConnectionStringExpression by vrátil emulátor připojovací řetězec. Při publikování prostředku ale může Aspire nastavit připojení založené na identitě a ConnectionStringExpression vrátit identifikátor URI služby. Pokud chcete nastavit připojení založená na identitách pro Azure Functions, budete možná muset zadat jiný název proměnné prostředí. Následující příklad používá builder.ExecutionContext.IsPublishMode k podmíněnému přidání nezbytné přípony:

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

V závislosti na vašem scénáři může být také potřeba upravit oprávnění, která budou přiřazena pro připojení založené na identitě. Pomocí této metody můžete ConfigureConstruct<T>() přizpůsobit, jak Aspire konfiguruje infrastrukturu při publikování projektu.

Podrobnosti o formátech připojení, které podporuje, a oprávnění, která tyto formáty vyžadují, najdete na referenčních stránkách každé vazby.

Ladění

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

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

Vzhledem k tomu, že aplikace izolovaného pracovního procesu běží mimo modul runtime Služby Functions, musíte vzdálený ladicí program připojit k samostatnému procesu. Další informace o ladění pomocí sady Visual Studio najdete v tématu Vzdálené ladění.

Ladění při cílení na rozhraní .NET Framework

Pokud váš izolovaný projekt cílí na rozhraní .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 = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults()
                .Build();

            host.Run();
        }
    }
}

Dále je potřeba ručně připojit k procesu pomocí ladicího programu rozhraní .NET Framework. Visual Studio to zatím neprovádí automaticky pro aplikace .NET Framework izolovaného pracovního procesu a operace Spustit ladění by se měla vyhnout.

V adresáři projektu (nebo jeho výstupním adresáři 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. K ručnímu připojení k procesu teď můžete použít Visual Studio. 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 Preview .NET

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 oficiálních zásadách podpory .NET.

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 se dají používat jenom s verzemi Preview nebo VerzeMi v reálném provozu, které jsou uvedené v této části.

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

Použití sady .NET SDK ve verzi Preview

Pokud chcete používat 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. TargetFramework Změna nastavení v .csproj souboru

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

Pro aplikace hostované ve 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:

  • Při vytváření funkcí v sadě Visual Studio musíte použít Sadu Visual Studio Preview, která podporuje vytváření projektů Azure Functions 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 Možnosti nástrojů>a v části Projekty a řešení zvolte Azure Functions.
    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ší aplikace funkcí při nasazení. Chcete-li to vyřešit, můžete zadat verzi sady SDK, ve global.jsonkteré se má použít .

    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 způsobí, dotnet new globaljson --sdk-version dotnet-sdk-8.0.100-preview.7.23376.3 --force že systém při sestavování projektu použije sadu .NET 8 Preview 7 SDK.

Poznámka:

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

Další kroky