How to use the Azure WebJobs SDK for event-driven background processing (Jak używać zestawu SDK usługi Azure WebJobs w celu opartego na zdarzeniach przetwarzania w tle)

Artykuł
06/13/2024

Ten artykuł zawiera wskazówki dotyczące pracy z zestawem SDK usługi Azure WebJobs. Aby od razu rozpocząć pracę z zadaniami WebJob, zobacz Wprowadzenie do zestawu SDK usługi Azure WebJobs.

Wersje zestawu SDK usługi WebJobs

Są to kluczowe różnice między wersją 3.x i wersja 2.x zestawu SDK usługi WebJobs:

Wersja 3.X dodaje obsługę platformy .NET Core.
W wersji 3.x zainstalujesz rozszerzenie powiązania magazynu wymagane przez zestaw SDK zadań WebJobs. W wersji 2.x, powiązania magazynu są zawarte w zestawie SDK.
Narzędzia programu Visual Studio 2019 dla platformy .NET Core (3).projekty x) różnią się od narzędzi programu .NET Framework (2).x) projektów. Aby dowiedzieć się więcej, zobacz Tworzenie i wdrażanie zadań WebJob przy użyciu programu Visual Studio — aplikacja systemu Azure Service.

Kilka opisów w tym artykule zawiera przykłady dla obu zadań WebJob w wersji 3.x i Zadania WebJob w wersji 2.x.

Usługa Azure Functions jest oparta na zestawie SDK usługi WebJobs.

Azure Functions w wersji 2.X jest oparty na zestawie SDK usługi WebJobs w wersji 3.x.
Azure Functions w wersji 1.X jest oparty na zestawie SDK usługi WebJobs w wersji 2.x.

Repozytoria kodu źródłowego dla zestawu SDK usługi Azure Functions i usługi WebJobs używają numeracji zestawu SDK usługi WebJobs. Kilka sekcji tego artykułu z instrukcjami zawiera link do dokumentacji usługi Azure Functions.

Aby uzyskać więcej informacji, zobacz Porównanie zestawu SDK usługi WebJobs i usługi Azure Functions

Host zadań WebJob

Host jest kontenerem środowiska uruchomieniowego dla funkcji. Host nasłuchuje wyzwalaczy i wywołuje funkcje. W wersji 3.x, host jest implementacją .IHost W wersji 2.x , należy użyć JobHost obiektu . Wystąpienie hosta należy utworzyć w kodzie i napisać kod, aby dostosować jego zachowanie.

Jest to kluczowa różnica między użyciem zestawu SDK usługi WebJobs bezpośrednio a użyciem go pośrednio za pośrednictwem usługi Azure Functions. W usłudze Azure Functions usługa kontroluje hosta i nie można dostosować hosta, pisząc kod. Usługa Azure Functions umożliwia dostosowywanie zachowania hosta za pomocą ustawień w pliku host.json. Te ustawienia to ciągi, a nie kod i użycie tych ciągów ogranicza rodzaje dostosowań, które można wykonać.

Połączenia hosta

Zestaw SDK usługi WebJobs wyszukuje połączenia usługi Azure Storage i Azure Service Bus w pliku local.settings.json po uruchomieniu lokalnie lub w środowisku zadania WebJob podczas uruchamiania na platformie Azure. Domyślnie zestaw SDK zadań WebJobs wymaga połączenia magazynu o nazwie AzureWebJobsStorage.

Gdy nazwa połączenia jest rozpoznawana jako pojedyncza dokładna wartość, środowisko uruchomieniowe identyfikuje wartość jako parametry połączenia, która zazwyczaj zawiera wpis tajny. Szczegóły parametry połączenia zależą od usługi, z którą nawiązujesz połączenie. Jednak nazwa połączenia może również odwoływać się do kolekcji wielu elementów konfiguracji, co jest przydatne do konfigurowania połączeń opartych na tożsamościach. Zmienne środowiskowe mogą być traktowane jako kolekcja przy użyciu udostępnionego prefiksu kończącego się podwójnymi podkreśleniami __. Następnie można odwoływać się do grupy, ustawiając nazwę połączenia na ten prefiks.

Na przykład connection właściwość definicji wyzwalacza obiektu blob platformy Azure może mieć wartość Storage1. Jeśli nie ma żadnej pojedynczej wartości parametrów skonfigurowanej przez zmienną środowiskową o nazwie , zmienna środowiskowa o nazwie Storage1Storage1__blobServiceUri może służyć do informowania blobServiceUri właściwości połączenia. Właściwości połączenia są różne dla każdej usługi. Zapoznaj się z dokumentacją składnika korzystającego z połączenia.

Połączenia oparte na tożsamościach

Aby używać połączeń opartych na tożsamościach w zestawie SDK usługi WebJobs, upewnij się, że używasz najnowszych wersji pakietów zadań WebJob w projekcie. Upewnij się również, że masz odwołanie do pliku Microsoft.Azure.WebJobs.Host.Storage. Poniżej przedstawiono przykładowy wygląd pliku projektu po wprowadzeniu tych aktualizacji:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>
    <IsWebJobProject>true</IsWebJobProject>
    <WebJobName>$(AssemblyName)</WebJobName>
    <WebJobType>Continuous</WebJobType>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.WebJobs" Version="3.0.41" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.Storage.Queues" Version="5.3.1" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Host.Storage" Version="5.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="2.1.1" />
  </ItemGroup>

  <ItemGroup>
    <None Update="appsettings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

Podczas konfigurowania zadań WebJob w programie HostBuilder upewnij się, że dołącz wywołanie metody AddAzureStorageCoreServices, ponieważ umożliwia AzureWebJobsStorage to używanie tożsamości i innych wyzwalaczy i powiązań usługi Storage:

    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        // other configurations...
    });

Następnie można skonfigurować AzureWebJobsStorage połączenie, ustawiając zmienne środowiskowe (lub ustawienia aplikacji, gdy są hostowane w usłudze App Service):

Zmienna środowiskowa	opis	Przykładowa wartość
`AzureWebJobsStorage__blobServiceUri`	Identyfikator URI płaszczyzny danych usługi obiektów blob konta magazynu przy użyciu schematu HTTPS.	<https:// storage_account_name.blob.core.windows.net>
`AzureWebJobsStorage__queueServiceUri`	Identyfikator URI płaszczyzny danych usługi kolejki konta magazynu przy użyciu schematu HTTPS.	<https:// storage_account_name.queue.core.windows.net>

Jeśli podasz konfigurację za pomocą jakichkolwiek środków innych niż zmienne środowiskowe, na przykład z elementem appsettings.json, należy podać konfigurację ustrukturyzowaną dla połączenia i jego właściwości:

{
    "AzureWebJobsStorage": {
        "blobServiceUri": "https://<storage_account_name>.blob.core.windows.net",
        "queueServiceUri": "https://<storage_account_name>.queue.core.windows.net"
    }
}

Jeśli nie planujesz używania wyzwalaczy obiektów blob, możesz pominąć queueServiceUri właściwość .

Gdy kod jest uruchamiany lokalnie, domyślnie będzie używany tożsamość dewelopera zgodnie z zachowaniem opisanym dla ustawienia DefaultAzureCredential.

Jeśli kod jest hostowany w usłudze aplikacja systemu Azure, konfiguracja przedstawiona powyżej będzie domyślnie przypisana przez system tożsamości zarządzanej dla zasobu. Aby zamiast tego użyć tożsamości przypisanej przez użytkownika, która została przypisana do aplikacji, należy dodać dodatkowe właściwości dla połączenia, które określają, która tożsamość ma być używana. Właściwość credential (AzureWebJobsStorage__credential jako zmienna środowiskowa) powinna być ustawiona na ciąg "managedidentity". Właściwość clientId (AzureWebJobsStorage__clientId jako zmienna środowiskowa) powinna być ustawiona na identyfikator klienta tożsamości zarządzanej przypisanej przez użytkownika do użycia. Jako konfiguracja ustrukturyzowana kompletny obiekt będzie następujący:

{
    "AzureWebJobsStorage": {
        "blobServiceUri": "https://<storage_account_name>.blob.core.windows.net",
        "queueServiceUri": "https://<storage_account_name>.queue.core.windows.net",
        "credential": "managedidentity",
        "clientId": "<user-assigned-identity-client-id>"
    }
}

Tożsamość używana dla AzureWebJobsStorage programu powinna mieć przypisania ról, które przyznają mu role Właściciel danych obiektu blob usługi Storage, Współautor danych kolejki magazynu i Współautor konta magazynu. Jeśli nie planujesz używania wyzwalaczy obiektów blob, możesz pominąć zarówno współautora danych kolejki magazynu, jak i współautora konta magazynu.

W poniższej tabeli przedstawiono wbudowane role, które są zalecane podczas korzystania z wyzwalaczy w powiązaniach w normalnej operacji. Aplikacja może wymagać dalszych uprawnień na podstawie zapisanego kodu.

Wiązanie	Przykładowe role wbudowane
Wyzwalacz obiektu blob	Właściciel danych obiektu blob usługi Storage i współautor danych kolejki magazynu Zobacz powyżej, aby zapoznać się z wymaganiami `AzureWebJobsStorage` dotyczącymi.
Obiekt blob (dane wejściowe)	Czytelnik danych obiektu blob usługi Storage
Obiekt blob (dane wyjściowe)	Właściciel danych obiektu blob usługi Storage
Wyzwalacz kolejki	Czytelnik danych kolejki usługi Storage, procesor komunikatów kolejki magazynu
Kolejka (dane wyjściowe)	Współautor danych kolejki usługi Storage, nadawca komunikatów dotyczących kolejki magazynu
Wyzwalacz^{usługi Service Bus 1}	Odbiornik danych usługi Azure Service Bus, właściciel danych usługi Azure Service Bus
Service Bus (dane wyjściowe)	Nadawca danych usługi Azure Service Bus

¹ W przypadku wyzwalania z tematów usługi Service Bus przypisanie roli musi mieć skuteczny zakres dla zasobu subskrypcji usługi Service Bus. Jeśli zostanie uwzględniony tylko temat, wystąpi błąd. Niektóre klienty, takie jak witryna Azure Portal, nie ujawniają zasobu subskrypcji usługi Service Bus jako zakresu dla przypisania roli. W takich przypadkach można użyć interfejsu wiersza polecenia platformy Azure. Aby dowiedzieć się więcej, zobacz Wbudowane role platformy Azure dla usługi Azure Service Bus.

Parametry połączenia w wersji 2.x

Wersja 2.X zestawu SDK nie wymaga określonej nazwy. Wersja 2.x umożliwia używanie własnych nazw dla tych parametry połączenia i umożliwia przechowywanie ich w innym miejscu. Nazwy w kodzie można ustawić przy użyciu polecenia JobHostConfiguration, w następujący sposób:

static void Main(string[] args)
{
    var _storageConn = ConfigurationManager
        .ConnectionStrings["MyStorageConnection"].ConnectionString;

    //// Dashboard logging is deprecated; use Application Insights.
    //var _dashboardConn = ConfigurationManager
    //    .ConnectionStrings["MyDashboardConnection"].ConnectionString;

    JobHostConfiguration config = new JobHostConfiguration();
    config.StorageConnectionString = _storageConn;
    //config.DashboardConnectionString = _dashboardConn;
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

Uwaga

Ponieważ wersja 3.X używa domyślnych interfejsów API konfiguracji platformy .NET Core, nie ma interfejsu API do zmiany nazw parametry połączenia. Zobacz Tworzenie i wdrażanie zadań WebJob przy użyciu programu Visual Studio

Ustawienia programowania hosta

Host można uruchomić w trybie programowania, aby usprawnić programowanie lokalne. Poniżej przedstawiono niektóre ustawienia, które są automatycznie zmieniane po uruchomieniu w trybie programowania:

Właściwości	Ustawienie programowania
`Tracing.ConsoleLevel`	`TraceLevel.Verbose` aby zmaksymalizować dane wyjściowe dziennika.
`Queues.MaxPollingInterval`	Niska wartość zapewniająca natychmiastowe wyzwolenie metod kolejki.
`Singleton.ListenerLockPeriod`	15 sekund, aby pomóc w szybkim rozwoju iteracyjnym.

Proces włączania trybu programowania zależy od wersji zestawu SDK.

Wersja 3.x

Wersja 3.X używa standardowych interfejsów API ASP.NET Core. Wywołaj metodę UseEnvironment w wystąpieniu HostBuilder . Przekaż ciąg o nazwie development, jak w tym przykładzie:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment("development");
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Wersja 2.x

Klasa JobHostConfiguration ma metodę UseDevelopmentSettings , która umożliwia tryb programowania. W poniższym przykładzie pokazano, jak używać ustawień programowania. Aby powrócić config.IsDevelopment true po uruchomieniu lokalnie, ustaw lokalną zmienną środowiskową o nazwie AzureWebJobsEnv z wartością Development.

static void Main()
{
    config = new JobHostConfiguration();

    if (config.IsDevelopment)
    {
        config.UseDevelopmentSettings();
    }

    var host = new JobHost(config);
    host.RunAndBlock();
}

Zarządzanie połączeniami współbieżnych (wersja 2.x)

W wersji 3.x, limit połączenia jest domyślnie domyślnie nieskończone połączenia. Jeśli z jakiegoś powodu musisz zmienić ten limit, możesz użyć MaxConnectionsPerServer właściwości WinHttpHandler klasy .

W wersji 2.x kontrolujesz liczbę współbieżnych połączeń z hostem przy użyciu interfejsu API ServicePointManager.DefaultConnectionLimit . W 2.x, należy zwiększyć tę wartość z wartości domyślnej 2 przed uruchomieniem hosta zadań WebJob.

Wszystkie wychodzące żądania HTTP wysyłane z funkcji przy użyciu HttpClient przepływu za pośrednictwem metody ServicePointManager. Po osiągnięciu wartości ustawionej w programie DefaultConnectionLimitServicePointManager rozpoczyna kolejkowanie żądań przed ich wysłaniem. Załóżmy, że ustawiono DefaultConnectionLimit wartość 2, a kod wysyła 1000 żądań HTTP. Początkowo do systemu operacyjnego dozwolone są tylko dwa żądania. Pozostałe 998 są w kolejce, dopóki nie będzie miejsca dla nich. Oznacza to, że może HttpClient upłynął limit czasu, ponieważ wydaje się, że żądanie zostało wysłane, ale żądanie nigdy nie zostało wysłane przez system operacyjny do serwera docelowego. Dlatego może być widoczne zachowanie, które nie wydaje się mieć sensu: lokalne HttpClient trwa 10 sekund, aby ukończyć żądanie, ale usługa zwraca każde żądanie w 200 ms.

Wartość domyślna dla aplikacji ASP.NET to Int32.MaxValue, która prawdopodobnie będzie działać dobrze w przypadku zadań WebJob działających w planie usługi App Service w warstwie Podstawowa lub wyższa. Zadania WebJob zwykle wymagają ustawienia Zawsze włączone i są obsługiwane tylko przez plany usługi App Service w warstwie Podstawowa i wyższa.

Jeśli twoje konto WebJob jest uruchomione w planie bezpłatnej lub udostępnionej usługi App Service, aplikacja jest ograniczona przez piaskownicę usługi App Service, która obecnie ma limit połączeń 300. W przypadku limitu połączenia bez ruchu w systemie ServicePointManagerjest bardziej prawdopodobne, że zostanie osiągnięty próg połączenia piaskownicy, a lokacja zostanie zamknięta. W takim przypadku ustawienie DefaultConnectionLimit wartości niższej, takiej jak 50 lub 100, może uniemożliwić takie zdarzenie i nadal zezwalać na wystarczającą przepływność.

Ustawienie należy skonfigurować przed wykonaniem żądań HTTP. Z tego powodu host zadań WebJob nie powinien automatycznie dostosowywać ustawienia. Mogą istnieć żądania HTTP, które występują przed uruchomieniem hosta, co może prowadzić do nieoczekiwanego zachowania. Najlepszym rozwiązaniem jest natychmiastowe ustawienie wartości w Main metodzie przed zainicjowaniem JobHostmetody , jak pokazano poniżej:

static void Main(string[] args)
{
    // Set this immediately so that it's used by all requests.
    ServicePointManager.DefaultConnectionLimit = Int32.MaxValue;

    var host = new JobHost();
    host.RunAndBlock();
}

Wyzwalacze

Zestaw SDK usługi WebJobs obsługuje ten sam zestaw wyzwalaczy i powiązań używanych przez usługę Azure Functions. Należy pamiętać, że w zestawie SDK zadań WebJob wyzwalacze są specyficzne dla funkcji i nie są powiązane z typem wdrożenia zadania WebJob. Zadania WebJob z funkcjami wyzwalanymi przez zdarzenia utworzone przy użyciu zestawu SDK powinny być zawsze publikowane jako ciągłe zadanie WebJob z włączonym zawsze włączonym funkcją .

Funkcje muszą być metodami publicznymi i muszą mieć jeden atrybut wyzwalacza lub NoAutomaticTrigger atrybut.

Wyzwalacze automatyczne

Wyzwalacze automatyczne wywołują funkcję w odpowiedzi na zdarzenie. Rozważmy ten przykład funkcji wyzwalanej przez komunikat dodany do usługi Azure Queue Storage. Funkcja odpowiada, odczytując obiekt blob z usługi Azure Blob Storage:

public static void Run(
    [QueueTrigger("myqueue-items")] string myQueueItem,
    [Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
    ILogger log)
{
    log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
}

Atrybut QueueTrigger informuje środowisko uruchomieniowe o wywołaniu funkcji za każdym razem, gdy w pliku pojawi się myqueue-itemskomunikat kolejki. Atrybut Blob informuje środowisko uruchomieniowe o użyciu komunikatu kolejki w celu odczytania obiektu blob w kontenerze sample-workitems . Nazwa elementu obiektu blob w kontenerze samples-workitems jest uzyskiwana bezpośrednio z wyzwalacza kolejki jako wyrażenie powiązania ({queueTrigger}).

Uwaga

Aplikacja internetowa może upłynął limit czasu po upływie 20 minut braku aktywności i tylko żądania do rzeczywistej aplikacji internetowej mogą zresetować czasomierz. Wyświetlanie konfiguracji aplikacji w witrynie Azure Portal lub wykonywanie żądań do witryny zaawansowanych narzędzi (https://<app_name>.scm.azurewebsites.net) nie powoduje zresetowania czasomierza. Jeśli ustawisz aplikację internetową, która hostuje zadanie do ciągłego uruchamiania, uruchom je zgodnie z harmonogramem lub użyj wyzwalaczy sterowanych zdarzeniami, włącz ustawienie Zawsze włączone na stronie Konfiguracja platformy Azure aplikacji internetowej. Ustawienie Zawsze włączone pomaga upewnić się, że tego rodzaju zadania WebJob działają niezawodnie. Ta funkcja jest dostępna tylko w warstwach cenowych Podstawowa, Standardowa i Premium.

Wyzwalacze ręczne

Aby ręcznie wyzwolić funkcję, użyj atrybutu NoAutomaticTrigger , jak pokazano poniżej:

[NoAutomaticTrigger]
public static void CreateQueueMessage(
ILogger logger,
string value,
[Queue("outputqueue")] out string message)
{
    message = value;
    logger.LogInformation("Creating queue message: ", message);
}

Proces ręcznego wyzwalania funkcji zależy od wersji zestawu SDK.

Wersja 3.x

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorage();
    });
    var host = builder.Build();
    using (host)
    {
        var jobHost = host.Services.GetService(typeof(IJobHost)) as JobHost;
        var inputs = new Dictionary<string, object>
        {
            { "value", "Hello world!" }
        };

        await host.StartAsync();
        await jobHost.CallAsync("CreateQueueMessage", inputs);
        await host.StopAsync();
    }
}

Wersja 2.x

static void Main(string[] args)
{
    JobHost host = new JobHost();
    host.Call(typeof(Program).GetMethod("CreateQueueMessage"), new { value = "Hello world!" });
}

Powiązania wejściowe i wyjściowe

Powiązania wejściowe zapewniają deklaratywny sposób udostępniania danych z usług platformy Azure lub usług innych firm w kodzie. Powiązania wyjściowe umożliwiają aktualizowanie danych. W artykule Wprowadzenie przedstawiono przykład każdego z nich.

Możesz użyć wartości zwracanej metody dla powiązania wyjściowego, stosując atrybut do wartości zwracanej metody. Zobacz przykład w temacie Używanie wartości zwracanej funkcji platformy Azure.

Typy powiązań

Proces instalowania typów powiązań i zarządzania nimi zależy od tego, czy używasz wersji 3.x lub wersja 2.x zestawu SDK. Pakiet do zainstalowania dla określonego typu powiązania można znaleźć w sekcji "Pakiety" artykułu referencyjnego usługi Azure Functions tego typu powiązania. Wyjątkiem jest wyzwalacz i powiązanie plików (dla lokalnego systemu plików), który nie jest obsługiwany przez usługę Azure Functions.

Wersja 3.x

W wersji 3.x, powiązania magazynu są zawarte w pakiecie Microsoft.Azure.WebJobs.Extensions.Storage . Wywołaj metodę AddAzureStorage rozszerzenia w metodzie ConfigureWebJobs , jak pokazano poniżej:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddAzureStorage();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby użyć innych typów wyzwalacza i powiązań, zainstaluj pakiet NuGet zawierający go i wywołaj Add<binding> metodę rozszerzenia zaimplementowaną w rozszerzeniu. Jeśli na przykład chcesz użyć powiązania usługi Azure Cosmos DB, zainstaluj i wywołaj Microsoft.Azure.WebJobs.Extensions.CosmosDB metodę AddCosmosDB, w następujący sposób:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddCosmosDB();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby użyć wyzwalacza czasomierza lub powiązania Pliki, które są częścią podstawowych usług, wywołaj AddTimers metody lub AddFiles rozszerzenia.

Wersja 2.x

Te typy wyzwalaczy i powiązań są uwzględniane w wersji 2.Microsoft.Azure.WebJobs x pakietu:

Blob storage
Queue Storage
Table Storage

Aby użyć innych typów wyzwalacza i powiązań, zainstaluj pakiet NuGet zawierający go i wywołaj metodę Use<binding> w JobHostConfiguration obiekcie . Jeśli na przykład chcesz użyć wyzwalacza czasomierza, zainstaluj Microsoft.Azure.WebJobs.Extensions i wywołaj UseTimers metodę Main , jak pokazano poniżej:

static void Main()
{
    config = new JobHostConfiguration();
    config.UseTimers();
    var host = new JobHost(config);
    host.RunAndBlock();
}

Aby użyć powiązania Pliki, zainstaluj Microsoft.Azure.WebJobs.Extensions i wywołaj polecenie UseFiles.

ExecutionContext

Zadania WebJob umożliwiają powiązanie z elementem ExecutionContext. Dzięki temu powiązaniu możesz uzyskać dostęp do parametru ExecutionContext jako parametru w podpisie funkcji. Na przykład poniższy kod używa obiektu kontekstu w celu uzyskania dostępu do identyfikatora wywołania, którego można użyć do skorelowania wszystkich dzienników generowanych przez wywołanie danej funkcji.

public class Functions
{
    public static void ProcessQueueMessage([QueueTrigger("queue")] string message,
        ExecutionContext executionContext,
        ILogger logger)
    {
        logger.LogInformation($"{message}\n{executionContext.InvocationId}");
    }
}

Proces wiązania z elementem ExecutionContext zależy od wersji zestawu SDK.

Wersja 3.x

Wywołaj metodę AddExecutionContextBinding rozszerzenia w metodzie ConfigureWebJobs , jak pokazano poniżej:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddExecutionContextBinding();
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Wersja 2.x

Pakiet Microsoft.Azure.WebJobs.Extensions wymieniony wcześniej udostępnia również specjalny typ powiązania, który można zarejestrować, wywołując metodę UseCore . To powiązanie umożliwia zdefiniowanie parametru ExecutionContext w podpisie funkcji, który jest włączony w następujący sposób:

class Program
{
    static void Main()
    {
        config = new JobHostConfiguration();
        config.UseCore();
        var host = new JobHost(config);
        host.RunAndBlock();
    }
}

Konfiguracja powiązania

Można skonfigurować zachowanie niektórych wyzwalaczy i powiązań. Proces ich konfigurowania zależy od wersji zestawu SDK.

Wersja 3.x: Ustaw konfigurację, gdy metoda jest wywoływana Add<Binding> w pliku ConfigureWebJobs.
Wersja 2.x: Ustaw konfigurację, ustawiając właściwości w obiekcie konfiguracji przekazywanym do elementu JobHost.

Te ustawienia specyficzne dla powiązania są równoważne z ustawieniami w pliku projektu host.json w usłudze Azure Functions.

Można skonfigurować następujące powiązania:

Wyzwalacz usługi Azure Cosmos DB
Wyzwalacz usługi Event Hubs
Wyzwalacz usługi Queue Storage
Powiązanie usługi SendGrid
Wyzwalacz usługi Service Bus

Konfiguracja wyzwalacza usługi Azure Cosmos DB (wersja 3.x)

W tym przykładzie pokazano, jak skonfigurować wyzwalacz usługi Azure Cosmos DB:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddCosmosDB(a =>
        {
            a.ConnectionMode = ConnectionMode.Gateway;
            a.Protocol = Protocol.Https;
            a.LeaseOptions.LeasePrefix = "prefix1";

        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby uzyskać więcej informacji, zobacz artykuł dotyczący powiązania usługi Azure Cosmos DB.

Konfiguracja wyzwalacza usługi Event Hubs (wersja 3.x)

W tym przykładzie pokazano, jak skonfigurować wyzwalacz usługi Event Hubs:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddEventHubs(a =>
        {
            a.BatchCheckpointFrequency = 5;
            a.EventProcessorOptions.MaxBatchSize = 256;
            a.EventProcessorOptions.PrefetchCount = 512;
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby uzyskać więcej informacji, zobacz artykuł powiązania usługi Event Hubs.

Konfiguracja wyzwalacza usługi Queue Storage

W poniższych przykładach pokazano, jak skonfigurować wyzwalacz usługi Queue Storage.

Wersja 3.x

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddAzureStorage(a => {
            a.BatchSize = 8;
            a.NewBatchThreshold = 4;
            a.MaxDequeueCount = 4;
            a.MaxPollingInterval = TimeSpan.FromSeconds(15);
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby uzyskać więcej informacji, zobacz artykuł Powiązanie usługi Queue Storage.

Wersja 2.x

static void Main(string[] args)
{
    JobHostConfiguration config = new JobHostConfiguration();
    config.Queues.BatchSize = 8;
    config.Queues.NewBatchThreshold = 4;
    config.Queues.MaxDequeueCount = 4;
    config.Queues.MaxPollingInterval = TimeSpan.FromSeconds(15);
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

Aby uzyskać więcej informacji, zobacz dokumentację host.json v1.x.

Konfiguracja powiązania usługi SendGrid (wersja 3.x)

W tym przykładzie pokazano, jak skonfigurować powiązanie wyjściowe usługi SendGrid:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddSendGrid(a =>
        {
            a.FromAddress.Email = "samples@functions.com";
            a.FromAddress.Name = "Azure Functions";
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby uzyskać więcej informacji, zobacz artykuł Dotyczący powiązania usługi SendGrid.

Konfiguracja wyzwalacza usługi Service Bus (wersja 3.x)

W tym przykładzie pokazano, jak skonfigurować wyzwalacz usługi Service Bus:

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddServiceBus(sbOptions =>
        {
            sbOptions.MessageHandlerOptions.AutoComplete = true;
            sbOptions.MessageHandlerOptions.MaxConcurrentCalls = 16;
        });
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Aby uzyskać więcej informacji, zobacz artykuł Powiązania usługi Service Bus.

Konfiguracja innych powiązań

Niektóre typy wyzwalaczy i powiązań definiują własne niestandardowe typy konfiguracji. Na przykład wyzwalacz Plik umożliwia określenie ścieżki głównej do monitorowania, tak jak w poniższych przykładach.

Wersja 3.x

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
        b.AddFiles(a => a.RootPath = @"c:\data\import");
    });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Wersja 2.x

static void Main()
{
    config = new JobHostConfiguration();
    var filesConfig = new FilesConfiguration
    {
        RootPath = @"c:\data\import"
    };
    config.UseFiles(filesConfig);
    var host = new JobHost(config);
    host.RunAndBlock();
}

Wyrażenia powiązania

W parametrach konstruktora atrybutu można użyć wyrażeń, które są rozpoznawane jako wartości z różnych źródeł. Na przykład w poniższym kodzie ścieżka atrybutu BlobTrigger tworzy wyrażenie o nazwie filename. W przypadku użycia powiązania filename wyjściowego jest rozpoznawana jako nazwa wyzwalającego obiektu blob.

public static void CreateThumbnail(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger logger)
{
    logger.Info($"Blob trigger processing: {filename}");
    // ...
}

Aby uzyskać więcej informacji na temat wyrażeń powiązań, zobacz Temat Binding expressions and patterns (Wyrażenia powiązań i wzorce ) w dokumentacji usługi Azure Functions.

Niestandardowe wyrażenia powiązań

Czasami chcesz określić nazwę kolejki, nazwę obiektu blob lub kontener albo nazwę tabeli w kodzie, a nie trwale kodować. Na przykład możesz określić nazwę kolejki dla atrybutu QueueTrigger w pliku konfiguracji lub zmiennej środowiskowej.

Można to zrobić, przekazując niestandardowy program rozpoznawania nazw podczas konfigurowania. Symbole zastępcze są uwzględniane w parametrach konstruktora wyzwalacza lub powiązania, a kod rozpoznawania zawiera rzeczywiste wartości, które mają być używane zamiast tych symboli zastępczych. Symbole zastępcze można zidentyfikować, otaczając je znakami procentu (%) jak pokazano poniżej:

public static void WriteLog([QueueTrigger("%logqueue%")] string logMessage)
{
    Console.WriteLine(logMessage);
}

Ten kod umożliwia użycie kolejki o nazwie logqueuetest w środowisku testowym i jednej o nazwie logqueueprod w środowisku produkcyjnym. Zamiast zakodowanej nazwy kolejki należy określić nazwę wpisu w kolekcji appSettings .

Jeśli nie podasz niestandardowego, jest dostępny domyślny program rozpoznawania nazw. Wartość domyślna pobiera wartości z ustawień aplikacji lub zmiennych środowiskowych.

Począwszy od platformy .NET Core 3.1, ConfigurationManager używany pakiet NuGet System.Configuration.ConfigurationManager jest wymagany. Przykład wymaga następującej using instrukcji:

using System.Configuration;

Klasa NameResolver pobiera nazwę kolejki z ustawień aplikacji, jak pokazano poniżej:

public class CustomNameResolver : INameResolver
{
    public string Resolve(string name)
    {
        return ConfigurationManager.AppSettings[name].ToString();
    }
}

Wersja 3.x

Rozpoznawanie można skonfigurować przy użyciu wstrzykiwania zależności. Te przykłady wymagają następującej using instrukcji:

using Microsoft.Extensions.DependencyInjection;

Dodasz program rozpoznawania, wywołując metodę ConfigureServices rozszerzenia w metodzie HostBuilder, jak w tym przykładzie:

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    var resolver = new CustomNameResolver();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureServices(s => s.AddSingleton<INameResolver>(resolver));
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Wersja 2.x

Przekaż klasę NameResolver JobHost do obiektu, jak pokazano poniżej:

 static void Main(string[] args)
{
    JobHostConfiguration config = new JobHostConfiguration();
    config.NameResolver = new CustomNameResolver();
    JobHost host = new JobHost(config);
    host.RunAndBlock();
}

Usługa Azure Functions implementuje INameResolver pobieranie wartości z ustawień aplikacji, jak pokazano w przykładzie. Korzystając bezpośrednio z zestawu SDK usługi WebJobs, możesz napisać niestandardową implementację, która pobiera zastępcze wartości zastępcze z dowolnego preferowanego źródła.

Wiązanie w czasie wykonywania

Jeśli musisz wykonać pewną pracę w funkcji przed użyciem atrybutu powiązania, takiego jak Queue, Bloblub Table, możesz użyć interfejsu IBinder .

Poniższy przykład przyjmuje komunikat kolejki wejściowej i tworzy nowy komunikat z tą samą zawartością w kolejce wyjściowej. Nazwa kolejki wyjściowej jest ustawiana przez kod w treści funkcji.

public static void CreateQueueMessage(
    [QueueTrigger("inputqueue")] string queueMessage,
    IBinder binder)
{
    string outputQueueName = "outputqueue" + DateTime.Now.Month.ToString();
    QueueAttribute queueAttribute = new QueueAttribute(outputQueueName);
    CloudQueue outputQueue = binder.Bind<CloudQueue>(queueAttribute);
    outputQueue.AddMessageAsync(new CloudQueueMessage(queueMessage));
}

Aby uzyskać więcej informacji, zobacz Wiązanie w czasie wykonywania w dokumentacji usługi Azure Functions.

Informacje referencyjne dotyczące powiązań

Dokumentacja usługi Azure Functions zawiera informacje referencyjne dotyczące każdego typu powiązania. Poniższe informacje znajdziesz w każdym artykule referencyjnym dotyczącym powiązań. (Ten przykład jest oparty na kolejce usługi Storage).

Pakiety. Pakiet, który należy zainstalować, aby uwzględnić obsługę powiązania w projekcie zestawu SDK zadań WebJobs.
Przykłady. Przykłady kodu. Przykład biblioteki klas języka C# dotyczy zestawu SDK usługi WebJobs. Po prostu pomiń FunctionName atrybut.
Atrybuty. Atrybuty do użycia dla typu powiązania.
Konfiguracja. Wyjaśnienia właściwości atrybutu i parametrów konstruktora.
Użycie. Typy, z których można powiązać, oraz informacje o sposobie działania powiązania. Na przykład: algorytm sondowania, zatrucie przetwarzania kolejek.

Uwaga

Powiązania HTTP, webhook i Event Grid są obsługiwane tylko przez usługę Azure Functions, a nie przez zestaw SDK usługi WebJobs.

Aby uzyskać pełną listę powiązań obsługiwanych w środowisku uruchomieniowym usługi Azure Functions, zobacz Obsługiwane powiązania.

Atrybuty wyłączenia, przekroczenia limitu czasu i pojedynczego

Za pomocą tych atrybutów można kontrolować wyzwalanie funkcji, anulować funkcje i upewnić się, że działa tylko jedno wystąpienie funkcji.

Wyłącz atrybut

Atrybut Disable umożliwia kontrolowanie, czy można wyzwolić funkcję.

W poniższym przykładzie, jeśli ustawienie Disable_TestJob aplikacji ma wartość 1 lub True (bez uwzględniania wielkości liter), funkcja nie zostanie uruchomiona. W takim przypadku środowisko uruchomieniowe tworzy komunikat dziennika Funkcja "Functions.TestJob" jest wyłączona.

[Disable("Disable_TestJob")]
public static void TestJob([QueueTrigger("testqueue2")] string message)
{
    Console.WriteLine("Function with Disable attribute executed!");
}

Po zmianie wartości ustawień aplikacji w witrynie Azure Portal usługa WebJob zostanie ponownie uruchomiona, aby pobrać nowe ustawienie.

Atrybut można zadeklarować na poziomie parametru, metody lub klasy. Nazwa ustawienia może również zawierać wyrażenia powiązania.

Atrybut limitu czasu

Atrybut Timeout powoduje anulowanie funkcji, jeśli nie zostanie ukończona w określonym czasie. W poniższym przykładzie funkcja będzie uruchamiana przez jeden dzień bez atrybutu Limit czasu. Limit czasu powoduje anulowanie funkcji po 15 sekundach. Gdy parametr "throwOnError" atrybutu limitu czasu jest ustawiony na wartość "true", wywołanie funkcji jest przerywane przez wyjątek zgłaszany przez zestaw SDK zadań webjobs po przekroczeniu interwału przekroczenia limitu czasu. Wartość domyślna "throwOnError" to "false". Gdy jest używany atrybut limitu czasu, domyślne zachowanie polega na anulowaniu wywołania funkcji przez ustawienie tokenu anulowania przy jednoczesnym umożliwieniu uruchamiania wywołania na czas nieokreślony, dopóki kod funkcji nie zwróci lub zgłosi wyjątek.

[Timeout("00:00:15")]
public static async Task TimeoutJob(
    [QueueTrigger("testqueue2")] string message,
    CancellationToken token,
    TextWriter log)
{
    await log.WriteLineAsync("Job starting");
    await Task.Delay(TimeSpan.FromDays(1), token);
    await log.WriteLineAsync("Job completed");
}

Atrybut Limit czasu można zastosować na poziomie klasy lub metody i można określić globalny limit czasu za pomocą polecenia JobHostConfiguration.FunctionTimeout. Limity czasu na poziomie klasy lub metody zastępują globalne limity czasu.

Atrybut singleton

Atrybut Singleton zapewnia, że jest uruchamiane tylko jedno wystąpienie funkcji, nawet jeśli istnieje wiele wystąpień aplikacji internetowej hosta. Atrybut Singleton używa rozproszonego blokowania , aby upewnić się, że jedno wystąpienie jest uruchomione.

W tym przykładzie w danym momencie jest uruchamiane tylko jedno wystąpienie ProcessImage funkcji:

[Singleton]
public static async Task ProcessImage([BlobTrigger("images")] Stream image)
{
     // Process the image.
}

SingletonMode.Listener

Niektóre wyzwalacze mają wbudowaną obsługę zarządzania współbieżnością:

QueueTrigger. Ustaw wartość opcji JobHostConfiguration.Queues.BatchSize na 1.
ServiceBusTrigger. Ustaw wartość opcji ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls na 1.
FileTrigger. Ustaw wartość opcji FileProcessor.MaxDegreeOfParallelism na 1.

Możesz użyć tych ustawień, aby upewnić się, że funkcja działa jako pojedynczy element w jednym wystąpieniu. Aby upewnić się, że tylko jedno wystąpienie funkcji jest uruchomione, gdy aplikacja internetowa skaluje się w poziomie do wielu wystąpień, zastosuj blokadę pojedynczego poziomu odbiornika w funkcji ([Singleton(Mode = SingletonMode.Listener)]). Blokady odbiornika są uzyskiwane po uruchomieniu elementu JobHost. Jeśli wszystkie wystąpienia skalowane w poziomie są uruchamiane w tym samym czasie, tylko jedno wystąpienie uzyskuje blokadę i uruchamia tylko jeden odbiornik.

Uwaga

Zobacz to repozytorium GitHub, aby dowiedzieć się więcej o sposobie działania funkcji SingletonMode.Function.

Wartości zakresu

Możesz określić wyrażenie/wartość zakresu w pojedynczym elemecie. Wyrażenie/wartość gwarantuje, że wszystkie wykonania funkcji w określonym zakresie zostaną serializowane. Zaimplementowanie bardziej szczegółowego blokowania w ten sposób może zapewnić pewien poziom równoległości dla funkcji podczas serializacji innych wywołań zgodnie z wymaganiami. Na przykład w poniższym kodzie wyrażenie zakresu wiąże się z wartością Region komunikatu przychodzącego. Gdy kolejka zawiera trzy komunikaty w regionach Wschodnie, Wschodnie i Zachodnie, komunikaty, które mają region Wschodni, są uruchamiane szeregowo. Komunikat z regionem Zachodnie jest uruchamiany równolegle z komunikatami w regionie Wschód.

[Singleton("{Region}")]
public static async Task ProcessWorkItem([QueueTrigger("workitems")] WorkItem workItem)
{
     // Process the work item.
}

public class WorkItem
{
     public int ID { get; set; }
     public string Region { get; set; }
     public int Category { get; set; }
     public string Description { get; set; }
}

SingletonScope.Host

Domyślny zakres blokady to SingletonScope.Function, co oznacza, że zakres blokady (ścieżka dzierżawy obiektu blob) jest powiązany z w pełni kwalifikowaną nazwą funkcji. Aby zablokować funkcje, określ SingletonScope.Host i użyj nazwy identyfikatora zakresu, która jest taka sama we wszystkich funkcjach, których nie chcesz uruchamiać jednocześnie. W poniższym przykładzie tylko jedno wystąpienie AddItem lub RemoveItem jest uruchamiane jednocześnie:

[Singleton("ItemsLock", SingletonScope.Host)]
public static void AddItem([QueueTrigger("add-item")] string message)
{
     // Perform the add operation.
}

[Singleton("ItemsLock", SingletonScope.Host)]
public static void RemoveItem([QueueTrigger("remove-item")] string message)
{
     // Perform the remove operation.
}

Wyświetlanie obiektów blob dzierżawy

Zestaw SDK usługi WebJobs używa dzierżaw obiektów blob platformy Azure w ramach okładek w celu zaimplementowania rozproszonej blokady. Obiekty blob dzierżawy używane przez usługę azure-webjobs-host Singleton można znaleźć w kontenerze AzureWebJobsStorage na koncie magazynu w ścieżce "blokady". Na przykład ścieżka dzierżawy obiektu blob dla pierwszego ProcessImage przykładu pokazanego wcześniej może być locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage. Wszystkie ścieżki obejmują identyfikator JobHost, w tym przypadku 061851c758f04938a4426a9ab3869c0.

Funkcje asynchroniczne

Aby uzyskać informacje o sposobie kodowania funkcji asynchronicznych, zobacz dokumentację usługi Azure Functions.

Tokeny anulowania

Aby uzyskać informacje na temat obsługi tokenów anulowania, zobacz dokumentację usługi Azure Functions dotyczącą tokenów anulowania i bezpiecznego zamykania.

Wiele wystąpień

Jeśli aplikacja internetowa działa na wielu wystąpieniach, ciągłe zadanie WebJob jest uruchamiane na każdym wystąpieniu, nasłuchiwanie wyzwalaczy i wywoływanie funkcji. Różne powiązania wyzwalacza zostały zaprojektowane tak, aby wydajnie udostępniać pracę we współpracy między wystąpieniami, dzięki czemu skalowanie w poziomie do większej liczby wystąpień umożliwia obsługę większego obciążenia.

Chociaż niektóre wyzwalacze mogą spowodować podwójne przetwarzanie, wyzwalacze kolejki i magazynu obiektów blob automatycznie uniemożliwiają funkcji przetwarzanie komunikatu kolejki lub obiektu blob więcej niż raz. Aby uzyskać więcej informacji, zobacz Projektowanie pod kątem identycznych danych wejściowych w dokumentacji usługi Azure Functions.

Wyzwalacz czasomierza automatycznie zapewnia, że tylko jedno wystąpienie czasomierza jest uruchamiane, dzięki czemu nie będzie więcej niż jedno wystąpienie funkcji uruchomione w danym zaplanowanym czasie.

Jeśli chcesz mieć pewność, że tylko jedno wystąpienie funkcji jest uruchamiane nawet wtedy, gdy istnieje wiele wystąpień aplikacji internetowej hosta, możesz użyć atrybutu Singleton .

Filtry

Filtry funkcji (wersja zapoznawcza) umożliwiają dostosowanie potoku wykonywania zadań WebJob przy użyciu własnej logiki. Filtry są podobne do filtrów ASP.NET Core. Można je zaimplementować jako atrybuty deklaratywne, które są stosowane do funkcji lub klas. Aby uzyskać więcej informacji, zobacz Filtry funkcji.

Rejestrowanie i monitorowanie

Zalecamy korzystanie z platformy rejestrowania opracowanej dla ASP.NET. W artykule Wprowadzenie pokazano, jak z niego korzystać.

Filtrowanie dzienników

Każdy dziennik utworzony przez ILogger wystąpienie ma skojarzone i Category Level. LogLevel to wyliczenie, a kod liczb całkowitych wskazuje względną ważność:

PoziomRejestrowania	Kod
Śledzenie	0
Debugowanie	1
Informacja	2
Ostrzeżenie	3
Błąd	100
Krytyczne	5
Brak	6

Można niezależnie filtrować każdą kategorię do określonej LogLevelkategorii. Na przykład możesz zobaczyć wszystkie dzienniki przetwarzania wyzwalacza obiektów blob, ale tylko Error i wyższe dla wszystkich innych elementów.

Wersja 3.x

Wersja 3.x zestawu SDK opiera się na filtrowaniu wbudowanym w platformę .NET Core. Klasa LogCategories umożliwia definiowanie kategorii dla określonych funkcji, wyzwalaczy lub użytkowników. Definiuje również filtry dla określonych stanów hosta, takich jak Startup i Results. Dzięki temu można dostosować dane wyjściowe rejestrowania. Jeśli nie znaleziono dopasowania w zdefiniowanych kategoriach, filtr wraca do Default wartości podczas podejmowania decyzji, czy filtrować komunikat.

LogCategories wymaga następującej instrukcji using:

using Microsoft.Azure.WebJobs.Logging;

Poniższy przykład tworzy filtr, który domyślnie filtruje wszystkie dzienniki na Warning poziomie. Kategorie Function i results (równoważne Host.Results w wersji 2.x) są filtrowane na Error poziomie. Filtr porównuje bieżącą kategorię ze wszystkimi zarejestrowanymi poziomami w wystąpieniu LogCategories i wybiera najdłuższe dopasowanie. Oznacza to, że Debug poziom zarejestrowany dla Host.Triggers dopasowań Host.Triggers.Queue lub Host.Triggers.Blob. Dzięki temu można kontrolować szersze kategorie bez konieczności dodawania każdego z nich.

static async Task Main(string[] args)
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureLogging(logging =>
            {
                logging.SetMinimumLevel(LogLevel.Warning);
                logging.AddFilter("Function", LogLevel.Error);
                logging.AddFilter(LogCategories.CreateFunctionCategory("MySpecificFunctionName"),
                    LogLevel.Debug);
                logging.AddFilter(LogCategories.Results, LogLevel.Error);
                logging.AddFilter("Host.Triggers", LogLevel.Debug);
            });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Wersja 2.x

W wersji 2.x zestawu SDK służy LogCategoryFilter klasa do kontrolowania filtrowania. Właściwość LogCategoryFilter ma Default właściwość z początkową wartością Information, co oznacza, że wszystkie komunikaty na Informationpoziomach , Warning, Errorlub Critical są rejestrowane, ale wszystkie komunikaty na Debug poziomach lub Trace są filtrowane.

LogCategories Podobnie jak w wersji 3.x, CategoryLevels właściwość umożliwia określenie poziomów dziennika dla określonych kategorii, dzięki czemu można dostosować dane wyjściowe rejestrowania. Jeśli w słowniku CategoryLevels nie znaleziono dopasowania, filtr wraca do Default wartości podczas podejmowania decyzji, czy filtrować komunikat.

Poniższy przykład tworzy filtr, który domyślnie filtruje wszystkie dzienniki na Warning poziomie. Kategorie Function i Host.Results są filtrowane na Error poziomie. Element LogCategoryFilter porównuje bieżącą kategorię ze wszystkimi zarejestrowanymi i CategoryLevels wybiera najdłuższe dopasowanie. W związku z tym Debug poziom zarejestrowany dla Host.Triggers będzie zgodny Host.Triggers.Queue z parametrem lub Host.Triggers.Blob. Dzięki temu można kontrolować szersze kategorie bez konieczności dodawania każdego z nich.

var filter = new LogCategoryFilter();
filter.DefaultLevel = LogLevel.Warning;
filter.CategoryLevels[LogCategories.Function] = LogLevel.Error;
filter.CategoryLevels[LogCategories.Results] = LogLevel.Error;
filter.CategoryLevels["Host.Triggers"] = LogLevel.Debug;

config.LoggerFactory = new LoggerFactory()
    .AddApplicationInsights(instrumentationKey, filter.Filter)
    .AddConsole(filter.Filter);

Niestandardowe dane telemetryczne dla usługi Application Insights

Proces implementowania niestandardowych danych telemetrycznych dla usługi Application Insights zależy od wersji zestawu SDK. Aby dowiedzieć się, jak skonfigurować usługę Application Insights, zobacz Dodawanie rejestrowania usługi Application Insights.

Wersja 3.x

Ponieważ wersja 3.X zestawu SDK usługi WebJobs opiera się na hoście ogólnym platformy .NET Core, niestandardowa fabryka telemetrii nie jest już dostępna. Można jednak dodać niestandardowe dane telemetryczne do potoku przy użyciu wstrzykiwania zależności. Przykłady w tej sekcji wymagają następujących using instrukcji:

using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.ApplicationInsights.Channel;

Poniższa niestandardowa implementacja polecenia ITelemetryInitializer umożliwia dodanie własnego ITelemetry elementu do domyślnego TelemetryConfigurationelementu .

internal class CustomTelemetryInitializer : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        // Do something with telemetry.
    }
}

Wywołaj metodę ConfigureServices w konstruktorze, aby dodać niestandardowy ITelemetryInitializer element do potoku.

static async Task Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
    {
        b.AddAzureStorageCoreServices();
    });
    builder.ConfigureLogging((context, b) =>
    {
        // Add logging providers.
        b.AddConsole();

        // If this key exists in any config, use it to enable Application Insights.
        string appInsightsKey = context.Configuration["APPINSIGHTS_INSTRUMENTATIONKEY"];
        if (!string.IsNullOrEmpty(appInsightsKey))
        {
            // This uses the options callback to explicitly set the instrumentation key.
            b.AddApplicationInsights(o => o.InstrumentationKey = appInsightsKey);
        }
    });
    builder.ConfigureServices(services =>
        {
            services.AddSingleton<ITelemetryInitializer, CustomTelemetryInitializer>();
        });
    var host = builder.Build();
    using (host)
    {
        await host.RunAsync();
    }
}

Po utworzeniu TelemetryConfiguration obiektu zostaną uwzględnione wszystkie zarejestrowane typy ITelemetryInitializer . Aby dowiedzieć się więcej, zobacz Interfejs API usługi Application Insights dla niestandardowych zdarzeń i metryk.

W wersji 3.x, nie trzeba już opróżniać TelemetryClient , gdy host zatrzymuje. System iniekcji zależności platformy .NET Core automatycznie usuwa zarejestrowany ApplicationInsightsLoggerProviderelement , który opróżnia TelemetryClientelement .

Wersja 2.x

W wersji 2.x, TelemetryClient utworzony wewnętrznie przez dostawcę usługi Application Insights dla zestawu SDK zadań WebJobs używa polecenia ServerTelemetryChannel. Gdy punkt końcowy usługi Application Insights jest niedostępny lub ogranicza żądania przychodzące, ten kanał zapisuje żądania w systemie plików aplikacji internetowej i przesyła je ponownie później.

Element TelemetryClient jest tworzony przez klasę, która implementuje ITelemetryClientFactoryelement . Domyślnie jest to .DefaultTelemetryClientFactory

Jeśli chcesz zmodyfikować dowolną część potoku usługi Application Insights, możesz podać własny ITelemetryClientFactoryelement , a host użyje klasy do utworzenia TelemetryClientklasy . Na przykład ten kod zastępuje modyfikowanie DefaultTelemetryClientFactory właściwości ServerTelemetryChannel:

private class CustomTelemetryClientFactory : DefaultTelemetryClientFactory
{
    public CustomTelemetryClientFactory(string instrumentationKey, Func<string, LogLevel, bool> filter)
        : base(instrumentationKey, new SamplingPercentageEstimatorSettings(), filter)
    {
    }

    protected override ITelemetryChannel CreateTelemetryChannel()
    {
        ServerTelemetryChannel channel = new ServerTelemetryChannel();

        // Change the default from 30 seconds to 15 seconds.
        channel.MaxTelemetryBufferDelay = TimeSpan.FromSeconds(15);

        return channel;
    }
}

Obiekt SamplingPercentageEstimatorSettings konfiguruje próbkowanie adaptacyjne. Oznacza to, że w niektórych scenariuszach o dużej ilości usługa Applications Insights wysyła wybrany podzestaw danych telemetrycznych do serwera.

Po utworzeniu fabryki telemetrii należy przekazać ją do dostawcy rejestrowania usługi Application Insights:

var clientFactory = new CustomTelemetryClientFactory(instrumentationKey, filter.Filter);

config.LoggerFactory = new LoggerFactory()
    .AddApplicationInsights(clientFactory);

Następne kroki

Ten artykuł zawiera fragmenty kodu, które pokazują, jak obsługiwać typowe scenariusze pracy z zestawem SDK usługi WebJobs. Aby uzyskać pełne przykłady, zobacz azure-webjobs-sdk-samples.

Udostępnij za pośrednictwem

How to use the Azure WebJobs SDK for event-driven background processing (Jak używać zestawu SDK usługi Azure WebJobs w celu opartego na zdarzeniach przetwarzania w tle)

Wersje zestawu SDK usługi WebJobs

Host zadań WebJob

Połączenia hosta

Połączenia oparte na tożsamościach

Parametry połączenia w wersji 2.x

Ustawienia programowania hosta

Wersja 3.x

Wersja 2.x

Zarządzanie połączeniami współbieżnych (wersja 2.x)

Wyzwalacze

Wyzwalacze automatyczne

Wyzwalacze ręczne

Wersja 3.x

Wersja 2.x

Powiązania wejściowe i wyjściowe

Typy powiązań

Wersja 3.x

Wersja 2.x

ExecutionContext

Wersja 3.x

Wersja 2.x

Konfiguracja powiązania

Konfiguracja wyzwalacza usługi Azure Cosmos DB (wersja 3.x)

Konfiguracja wyzwalacza usługi Event Hubs (wersja 3.x)

Konfiguracja wyzwalacza usługi Queue Storage

Wersja 3.x

Wersja 2.x

Konfiguracja powiązania usługi SendGrid (wersja 3.x)

Konfiguracja wyzwalacza usługi Service Bus (wersja 3.x)

Konfiguracja innych powiązań

Wersja 3.x

Wersja 2.x

Wyrażenia powiązania

Niestandardowe wyrażenia powiązań

Wersja 3.x

Wersja 2.x

Wiązanie w czasie wykonywania

Informacje referencyjne dotyczące powiązań

Atrybuty wyłączenia, przekroczenia limitu czasu i pojedynczego

Wyłącz atrybut

Atrybut limitu czasu

Atrybut singleton

SingletonMode.Listener

Wartości zakresu

SingletonScope.Host

Wyświetlanie obiektów blob dzierżawy

Funkcje asynchroniczne

Tokeny anulowania

Wiele wystąpień

Filtry

Rejestrowanie i monitorowanie

Filtrowanie dzienników

Wersja 3.x

Wersja 2.x

Niestandardowe dane telemetryczne dla usługi Application Insights

Wersja 3.x

Wersja 2.x

Następne kroki

Opinia

Dodatkowe zasoby