Udostępnij za pośrednictwem

Korzystanie z zestawu SDK usługi Azure WebJobs na potrzeby przetwarzania w tle opartego na zdarzeniach

W tym artykule opisano sposób pracy z zestawem SDK usługi Azure WebJobs. Aby szybko rozpocząć pracę z zadaniami WebJobs, zobacz Wprowadzenie do pakietu SDK usługi Azure WebJobs.

Wersje zestawu SDK usługi WebJobs

Najważniejsze różnice między wersją 3.x a wersją 2.x zestawu SDK WebJobs to:

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

Niektóre przykłady w tym artykule są dostępne zarówno dla WebJobs w wersji 3.x, jak i 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 WebJobs SDK w wersji 3.x.
  • Azure Functions w wersji 1.x jest oparte na Zestawie SDK WebJobs w wersji 2.x.

Repozytoria kodu źródłowego zarówno dla usługi Azure Functions, jak i zestawu SDK usługi WebJobs używają numeracji zestawu SDK usługi WebJobs. Kilka sekcji tego artykułu 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ń WebJobs

Host WebJobs 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 . W swoim kodzie tworzysz wystąpienie hosta i piszesz kod, aby dostosować jego zachowanie.

Ta zmiana architektury jest kluczową różnicą 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. Nie można dostosować hosta poprzez pisanie kodu. W usłudze Azure Functions można dostosować zachowanie hosta za pomocą ustawień w host.json pliku. 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 z usługami Azure Storage i Azure Service Bus w pliku local.settings.json podczas uruchamiania lokalnie lub w środowisku zadania WebJob, gdy uruchamiane są na platformie Azure. Domyślnie zestaw SDK WebJobs wymaga połączenia z magazynem o nazwie AzureWebJobsStorage.

Gdy nazwa połączenia rozwiązuje się do pojedynczej dokładnej wartości, środowisko uruchomieniowe identyfikuje tę wartość jako ciąg połączenia, który zazwyczaj zawiera tajny klucz. Szczegóły łańcucha połączenia zależą od usługi, z którą się łączysz. Jednak nazwa połączenia może również odwoływać się do kolekcji wielu elementów konfiguracji. Ta metoda jest przydatna do konfigurowania połączeń opartych na tożsamościach. Zmienne środowiskowe można traktować jako kolekcję przy użyciu udostępnionego prefiksu kończącego się podwójnymi podkreśleniami (__). Następnie możesz odwołać się do grupy, ustawiając nazwę połączenia na ten prefiks.

Na przykład connection właściwość definicji wyzwalacza usługi Azure Blob Storage może mieć wartość Storage1. Jeśli nie ma skonfigurowanej pojedynczej wartości typu string poprzez zmienną środowiskową o nazwie Storage1, można użyć zmiennej środowiskowej o nazwie Storage1__blobServiceUri, aby poinformować właściwość blobServiceUri 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ści

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.

W poniższym przykładzie pokazano, jak może wyglądać plik 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.42" />
    <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 WebJobs w wystąpieniu HostBuilder upewnij się, że dołączysz wywołanie funkcji AddAzureStorageCoreServices. To wywołanie umożliwia używanie tożsamości przez AzureWebJobsStorage oraz inne wyzwalacze i powiązania usługi Storage.

Oto przykład:

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

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

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

Jeśli podasz konfigurację w dowolny sposób inny niż zmienne środowiskowe, na przykład w appsettings.json pliku konfiguracji, musisz 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"
    }
}

Możesz pominąć właściwość queueServiceUri, jeśli nie planujesz używać wyzwalaczy blob.

Gdy kod jest uruchamiany lokalnie, wartością domyślną jest użycie tożsamości dewelopera zgodnie z opisem dla elementu DefaultAzureCredential.

Gdy kod jest hostowany w usłudze App Service, konfiguracja w poprzednim przykładzie jest domyślnie ustawiona na tożsamość zarządzaną przypisaną przez system dla zasobu. Aby zamiast tego użyć tożsamości przypisanej przez użytkownika przypisanej do aplikacji, musisz dodać właściwości połączenia, aby określić, 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 dla przypisanej przez użytkownika tożsamości zarządzanej, którą chcesz używać.

Jako konfiguracja ustrukturyzowana kompletny obiekt będzie podobny do tego przykładu:

{
    "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 powinna mieć przypisane role, które przyznają jej uprawnienia Właściciela danych obiektów Blob w usłudze Storage, Kontrybutora danych kolejek magazynu oraz Kontrybutora danych konta magazynu. Jeśli nie planujesz używania wyzwalaczy obiektów blob, możesz pominąć role Współtwórca danych kolejki magazynu i Współtwórca konta magazynu.

W poniższej tabeli przedstawiono wbudowane role, które zalecamy stosować podczas korzystania z wyzwalaczy w powiązaniach w normalnej pracy. Aplikacja może wymagać większej liczby uprawnień w zależności od pisanego kodu.

Wiązanie Przykładowe role wbudowane
Wyzwalacz dla obiektu BLOB Właściciel danych obiektu blobiwspółautor danych kolejki
Zapoznaj się również z wcześniejszymi wymaganiami dotyczącymi AzureWebJobsStorage.
Blob (dane wejściowe) Czytelnik danych obiektu blob Storage
Blob (dane wyjściowe) Właściciel danych obiektu blob Storage
Mechanizm wyzwalający kolejki Czytelnik danych kolejki magazynującej, Procesor komunikatów danych kolejki magazynującej
Kolejka (wyjście) Użytkownik z dostępem do danych kolejki magazynu, Nadawca wiadomości danych z kolejki magazynu
Wyzwalacz Service Bus1 Odbiornik danych usługi Azure Service Bus, właściciel danych usługi Azure Service Bus
Service Bus (wyjście) Nadawca danych usługi Azure Service Bus

1 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 uwzględniony jest 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 tych scenariuszach możesz zamiast tego użyć interfejsu wiersza polecenia platformy Azure. Aby uzyskać więcej informacji, zobacz Role wbudowane 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 parametrów połączenia. W wersji 2. x, możesz użyć własnych nazw dla tych parametrów połączenia i można je przechowywać gdzie indziej. Nazwy w kodzie można ustawić przy użyciu metody JobHostConfiguration, na przykład w tym przykładzie:

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 istnieje interfejs API, aby zmienić nazwy łańcuchów połączeń. Aby uzyskać więcej informacji, 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:

Nieruchomość / Własność Ustawienie programowania
Tracing.ConsoleLevel TraceLevel.Verbose aby zmaksymalizować dane wyjściowe dziennika.
Queues.MaxPollingInterval Niska wartość, aby zapewnić 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

W wersji 3. X używasz standardowych interfejsów API ASP.NET Core, aby zmienić środowisko hosta. 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 sprawić, by config.IsDevelopment zwracał true po uruchomieniu lokalnie, ustaw lokalną zmienną środowiskową o nazwie AzureWebJobsEnv o 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łączeń jest domyślnie ustawiony na nieskończoność. 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 ServicePointManager.DefaultConnectionLimit właściwości . W 2.x, przed uruchomieniem hosta WebJobs, należy zwiększyć tę wartość od wartości domyślnej 2.

Wszystkie wychodzące żądania HTTP, które wysyłasz z funkcji przy użyciu HttpClient, przechodzą przez ServicePointManager. Po osiągnięciu wartości ustawionej w DefaultConnectionLimit, ServicePointManager rozpoczyna kolejkowanie żądań przed ich wysłaniem. Załóżmy, że twój DefaultConnectionLimit jest ustawiony na 2, a twój kod wysyła 1000 żądań HTTP. Początkowo do systemu operacyjnego dozwolone są tylko 2 żądania. Pozostałe 998 żądań są kolejkowane, dopóki nie będzie miejsca dla nich. Jest możliwe, że HttpClient doświadczy wyłączenia z powodu limitu czasu, ponieważ wygląda na to, że żądanie zostało wykonane, ale nigdy nie zostało przesłane przez system operacyjny do serwera docelowego. Możesz zauważyć zachowanie, które wydaje się bez sensu: Twoje lokalne HttpClient potrzebuje 10 sekund, aby zakończyć żądanie, ale Twoja 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ń WebJobs działających w planie App Service w warstwie podstawowej lub wyższej. Zadania WebJob zwykle wymagają ustawienia Zawsze włączone i są obsługiwane tylko w przypadku planów usługi App Service w warstwie Podstawowa i wyższa.

Jeśli twój WebJob jest uruchomiony w darmowym lub współdzielonym planie App Service, aplikacja jest ograniczona przez piaskownicę usługi App Service, która obecnie posiada limit połączeń wynoszący 600. Jeśli w systemie ServicePointManageristnieje limit połączeń niezwiązanych, jest bardziej prawdopodobne, że próg połączenia piaskownicy zostanie osiągnięty, a lokacja zostanie zamknięta. W takim przypadku ustawienie DefaultConnectionLimit wartości niższej, takiej jak 200, może uniemożliwić występowanie tego scenariusza i nadal zezwalać na wystarczającą przepływność.

Ustawienie należy skonfigurować przed wykonaniem żądań HTTP. Z tego powodu host WebJobs 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 ustawienie wartości natychmiast w metodzie Main przed zainicjowaniem metody JobHost, jak pokazano w poniższym przykładzie:

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ązanie używane przez usługę Azure Functions . W SDK WebJobs wyzwalacze są specyficzne dla funkcji i nie są powiązane z rodzajem wdrożenia WebJob. Zadania WebJob, które mają funkcje wyzwalane przez zdarzenia utworzone przy użyciu zestawu SDK, powinny być zawsze publikowane jako ciągłe zadanie WebJob z włączoną funkcją Always on .

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 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 pojawi się komunikat kolejki w myqueue-items. Atrybut Blob informuje środowisko uruchomieniowe, aby użyć komunikatu kolejki do odczytania bloba w kontenerze sample-workitems. Nazwa elementu blob w kontenerze samples-workitems jest uzyskiwana bezpośrednio z wyzwalacza kolejki jako wyrażenie wiążące ({queueTrigger}).

Uwaga

Aplikacja internetowa może upłynąć limit czasu po 20 minutach braku aktywności, a tylko żądania do samej aplikacji internetowej mogą zresetować licznik czasu. Wyświetlanie konfiguracji aplikacji w witrynie Azure Portal lub wykonywanie żądań do witryny zaawansowanych narzędzi nie powoduje zresetowania czasomierza. Jeśli skonfigurujesz aplikację internetową, która hostuje twoje zadanie, aby działała w trybie ciągłym, zgodnie z harmonogramem lub używając wyzwalaczy sterowanych zdarzeniami, włącz ustawienie Zawsze włączone w okienku Konfiguracja platformy Azure dla swojej 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 :

[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 przez metodę jako powiązanie wyjściowe, stosując atrybut do tej wartości. Zobacz przykład w sekcji Używanie wartości zwracanej przez funkcję 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 części "Pakiety" artykułu referencyjnego Azure Functions dla tego typu powiązania. Wyjątkiem jest wyzwalacz i powiązanie plików (dla lokalnego systemu plików), których Azure Functions nie obsługuje.

Wersja 3.x

W wersji 3.x wiązania magazynowe są zawarte w pakiecie Microsoft.Azure.WebJobs.Extensions.Storage. Wywołaj metodę rozszerzenia AddAzureStorage w metodzie ConfigureWebJobs.

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 Microsoft.Azure.WebJobs.Extensions.CosmosDB i wywołaj polecenie AddCosmosDB:

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 Timer lub powiązania Pliki, które są częścią podstawowej usługi, wywołaj metody AddTimers lub rozszerzenia AddFiles.

Wersja 2.x

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

  • Przechowywanie blobów
  • Przechowywanie kolejki
  • Magazyn Tabel

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 w metodzie Main.

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

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

Kontekst wykonania

W zadaniach WebJobs można powiązać z wystąpieniem ExecutionContext. Dzięki wiązaniu możesz uzyskać dostęp do 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 łączenia z ExecutionContext zależy od wersji zestawu SDK.

Wersja 3.x

Wywołaj metodę rozszerzenia AddExecutionContextBinding w metodzie ConfigureWebJobs.

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 . Możesz użyć powiązania, aby zdefiniować parametr ExecutionContext w podpisie funkcji.

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ę podczas wywoływania metody Add<Binding> w ConfigureWebJobs.
  • Wersja 2.x: Ustaw konfigurację, ustawiając właściwości w obiekcie konfiguracji przekazywanym do elementu JobHost.

Ustawienia specyficzne dla powiązań są równoważne z ustawieniami w host.json w Azure Functions.

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

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 sekcję Wiązania Azure Cosmos DB.

Konfiguracja wyzwalacza usługi Azure 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 Powiązanie 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 Wiązanie magazynu kolejek.

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ę dotyczącąhost.json wersji 1.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 SendGrid wiązanie.

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 Powiązanie z usługą Service Bus.

Konfiguracja innych powiązań

Niektóre typy wyzwalaczy i powiązań definiują własne niestandardowe typy konfiguracji. Możesz na przykład użyć wyzwalacza pliku, aby określić ścieżkę główną 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 wią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. Podczas używania do powiązania wyjściowego, filename ustala nazwę 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, kontener czy nazwę tabeli w kodzie, zamiast twardo kodować. Na przykład możesz określić nazwę kolejki dla atrybutu QueueTrigger w pliku konfiguracji lub zmiennej środowiskowej.

Nazwę kolejki można przyznać atrybutowi, przekazując niestandardowy rozwiązywacz nazw podczas konfiguracji. W parametrach konstruktora atrybutu wyzwalacza lub powiązania używasz symboli zastępczych, a twój kod rozwiązujący dostarcza rzeczywistych wartości, które mają zastąpić te symbole zastępcze. Możesz zidentyfikować symbole zastępcze, otaczając je znakami procentu (%):

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

W tym kodzie użyjesz kolejki o nazwie logqueuetest w środowisku testowym i kolejki o nazwie logqueueprod w środowisku produkcyjnym. Zamiast zakodowanej nazwy kolejki należy określić nazwę wpisu w kolekcji appSettings .

Domyślny program rozpoznawania ma zastosowanie, jeśli nie podasz niestandardowego. Wartość domyślna pobiera wartości z ustawień aplikacji lub zmiennych środowiskowych.

Począwszy od .NET Core 3.1, instancja ConfigurationManager, której używasz, wymaga pakietu NuGet System.Configuration.ConfigurationManager. Przykład wymaga następującej using instrukcji:

using System.Configuration;

Klasa NameResolver pobiera nazwę kolejki z ustawień aplikacji:

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

Wersja 3.x

Konfigurujesz resolver przy użyciu wstrzykiwania zależności. Te przykłady wymagają następującej using instrukcji:

using Microsoft.Extensions.DependencyInjection;

Dodajesz resolver, wywołując metodę rozszerzenia ConfigureServices na 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 do obiektu JobHost:

 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 i służy do uzyskiwania wartości z ustawień aplikacji, jak pokazano w przykładzie. Korzystając bezpośrednio z SDK WebJobs, możesz napisać niestandardową implementację, która pobiera 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, który ma tę samą zawartość 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, zapoznaj się z Wiązanie w czasie wykonywania w dokumentacji usługi Azure Functions.

Informacje referencyjne dotyczące wiązań

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

  • Pakiety. Pakiet, który należy zainstalować, aby zapewnić obsługę powiązań w projekcie SDK 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órymi można się powiązać, oraz informacje o sposobie działania powiązania. Na przykład algorytm sondowania lub przetwarzanie kolejki trucizny.

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łącz, Timeout i Singleton

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

Użyj atrybutu Disable , aby określić, czy można wyzwolić funkcję.

W poniższym przykładzie, jeśli ustawienie Disable_TestJob aplikacji ma wartość 1 lub True (bez rozróżniania wielkości liter), funkcja nie zostaje uruchomiona. W tym scenariuszu ś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 Timeout . Limit czasu powoduje anulowanie funkcji po 15 sekundach. Gdy parametr atrybutu TimeoutthrowOnError jest ustawiony na true, wywołanie funkcji jest przerywane przez wyjątek zgłaszany przez WebJobs SDK po przekroczeniu limitu czasu. Wartość domyślna throwOnError to false. Timeout Gdy atrybut jest używany, domyślne zachowanie polega na anulowaniu wywołania funkcji przez ustawienie tokenu anulowania przy jednoczesnym umożliwieniu uruchamiania wywołania w nieskończoność, 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 można zastosować Timeout na poziomie klasy lub na poziomie 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 tylko 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 jedna instancja funkcji jest uruchomiona, gdy aplikacja internetowa skaluje się do wielu wystąpień, zastosuj blokadę typu singleton na poziomie odbiornika w funkcji ([Singleton(Mode = SingletonMode.Listener)]). Blokady nasłuchiwacza są uzyskiwane, gdy JobHost się uruchamia. Jeśli trzy wystąpienia skalowane w poziomie są uruchamiane w tym samym czasie, tylko jedno z wystąpień uzyskuje blokadę i tylko jeden odbiornik się uruchamia.

Uwaga

Aby dowiedzieć się więcej o SingletonMode.Function sposobie działania, zobacz repozytorium GitHub SingletonMode.

Wartości zakresu

Możesz określić wyrażenie/wartość zakresu w singletonie. Wyrażenie/wartość gwarantuje, że wszystkie wykonania funkcji w określonym zakresie są serializowane. Zaimplementowanie bardziej szczegółowego blokowania w ten sposób może pozwolić na pewien poziom równoległości dla twojej funkcji, podczas gdy inne wywołania są szeregowane 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 wiadomości w regionach Wschód, Wschód i Zachód, wiadomości, które mają region Wschód, są uruchamiane szeregowo. Komunikat z regionu Zachód działa równolegle z komunikatami z regionu 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ślnym zakresem blokady jest SingletonScope.Function. Zakres blokady (ścieżka dzierżawy blobu) jest powiązany z w pełni określoną 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 jedna instancja AddItem lub RemoveItem działa 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 blobów związanych z dzierżawą

SDK WebJobs używa dzierżaw blobów Azure do implementowania rozproszonych blokad. Obiekty blob dzierżawy używane przez Singleton można znaleźć w kontenerze azure-webjobs-host na koncie magazynu AzureWebJobsStorage w ścieżce "blokady". Na przykład ścieżka do obiektu blob dzierżawy dla pierwszego przykładu ProcessImage 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 uruchamia się na każdym wystąpieniu, nasłuchuje wyzwalaczy i wywołuje funkcje. Różne powiązania wyzwalaczy zostały zaprojektowane tak, aby wspólnie udostępniać pracę między wystąpieniami, dzięki czemu skalowanie na większą liczbę wystąpień umożliwia przejęcie większego obciążenia.

Chociaż niektóre wyzwalacze mogą prowadzić do podwójnego przetwarzania, wyzwalacze kolejki i przechowywania obiektów BLOB automatycznie zapobiegają przetwarzaniu wiadomości z 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 timera automatycznie zapewnia, że tylko jedno wystąpienie timera jest uruchamiane, dzięki czemu nie uruchomi się więcej niż jedno wystąpienie funkcji w danym zaplanowanym czasie.

Jeśli chcesz mieć pewność, że jest uruchamiane tylko jedno wystąpienie funkcji, nawet jeśli 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. Te 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 użycie struktury rejestrowania, która została opracowana na potrzeby ASP.NET. W artykule Wprowadzenie pokazano, jak z niego korzystać.

Filtrowanie dzienników

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

Poziom Logowania Kod
Śledzenie 0
Debugowanie 1
Informacja 2
Ostrzeżenie 3
Błąd 4
Krytyczny 5
Brak 6

Można niezależnie filtrować każdą kategorię do określonej LogLevel wartości. Na przykład możesz chcieć zobaczyć wszystkie logi przetwarzania wyzwalacza dla obiektów blob, ale tylko Error i wyższe dla wszystkiego innego.

Wersja 3.x

Wersja 3. X zestawu SDK opiera się na filtrowaniu wbudowanym w platformę .NET Core. LogCategories Użyj klasy , aby zdefiniować kategorie dla określonych funkcji, wyzwalaczy lub użytkowników. Klasa LogCategories definiuje również filtry dla określonych stanów hosta, takich jak Startup i Results, dzięki czemu można dostosować dane wyjściowe rejestrowania. Jeśli nie znaleziono dopasowania w zdefiniowanych kategoriach, filtr wraca do Default wartości podczas określania, czy filtrować komunikat.

LogCategories wymaga następującej using instrukcji:

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 instancji LogCategories i wybiera najdłuższe dopasowanie. Dlatego poziom zarejestrowany dla Debug odpowiada Host.Triggers lub Host.Triggers.Queue. Możesz 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

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

LogCategories Podobnie jak w wersji 3.x, właściwość CategoryLevels umożliwia określenie poziomów logów dla określonych kategorii, aby można było dostosować dane wyjściowe rejestrowania. Jeśli w słowniku CategoryLevels nie znaleziono dopasowania, filtr wraca do Default wartości podczas określania, 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 CategoryLevels i wybiera najdłuższe dopasowanie. Dlatego poziom zarejestrowany dla Debug odpowiada Host.Triggers lub Host.Triggers.Queue. Możesz 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 bazuje na ogólnym hoście platformy .NET Core, niestandardowy moduł telemetrii nie jest już dostępny. Można jednak dodać niestandardowe dane telemetryczne do potoku za pomocą wstrzykiwania zależności. Przykłady w tej sekcji wymagają następujących using deklaracji:

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

Możesz użyć następującej niestandardowej implementacji ITelemetryInitializer, aby dodać własne ITelemetry wystąpienie do domyślnego TelemetryConfiguration elementu.

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

Wywołaj metodę ConfigureServices w konstruktorze, aby dodać wystąpienie niestandardowe ITelemetryInitializer 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 code 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();
    }
}

Kiedy TelemetryConfiguration jest tworzony, wszystkie zarejestrowane typy ITelemetryInitializer są uwzględniane. Aby uzyskać więcej informacji, zobacz interfejs API usługi Application Insights dla zdarzeń i metryk niestandardowych.

W wersji 3.x, nie trzeba opróżniać TelemetryClient, gdy host zostanie zatrzymany. System iniekcji zależności platformy .NET Core automatycznie usuwa zarejestrowane wystąpienie ApplicationInsightsLoggerProvider, które opróżnia element TelemetryClient.

Wersja 2.x

W wersji 2.x wystąpienie TelemetryClient, utworzone wewnętrznie przez dostawcę Application Insights dla SDK WebJobs, używa elementu 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.

TelemetryClient jest tworzony przez klasę implementującą ITelemetryClientFactory. Domyślnie ta klasa to DefaultTelemetryClientFactory.

Jeśli chcesz zmodyfikować dowolną część potoku usługi Application Insights, możesz podać własne wystąpienie usługi ITelemetryClientFactory. Następnie host używa twojej klasy do skonstruowania TelemetryClient. Na przykład ten kod nadpisuje DefaultTelemetryClientFactory, aby zmodyfikować właściwość 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. W tym scenariuszu 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);

Powiązana zawartość

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.