Freigeben über

Verwenden des Azure WebJobs SDK für ereignisgesteuerte Hintergrundverarbeitung

In diesem Artikel wird beschrieben, wie Sie mit dem Azure WebJobs SDK arbeiten. Informationen zu den ersten Schritten mit WebJobs finden Sie unter "Erste Schritte mit dem Azure WebJobs SDK".

WebJobs SDK-Versionen

Die wichtigsten Unterschiede zwischen Version 3. x und Version 2. x des WebJobs SDK sind:

  • Version 3. x fügt Unterstützung für .NET Core hinzu.
  • In Version 3. x installieren Sie die Speicherbindungserweiterung, die vom WebJobs SDK benötigt wird. In Version 2.x sind die Speicherbindungen im Paket enthalten.
  • Visual Studio 2019-Tools für .NET Core (3.x)-Projekte unterscheiden sich von Tools für .NET Framework (2.x)-Projekte. Weitere Informationen finden Sie unter Entwickeln und Bereitstellen von WebJobs mit Visual Studio.

Einige Beispiele in diesem Artikel werden für beide WebJobs Version 3 bereitgestellt. x und WebJobs, Version 2. x.

Azure Functions basiert auf dem WebJobs SDK:

  • Azure Functions Version 2.x basiert auf WebJobs SDK Version 3.x.
  • Azure Functions Version 1.x basiert auf WebJobs SDK Version 2.x.

Quellcoderepositorys für Azure Functions und das WebJobs SDK verwenden die WebJobs SDK-Nummerierung. Mehrere Abschnitte dieses Artikels verweisen auf die Dokumentation zu Azure Functions.

Weitere Informationen finden Sie unter Compare the WebJobs SDK and Azure Functions.

WebJobs-Host

Der WebJobs-Host ist ein Laufzeitcontainer für Funktionen. Der Host lauscht auf Trigger und ruft Funktionen auf. In Version 3. x ist der Host eine Implementierung von IHost. In Version 2.x verwenden Sie das JobHost-Objekt. Sie erstellen eine Hostinstanz in Ihrem Code und schreiben Code zum Anpassen des entsprechenden Verhaltens.

Diese Architekturänderung ist ein wichtiger Unterschied zwischen der direkten Verwendung des WebJobs SDK und der indirekten Verwendung über Azure Functions. In Azure Functions steuert der Dienst den Host. Sie können den Host nicht anpassen, indem Sie Code schreiben. In Azure Functions passen Sie das Hostverhalten über Einstellungen in der host.json Datei an. Bei diesen Einstellungen handelt es sich um Zeichenfolgen, nicht um Code, und die Verwendung dieser Zeichenfolgen schränkt die Arten von Anpassungen ein, die Sie vornehmen können.

Hostverbindungen

Das WebJobs SDK sucht sowohl bei lokaler Ausführung als auch in der Umgebung des WebJobs in Azure nach Azure Storage- und Azure Service Bus-Verbindungen in der local.settings.json Datei. Standardmäßig erfordert das WebJobs SDK eine Speicherverbindung mit dem Namen AzureWebJobsStorage.

Wenn der Verbindungsname in einen einzelnen exakten Wert aufgelöst wird, identifiziert die Laufzeit den Wert als Verbindungszeichenfolge, die normalerweise einen geheimen Schlüssel enthält. Die Details einer Verbindungszeichenfolge werden durch den Dienst definiert, mit dem Sie eine Verbindung herstellen möchten. Ein Verbindungsname kann jedoch auch auf eine Sammlung mehrerer Konfigurationselemente verweisen. Diese Methode ist nützlich zum Konfigurieren von identitätsbasierten Verbindungen. Sie können Umgebungsvariablen als Sammlung behandeln, indem Sie ein freigegebenes Präfix verwenden, das mit doppelten Unterstrichen (__) endet. Anschließend können Sie auf die Gruppe verweisen, indem Sie den Verbindungsnamen auf dieses Präfix festlegen.

Beispielsweise kann die connection-Eigenschaft für eine Azure Blob Storage-Triggerdefinition Storage1 lauten. Solange kein einzelner Zeichenfolgenwert von einer Umgebungsvariablen namens Storage1 konfiguriert wurde, kann die Storage1__blobServiceUri-Eigenschaft durch eine Umgebungsvariable namens blobServiceUri über die Verbindung informiert werden. Die Verbindungseigenschaften unterscheiden sich für jeden Dienst. In der Dokumentation finden Sie Informationen zu der Komponente, die die Verbindung verwendet.

Identitätsbasierte Verbindungen

Um identitätsbasierte Verbindungen im WebJobs SDK zu verwenden, stellen Sie sicher, dass Sie die neuesten Versionen von WebJobs-Paketen in Ihrem Projekt verwenden. Stellen Sie außerdem sicher, dass Sie über einen Verweis auf Microsoft.Azure.WebJobs.Host.Storage verfügen.

Das folgende Beispiel zeigt, wie Ihre Projektdatei aussehen könnte, nachdem Sie diese Aktualisierungen vorgenommen haben:

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

Stellen Sie sicher, dass Sie beim Einrichten von WebJobs in Ihrer HostBuilder-Instanz einen Aufruf zu AddAzureStorageCoreServices einschließen. Dieser Aufruf ermöglicht AzureWebJobsStorage und den anderen Speicherauslösern und Bindungen, die Identität zu verwenden.

Ein Beispiel:

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

Anschließend können Sie die AzureWebJobsStorage Verbindung konfigurieren, indem Sie Umgebungsvariablen festlegen (oder Anwendungseinstellungen, wenn Ihr Code in Azure App Service gehostet wird):

Umgebungsvariable Beschreibung Beispielwert
AzureWebJobsStorage__blobServiceUri Der Datenebenen-URI des Blob-Dienstes des Speicherkontos. Es verwendet das HTTPS-Schema. <https:// storage_account_name.blob.core.windows.net>
AzureWebJobsStorage__queueServiceUri Der Datenebenen-URI des Warteschlangendiensts des Speicherkontos Es verwendet das HTTPS-Schema. https://<Speicherkontoname>.queue.core.windows.net

Wenn Sie Ihre Konfiguration auf andere Weise als Umgebungsvariablen bereitstellen, z. B. in einer appsettings.json Konfigurationsdatei, müssen Sie stattdessen eine strukturierte Konfiguration für die Verbindung und deren Eigenschaften bereitstellen:

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

Sie können die queueServiceUri Eigenschaft weglassen, wenn Sie keine Blobtrigger verwenden möchten.

Wenn Ihr Code lokal ausgeführt wird, besteht die Standardeinstellung darin, die Entwickleridentität, wie beschrieben, zu verwenden für DefaultAzureCredential.

Wenn Ihr Code in App Service gehostet wird, wird die Konfiguration im vorherigen Beispiel standardmäßig auf die vom System zugewiesene verwaltete Identität für die Ressource festgelegt. Um stattdessen eine benutzerdefinierte Identität zu verwenden, die der App zugewiesen ist, müssen Sie Eigenschaften für Ihre Verbindung hinzufügen, um anzugeben, welche Identität verwendet werden soll. Die credential Eigenschaft (AzureWebJobsStorage__credential als Umgebungsvariable) sollte auf die Zeichenfolge managedidentityfestgelegt werden. Die clientId-Eigenschaft (AzureWebJobsStorage__clientId als Umgebungsvariable) sollte auf die Client-ID der benutzerseitig zugewiesenen verwalteten Identität festgelegt werden.

Als strukturierte Konfiguration würde das vollständige Objekt diesem Beispiel ähneln:

{
    "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>"
    }
}

Die Identität, die für AzureWebJobsStorage verwendet wird, sollte über Rollenzuweisungen verfügen, die ihr die Rollen "Storage Blob Data Owner", "Storage Queue Data Contributor" und "Storage Account Contributor" gewähren. Sie können die Rollen Mitwirkender von Speicherwarteschlangendaten undMitwirkender des Speicherkontos weglassen, wenn Sie keine Blobtrigger verwenden möchten.

In der folgenden Tabelle sind integrierte Rollen aufgeführt, die empfohlen werden, wenn Sie Trigger in Bindungen im normalen Betrieb verwenden. Ihre Anwendung erfordert je nach geschriebenen Code möglicherweise mehr Berechtigungen.

Verbindlich Integrierte Beispielrollen
Blobtrigger Besitzer von SpeicherblobdatenundMitwirkender an Speicherblobdaten
Siehe auch die vorstehenden Anforderungen für AzureWebJobsStorage.
Blob (Eingabe) Leser von Speicherblobdaten
Blob (Ausgabe) Besitzer von Speicherblobdaten
Warteschlangentrigger Storage-Warteschlangendatenleser, Verarbeiter von Speicherwarteschlangen-Datennachrichten
Warteschlange (Ausgabe) Mitwirkender an Storage-Warteschlangendaten, Absender der Speicherwarteschlangen-Datennachricht
Service Bus-Trigger1 Azure Service Bus-Datenempfänger, Azure Service Bus-Datenbesitzer
Service Bus (Ausgabe) Azure Service Bus-Datensender

1 Für die Auslösung aus Service Bus-Themen muss die Rollenzuweisung einen effektiven Bereich über die Service Bus-Abonnementressource haben. Wenn nur das Thema enthalten ist, tritt ein Fehler auf. Einige Clients (z. B. das Azure-Portal) stellen die Service Bus-Abonnementressource nicht als Bereich für die Rollenzuweisung bereit. In diesen Szenarien können Sie stattdessen die Azure CLI verwenden. Weitere Informationen finden Sie unter den integrierten Azure-Rollen für Azure Service Bus.

Verbindungszeichenfolgen in Version 2. x

Version 2. x des SDK erfordert keinen bestimmten Namen für Verbindungszeichenfolgen. In Version 2. x, Sie können Ihre eigenen Namen für diese Verbindungszeichenfolgen verwenden und sie an anderer Stelle speichern. Sie können Namen im Code festlegen, indem Sie JobHostConfiguration verwenden, wie in diesem Beispiel:

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

Hinweis

Da Version 3. x verwendet die standardmäßigen .NET Core-Konfigurations-APIs, es ist keine API vorhanden, um Verbindungszeichenfolgennamen zu ändern. Weitere Informationen finden Sie unter Entwickeln und Bereitstellen von WebJobs mithilfe von Visual Studio.

Hostentwicklungseinstellungen

Sie können den Host im Entwicklungsmodus ausführen, um die lokale Entwicklung effizienter zu machen. Bei der Ausführung im Entwicklungsmodus ändern sich unter anderem folgende Einstellungen:

Eigenschaft Entwicklungseinstellung
Tracing.ConsoleLevel TraceLevel.Verbose zum Maximieren der Protokollausgabe.
Queues.MaxPollingInterval Ein niedriger Wert, um sicherzustellen, dass Warteschlangenmethoden sofort ausgelöst werden.
Singleton.ListenerLockPeriod 15 Sekunden, um bei der schnellen iterativen Entwicklung zu helfen.

Der Prozess zum Aktivieren des Entwicklungsmodus hängt von der SDK-Version ab.

Version 3. x

In Version 3. x, Sie verwenden die Standard-ASP.NET Core-APIs, um die Hostumgebung zu ändern. Rufen Sie die UseEnvironment-Methode für die HostBuilder-Instanz auf. Übergeben Sie eine Zeichenfolge namens development wie in diesem Beispiel:

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

Version 2. x

Die Klasse JobHostConfiguration verfügt zum Aktivieren des Entwicklungsmodus über die Methode UseDevelopmentSettings. Im folgenden Beispiel wird die Verwendung von Entwicklungseinstellungen aufgezeigt. Legen Sie eine lokale Umgebungsvariable namens config.IsDevelopment mit dem Wert true fest, damit AzureWebJobsEnv bei lokaler Ausführung den Wert Development zurückgibt.

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

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

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

Verwalten von gleichzeitigen Verbindungen (Version 2.x)

In Version 3.x ist die Verbindungsanzahl standardmäßig nicht beschränkt. Wenn Sie diese Einstellung ändern müssen, können Sie die Eigenschaft MaxConnectionsPerServer der Klasse WinHttpHandler verwenden.

In Version 2. x, Sie steuern die Anzahl der gleichzeitigen Verbindungen mit einem Host mithilfe der ServicePointManager.DefaultConnectionLimit Eigenschaft. In 2. x, Sie sollten diesen Wert von der Standardeinstellung 2 erhöhen, bevor Sie Ihren WebJobs-Host starten.

Alle ausgehenden HTTP-Anforderungen, die Sie über eine Funktion mit HttpClient ausführen, durchlaufen ServicePointManager. Nachdem Sie den in DefaultConnectionLimit festgelegten Wert erreicht haben, startet ServicePointManager das Queueing von Anforderungen, bevor er sie sendet. Angenommen, Ihr DefaultConnectionLimit ist auf 2 festgelegt und Ihr Code führt 1.000 HTTP-Anfragen aus. Zunächst sind nur 2 Anforderungen an das Betriebssystem zulässig. Die anderen 998 Anfragen werden in die Warteschlange gestellt, bis Platz für sie vorhanden ist. Ihr HttpClient könnte ein Timeout haben, weil es so aussieht, als ob die Anforderung erfolgt ist, jedoch vom Betriebssystem nie an den Zielserver gesendet wurde. Möglicherweise wird ein Verhalten angezeigt, das nicht sinnvoll erscheint: Ihr Lokales HttpClient dauert 10 Sekunden, um eine Anforderung abzuschließen, aber Ihr Dienst gibt jede Anforderung in 200 ms zurück.

Der Standardwert für ASP.NET Anwendungen ist Int32.MaxValue, und das funktioniert wahrscheinlich gut für WebJobs, die in einem Basic- oder höheren App Service-Plan ausgeführt werden. WebJobs benötigen in der Regel die AlwaysOn-Einstellung , und dies wird nur von Standard- und höheren App Service-Plänen unterstützt.

Wenn Ihr WebJob in einem Kostenlosen oder freigegebenen App-Dienstplan ausgeführt wird, wird Ihre Anwendung durch den App Service-Sandkasten eingeschränkt, der derzeit eine Verbindungsgrenze von 600 hat. Wenn Sie über ein unbeschränktes Verbindungslimit in ServicePointManager verfügen, ist es wahrscheinlicher, dass der Schwellenwert für die Sandkastenverbindung erreicht wird und die Seite heruntergefahren wird. In diesem Fall kann die Einstellung DefaultConnectionLimit auf einen niedrigeren Wert wie 200 das Auftreten dieses Szenarios verhindern und dennoch einen ausreichenden Durchsatz zulassen.

Die Einstellung muss vor dem Ausführen von HTTP-Anforderungen konfiguriert werden. Aus diesem Grund sollte der WebJobs-Host die Einstellung nicht automatisch anpassen. Es kann HTTP-Anforderungen geben, die vor dem Start des Hosts auftreten, was zu unerwartetem Verhalten führen kann. Der beste Ansatz besteht darin, den Wert sofort in Ihrer Main Methode festzulegen, bevor Sie initialisieren JobHost, wie in diesem Beispiel gezeigt:

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

Trigger

Das WebJobs SDK unterstützt denselben Satz von Triggern und Bindungen, die Azure Functions verwendet. Im WebJobs SDK sind Trigger funktionsspezifisch und nicht mit dem WebJob-Bereitstellungstyp verknüpft. WebJobs mit ereignisauslösten Funktionen, die mit dem SDK erstellt wurden, sollten immer als fortlaufendes WebJob veröffentlicht werden, wobei Always On aktiviert ist.

Funktionen müssen öffentliche Methoden sein, und sie müssen über ein Trigger-Attribut oder das NoAutomaticTrigger Attribut verfügen.

Automatische Trigger

Automatische Trigger rufen eine Funktion als Reaktion auf ein Ereignis auf. Betrachten Sie dieses Beispiel einer Funktion, die von einer Nachricht ausgelöst wird, die Azure Queue Storage hinzugefügt wurde. Die Funktion antwortet durch Lesen eines BLOB aus 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");
}

Das QueueTrigger-Attribut weist die Runtime an, die Funktion jedes Mal aufzurufen, wenn eine Warteschlangennachricht in myqueue-items erscheint. Das Attribut Blob weist die Laufzeit an, die Warteschlangennachricht zu verwenden, um einen Blob im sample-workitems Container zu lesen. Der Name des Blobelements im samples-workitems-Container wird als Bindungsausdruck ({queueTrigger}) direkt aus dem Warteschlangentrigger abgerufen.

Hinweis

Für eine Web-App kann nach 20 Minuten Inaktivität ein Timeout auftreten, und dieser Zeitgeber kann nur durch Anforderungen an die tatsächliche Web-App zurückgesetzt werden. Das Anzeigen der App-Konfiguration im Azure-Portal oder das Senden von Anforderungen an die Website für erweiterte Tools setzt den Timer nicht zurück. Wenn Sie die Web-App festlegen, die Ihren Auftrag für die kontinuierliche Ausführung hostet, sie nach einem Zeitplan ausführen oder ereignisgesteuerte Trigger verwenden, aktivieren Sie die Einstellung "Immer aktivieren" im Azure-Konfigurationsbereich Ihrer Web-App. Die Einstellung "Immer aktiviert " hilft sicherzustellen, dass diese Arten von WebJobs zuverlässig ausgeführt werden. Dieses Feature steht nur in den Tarifen „Basic“, „Standard“ und „Premium“ zur Verfügung.

Manuelle Trigger

Verwenden Sie das NoAutomaticTrigger Attribut, um eine Funktion manuell auszulösen:

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

Der Prozess zum manuellen Auslösen der Funktion hängt von der SDK-Version ab.

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

Version 2. x

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

Eingabe- und Ausgabebindungen

Eingabebindungen bieten eine deklarative Möglichkeit, Daten aus Azure oder Diensten von Drittanbietern für Ihren Code verfügbar zu machen. Ausgabebindungen bieten eine Möglichkeit, Daten zu aktualisieren. Im Artikel Erste Schritte finden Sie ein Beispiel für die einzelnen Bindungen.

Sie können einen Rückgabewert einer Methode für eine Ausgabebindung nutzen, indem Sie das Attribut auf den Rückgabewert einer Methode anwenden. Siehe dazu das Beispiel in Verwenden des Rückgabewerts einer Azure-Funktion.

Bindungstypen

Der Prozess zum Installieren und Verwalten von Bindungstypen hängt davon ab, ob Sie Version 3.x oder Version 2.x des SDK verwenden. Sie finden das für einen bestimmten Bindungstyp zu installierende Paket im Abschnitt „Pakete“ des jeweiligen Referenzartikels von Azure Functions für diesen Bindungstyp. Eine Ausnahme ist der Auslöser und die Bindung von Dateien (für das lokale Dateisystem), der von Azure Functions nicht unterstützt wird.

Version 3. x

In Version 3.x sind die Speicherbindungen im Paket Microsoft.Azure.WebJobs.Extensions.Storage enthalten. Rufen Sie die AddAzureStorage Erweiterungsmethode in der ConfigureWebJobs Methode auf:

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

Wenn Sie andere Trigger- und Bindungstypen verwenden möchten, installieren Sie das NuGet-Paket, das diese Typen enthält, und rufen Sie die in der Erweiterung implementierte Erweiterungsmethode Add<binding> auf. Wenn Sie beispielsweise eine Azure Cosmos DB-Bindung verwenden möchten, installieren Microsoft.Azure.WebJobs.Extensions.CosmosDB und aufrufen 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();
    }
}

Wenn Sie den Trigger „Selbstauslöser“ und die Bindung „Dateien“ verwenden möchten, die beide Teil der Kerndienste sind, rufen Sie die Erweiterungsmethoden AddTimers bzw. AddFiles auf.

Version 2. x

In Version 2.x des Pakets Microsoft.Azure.WebJobs sind folgende Trigger- und Bindungstypen enthalten:

  • Blob Storage
  • Queue Storage
  • Table Storage

Wenn Sie andere Trigger- und Bindungstypen verwenden möchten, installieren Sie das NuGet-Paket, das diese Typen enthält, und rufen Sie eine Use<binding>-Methode für das JobHostConfiguration-Objekt auf. Wenn Sie z. B. einen Timertrigger verwenden möchten, installieren Sie Microsoft.Azure.WebJobs.Extensions und rufen UseTimers in der Main Methode auf.

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

Wenn Sie die Bindung „Dateien“ verwenden möchten, installieren Sie Microsoft.Azure.WebJobs.Extensions, und rufen Sie UseFiles auf.

Ausführungskontext (ExecutionContext)

In WebJobs können Sie eine Bindung an eine ExecutionContext Instanz erstellen. Mit dieser Bindung können Sie ExecutionContext als Parameter in Ihrer Funktionssignatur verwenden. Im folgenden Code wird das Kontextobjekt beispielsweise verwendet, um auf die Aufruf-ID zuzugreifen, mit der Sie alle von einem bestimmten Funktionsaufruf erzeugten Protokolle korrelieren können.

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

Der Prozess für die ExecutionContext Bindung hängt von Ihrer SDK-Version ab.

Version 3. x

Rufen Sie die AddExecutionContextBinding Erweiterungsmethode in der ConfigureWebJobs Methode auf:

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

Version 2. x

In dem zuvor erwähnten Microsoft.Azure.WebJobs.Extensions-Paket wird auch ein spezieller Bindungstyp bereitgestellt, den Sie durch Aufrufen der UseCore-Methode registrieren können. Sie können die Bindung verwenden, um einen ExecutionContext Parameter in Ihrer Funktionssignatur zu definieren:

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

Bindungskonfiguration

Sie können das Verhalten einiger Trigger und Bindungen konfigurieren. Der Prozess für deren Konfiguration hängt von der SDK-Version ab.

  • Version 3.x: Legen Sie die Konfiguration fest, wenn die Add<Binding>-Methode in ConfigureWebJobs aufgerufen wird.
  • Version 2.x: Legen Sie die Konfiguration fest, indem Sie Eigenschaften in einem Konfigurationsobjekt festlegen, das Sie an JobHost übergeben.

Diese bindungsspezifischen Einstellungen entsprechen den Einstellungen in der host.json Projektdatei in Azure Functions.

Sie können die folgenden Bindungen konfigurieren:

Konfiguration des Azure Cosmos DB-Triggers (Version 3.x)

Dieses Beispiel zeigt, wie der Azure Cosmos DB-Trigger konfiguriert wird:

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

Weitere Informationen finden Sie unter Azure Cosmos DB-Bindung.

Azure Event Hubs-Triggerkonfiguration (Version 3.x)

Dieses Beispiel zeigt, wie der Event Hubs-Trigger konfiguriert wird:

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

Weitere Informationen finden Sie unter Event Hubs-Bindung.

Konfiguration des Queue Storage-Triggers

Die folgenden Beispiele zeigen, wie der Queue Storage-Trigger konfiguriert wird.

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

Weitere Informationen finden Sie unter Warteschlange Storage-Bindung.

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

Weitere Informationen finden Sie in der host.json v1.x-Referenz.

Konfiguration der SendGrid-Bindung (Version 3.x)

In diesem Beispiel wird gezeigt, wie die SendGrid-Ausgabebindung konfiguriert wird:

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

Weitere Informationen finden Sie unter SendGrid Bindung.

Konfiguration des Service Bus-Triggers (Version 3.x)

Dieses Beispiel zeigt, wie der Service Bus-Trigger konfiguriert wird:

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

Weitere Informationen finden Sie unter Service Bus-Bindung.

Konfiguration für andere Bindungen

Einige Trigger- und Bindungstypen definieren ihre eigenen benutzerdefinierten Konfigurationstypen. Sie können z. B. den Dateitrigger verwenden, um den zu überwachenden Stammpfad anzugeben, wie in den folgenden Beispielen gezeigt.

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

Bindungsausdrücke

In Attributkonstruktorparametern können Sie Ausdrücke verwenden, die in Werte aus verschiedenen Quellen aufgelöst werden. Im folgenden Code erstellt beispielsweise der Pfad für das BlobTrigger-Attribut einen Ausdruck mit dem Namen filename. Bei Verwendung für die Ausgabebindung wird filename in den Namen des auslösenden Blobs aufgelöst.

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

Weitere Informationen zu Bindungsausdrücken finden Sie unter Bindungsausdrücke und Muster in der Azure Functions-Dokumentation.

Benutzerdefinierte Bindungsausdrücke

Manchmal möchten Sie einen Warteschlangennamen, einen Blobnamen oder Container oder aber einen Tabellennamen im Code angeben, anstatt ihn hart zu codieren. So möchten Sie z. B. den Warteschlangennamen für das QueueTrigger-Attribut in einer Konfigurationsdatei oder Umgebungsvariablen angeben.

Sie können dem Attribut einen Warteschlangennamen zuweisen, indem Sie während der Konfiguration einen benutzerdefinierten Namenslöser übergeben. Sie schließen Platzhalter in Konstruktorparameter von Trigger- oder Bindungsattributen ein, und Ihr Resolver-Code gibt die tatsächlichen Werte an, die anstelle dieser Platzhalter verwendet werden sollen. Sie identifizieren Platzhalter, indem Sie sie mit Prozentzeichen (%) umgeben:

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

In diesem Code verwenden Sie eine Warteschlange namens logqueuetest in der Testumgebung und eine Warteschlange namens logqueueprod in der Produktion. Anstelle eines hartcodierten Warteschlangennamens geben Sie den Namen eines Eintrags in der appSettings-Auflistung an.

Ein Standardlöser wird wirksam, wenn Sie keine benutzerdefinierte Lösung bereitstellen. Der Standardwert ruft Werte aus App-Einstellungen oder Umgebungsvariablen ab.

Ab .NET Core 3.1 erfordert die ConfigurationManager verwendete Instanz das System.Configuration.ConfigurationManager NuGet-Paket. Das Beispiel erfordert die folgende using-Anweisung:

using System.Configuration;

Ihre NameResolver Klasse ruft den Warteschlangennamen aus den App-Einstellungen ab:

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

Version 3. x

Sie konfigurieren den Resolver mithilfe von Abhängigkeitsinjektion. Für diese Beispiele ist die folgende using-Anweisung erforderlich:

using Microsoft.Extensions.DependencyInjection;

Sie fügen den Resolver hinzu, indem Sie die Erweiterungsmethode ConfigureServices für HostBuilder wie in diesem Beispiel aufrufen:

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

Version 2. x

Übergeben Sie Ihre NameResolver Klasse an das JobHost Objekt:

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

Azure Functions implementiert INameResolver, um Werte aus App-Einstellungen abzurufen, wie im Beispiel gezeigt. Wenn Sie das WebJobs SDK direkt verwenden, können Sie eine benutzerdefinierte Implementierung schreiben, die Ersatzwerte für Platzhalter aus einer beliebigen von Ihnen gewünschten Quelle abruft.

Binden zur Laufzeit

Wenn Sie vor der Verwendung eines Bindungsattributs wie Queue, Blob oder Table weitere Aufgaben in Ihrer Funktion ausführen müssen, können Sie dazu die IBinder-Schnittstelle verwenden.

Im folgenden Beispiel wird eine Eingabewarteschlangennachricht verwendet und eine neue Nachricht erstellt, die denselben Inhalt in einer Ausgabewarteschlange enthält. Der Name der Ausgabewarteschlangenname wird durch Code im Text der Funktion festgelegt.

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

Weitere Informationen finden Sie unter Binden zur Laufzeit in der Azure Functions-Dokumentation.

Referenzinformationen für Bindungen

Die Azure Functions-Dokumentation enthält Referenzinformationen zu den einzelnen Bindungstypen. Die folgenden Informationen finden Sie in jedem Bindungsverweisartikel. (Dieses Beispiel basiert auf einer Speicherwarteschlange.)

  • Pakete. Das Paket, das Sie installieren müssen, um Unterstützung für die Bindung in ein WebJobs SDK-Projekt zu integrieren.
  • Beispiele. Codebeispiele. Das Beispiel für die C#-Klassenbibliothek bezieht sich auf das WebJobs SDK. Lassen Sie nur das FunctionNameAttribut weg.
  • Attribute. Die für den Bindungstyp zu verwendenden Attribute.
  • Konfiguration. Erläuterungen der Attributeigenschaften und Konstruktorparameter.
  • Verwendung: Die Typen, die Sie binden können, und Informationen zur Funktionsweise der Bindung. Zum Beispiel ein Abrufalgorithmus oder eine Giftwarteschlangenverarbeitung.

Hinweis

Die Bindungen „HTTP“, „Webhooks“ und „Event Grid“ werden nur von Azure Functions und, nicht vom WebJobs SDK unterstützt.

Eine vollständige Liste der Bindungen, die in der Azure Functions-Laufzeit unterstützt werden, finden Sie unter "Unterstützte Bindungen".

Attribute: Disable, Timeout und Singleton

Mit diesen Attributen können Sie das Auslösen von Funktionen steuern, Funktionen abbrechen und sicherstellen, dass nur eine Instanz einer Funktion ausgeführt wird.

Disable-Attribut

Verwenden Sie das Disable Attribut, um zu steuern, ob eine Funktion ausgelöst werden kann.

Im folgenden Beispiel wird die Funktion nicht ausgeführt, wenn die App-Einstellung Disable_TestJob einen Wert von 1 oder True (nicht fallspezifisch) aufweist. In diesem Szenario generiert die Laufzeit die Protokollnachricht Funktion 'Functions.TestJob' ist deaktiviert.

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

Wenn Sie im Azure-Portal die Werte einer App-Einstellung ändern, wird der WebJob neu gestartet, um die neue Einstellung zu übernehmen.

Das Attribut kann auf Parameter-, Methoden- oder Klassenebene deklariert werden. Der Einstellungsname kann auch Bindungsausdrücke enthalten.

Timeout-Attribut

Das Timeout-Attribut bewirkt, dass eine Funktion abgebrochen wird, wenn sie nicht innerhalb einer angegebenen Zeit abgeschlossen wurde. Im folgenden Beispiel würde die Funktion für einen Tag ohne das Timeout Attribut ausgeführt. Timeout bewirkt, dass die Funktion nach 15 Sekunden abgebrochen werden soll. Wenn der Timeout Attributparameter throwOnError auf true festgelegt ist, wird der Funktionsaufruf beendet, indem eine Ausnahme vom WebJobs SDK ausgelöst wird, wenn das Timeoutintervall überschritten wird. Der Standardwert von throwOnError ist false. Wenn das Timeout Attribut verwendet wird, besteht das Standardverhalten darin, den Aufruf der Funktion abzubrechen, indem das Abbruchtoken festgelegt wird, während der Aufruf unbegrenzt ausgeführt werden kann, bis der Funktionscode eine Ausnahme zurückgibt oder auslöst.

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

Sie können das Timeout-Attribut auf Klassenebene oder Methodenebene anwenden, und Sie können einen globalen Timeout mithilfe von JobHostConfiguration.FunctionTimeout festlegen. Zeitlimits auf Klassen- oder Methodenebene setzen das globale Zeitlimit außer Kraft.

Singleton-Attribut

Das Singleton-Attribut stellt sicher, dass nur eine Instanz einer Funktion ausgeführt wird, auch wenn mehrere Instanzen der Host-Web-App vorhanden sind. Das Singleton Attribut verwendet verteilte Sperren , um sicherzustellen, dass nur eine Instanz ausgeführt wird.

In diesem Beispiel wird immer nur eine einzige Instanz der ProcessImage-Funktion ausgeführt:

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

SingletonMode.Listener

In einige Trigger ist die Unterstützung der Parallelitätsverwaltung integriert:

  • QueueTrigger. Legen Sie JobHostConfiguration.Queues.BatchSize auf 1 fest.
  • ServiceBusTrigger. Legen Sie ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls auf 1 fest.
  • FileTrigger. Legen Sie FileProcessor.MaxDegreeOfParallelism auf 1 fest.

Sie können diese Einstellungen verwenden, um sicherzustellen, dass Ihre Funktion als Singleton auf einer einzigen Instanz ausgeführt wird. Wenn Sie sicherstellen möchten, dass nur eine Instanz der Funktion ausgeführt wird, wenn die Web-App auf mehrere Instanzen skaliert wird, wenden Sie eine Singleton-Sperre auf Listener-Ebene für die Funktion an ([Singleton(Mode = SingletonMode.Listener)]). Listener-Sperren werden beim Starten des JobHosts abgerufen. Wenn drei horizontal skalierte Instanzen zur selben Zeit gestartet werden, erhält nur eine der Instanzen die Sperre, und es wird nur ein Listener gestartet.

Hinweis

Weitere Informationen zur SingletonMode.Function Funktionsweise finden Sie im GitHub-Repository von SingletonMode.

Bereichswerte

Sie können einen Bereichsausdruck/Wert in einem Singleton angeben. Der Ausdruck/Wert stellt sicher, dass alle Ausführungen der Funktion in einem bestimmten Bereich serialisiert werden. Die Implementierung einer detaillierteren Sperre auf diese Weise kann eine gewisse Parallelität für Ihre Funktion ermöglichen, während andere Aufrufe entsprechend Ihren Anforderungen serialisiert werden. Im folgenden Code wird beispielsweise der Bereichsausdruck an den Wert Region der eingehenden Nachricht gebunden. Wenn die Warteschlange drei Nachrichten in den Regionen "Osten", "Osten" und "Westen" enthält, werden die Nachrichten mit der Region "Osten" seriell ausgeführt. Die Nachricht mit Region West wird parallel zu den Nachrichten in der Region Ost ausgeführt.

[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

Der Standardbereich für eine Sperre ist SingletonScope.Function. Der Sperrbereich (der Blob-Leasepfad) ist an den vollqualifizierten Funktionsnamen gebunden. Um funktionenübergreifende Sperren festzulegen, geben Sie SingletonScope.Host an, und verwenden Sie eine Bereichs-ID, die für alle Funktionen, die nicht gleichzeitig ausgeführt werden sollen, identisch ist. Im folgenden Beispiel wird jeweils nur eine Instanz von AddItem oder RemoveItem ausgeführt:

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

Anzeigen von Lease-Blobs

Das WebJobs SDK verwendet Azure-Blob-Leases , um verteilte Sperren zu implementieren. Die von Singleton verwendeten Lease-Blobs finden Sie im azure-webjobs-host-Container im AzureWebJobsStorage-Speicherkonto unter dem Pfad „locks.“ Beispielsweise könnte der Lease-Blob-Pfad für das erste zuvor dargestellte ProcessImage-Beispiel locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage lauten. Alle Pfade enthalten die JobHost-ID, in diesem Fall „061851c758f04938a4426aa9ab3869c0“.

Asynchrone Funktionen

Informationen zum Codieren asynchroner Funktionen finden Sie in der Azure Functions-Dokumentation.

Abbruchtoken

Informationen zum Umgang mit Abbruchtoken finden Sie in der Azure Functions-Dokumentation unter Abbruchtoken und ordnungsgemäßes Herunterfahren.

Mehrere Instanzen

Bei der Ausführung Ihrer Web-App auf mehreren Instanzen wird ein kontinuierlicher WebJob auf allen Instanzen ausgeführt, der Trigger überwacht und Funktionen aufruft. Die verschiedenen Triggerbindungen sind so konzipiert, dass die Arbeit effizient über mehrere Instanzen hinweg geteilt wird, sodass Sie bei einer Skalierung auf mehrere Instanzen mehr Last bewältigen können.

Während einige Trigger zu einer doppelten Verarbeitung führen können, verhindern Warteschlangen- und Blobspeichertrigger automatisch, dass eine Funktion eine Warteschlangennachricht oder einen Blob mehr als einmal verarbeitet. Weitere Informationen finden Sie unter Entwerfen für identische Eingaben in der Azure Functions-Dokumentation.

Mit dem Zeitgebertrigger wird automatisch sichergestellt, dass jeweils nur eine Instanz des Zeitgebers ausgeführt wird, damit zu einem geplanten Zeitpunkt nicht mehrere Funktionsinstanzen ausgeführt werden.

Wenn Sie sicherstellen möchten, dass nur eine Instanz einer Funktion ausgeführt wird, auch wenn mehrere Instanzen der Hostweb-App vorhanden sind, können Sie das Singleton Attribut verwenden.

Filter

Funktionsfilter (Vorschau) bieten eine Möglichkeit zum Anpassen der WebJobs-Ausführungspipeline mithilfe Ihrer eigenen Logik. Diese Filter ähneln ASP.NET Core-Filter. Sie können sie als deklarative Attribute implementieren, die auf Ihre Funktionen oder Klassen angewendet werden. Weitere Informationen finden Sie unter Funktionsfilter.

Protokollierung und Überwachung

Es wird empfohlen, das protokollierungsframework zu verwenden, das für ASP.NET entwickelt wurde. Im Artikel Erste Schritte finden Sie ein Beispiel für dessen Verwendung.

Protokollfilterung

Jedes von einer ILogger Instanz erstellte Protokoll weist zugeordnete Category Und Level Werte auf. LogLevel ist eine Enumeration, und der Code (eine ganze Zahl) weist auf die relative Bedeutung hin:

LogLevel Programmcode
Spur 0
Debuggen 1
Informationen 2
Warnung 3
Fehler 4
Kritisch 5
Keine 6

Sie können jede Kategorie unabhängig nach einem bestimmten LogLevel Wert filtern. Beispielsweise möchten Sie möglicherweise alle Protokolle für die Blobtriggerverarbeitung anzeigen, aber nur Error und höher für alles andere.

Version 3. x

Version 3. x des SDK basiert auf der Filterung, die in .NET Core integriert ist. Verwenden Sie die LogCategories Klasse, um Kategorien für bestimmte Funktionen, Trigger oder Benutzer zu definieren. Die LogCategories Klasse definiert auch Filter für bestimmte Hostzustände, wie z. B. Startup und Results, sodass Sie die Protokollierungsausgabe optimieren können. Wenn in den definierten Kategorien keine Übereinstimmung gefunden wird, greift der Filter auf den Default Wert zurück, wenn ermittelt wird, ob die Nachricht gefiltert werden soll.

LogCategories erfordert die folgende using Anweisung:

using Microsoft.Azure.WebJobs.Logging;

Im folgenden Beispiel wird ein Filter erstellt, der standardmäßig alle Protokolle auf der Warning-Ebene filtert. Die Kategorien Function und results (äquivalent zu Host.Results in Version2.x) werden auf der Ebene Error gefiltert. Der Filter vergleicht die aktuelle Kategorie mit allen registrierten Ebenen in der LogCategories-Instanz und wählt die längste Übereinstimmung aus. Das heißt, die für Debug registrierte Host.Triggers-Ebene entspricht entweder Host.Triggers.Queue oder Host.Triggers.Blob. Sie können umfassendere Kategorien steuern, ohne jede hinzufügen zu müssen.

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

Version 2. x

In Version 2.x des SDK verwenden Sie die Klasse LogCategoryFilter zum Steuern der Filterung. Der LogCategoryFilter verfügt über eine Default-Eigenschaft mit dem Anfangswert Information. Dies bedeutet, dass alle Nachrichten der Ebene Information, Warning, Error oder Critical protokolliert, aber Nachrichten der Ebene Debug oder Trace weggefiltert werden.

Die Eigenschaft LogCategories ermöglicht genau wie in Version 3.CategoryLevels das Angeben von Protokollebenen für bestimmte Kategorien, sodass Sie die Protokollierungsausgabe optimieren können. Wenn im CategoryLevels Wörterbuch keine Übereinstimmung gefunden wird, greift der Filter auf den Default Wert zurück, wenn ermittelt wird, ob die Nachricht gefiltert werden soll.

Im folgenden Beispiel wird ein Filter erstellt, der standardmäßig alle Protokolle auf der Warning-Ebene filtert. Die Kategorien Function und Host.Results werden auf der Error-Ebene gefiltert. Der LogCategoryFilter vergleicht die aktuelle Kategorie mit allen registrierten CategoryLevels und wählt die längste Übereinstimmung aus. Das heißt, die für Debug registrierte Host.Triggers-Ebene entspricht entweder Host.Triggers.Queue oder Host.Triggers.Blob. Sie können umfassendere Kategorien steuern, ohne jede hinzufügen zu müssen.

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

Benutzerdefinierte Telemetrie für Application Insights

Der Prozess zum Implementieren von benutzerdefinierter Telemetrie für Application Insights hängt von der SDK-Version ab. Informationen zum Konfigurieren von Application Insights finden Sie unter Hinzufügen der Application Insights-Protokollierung.

Version 3. x

Da in Version 3.x des WebJobs SDK der generische .NET Core-Host verwendet wird, steht keine Factory für benutzerdefinierte Telemetrie mehr zur Verfügung. Sie können der Pipeline aber mithilfe von Abhängigkeitsinjektion benutzerdefinierte Telemetrie hinzufügen. Für die Beispiele in diesem Abschnitt sind folgende using-Anweisungen erforderlich:

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

Sie können die folgende benutzerdefinierte Implementierung ITelemetryInitializer verwenden, um Der Standardinstanz ITelemetryeine eigene TelemetryConfiguration Instanz hinzuzufügen.

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

Rufen Sie ConfigureServices im Builder auf, um der Pipeline eine benutzerdefinierte ITelemetryInitializer Instanz hinzuzufügen.

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

Wenn TelemetryConfiguration erstellt wird, sind alle registrierten Typen von ITelemetryInitializer enthalten. Weitere Informationen finden Sie unter Application Insights-API für benutzerdefinierte Ereignisse und Metriken.

In Version 3.x muss der TelemetryClient nicht geleert werden, wenn der Host beendet wird. Das .NET Core-Abhängigkeitsinjektionssystem entsorgt automatisch die registrierte ApplicationInsightsLoggerProvider-Instanz, wodurch die TelemetryClient geleert wird.

Version 2. x

In Version 2.x verwendet die TelemetryClient-Instanz, die intern durch den Application Insights-Anbieter für das WebJobs SDK erstellt wurde, ServerTelemetryChannel. Wenn der Application Insights-Endpunkt nicht verfügbar ist oder eingehende Anforderungen drosselt, speichert dieser Kanal Anforderungen im Dateisystem der Web-App und sendet sie später erneut.

TelemetryClient wird von einer Klasse erstellt, die ITelemetryClientFactory implementiert. Diese Klasse ist DefaultTelemetryClientFactorystandardmäßig .

Wenn Sie Änderungen an einem Teil der Application Insights-Pipeline vornehmen möchten, können Sie auch Ihre eigene Instanz bereitstellen von ITelemetryClientFactory. Der Host verwendet dann Ihre Klasse zum Erstellen TelemetryClient. Dieser Code überschreibt z. B. DefaultTelemetryClientFactory, um eine Eigenschaft von ServerTelemetryChannel zu ändern:

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

Das SamplingPercentageEstimatorSettings konfiguriert adaptive Stichprobenerstellung. In diesem Szenario sendet Applications Insights in bestimmten Szenarien mit hohem Volumen eine ausgewählte Teilmenge von Telemetriedaten an den Server.

Nachdem Sie die Telemetrie-Factory erstellt haben, übergeben Sie sie an den Application Insights-Protokollierungsanbieter:

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

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

Verwandte Inhalte

Dieser Artikel enthält Codeausschnitte, die zeigen, wie allgemeine Szenarien für die Arbeit mit dem WebJobs SDK behandelt werden. Vollständige Beispiele finden Sie unter azure-webjobs-sdk-samples.