Przewodnik dotyczący uruchamiania usługi Azure Functions w języku C# w modelu izolowanego procesu roboczego

W tym artykule przedstawiono pracę z usługą Azure Functions na platformie .NET przy użyciu modelu izolowanego procesu roboczego. Ten model umożliwia Twojemu projektowi targetowanie wersji platformy .NET niezależnie od innych składników środowiska uruchomieniowego. Aby uzyskać informacje o obsługiwanych wersjach platformy .NET, zobacz obsługiwaną wersję.

Skorzystaj z poniższych linków, aby od razu rozpocząć tworzenie izolowanych funkcji modelu procesu roboczego platformy .NET.

Aby dowiedzieć się więcej o wdrażaniu izolowanego projektu modelu procesu roboczego na platformie Azure, zobacz Wdrażanie w usłudze Azure Functions.

Korzyści wynikające z modelu izolowanego pracownika

Funkcje biblioteki klas platformy .NET można uruchamiać w dwóch trybach: w tym samym procesie co środowisko uruchomieniowe hosta usługi Functions (w procesie) lub w izolowanym procesie roboczym. Gdy funkcje platformy .NET działają w izolowanym procesie roboczym, możesz skorzystać z następujących korzyści:

• Mniej konfliktów: Ponieważ funkcje działają w osobnym procesie, zestawy używane w aplikacji nie powodują konfliktu z różnymi wersjami tych samych zestawów używanych przez proces hosta.
• Pełna kontrola procesu: kontrolujesz uruchamianie aplikacji, co oznacza, że możesz zarządzać używanymi konfiguracjami i uruchomionym oprogramowaniem pośredniczącym.
• Standardowe wstrzykiwanie zależności: Ponieważ masz pełną kontrolę nad procesem, możesz użyć bieżących zachowań platformy .NET do wstrzykiwania zależności i dołączania oprogramowania pośredniczącego do aplikacji funkcji.
• Elastyczność wersji platformy .NET: Uruchomienie poza procesem hosta oznacza, że funkcje mogą być uruchamiane w wersjach platformy .NET, które nie są natywnie obsługiwane przez środowisko uruchomieniowe usługi Functions, w tym program .NET Framework.

Jeśli masz istniejącą aplikację funkcji języka C#, która działa w trakcie procesu, musisz zmigrować aplikację, aby skorzystać z tych korzyści. Aby uzyskać więcej informacji, zobacz Migrowanie aplikacji .NET z modelu procesu do izolowanego modelu roboczego.

Aby uzyskać kompleksowe porównanie dwóch trybów, zobacz Różnice między procesem w procesie i izolowanym procesem roboczym .NET Azure Functions.

Obsługiwane wersje

Wersje środowiska uruchomieniowego usługi Functions obsługują określone wersje platformy .NET. Aby dowiedzieć się więcej na temat wersji usługi Functions, zobacz Omówienie wersji środowiska uruchomieniowego usługi Azure Functions. Obsługa wersji zależy również od tego, czy funkcje działają w procesie przetwarzania, czy izolowanego procesu roboczego.

W poniższej tabeli przedstawiono najwyższy poziom platformy .NET lub .NET Framework, który może być używany z określoną wersją usługi Functions.

^{Wersja 1} .NET 6 była wcześniej obsługiwana w obu modelach, ale osiągnęła koniec oficjalnego wsparcia 12 listopada 2024 r. Platforma .NET 7 była wcześniej obsługiwana w modelu izolowanego procesu roboczego, ale 14 maja 2024 r. zakończyła się oficjalnym wsparciem .

² Proces kompilacji wymaga również zestawu .NET SDK.

³ Zakończenie wsparcia dla wersji 1.x środowiska uruchomieniowego usługi Azure Functions 14 września 2026 r. Aby uzyskać więcej informacji, zobacz to ogłoszenie pomocy technicznej. Aby zapewnić ciągłą pełną obsługę, należy przeprowadzić migrację aplikacji do wersji 4.x.

⁴ Wsparcie kończy się dla modelu procesu 10 listopada 2026 r. Aby uzyskać więcej informacji, zobacz to ogłoszenie pomocy technicznej. Aby zapewnić ciągłą pełną obsługę, należy przeprowadzić migrację aplikacji do izolowanego modelu procesu roboczego.

⁵ Nie można uruchamiać aplikacji platformy .NET 10 w systemie Linux w planie Zużycie. Aby uruchomić program w systemie Linux, należy zamiast tego użyć planu Flex Consumption.

Aby uzyskać najnowsze informacje o wydaniach usługi Azure Functions, w tym o usunięciu określonych starszych wersji pomocniczych, monitoruj ogłoszenia usługi Azure App Service.

Struktura projektu

Projekt platformy .NET dla usługi Azure Functions, który korzysta z izolowanego modelu roboczego, jest w zasadzie projektem aplikacji konsolowej platformy .NET przeznaczonym dla obsługiwanego środowiska uruchomieniowego platformy .NET. Następujące pliki to podstawowe pliki wymagane w dowolnym izolowanym projekcie platformy .NET:

• Plik projektu języka C# (csproj), który definiuje projekt i zależności.
• Plik Program.cs, który jest punktem wejściowym aplikacji.
• Wszystkie pliki kodu definiujące funkcje.
• host.json plik definiujący konfigurację współużytkowany przez funkcje w projekcie.
• local.settings.json plik, który definiuje zmienne środowiskowe używane przez projekt podczas uruchamiania lokalnego na maszynie.

Kompletne przykłady można znaleźć w przykładowym projekcie platformy .NET 8 i przykładowym projekcie programu .NET Framework 4.8.

Odwołania do pakietu

Projekt platformy .NET dla usługi Azure Functions, który korzysta z izolowanego modelu roboczego, używa unikatowego zestawu pakietów zarówno dla podstawowych funkcji, jak i rozszerzeń powiązań.

Pakiety podstawowe

Aby uruchomić funkcje platformy .NET w izolowanym procesie roboczym, potrzebne są następujące pakiety:

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

Minimalne wersje tych pakietów zależą od docelowej wersji platformy .NET:

Wersja 2.x

Wersje 2.x pakietów podstawowych zmieniają obsługiwane struktury i obsługują nowe interfejsy API platformy .NET z tych nowszych wersji. Podczas aktualizowania do wersji 2.x zwróć uwagę na następujące zmiany:

• Począwszy od wersji 2.0.0 zestawu Microsoft.Azure.Functions.Worker.Sdk:
  • Zestaw SDK zawiera domyślne konfiguracje kompilacji kontenera SDK.
  • Zestaw SDK obejmuje obsługę dotnet run pod warunkiem, że narzędzia Azure Functions Core Tools są zainstalowane. W systemie Windows zainstaluj narzędzia Core Tools za pomocą mechanizmu innego niż NPM.
• Począwszy od wersji 2.0.0 microsoft.Azure.Functions.Worker:
  • Ta wersja dodaje obsługę IHostApplicationBuilder. Niektóre przykłady w tym przewodniku zawierają zakładki pokazujące alternatywy przy użyciu IHostApplicationBuilder. Te przykłady wymagają wersji 2.x.
  • Sprawdzanie poprawności zakresu dostawcy usług jest domyślnie uwzględniane w przypadku uruchamiania w środowisku deweloperskim. To zachowanie jest zgodne z ASP.NET Core.
  • Opcja EnableUserCodeException jest domyślnie włączona. Właściwość jest teraz oznaczona jako przestarzała.
  • Opcja IncludeEmptyEntriesInMessagePayload jest domyślnie włączona. Po włączeniu tej opcji ładunki wyzwalacza reprezentujące kolekcje zawsze zawierają puste wpisy. Jeśli na przykład komunikat jest wysyłany bez treści, dla danych wyzwalacza pusty wpis jest wciąż obecny w string[]. Włączenie pustych wpisów ułatwia odwoływanie się do tablic metadanych, do których może się odwoływać również funkcja. To zachowanie można wyłączyć, ustawiając wartość IncludeEmptyEntriesInMessagePayload na false w WorkerOptions konfiguracji usługi.
  • Nazwa ILoggerExtensions klasy została zmieniona na FunctionsLoggerExtensions. Zmiana nazwy zapobiega wystąpieniu błędu niejednoznacznego wywołania, kiedy używasz LogMetric() na ILogger instancji.
  • W przypadku aplikacji korzystających z HttpResponseData metoda WriteAsJsonAsync() nie ustawia już kodu stanu na 200 OK. W wersji 1.x to zachowanie powoduje zastąpienie innych ustawionych kodów błędów.
• Wersje 2.x porzucają obsługę programu .NET 5 TFM.

Pakiety rozszerzeń

Ponieważ funkcje procesu roboczego izolowanego platformy .NET używają różnych typów powiązań, wymagają unikatowego zestawu pakietów rozszerzeń powiązań.

Te pakiety rozszerzeń można znaleźć w obszarze Microsoft.Azure.Functions.Worker.Extensions.

Uruchamianie i konfiguracja

W przypadku korzystania z izolowanego modelu pracownika masz dostęp do uruchamiania aplikacji funkcji, która zwykle znajduje się w Program.cs. Odpowiadasz za tworzenie i uruchamianie własnej instancji hosta. W związku z tym masz również bezpośredni dostęp do systemu konfiguracji Twojej aplikacji. Dzięki izolowanemu procesowi roboczemu w usłudze .NET Functions możesz znacznie łatwiej dodawać konfiguracje, wprowadzać zależności i uruchamiać własne oprogramowanie middleware.

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

var builder = FunctionsApplication.CreateBuilder(args);

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

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

var host = builder.Build();

await host.RunAsync();

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

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

await host.RunAsync();

Konfiguracja

Typ używanego konstruktora określa sposób konfigurowania aplikacji.

.ConfigureFunctionsWorkerDefaults()

Te konfiguracje mają zastosowanie tylko do kodu pracownika, który tworzysz. Nie mają bezpośredniego wpływu na konfigurację hosta ani wyzwalaczy i powiązań usługi Functions. Aby wprowadzić zmiany w konfiguracji hosta lub wyzwalacza i powiązania funkcji, użyj pliku host.json.

Wstrzykiwanie zależności

Model izolowanego pracownika używa standardowych mechanizmów .NET do wstrzykiwania usług.

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

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

Ten kod wymaga using Microsoft.Extensions.DependencyInjection;. Aby dowiedzieć się więcej, zobacz Wstrzykiwanie zależności w ASP.NET Core.

Rejestrowanie klientów platformy Azure

Użyj iniekcji zależności, aby wchodzić w interakcje z innymi usługami platformy Azure. Klientów z zestawu Azure SDK dla platformy .NET można wstrzyknąć przy użyciu pakietu Microsoft.Extensions.Azure . Po zainstalowaniu pakietu zarejestruj klientów, wywołując AddAzureClients() na zbiorze usług w Program.cs. W poniższym przykładzie skonfigurowano nazwanego klienta dla obiektów blob platformy 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();

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

W poniższym przykładzie pokazano, jak za pomocą tych typów rejestracji i zestawu SDK skopiować zawartość obiektu blob jako strumień z jednego kontenera do innego przy użyciu wprowadzonego 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!");
        }

    }
}

Element ILogger<T> w tym przykładzie jest również uzyskiwany za pośrednictwem wstrzykiwania zależności, więc jest on rejestrowany automatycznie. Aby dowiedzieć się więcej na temat opcji konfiguracji rejestrowania, zobacz Rejestrowanie.

Oprogramowanie pośredniczące

Model izolowanego procesu roboczego obsługuje również rejestrację oprogramowania pośredniczącego, ponownie używając modelu podobnego do tego, co istnieje w ASP.NET. Ten model daje możliwość wprowadzania logiki do procesu wywołań, zarówno przed, jak i po wykonaniu funkcji.

Metoda rozszerzenia ConfigureFunctionsWorkerDefaults ma przeciążenie, które umożliwia zarejestrowanie własnego oprogramowania pośredniczącego, jak pokazano w poniższym przykładzie.

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

var builder = FunctionsApplication.CreateBuilder(args);

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

builder.Build().Run();

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

        workerApplication.UseMiddleware<ExceptionHandlingMiddleware>();

        workerApplication.UseMiddleware<MyCustomMiddleware>();

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

Metoda UseWhen rozszerzenia rejestruje oprogramowanie pośredniczące, które jest wykonywane warunkowo. Należy przekazać predykat, który zwraca wartość logiczną do tej metody. Oprogramowanie pośredniczące uczestniczy w potoku przetwarzania wywołań, gdy predykat zwraca wartość true.

Następujące metody rozszerzenia w funkcjiContext ułatwiają pracę z oprogramowaniem pośredniczącym w izolowanym modelu.

W tym przykładzie pokazano implementację middleware, która podczas wykonywania funkcji odczytuje instancję HttpRequestData i aktualizuje instancję HttpResponseData.

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

To oprogramowanie pośredniczące sprawdza obecność określonego nagłówka żądania (x-correlationId). Gdy nagłówek jest obecny, oprogramowanie pośredniczące używa wartości nagłówka do oznaczania nagłówka odpowiedzi. W przeciwnym razie generuje nową wartość identyfikatora GUID i używa tej wartości do oznaczania nagłówka odpowiedzi.

Aby uzyskać bardziej kompletny przykład używania niestandardowego oprogramowania pośredniczącego w funkcjonalnej aplikacji, zobacz przykład niestandardowego oprogramowania pośredniczącego.

Dostosowywanie serializacji JSON

Model izolowanego procesu roboczego używa System.Text.Json domyślnie. Zachowanie serializatora można dostosować, konfigurując usługi w ramach Program.cs pliku. W tej sekcji omówiona jest serializacja ogólnego przeznaczenia, która nie wpływa na serializację JSON wyzwalacza HTTP z integracją ASP.NET Core; tę ostatnią należy skonfigurować oddzielnie.

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

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

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

builder.Build().Run();

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

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

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

host.Run();

Aby użyć JSON.NET (Newtonsoft.Json) do serializacji, zainstaluj Microsoft.Azure.Core.NewtonsoftJson pakiet. Następnie, w rejestracji usługi, ponownie przypisz właściwość Serializer na konfiguracji WorkerOptions. W poniższym przykładzie pokazano tę konfigurację przy użyciu polecenia ConfigureFunctionsWebApplication, ale działa również dla elementu ConfigureFunctionsWorkerDefaults:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

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

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

builder.Build().Run();

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

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

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

host.Run();

Metody rozpoznawane jako funkcje

Metoda funkcji jest publiczną metodą klasy publicznej z atrybutem Function zastosowanym do metody i atrybutem wyzwalacza zastosowanym do parametru wejściowego, jak pokazano w poniższym przykładzie:

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

Atrybut wyzwalacza określa typ wyzwalacza i wiąże dane wejściowe z parametrem metody. Poprzednia przykładowa funkcja jest wyzwalana przez komunikat kolejki, a komunikat kolejki jest przekazywany do metody w parametrze myQueueItem .

Atrybut Function oznacza metodę jako punkt wejścia funkcji. Nazwa musi być unikatowa w projekcie, zaczynać się literą i zawierać tylko litery, cyfry, _i -, do 127 znaków. Szablony projektów często tworzą metodę o nazwie Run, ale nazwa metody może być dowolną prawidłową nazwą metody języka C#. Metoda musi być publicznym elementem członkowskim klasy publicznej. Zazwyczaj powinna to być metoda instancji, aby usługi mogły być przekazywane poprzez wstrzykiwanie zależności.

Parametry funkcji

Poniżej przedstawiono niektóre parametry, które można uwzględnić jako część podpisu metody funkcji:

• Powiązania, które są oznaczone jako takie, dekorując parametry jako atrybuty. Funkcja musi zawierać dokładnie jeden parametr wyzwalacza.
• Obiekt kontekstu wykonywania, który zawiera informacje na temat bieżącego wywołania.
• Token anulowania używany do bezpiecznego zamykania.

Kontekst wykonywania

W modelu izolowanego procesu roboczego proces roboczy przekazuje obiekt FunctionContext do metod funkcji. Ten obiekt umożliwia uzyskanie instancji ILogger do zapisu w dziennikach przez wywołanie metody GetLogger i podanie parametru categoryName ciągu. Można użyć tego kontekstu, aby uzyskać ILogger bez konieczności używania wstrzykiwania zależności. Aby uzyskać więcej informacji, zobacz Logging.

Tokeny anulowania

Funkcja może zaakceptować parametr cancellationToken , który umożliwia systemowi operacyjnemu powiadamianie kodu o zakończeniu działania funkcji. Możesz użyć tego powiadomienia, aby upewnić się, że funkcja nie zostanie nieoczekiwanie zakończona w sposób, który pozostawia dane w stanie niespójnym.

Funkcje platformy .NET uruchamiane w izolowanym procesie roboczym obsługują tokeny anulowania. Poniższy przykład zgłasza wyjątek po odebraniu żądania anulowania:

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

Poniższy przykład wykonuje akcje czyszczenia po odebraniu żądania anulowania:

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

Scenariusze prowadzące do anulowania

Token anulowania jest sygnalizowany, gdy wywołanie funkcji zostanie anulowane. Kilka przyczyn może prowadzić do anulowania, a przyczyny te różnią się w zależności od używanego typu wyzwalacza. Oto niektóre typowe przyczyny:

• Rozłączanie klienta: klient wywołujący funkcję rozłącza się. Jest to najbardziej prawdopodobne w przypadku funkcji wyzwalacza HTTP.
• Ponowne uruchomienie aplikacji funkcji: Ty lub platforma uruchamiacie ponownie (lub zatrzymujecie) aplikację funkcji w tym samym czasie, gdy jest żądane wywołanie. Ponowne uruchomienie może wystąpić z powodu przenoszenia procesów roboczych, aktualizacji procesów roboczych lub skalowania.

Zagadnienia dotyczące anulowania

• Wywołania w locie podczas zdarzenia ponownego uruchamiania mogą być ponawiane w zależności od sposobu ich wyzwolenia. Aby uzyskać więcej informacji, zobacz dokumentację ponawiania prób.

• Host przekazuje wywołanie do procesu roboczego nawet, jeśli token anulowania zostanie cofnięty zanim host zdąży wysłać żądanie wywołania do procesu roboczego.

• Jeśli nie chcesz, aby wstępnie anulowane wywołania były wysyłane do pracownika, dodaj do pliku host.json właściwość SendCanceledInvocationsToWorker, aby wyłączyć to zachowanie.

  W tym przykładzie pokazano host.json plik, który używa tej właściwości:

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

• Ustawienie SendCanceledInvocationsToWorker na false może prowadzić do wyjątku FunctionInvocationCanceled z następującym logiem:

  Zażądano anulowania. Żądanie wywołania o identyfikatorze {invocationId} zostało anulowane i nie zostanie wysłane do pracownika.

  Ten wyjątek występuje, gdy token anulowania zostanie anulowany (w wyniku jednego z zdarzeń opisanych wcześniej) przed wysłaniem przychodzącego żądania wywołania do procesu roboczego. Ten wyjątek można bezpiecznie zignorować i jest oczekiwany, gdy SendCanceledInvocationsToWorker ma wartość false.

Powiązania

Definiowanie powiązań przy użyciu atrybutów metod, parametrów i typów zwracanych. Powiązania mogą dostarczać dane jako ciągi, tablice i typy, które można zserializować, takie jak zwykłe obiekty klas (POCO). W przypadku niektórych rozszerzeń powiązań można również powiązać z typami specyficznymi dla usługi zdefiniowanymi w SDK usługi.

W przypadku wyzwalaczy HTTP zobacz sekcję Wyzwalacz HTTP .

Pełny zestaw przykładów referencyjnych korzystających z wyzwalaczy i powiązań z izolowanymi funkcjami procesu roboczego można znaleźć w przykładzie referencyjnym rozszerzeń powiązań.

Powiązania wejściowe

Funkcja może mieć zero lub więcej powiązań wejściowych, które przekazują dane do funkcji. Podobnie jak wyzwalacze, należy zdefiniować powiązania wejściowe, stosując atrybut powiązania do parametru wejściowego. Po wykonaniu funkcji środowisko uruchomieniowe próbuje pobrać dane określone w powiązaniu. Żądane dane często zależą od informacji dostarczonych przez wyzwalacz za pośrednictwem parametrów powiązania.

Powiązania wyjściowe

Aby zapisać w powiązaniu wyjściowym, należy zastosować atrybut powiązania wyjściowego do metody funkcji. Ten atrybut definiuje sposób zapisywania w powiązanej usłudze. Wartość zwracana metody jest zapisywana w powiązaniu wyjściowym. Na przykład w poniższym przykładzie wartość ciągu jest zapisywana w kolejce komunikatów o nazwie output-queue przy użyciu powiązania wyjściowego:

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

Wiele powiązań wyjściowych

Dane zapisywane w powiązaniu wyjściowym są zawsze zwracaną wartością funkcji. Jeśli musisz zapisać więcej niż jedno powiązanie wyjściowe, musisz utworzyć niestandardowy typ danych zwracanych. Ten zwracany typ musi mieć atrybut powiązania wyjściowego zastosowany do co najmniej jednej właściwości klasy. Poniższy przykład jest funkcją wyzwalaną przez protokół HTTP, która używa integracji ASP.NET Core i zapisuje zarówno do odpowiedzi HTTP, jak i do powiązania wyjściowego kolejki.

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

W przypadku używania niestandardowych typów zwrotnych dla wielu powiązań wyjściowych z integracją ASP.NET Core, należy dodać atrybut [HttpResult] do właściwości, która zapewnia wynik. Atrybut HttpResult jest dostępny w przypadku korzystania z zestawu SDK 1.17.3-preview2 lub nowszego wraz z wersją 3.2.0 lub nowszą rozszerzenia HTTP i wersją 1.3.0 lub nowszą rozszerzenia ASP.NET Core.

Typy zestawów SDK

W przypadku niektórych typów powiązań specyficznych dla usługi można dostarczać dane powiązania przy użyciu typów z zestawów SDK usług i struktur. Te typy oferują możliwości poza tym, co może zapewnić serializowany ciąg lub zwykły obiekt CLR (POCO). Aby użyć nowszych typów, zaktualizuj projekt, aby używać nowszych wersji podstawowych zależności.

Podczas testowania typów zestawu SDK lokalnie na maszynie należy również używać narzędzi Azure Functions Core Tools w wersji 4.0.5000 lub nowszej. Bieżącą wersję można sprawdzić za pomocą func --version polecenia .

Każde rozszerzenie powiązania ma również własne minimalne wymaganie dotyczące wersji, które opisano w artykułach referencyjnych dotyczących rozszerzeń. Te rozszerzenia powiązań obsługują obecnie typy zestawów SDK:

Zagadnienia dotyczące typów zestawów SDK:

• W przypadku używania wyrażeń powiązań , które opierają się na danych wyzwalacza, nie można używać typów zestawu SDK dla samego wyzwalacza.
• W przypadku scenariuszy dotyczących wyjścia, w których można użyć typu SDK, należy utworzyć klientów SDK i nawiązać bezpośrednio współpracę z nimi zamiast używać powiązania wyjściowego.
• Wyzwalacz usługi Azure Cosmos DB używa zestawienia zmian usługi Azure Cosmos DB i uwidacznia elementy zestawienia zmian jako typy serializowalne w formacie JSON. W związku z tym typy zestawów SDK nie są obsługiwane dla tego wyzwalacza.

Wyzwalacz HTTP

Wyzwalacze HTTP umożliwiają wywoływanie funkcji przez żądanie HTTP. Można użyć dwóch różnych podejść:

• Model integracji ASP.NET Core korzystający z pojęć znanych deweloperom ASP.NET Core
• Wbudowany model, który nie wymaga dodatkowych zależności i używa typów niestandardowych dla żądań i odpowiedzi HTTP. Takie podejście jest utrzymywane dla zachowania wstecznej kompatybilności z poprzednimi aplikacjami roboczymi izolowanymi na platformie .NET.

integracja ASP.NET Core

W tej sekcji pokazano, jak pracować z bazowymi obiektami żądania HTTP i odpowiedzi przy użyciu typów z platformy ASP.NET Core, w tym HttpRequest, HttpResponse i IActionResult. Ten model nie jest dostępny dla aplikacji przeznaczonych dla platformy .NET Framework, które zamiast tego powinny używać wbudowanego modelu.

Aby włączyć integrację ASP.NET Core dla protokołu HTTP:

1. Dodaj odwołanie w projekcie do pakietu Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore w wersji 1.0.0 lub nowszej.

2. Zaktualizuj projekt, aby używał tych określonych wersji pakietów:

   • Microsoft.Azure.Functions.Worker.Sdk, wersja 1.11.0. lub później
   • Microsoft.Azure.Functions.Worker, wersja 1.16.0 lub nowsza.

3. W pliku Program.cs zaktualizuj konfigurację konstruktora hosta, aby wywołać ConfigureFunctionsWebApplication(). Jeśli użyłbyś tej metody w innym przypadku, ta metoda zastępuje ConfigureFunctionsWorkerDefaults(). W poniższym przykładzie przedstawiono minimalną konfigurację bez innych dostosowań:

   • IHostBuilder
   • IHostApplicationBuilder

   Uwaga / Notatka

   Aplikacja musi odwoływać się do wersji 2.0.0 lub nowszej programu Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore , aby korzystać z integracji ASP.NET Core z IHostApplicationBuilderprogramem .

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

4. Zaktualizuj wszystkie istniejące funkcje wyzwalane przez protokół HTTP, aby używać typów ASP.NET Core. W tym przykładzie przedstawiono standard HttpRequest oraz IActionResult używany dla prostej funkcji "hello, world":

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

Serializacja JSON z integracją ASP.NET Core

ASP.NET Core ma własną warstwę serializacji i nie ma to wpływu na dostosowanie ogólnej konfiguracji serializacji. Aby dostosować zachowanie serializacji używane dla wyzwalaczy HTTP, należy zarejestrować wywołanie .AddMvc() w ramach usługi. Zwrócony IMvcBuilder element może służyć do modyfikowania ustawień serializacji JSON ASP.NET Core.

Nadal można używać HttpRequestData i HttpResponseData podczas korzystania z integracji ASP.NET, jednak dla większości aplikacji lepiej jest używać HttpRequest i IActionResult. Użycie HttpRequestData/HttpResponseData nie wywołuje warstwy serializacji ASP.NET Core i zamiast tego opiera się na ogólnej konfiguracji serializacji procesów roboczych dla aplikacji. Jednak po włączeniu integracji ASP.NET Core może być konieczne dodanie konfiguracji. Domyślne zachowanie ASP.NET Core polega na niezezwalaniu na synchroniczne operacje I/O. Aby użyć niestandardowego serializatora, który nie obsługuje asynchronicznego we/wy, takiego jak NewtonsoftJsonObjectSerializer, należy włączyć synchroniczne operacje we/wy dla aplikacji, poprzez skonfigurowanie KestrelServerOptions.

W poniższym przykładzie pokazano, jak skonfigurować JSON.NET (Newtonsoft.Json) i pakiet NuGet Microsoft.AspNetCore.Mvc.NewtonsoftJson na potrzeby serializacji przy użyciu tego podejścia:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

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

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

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

builder.Build().Run();

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

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

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

Wbudowany model HTTP

W modelu wbudowanym system tłumaczy przychodzący komunikat żądania HTTP na obiekt HttpRequestData , który przekazuje do funkcji. Ten obiekt udostępnia dane z żądania, w tym Headers, Cookies, Identities, i URLopcjonalnie komunikat Body. Ten obiekt reprezentuje żądanie HTTP, ale nie jest bezpośrednio połączony z podstawowym odbiornikiem HTTP ani odebraną wiadomością.

Podobnie funkcja zwraca obiekt HttpResponseData , który dostarcza dane używane do tworzenia odpowiedzi HTTP, w tym komunikatu StatusCode, Headersi opcjonalnie komunikatu Body.

W poniższym przykładzie pokazano użycie elementów HttpRequestData i 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;
}

Rejestrowanie

Możesz zapisywać w dziennikach, używając instancji ILogger<T> lub ILogger. Rejestrator można uzyskać za pomocą wstrzykiwania zależności elementu ILogger<T> lub elementu 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}");
    }

}

Możesz również uzyskać rejestrator z obiektu FunctionContext przekazanego do twojej funkcji. Wywołaj metodę GetLogger<T> lub GetLogger , przekazując wartość ciągu, która jest nazwą kategorii, w której są zapisywane dzienniki. Kategoria jest zwykle nazwą konkretnej funkcji, z której są zapisywane dzienniki. Aby uzyskać więcej informacji na temat kategorii, zobacz artykuł dotyczący monitorowania.

Użyj metod ILogger<T> i ILogger, aby zapisywać różne poziomy logowania, takie jak LogWarning lub LogError. Aby uzyskać więcej informacji na temat poziomów logów, odwołaj się do artykułu dotyczącego monitorowania. Poziomy dziennika składników dodanych do kodu można dostosować, rejestrując filtry:

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

var builder = FunctionsApplication.CreateBuilder(args);

builder.ConfigureFunctionsWebApplication();

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

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

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

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

W ramach konfigurowania aplikacji w Program.cs, można również zdefiniować sposób raportowania błędów w dziennikach. Domyślne zachowanie zależy od typu konstruktora, którego używasz.

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

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

host.Run();

Application Insights

Aplikację procesu izolowanego można skonfigurować tak, aby wysyłała dzienniki bezpośrednio do usługi Application Insights. Ta konfiguracja zastępuje domyślne zachowanie przekazywania dzienników za pośrednictwem hosta. Jeśli nie używasz Aspire, skonfiguruj bezpośrednią integrację z Application Insights, ponieważ zapewnia kontrolę nad sposobem, w jaki te dzienniki są tworzone.

Integracja usługi Application Insights nie jest domyślnie włączona we wszystkich środowiskach konfiguracji. Niektóre szablony tworzą projekty usługi Functions z niezbędnymi pakietami i kodem uruchamiania zakomentowanym. Jeśli chcesz użyć integracji usługi Application Insights, usuń komentarz z tych linii w pliku Program.cs i pliku projektu .csproj. Instrukcje w pozostałej części tej sekcji opisują również sposób włączania integracji.

Jeśli projekt jest częścią orkiestracji Aspire, korzysta z OpenTelemetry do monitorowania. Nie włączaj bezpośredniej integracji usługi Application Insights w projektach Aspire. Zamiast tego skonfiguruj eksportera OpenTelemetry usługi Azure Monitor w ramach projektu ustawień domyślnych usługi. Jeśli projekt Functions używa integracji z Application Insights w kontekście Aspire, występują błędy aplikacji podczas uruchamiania.

Instalowanie pakietów

Aby zapisać dzienniki bezpośrednio w usłudze Application Insights z poziomu kodu, dodaj odwołania do tych pakietów w projekcie:

• Microsoft.Azure.Functions.Worker.ApplicationInsights, wersja 1.0.0 lub nowsza.
• Microsoft.ApplicationInsights.WorkerService.

Uruchom następujące polecenia, aby dodać te odwołania do projektu:

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

Konfigurowanie uruchamiania

Po zainstalowaniu pakietów wywołaj AddApplicationInsightsTelemetryWorkerService() i ConfigureFunctionsApplicationInsights() podczas konfiguracji usługi w pliku Program.cs, jak pokazano w poniższym przykładzie.

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

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

builder.Build().Run();

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

host.Run();

Wywołanie ConfigureFunctionsApplicationInsights() dodaje ITelemetryModule, który słucha na zdarzenia zdefiniowanego przez ActivitySource. Ten moduł tworzy telemetrię zależności wymaganą do obsługi śledzenia rozproszonego. Aby uzyskać więcej informacji o AddApplicationInsightsTelemetryWorkerService() i jak go używać, zobacz Application Insights dla aplikacji usług Worker Service (Application Insights dla aplikacji usług Worker Service).

Zarządzanie poziomami dzienników

Pozostała część aplikacji nadal współpracuje z elementami ILogger i ILogger<T>. Jednak domyślnie zestaw SDK usługi Application Insights dodaje filtr rejestrowania, który nakazuje rejestratorowi przechwytywanie tylko ostrzeżeń i poważniejszych dzienników. Można skonfigurować poziomy logów w odizolowanym procesie roboczym na jeden z następujących sposobów:

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

var builder = FunctionsApplication.CreateBuilder(args);

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

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

builder.Build().Run();

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

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

host.Run();

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

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

var builder = FunctionsApplication.CreateBuilder(args);

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

builder.Build().Run();

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

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

host.Run();

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

Aby uzyskać więcej informacji na temat konfigurowania rejestrowania, zobacz Rejestrowanie na platformie .NET i w usłudze Application Insights dla aplikacji usługi Worker Service.

Optymalizacje wydajności

W tej sekcji opisano opcje, które można włączyć, aby zwiększyć wydajność wokół zimnego startu.

Ogólnie rzecz biorąc, aplikacja powinna używać najnowszych wersji jej podstawowych zależności. Zaktualizuj projekt co najmniej w następujący sposób:

1. Uaktualnij program Microsoft.Azure.Functions.Worker do wersji 1.19.0 lub nowszej.
2. Uaktualnij zestaw Microsoft.Azure.Functions.Worker.Sdk do wersji 1.16.4 lub nowszej.
3. Dodaj odwołanie do struktury Microsoft.AspNetCore.App, chyba że aplikacja jest przeznaczona dla platformy .NET Framework.

Poniższy fragment kodu przedstawia tę konfigurację w kontekście pliku 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>

Symbole zastępcze

Symbole zastępcze to funkcja platformy, która poprawia zimny start dla aplikacji przeznaczonych dla platformy .NET 6 lub nowszej. Aby użyć tej optymalizacji, należy jawnie włączyć obiekty zastępcze, wykonując następujące kroki:

1. Zaktualizuj konfigurację projektu, aby używać najnowszych wersji zależności, zgodnie z opisem w poprzedniej sekcji.

2. WEBSITE_USE_PLACEHOLDER_DOTNETISOLATED Ustaw ustawienie aplikacji na 1. Użyj tego polecenia az functionapp config appsettings set :

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

   W tym przykładzie zastąp <groupName> nazwą grupy zasobów i zastąp <appName> nazwą aplikacji funkcji.

3. Upewnij się, że netFrameworkVersion właściwość aplikacji funkcji jest zgodna z platformą docelową projektu, która musi być platformą .NET 6 lub nowszą. Użyj tego polecenia az functionapp config set :

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

   W tym przykładzie zastąp <framework> również ciągiem odpowiedniej wersji, takim jak v8.0, zgodnie z docelową wersją platformy .NET.

4. Upewnij się, że aplikacja funkcji jest skonfigurowana do korzystania z 64-bitowego procesu. Użyj tego polecenia az functionapp config set :

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

Zoptymalizowana funkcja wykonawcza

Funkcja wykonawcza jest składnikiem platformy, która powoduje uruchomienie wywołań. Zoptymalizowana wersja tego składnika jest domyślnie włączona, począwszy od wersji 1.16.2 zestawu SDK. Nie jest wymagana żadna inna konfiguracja.

ReadyToRun

Aplikację funkcji można skompilować jako pliki binarne ReadyToRun. ReadyToRun to forma kompilacji ahead-of-time, która może poprawić wydajność startową i zmniejszyć efekt zimnych startów podczas uruchamiania w planie Zużycia. Funkcja ReadyToRun jest dostępna na platformie .NET 6 i nowszych wersjach i wymaga wersji 4.0 lub nowszej środowiska uruchomieniowego usługi Azure Functions.

Funkcja ReadyToRun wymaga skompilowania projektu pod kątem architektury środowiska uruchomieniowego aplikacji hostingowej. Gdy te architektury nie są wyrównane, aplikacja napotka błąd podczas uruchamiania. Wybierz identyfikator środowiska uruchomieniowego z tej tabeli:

¹ Tylko aplikacje 64-bitowe kwalifikują się do innych optymalizacji wydajności.

Aby sprawdzić, czy aplikacja systemu Windows jest 32-bitowa lub 64-bitowa, uruchom następujące polecenie interfejsu wiersza polecenia, zastępując <group_name> nazwę grupy zasobów i <app_name> nazwą aplikacji. Dane wyjściowe "true" wskazują, że aplikacja jest 32-bitowa, a wartość "false" wskazuje 64-bitową wartość.

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

Możesz zmienić aplikację na 64-bitową przy użyciu następującego polecenia, używając tych samych podstawień:

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

Aby skompilować projekt jako ReadyToRun, zaktualizuj plik projektu, dodając <PublishReadyToRun> elementy i <RuntimeIdentifier> . W poniższym przykładzie przedstawiono konfigurację publikowania w aplikacji funkcji systemu Windows 64-bitowej.

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

Jeśli nie chcesz ustawiać elementu <RuntimeIdentifier> jako części pliku projektu, możesz także skonfigurować to ustawienie jako część samego procesu publikacji. Na przykład w przypadku aplikacji funkcji systemu Windows 64-bitowej polecenie interfejsu wiersza polecenia platformy .NET to:

dotnet publish --runtime win-x64

W programie Visual Studio ustaw opcję Target Runtime (Docelowe środowisko uruchomieniowe ) w profilu publikowania na prawidłowy identyfikator środowiska uruchomieniowego. Po ustawieniu wartości domyślnej elementu Portable nie jest używana funkcja ReadyToRun.

Wdrażanie w Azure Functions

Podczas wdrażania projektu kodu funkcji na platformie Azure musi on działać w aplikacji funkcji lub w kontenerze systemu Linux. Przed wdrożeniem kodu należy utworzyć aplikację funkcji i inne wymagane zasoby platformy Azure.

Aplikację funkcji można również wdrożyć w kontenerze systemu Linux. Aby uzyskać więcej informacji, zobacz Praca z kontenerami i usługą Azure Functions.

Tworzenie zasobów platformy Azure

Aplikację funkcji i inne wymagane zasoby można utworzyć na platformie Azure przy użyciu jednej z następujących metod:

• Visual Studio: program Visual Studio może tworzyć zasoby podczas procesu publikowania kodu.
• Visual Studio Code: program Visual Studio Code może łączyć się z subskrypcją, tworzyć zasoby wymagane przez aplikację, a następnie publikować kod.
• Interfejs wiersza polecenia platformy Azure: użyj interfejsu wiersza polecenia platformy Azure, aby utworzyć wymagane zasoby na platformie Azure.
• Azure PowerShell: użyj programu Azure PowerShell, aby utworzyć wymagane zasoby na platformie Azure.
• Szablony wdrażania: używać szablonów ARM i plików Bicep, aby zautomatyzować wdrażanie wymaganych zasobów na Azure. Upewnij się, że szablon zawiera wszystkie wymagane ustawienia.
• Witryna Azure Portal: utwórz wymagane zasoby w witrynie Azure Portal.

Publikowanie aplikacji

Po utworzeniu aplikacji funkcji i innych wymaganych zasobów na platformie Azure wdróż projekt kodu na platformie Azure przy użyciu jednej z następujących metod:

• Visual Studio: proste ręczne wdrażanie podczas programowania.
• Visual Studio Code: proste ręczne wdrażanie podczas programowania.
• Azure Functions Core Tools: wdróż plik projektu z wiersza polecenia.
• Ciągłe wdrażanie: przydatne w przypadku ciągłej konserwacji, często w miejscu przejściowym.
• Szablony wdrażania: do automatyzowania wdrożeń pakietów można użyć szablonów usługi ARM lub plików Bicep.

Aby uzyskać więcej informacji, zobacz Technologie wdrażania w usłudze Azure Functions.

Ładunek wdrożenia

Wiele metod wdrażania używa archiwum zip. Jeśli samodzielnie utworzysz archiwum zip, należy postępować zgodnie ze strukturą opisaną w tej sekcji. Jeśli tak nie jest, aplikacja może napotkać błędy podczas uruchamiania.

Pakiet wdrożeniowy powinien odpowiadać wynikowi polecenia dotnet publish, jednak bez dołączonego folderu nadrzędnego. Archiwum zip należy wykonać z następujących plików:

• .azurefunctions/
• extensions.json
• functions.metadata
• host.json
• worker.config.json
• Plik wykonywalny projektu (aplikacja konsolowa)
• Inne pliki pomocnicze i katalogi równorzędne do tego pliku wykonywalnego

Proces kompilacji generuje te pliki i nie należy ich edytować bezpośrednio.

Podczas przygotowywania archiwum zip do wdrożenia kompresuj tylko zawartość katalogu wyjściowego, a nie samego otaczającego katalogu. Po wyodrębnieniu archiwum do bieżącego katalogu roboczego pliki wymienione wcześniej muszą być natychmiast widoczne.

Wymagania dotyczące wdrażania

Aby uruchomić funkcje platformy .NET w modelu izolowanego procesu roboczego na platformie Azure, musisz spełnić kilka wymagań. Wymagania zależą od systemu operacyjnego:

Podczas tworzenia aplikacji funkcji w Azure przy użyciu metod opisanych w poprzedniej sekcji, te wymagane ustawienia są automatycznie dodawane. Podczas tworzenia tych zasobów przy użyciu szablonów usługi ARM lub plików Bicep na potrzeby automatyzacji należy upewnić się, że zostały one ustawione w szablonie.

Aspire

Aspire to specyficzny stos, który upraszcza rozwój aplikacji rozproszonych w chmurze. Możesz zarejestrować izolowane projekty modeli procesów roboczych w aranżacjach Programu Aspire 13. Aby uzyskać więcej informacji, zobacz Azure Functions with Aspire.

Debugowanie

W przypadku uruchamiania lokalnego przy użyciu programu Visual Studio lub Visual Studio Code możesz debugować izolowany projekt roboczy platformy .NET w zwykły sposób. Istnieją jednak dwa scenariusze debugowania, które nie działają zgodnie z oczekiwaniami.

Debugowanie zdalne przy użyciu programu Visual Studio

Ponieważ aplikacja izolowanego procesu roboczego działa poza środowiskiem uruchomieniowym usługi Functions, musisz dołączyć zdalny debuger do oddzielnego procesu. Aby dowiedzieć się więcej na temat debugowania przy użyciu programu Visual Studio, zobacz Debugowanie zdalne.

Debugowanie podczas określania wartości docelowej programu .NET Framework

Jeśli izolowany projekt jest przeznaczony dla programu .NET Framework 4.8, należy wykonać kroki ręczne w celu włączenia debugowania. Te kroki nie są wymagane w przypadku korzystania z innej platformy docelowej.

Aplikacja powinna zaczynać się od wywołania metody jako FunctionsDebugger.Enable(); pierwszej operacji. Dzieje się tak w metodzie Main() przed zainicjowaniem programu HostBuilder. Plik Program.cs powinien wyglądać podobnie do następującego:

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

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

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

            host.Run();
        }
    }
}

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

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

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

            host.Run();
        }
    }
}

Następnie należy ręcznie dołączyć do procesu przy użyciu debugera programu .NET Framework. Program Visual Studio nie wykonuje tego automatycznie w przypadku aplikacji programu .NET Framework procesu roboczego izolowanego, a należy unikać operacji "Rozpocznij debugowanie".

W katalogu projektu (lub w katalogu wyjściowym kompilacji) uruchom polecenie:

func host start --dotnet-isolated-debug

To uruchamia twojego pracownika, a proces zatrzymuje się z następującym komunikatem:

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

Gdzie <process id> jest identyfikatorem procesu roboczego. Teraz możesz użyć programu Visual Studio do ręcznego dołączenia do procesu. Aby uzyskać instrukcje dotyczące tej operacji, zobacz Jak dołączyć do uruchomionego procesu.

Po dołączeniu debugera wykonywanie procesu zostanie wznowione i będzie można debugować.

Wersje platformy .NET w wersji zapoznawczej

Przed ogólnie dostępnym wydaniem wersja platformy .NET może zostać wydana w wersji zapoznawczej lub w stanie Go-live . Aby uzyskać szczegółowe informacje na temat tych stanów, zobacz oficjalne zasady pomocy technicznej platformy .NET .

Chociaż możliwe może być ustawienie konkretnej wersji z lokalnego projektu usługi Functions, aplikacje funkcji hostowane na platformie Azure mogą nie mieć tej wersji dostępnej. Usługi Azure Functions można używać tylko z wersjami zapoznawczymi lub wydaniami na żywo zanotowanymi w tej sekcji.

Usługa Azure Functions nie działa obecnie z żadnymi wydaniami platformy .NET "Wersja zapoznawcza" ani "Go-live". Zobacz Obsługiwane wersje , aby uzyskać listę ogólnie dostępnych wersji, których można użyć.

Korzystanie z zestawu SDK platformy .NET w wersji zapoznawczej

Aby używać usługi Azure Functions z wersją zapoznawcza platformy .NET, należy zaktualizować projekt, wykonując następujące czynności:

1. Instalowanie odpowiedniej wersji zestawu .NET SDK w środowisku programistycznym
2. TargetFramework Zmiana ustawienia w .csproj pliku

Podczas wdrażania w aplikacji funkcji na platformie Azure należy również upewnić się, że platforma jest udostępniana aplikacji. W okresie obowiązywania wersji zapoznawczej niektóre narzędzia i środowiska mogą nie wyświetlać nowej wersji zapoznawczej jako opcji. Jeśli na przykład nie widzisz wersji zapoznawczej zawartej w witrynie Azure Portal, możesz użyć interfejsu API REST, plików Bicep lub interfejsu wiersza polecenia platformy Azure, aby ręcznie skonfigurować wersję.

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

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

Zagadnienia dotyczące korzystania z wersji zapoznawczych platformy .NET

Podczas korzystania z usługi Functions z wersjami zapoznawcza platformy .NET należy wziąć pod uwagę następujące zagadnienia:

• Podczas tworzenia funkcji w programie Visual Studio należy używać programu Visual Studio Insiders, który obsługuje tworzenie projektów Azure Functions przy użyciu wersji zapoznawczej zestawów SDK platformy .NET.

• Upewnij się, że masz najnowsze narzędzia i szablony usługi Functions. Aby zaktualizować narzędzia:

  1. Przejdź dopozycji Opcje>, wybierz pozycję Azure Functions w obszarze Projekty i rozwiązania>Więcej ustawień.
  2. Wybierz pozycję Sprawdź dostępność aktualizacji i zainstaluj aktualizacje zgodnie z monitem.

• Podczas okresu wersji zapoznawczej środowisko deweloperskie może mieć nowszą wersję zapoznawczą platformy .NET niż ta używana przez hostowaną usługę. Może to spowodować niepowodzenie aplikacji funkcji podczas wdrażania. Aby rozwiązać ten problem, możesz określić wersję zestawu SDK do użycia w programie global.json.

  1. Uruchom polecenie dotnet --list-sdks i zanotuj wersję zapoznawczą używaną obecnie podczas rozwoju lokalnego.
  2. dotnet new globaljson --sdk-version <SDK_VERSION> --force Uruchom polecenie , gdzie <SDK_VERSION> jest wersją używaną lokalnie. Na przykład dotnet new globaljson --sdk-version dotnet-sdk-10.0.100-preview.5.25277.114 --force powoduje, że podczas kompilowania projektu system używa zestawu SDK platformy .NET 10 Preview 5.

Dalsze kroki