Share via

De Azure WebJobs SDK gebruiken voor gebeurtenisgestuurde verwerking op de achtergrond

  • Artikel

Dit artikel bevat richtlijnen voor het werken met de Azure WebJobs SDK. Zie Aan de slag met de Azure WebJobs SDK om meteen aan de slag te gaan met WebJobs.

WebJobs SDK-versies

Dit zijn de belangrijkste verschillen tussen versie 3.x en versie 2.x van de WebJobs SDK:

  • Versie 3.x voegt ondersteuning toe voor .NET Core.
  • In versie 3.x, installeert u de opslagbindingsextensie die is vereist voor de WebJobs SDK. In versie 2.x, de Storage-bindingen zijn opgenomen in de SDK.
  • Visual Studio 2019-hulpprogramma's voor .NET Core (3.x) projecten verschillen van hulpprogramma's voor .NET Framework (2).x) projecten. Zie Webjobs ontwikkelen en implementeren met Visual Studio - Azure-app Service voor meer informatie.

Verschillende beschrijvingen in dit artikel bevatten voorbeelden voor beide WebJobs versie 3.x en WebJobs versie 2.x.

Azure Functions is gebaseerd op de WebJobs SDK.

  • Azure Functions versie 2.x is gebouwd op WebJobs SDK versie 3.x.
  • Azure Functions versie 1.x is gebouwd op WebJobs SDK versie 2.x.

Broncodeopslagplaatsen voor zowel Azure Functions als WebJobs SDK maken gebruik van de nummering van de WebJobs SDK. In verschillende secties van dit artikel wordt een koppeling gemaakt naar de Documentatie van Azure Functions.

Zie De WebJobs SDK en Azure Functions vergelijken voor meer informatie

WebJobs-host

De host is een runtimecontainer voor functies. De host luistert naar triggers en aanroepen. In versie 3.x, de host is een implementatie van IHost. In versie 2.x, u gebruikt het JobHost object. U maakt een hostinstantie in uw code en schrijft code om het gedrag ervan aan te passen.

Dit is een belangrijk verschil tussen het rechtstreeks gebruiken van de WebJobs SDK en het indirect gebruiken via Azure Functions. In Azure Functions beheert de service de host en kunt u de host niet aanpassen door code te schrijven. Met Azure Functions kunt u het gedrag van de host aanpassen via instellingen in het host.json-bestand. Deze instellingen zijn tekenreeksen, geen code en het gebruik van deze tekenreeksen beperkt de soorten aanpassingen die u kunt doen.

Hostverbindingen

De WebJobs SDK zoekt naar Azure Storage- en Azure Service Bus-verbindingen in het local.settings.json-bestand wanneer u lokaal of in de omgeving van de webtaak uitvoert wanneer u in Azure uitvoert. Voor de WebJobs SDK is standaard een opslagverbinding met de naam AzureWebJobsStoragevereist.

Wanneer de verbindingsnaam wordt omgezet in één exacte waarde, identificeert de runtime de waarde als een verbindingsreeks, die doorgaans een geheim bevat. De details van een verbindingsreeks zijn afhankelijk van de service waarmee u verbinding maakt. Een verbindingsnaam kan echter ook verwijzen naar een verzameling van meerdere configuratie-items, handig voor het configureren van op identiteit gebaseerde verbindingen. Omgevingsvariabelen kunnen worden behandeld als een verzameling met behulp van een gedeeld voorvoegsel dat eindigt op dubbele onderstrepingstekens __. Er kan vervolgens naar de groep worden verwezen door de verbindingsnaam in te stellen op dit voorvoegsel.

De eigenschap voor een Azure Blob-triggerdefinitie kan bijvoorbeeld connection zijn Storage1. Zolang er geen enkele tekenreekswaarde is geconfigureerd door een omgevingsvariabele met de naam Storage1, kan een omgevingsvariabele met de naam Storage1__blobServiceUri worden gebruikt om de blobServiceUri eigenschap van de verbinding te informeren. De verbindingseigenschappen verschillen voor elke service. Raadpleeg de documentatie voor het onderdeel dat gebruikmaakt van de verbinding.

Op identiteit gebaseerde verbindingen

Als u op identiteit gebaseerde verbindingen in de WebJobs SDK wilt gebruiken, moet u ervoor zorgen dat u de nieuwste versies van WebJobs-pakketten in uw project gebruikt. Zorg er ook voor dat u een verwijzing hebt naar Microsoft.Azure.WebJobs.Host.Storage. Hier volgt een voorbeeld van hoe uw projectbestand eruit kan zien nadat u deze updates hebt uitgevoerd:

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

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

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

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

Wanneer u WebJobs instelt in uw HostBuilder, moet u een aanroep toevoegen aan AddAzureStorageCoreServices, omdat dit is wat het mogelijk maakt AzureWebJobsStorage en andere opslagtriggers en bindingen om identiteit te gebruiken:

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

Vervolgens kunt u de AzureWebJobsStorage verbinding configureren door omgevingsvariabelen in te stellen (of toepassingsinstellingen wanneer deze worden gehost in App Service):

Omgevingsvariabele Beschrijving Voorbeeldwaarde
AzureWebJobsStorage__blobServiceUri De gegevensvlak-URI van de blobservice van het opslagaccount met behulp van het HTTPS-schema. <https:// storage_account_name.blob.core.windows.net>
AzureWebJobsStorage__queueServiceUri De gegevensvlak-URI van de wachtrijservice van het opslagaccount met behulp van het HTTPS-schema. <https:// storage_account_name.queue.core.windows.net>

Als u uw configuratie opgeeft via een andere manier dan omgevingsvariabelen, zoals met een appsettings.json, moet u in plaats daarvan een gestructureerde configuratie opgeven voor de verbinding en de bijbehorende eigenschappen:

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

U kunt de queueServiceUri eigenschap weglaten als u geen blobtriggers wilt gebruiken.

Wanneer uw code lokaal wordt uitgevoerd, wordt uw ontwikkelaarsidentiteit standaard gebruikt volgens het gedrag dat wordt beschreven voor DefaultAzureCredential.

Wanneer uw code wordt gehost in Azure-app Service, wordt de bovenstaande configuratie standaard ingesteld op de door het systeem toegewezen beheerde identiteit voor de resource. Als u in plaats daarvan een door de gebruiker toegewezen identiteit wilt gebruiken die aan de app is toegewezen, moet u extra eigenschappen toevoegen voor uw verbinding waarmee wordt opgegeven welke identiteit moet worden gebruikt. De credential eigenschap (AzureWebJobsStorage__credential als een omgevingsvariabele) moet worden ingesteld op de tekenreeks 'managedidentity'. De clientId eigenschap (AzureWebJobsStorage__clientId als een omgevingsvariabele) moet worden ingesteld op de client-id van de door de gebruiker toegewezen beheerde identiteit die moet worden gebruikt. Als gestructureerde configuratie is het volledige object:

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

De identiteit die voor deze identiteit wordt gebruikt AzureWebJobsStorage , moet roltoewijzingen hebben die deze toewijzen aan de rol Eigenaar van opslagblobgegevens, Inzender voor opslagwachtrijgegevens en Inzender voor opslagaccounts . U kunt zowel inzender voor opslagwachtrijgegevens als inzender voor opslagaccounts weglaten als u geen blobtriggers wilt gebruiken.

De volgende tabel bevat ingebouwde rollen die worden aanbevolen bij het gebruik van triggers in bindingen in normale werking. Uw toepassing vereist mogelijk verdere machtigingen op basis van de code die u schrijft.

Binding Voorbeeld van ingebouwde rollen
Blob-trigger Eigenaar van opslagblobgegevens en Inzender voor opslagwachtrijgegevens
Zie hierboven ook voor vereisten AzureWebJobsStorage .
Blob (invoer) Lezer voor opslagblobgegevens
Blob (uitvoer) Eigenaar van opslagblobgegevens
Wachtrijtrigger Storage Queue Data Reader, Storage Queue Data Message Processor
Wachtrij (uitvoer) Inzender voor opslagwachtrijgegevens, afzender van opslagwachtrijgegevensbericht
Service Bus-trigger1 Azure Service Bus-gegevensontvanger, Azure Service Bus-gegevenseigenaar
Service Bus (uitvoer) Azure Service Bus-gegevenszender

1 Voor triggering vanuit Service Bus-onderwerpen moet de roltoewijzing een effectief bereik hebben voor de Service Bus-abonnementsresource. Als alleen het onderwerp is opgenomen, treedt er een fout op. Sommige clients, zoals de Azure Portal, maken de Service Bus-abonnementsresource niet beschikbaar als een bereik voor roltoewijzing. In dergelijke gevallen kan de Azure CLI worden gebruikt. Zie ingebouwde Azure-rollen voor Azure Service Bus voor meer informatie.

Verbindingsreeksen in versie 2.x

Versie 2.x van de SDK vereist geen specifieke naam. Versie 2.met x kunt u uw eigen namen gebruiken voor deze verbindingsreeks s en kunt u ze elders opslaan. U kunt namen instellen in code met behulp van de JobHostConfiguration, zoals deze:

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

Notitie

Omdat versie 3.x maakt gebruik van de standaard .NET Core-configuratie-API's. Er is geen API om verbindingsreeks namen te wijzigen. Zie WebJobs ontwikkelen en implementeren met Visual Studio

Instellingen voor hostontwikkeling

U kunt de host uitvoeren in de ontwikkelingsmodus om lokale ontwikkeling efficiënter te maken. Hier volgen enkele van de instellingen die automatisch worden gewijzigd wanneer u in de ontwikkelingsmodus wordt uitgevoerd:

Eigenschappen Ontwikkelingsinstelling
Tracing.ConsoleLevel TraceLevel.Verbose om logboekuitvoer te maximaliseren.
Queues.MaxPollingInterval Een lage waarde om ervoor te zorgen dat wachtrijmethoden onmiddellijk worden geactiveerd.
Singleton.ListenerLockPeriod 15 seconden om te helpen bij snelle iteratieve ontwikkeling.

Het proces voor het inschakelen van de ontwikkelingsmodus is afhankelijk van de SDK-versie.

Versie 3.x

Versie 3.x maakt gebruik van de standaard-ASP.NET Core-API's. Roep de UseEnvironment methode aan op het HostBuilder exemplaar. Geef een tekenreeks met de naam developmentdoor, zoals in dit voorbeeld:

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

Versie 2.x

De JobHostConfiguration klasse heeft een UseDevelopmentSettings methode waarmee de ontwikkelmodus wordt ingeschakeld. In het volgende voorbeeld ziet u hoe u ontwikkelinstellingen gebruikt. config.IsDevelopment Als u wilt retourneren true wanneer deze lokaal wordt uitgevoerd, stelt u een lokale omgevingsvariabele AzureWebJobsEnv in met de waardeDevelopment.

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

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

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

Gelijktijdige verbindingen beheren (versie 2.x)

In versie 3.x, de verbindingslimiet wordt standaard ingesteld op oneindige verbindingen. Als u deze limiet om een of andere reden moet wijzigen, kunt u de MaxConnectionsPerServer eigenschap van de WinHttpHandler klasse gebruiken.

In versie 2.x, u bepaalt het aantal gelijktijdige verbindingen met een host met behulp van de ServicePointManager.DefaultConnectionLimit-API . In 2.x, moet u deze waarde verhogen vanaf de standaardwaarde van 2 voordat u uw WebJobs-host start.

Alle uitgaande HTTP-aanvragen die u vanuit een functie maakt met behulp van HttpClient stroom.ServicePointManager Nadat u de waarde hebt bereikt die is ingesteld DefaultConnectionLimit, ServicePointManager begint u aanvragen in de wachtrij te plaatsen voordat u ze verzendt. Stel dat uw DefaultConnectionLimit code is ingesteld op 2 en dat uw code 1000 HTTP-aanvragen doet. In eerste instantie zijn slechts twee aanvragen toegestaan naar het besturingssysteem. De andere 998 worden in de wachtrij geplaatst totdat er ruimte voor hen is. Dit betekent dat er HttpClient mogelijk een time-out optreedt omdat deze de aanvraag heeft ingediend, maar de aanvraag nooit is verzonden door het besturingssysteem naar de doelserver. U ziet dus mogelijk gedrag dat niet logisch lijkt te zijn: het duurt 10 seconden voordat uw lokale HttpClient aanvraag is voltooid, maar uw service retourneert elke aanvraag in 200 ms.

De standaardwaarde voor ASP.NET toepassingen is Int32.MaxValueen dat werkt waarschijnlijk goed voor WebJobs die worden uitgevoerd in een Basic- of hoger App Service-plan. WebJobs hebben doorgaans de AlwaysOn-instelling nodig en dat wordt alleen ondersteund door Basic- en hogere App Service-plannen.

Als uw webtaak wordt uitgevoerd in een gratis of gedeeld App Service-plan, wordt uw toepassing beperkt door de App Service-sandbox, die momenteel een verbindingslimiet van 300 heeft. Als er een niet-afhankelijke verbindingslimiet is, ServicePointManageris de kans groter dat de drempelwaarde voor de sandbox-verbinding wordt bereikt en de site wordt afgesloten. In dat geval kan het instellen DefaultConnectionLimit op iets lagers, zoals 50 of 100, dit voorkomen en nog steeds voldoende doorvoer toestaan.

De instelling moet worden geconfigureerd voordat er HTTP-aanvragen worden gedaan. Daarom moet de webtaakhost de instelling niet automatisch aanpassen. Er kunnen HTTP-aanvragen zijn die plaatsvinden voordat de host wordt gestart, wat kan leiden tot onverwacht gedrag. De beste methode is om de waarde direct in uw Main methode in te stellen voordat u initialiseert JobHost, zoals hier wordt weergegeven:

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

Triggers

WebJobs SDK ondersteunt dezelfde set triggers en bindingen die worden gebruikt door Azure Functions. Houd er rekening mee dat triggers in de WebJobs SDK functiespecifiek zijn en niet gerelateerd zijn aan het implementatietype WebJob. WebJobs met door gebeurtenissen geactiveerde functies die zijn gemaakt met behulp van de SDK, moeten altijd worden gepubliceerd als een doorlopende webtaak, waarbij Alwayson is ingeschakeld.

Functies moeten openbare methoden zijn en moeten één triggerkenmerk of het NoAutomaticTrigger kenmerk hebben.

Automatische triggers

Automatische triggers roepen een functie aan als reactie op een gebeurtenis. Bekijk dit voorbeeld van een functie die wordt geactiveerd door een bericht dat is toegevoegd aan Azure Queue Storage. De functie reageert door een blob uit Azure Blob Storage te lezen:

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

Het QueueTrigger kenmerk geeft de runtime de opdracht om de functie aan te roepen wanneer er een wachtrijbericht wordt weergegeven in myqueue-items. Het Blob kenmerk vertelt de runtime dat het wachtrijbericht moet worden gebruikt om een blob te lezen in de container sample-workitems . De naam van het blob-item in de samples-workitems container wordt rechtstreeks verkregen via de wachtrijtrigger als een bindingexpressie ({queueTrigger}).

Notitie

Een web-app kan een time-out uitvoeren na 20 minuten inactiviteit en alleen aanvragen voor de werkelijke web-app kunnen de timer opnieuw instellen. De timer wordt niet gereset als de configuratie van de toepassing in de Azure-portal wordt bekeken of als aanvragen worden ingediend op de pagina met geavanceerde hulpmiddelen (https://<app_name>.scm.azurewebsites.net). Als u de web-app instelt die als host fungeert voor het continu uitvoeren van uw taak, wordt uitgevoerd volgens een schema of gebeurtenisgestuurde triggers gebruikt, schakelt u de instelling Altijd in op de Azure-configuratiepagina van uw web-app. De instelling AlwaysOn helpt ervoor te zorgen dat dit soort webtaken betrouwbaar wordt uitgevoerd. Deze functie is alleen beschikbaar in de prijscategorieën Basic, Standard en Premium.

Handmatige triggers

Als u een functie handmatig wilt activeren, gebruikt u het NoAutomaticTrigger kenmerk, zoals hier wordt weergegeven:

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

Het proces voor het handmatig activeren van de functie is afhankelijk van de SDK-versie.

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

Versie 2.x

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

Invoer- en uitvoerbindingen

Invoerbindingen bieden een declaratieve manier om gegevens van Azure- of services van derden beschikbaar te maken voor uw code. Uitvoerbindingen bieden een manier om gegevens bij te werken. In het artikel Aan de slag ziet u een voorbeeld van elk artikel.

U kunt een retourwaarde voor een methode gebruiken voor een uitvoerbinding door het kenmerk toe te passen op de retourwaarde van de methode. Zie het voorbeeld in De retourwaarde van De Azure-functie gebruiken.

Bindingstypen

Het proces voor het installeren en beheren van bindingstypen is afhankelijk van of u versie 3 gebruikt.x of versie 2.x van de SDK. U vindt het pakket dat moet worden geïnstalleerd voor een bepaald bindingstype in de sectie Pakketten van het Azure Functions-referentieartikel van dat bindingstype. Een uitzondering is de bestandstrigger en -binding (voor het lokale bestandssysteem), die niet wordt ondersteund door Azure Functions.

Versie 3.x

In versie 3.x, de opslagbindingen zijn opgenomen in het Microsoft.Azure.WebJobs.Extensions.Storage pakket. Roep de AddAzureStorage extensiemethode aan in de ConfigureWebJobs methode, zoals hier wordt weergegeven:

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

Als u andere trigger- en bindingstypen wilt gebruiken, installeert u het NuGet-pakket dat deze bevat en roept u de Add<binding> extensiemethode aan die in de extensie is geïmplementeerd. Als u bijvoorbeeld een Azure Cosmos DB-binding wilt gebruiken, installeert Microsoft.Azure.WebJobs.Extensions.CosmosDB en roept AddCosmosDBu deze als volgt aan:

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

Als u de timertrigger of de bestandsbinding wilt gebruiken, die deel uitmaken van kernservices, roept u de AddTimers methoden of AddFiles uitbreidingsmethoden aan.

Versie 2.x

Deze trigger- en bindingstypen zijn opgenomen in versie 2.x van het Microsoft.Azure.WebJobs pakket:

  • Blob-opslag
  • Queue Storage
  • Table Storage

Als u andere trigger- en bindingstypen wilt gebruiken, installeert u het NuGet-pakket dat deze bevat en roept u een Use<binding> methode op het JobHostConfiguration object aan. Als u bijvoorbeeld een timertrigger wilt gebruiken, installeert Microsoft.Azure.WebJobs.Extensions en roept UseTimers u deze aan in de Main methode, zoals hier wordt weergegeven:

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

Als u de bestandsbinding wilt gebruiken, installeert Microsoft.Azure.WebJobs.Extensions en roept u deze UseFilesaan.

ExecutionContext

Met WebJobs kunt u verbinding maken met een ExecutionContext. Met deze binding hebt u toegang tot de ExecutionContext parameter in uw functiehandtekening. De volgende code gebruikt bijvoorbeeld het contextobject voor toegang tot de aanroep-id, die u kunt gebruiken om alle logboeken te correleren die zijn geproduceerd door een bepaalde functie-aanroep.

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

Het proces voor binding met de ExecutionContext SDK is afhankelijk van uw SDK-versie.

Versie 3.x

Roep de AddExecutionContextBinding extensiemethode aan in de ConfigureWebJobs methode, zoals hier wordt weergegeven:

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

Versie 2.x

Het Microsoft.Azure.WebJobs.Extensions eerder genoemde pakket biedt ook een speciaal bindingstype dat u kunt registreren door de methode aan te UseCore roepen. Met deze binding kunt u een ExecutionContext parameter definiëren in uw functiehandtekening, die als volgt is ingeschakeld:

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

Bindingsconfiguratie

U kunt het gedrag van sommige triggers en bindingen configureren. Het proces voor het configureren ervan is afhankelijk van de SDK-versie.

  • Versie 3.x: Stel de configuratie in wanneer de Add<Binding> methode wordt aangeroepen ConfigureWebJobs.
  • Versie 2.x: Stel de configuratie in door eigenschappen in te stellen in een configuratieobject dat u doorgeeft.JobHost

Deze bindingsspecifieke instellingen zijn gelijk aan instellingen in het host.json projectbestand in Azure Functions.

U kunt de volgende bindingen configureren:

Azure Cosmos DB-triggerconfiguratie (versie 3.x)

In dit voorbeeld ziet u hoe u de Azure Cosmos DB-trigger configureert:

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

Zie het azure Cosmos DB-bindingsartikel voor meer informatie.

Event Hubs-triggerconfiguratie (versie 3.x)

In dit voorbeeld ziet u hoe u de Event Hubs-trigger configureert:

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

Zie het Event Hubs-bindingsartikel voor meer informatie.

Configuratie van wachtrijopslagtrigger

In de volgende voorbeelden ziet u hoe u de wachtrijopslagtrigger configureert.

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

Zie het artikel Queue Storage Binding voor meer informatie.

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

Zie de naslaginformatie host.json v1.x voor meer informatie.

SendGrid-bindingsconfiguratie (versie 3.x)

In dit voorbeeld ziet u hoe u de SendGrid-uitvoerbinding configureert:

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

Zie het SendGrid-bindingsartikel voor meer informatie.

Service Bus-triggerconfiguratie (versie 3.x)

In dit voorbeeld ziet u hoe u de Service Bus-trigger configureert:

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

Zie het Service Bus-bindingsartikel voor meer informatie.

Configuratie voor andere bindingen

Sommige trigger- en bindingstypen definiëren hun eigen aangepaste configuratietypen. Met de bestandstrigger kunt u bijvoorbeeld het hoofdpad opgeven dat moet worden bewaakt, zoals in de volgende voorbeelden.

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

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

Bindingexpressies

In kenmerkconstructorparameters kunt u expressies gebruiken die worden omgezet in waarden uit verschillende bronnen. In de volgende code maakt het pad voor het kenmerk bijvoorbeeld een expressie met de BlobTrigger naam filename. Als deze wordt gebruikt voor de uitvoerbinding, filename wordt omgezet in de naam van de triggerende 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}");
    // ...
}

Zie Bindingexpressies en -patronen in de Documentatie van Azure Functions voor meer informatie over bindingsexpressies.

Aangepaste bindingexpressies

Soms wilt u een wachtrijnaam, een blobnaam of container of een tabelnaam opgeven in code in plaats van deze hard te coderen. U kunt bijvoorbeeld de wachtrijnaam voor het QueueTrigger kenmerk opgeven in een configuratiebestand of omgevingsvariabele.

U kunt dit doen door een aangepaste naamomzetting door te geven tijdens de configuratie. U neemt tijdelijke aanduidingen op in de constructorparameters voor trigger- of bindingskenmerken en de code van de resolver bevat de werkelijke waarden die moeten worden gebruikt in plaats van deze tijdelijke aanduidingen. U identificeert tijdelijke aanduidingen door deze te omringen met procenttekens (%) zoals hier wordt weergegeven:

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

Met deze code kunt u een wachtrij gebruiken met de naam logqueuetest in de testomgeving en een wachtrij die in productie wordt genoemd logqueueprod . In plaats van een in code vastgelegde wachtrijnaam geeft u de naam op van een vermelding in de appSettings verzameling.

Er is een standaard resolver die van kracht wordt als u geen aangepaste oplossing opgeeft. De standaardwaarde haalt waarden op uit app-instellingen of omgevingsvariabelen.

Voor het ConfigurationManager gebruik van .NET Core 3.1 is het NuGet-pakket System.Configuration.ConfigurationManager vereist. Voor het voorbeeld is de volgende using instructie vereist:

using System.Configuration;

Uw NameResolver klasse haalt de wachtrijnaam op uit app-instellingen, zoals hier wordt weergegeven:

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

Versie 3.x

U configureert de resolver met behulp van afhankelijkheidsinjectie. Voor deze voorbeelden is de volgende using instructie vereist:

using Microsoft.Extensions.DependencyInjection;

U voegt de resolver toe door de ConfigureServices extensiemethode aan HostBuilderte roepen, zoals in dit voorbeeld:

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

Versie 2.x

Geef uw NameResolver klasse door aan het JobHost object, zoals hier wordt weergegeven:

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

Azure Functions implementeert INameResolver om waarden op te halen uit app-instellingen, zoals wordt weergegeven in het voorbeeld. Wanneer u de WebJobs SDK rechtstreeks gebruikt, kunt u een aangepaste implementatie schrijven die tijdelijke aanduidingen voor vervangingswaarden ophaalt van de bron die u wilt gebruiken.

Binding tijdens runtime

Als u wat werk in uw functie moet uitvoeren voordat u een bindingskenmerk zoals Queue, Blobof Table, gebruikt, kunt u de IBinder interface gebruiken.

In het volgende voorbeeld wordt een bericht in de invoerwachtrij gebruikt en wordt een nieuw bericht gemaakt met dezelfde inhoud in een uitvoerwachtrij. De naam van de uitvoerwachtrij wordt ingesteld op code in de hoofdtekst van de functie.

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

Zie Binding tijdens runtime in de Documentatie van Azure Functions voor meer informatie.

Referentie-informatie voor binding

De Documentatie van Azure Functions bevat naslaginformatie over elk bindingstype. U vindt de volgende informatie in elk bindingsreferentieartikel. (Dit voorbeeld is gebaseerd op opslagwachtrij.)

  • Pakketten. Het pakket dat u moet installeren om ondersteuning voor de binding in een WebJobs SDK-project op te nemen.
  • Voorbeelden. Codevoorbeelden. Het voorbeeld van de C#-klassebibliotheek is van toepassing op de WebJobs SDK. Laat het FunctionName kenmerk gewoon weg.
  • Kenmerken. De kenmerken die moeten worden gebruikt voor het bindingstype.
  • Configuratie. Uitleg van de kenmerkeigenschappen en constructorparameters.
  • Gebruik. De typen waaraan u kunt binden en informatie over hoe de binding werkt. Bijvoorbeeld: polling-algoritme, verwerking van gifwachtrijen.

Notitie

De HTTP-, Webhooks- en Event Grid-bindingen worden alleen ondersteund door Azure Functions, niet door de WebJobs SDK.

Zie Ondersteunde bindingen voor een volledige lijst met bindingen die worden ondersteund in Azure Functions Runtime.

Kenmerken voor Uitschakelen, Time-out en Singleton

Met deze kenmerken kunt u de functie activeren, annuleren en ervoor zorgen dat slechts één exemplaar van een functie wordt uitgevoerd.

Kenmerk uitschakelen

Met het Disable kenmerk kunt u bepalen of een functie kan worden geactiveerd.

Als de app-instelling Disable_TestJob in het volgende voorbeeld een waarde heeft van 1 of True (niet hoofdlettergevoelig), wordt de functie niet uitgevoerd. In dat geval maakt de runtime een logboekbericht functie Functions.TestJob is uitgeschakeld.

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

Wanneer u app-instellingswaarden wijzigt in Azure Portal, wordt de webtaak opnieuw gestart om de nieuwe instelling op te halen.

Het kenmerk kan worden gedeclareerd op het niveau van de parameter, methode of klasse. De naam van de instelling kan ook bindingexpressies bevatten.

Time-outkenmerk

Het Timeout kenmerk zorgt ervoor dat een functie wordt geannuleerd als deze niet binnen een opgegeven periode wordt voltooid. In het volgende voorbeeld wordt de functie één dag uitgevoerd zonder het kenmerk Timeout. Time-out zorgt ervoor dat de functie na 15 seconden wordt geannuleerd. Wanneer de parameter 'throwOnError' van het time-outkenmerk is ingesteld op 'true', wordt de aanroep van de functie beëindigd door een uitzondering die wordt gegenereerd door de webjobs-SDK wanneer het time-outinterval wordt overschreden. De standaardwaarde 'throwOnError' is 'false'. Wanneer het time-outkenmerk wordt gebruikt, is het standaardgedrag om de aanroep van de functie te annuleren door het annuleringstoken in te stellen terwijl de aanroep voor onbepaalde tijd kan worden uitgevoerd totdat de functiecode een uitzondering retourneert of genereert.

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

U kunt het time-outkenmerk toepassen op klasse- of methodeniveau en u kunt een globale time-out opgeven met behulp van JobHostConfiguration.FunctionTimeout. Time-outs op klasseniveau of op methodeniveau overschrijven globale time-outs.

Kenmerk Singleton

Het Singleton kenmerk zorgt ervoor dat slechts één exemplaar van een functie wordt uitgevoerd, zelfs wanneer er meerdere exemplaren van de hostweb-app zijn. Het kenmerk Singleton maakt gebruik van gedistribueerde vergrendelingen om ervoor te zorgen dat één exemplaar wordt uitgevoerd.

In dit voorbeeld wordt slechts één exemplaar van de ProcessImage functie op een bepaald moment uitgevoerd:

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

SingletonMode.Listener

Sommige triggers hebben ingebouwde ondersteuning voor gelijktijdigheidsbeheer:

  • QueueTrigger. Stel JobHostConfiguration.Queues.BatchSize in op 1.
  • ServiceBusTrigger. Stel ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls in op 1.
  • FileTrigger. Stel FileProcessor.MaxDegreeOfParallelism in op 1.

U kunt deze instellingen gebruiken om ervoor te zorgen dat uw functie wordt uitgevoerd als een singleton op één exemplaar. Als u ervoor wilt zorgen dat slechts één exemplaar van de functie wordt uitgevoerd wanneer de web-app wordt uitgeschaald naar meerdere exemplaren, past u een singletonvergrendeling op listenerniveau toe op de functie ([Singleton(Mode = SingletonMode.Listener)]). Listenervergrendelingen worden verkregen wanneer jobhost wordt gestart. Als drie uitgeschaalde exemplaren allemaal tegelijk beginnen, verkrijgt slechts één van de exemplaren de vergrendeling en wordt slechts één listener gestart.

Notitie

Zie deze GitHub-opslagplaats voor meer informatie over hoe de SingletonMode.Function werkt.

Bereikwaarden

U kunt een bereikexpressie/-waarde opgeven voor een singleton. De expressie/waarde zorgt ervoor dat alle uitvoeringen van de functie in een specifiek bereik worden geserialiseerd. Door op deze manier gedetailleerdere vergrendeling te implementeren, kunt u een zekere mate van parallelle uitvoering voor uw functie mogelijk maken terwijl andere aanroepen worden geserialiseerd zoals bepaald door uw vereisten. In de volgende code wordt de bereikexpressie bijvoorbeeld gekoppeld aan de Region waarde van het binnenkomende bericht. Wanneer de wachtrij drie berichten bevat in regio's Oost, Oost en West, worden de berichten met regio Oost serieel uitgevoerd. Het bericht met regio West wordt parallel uitgevoerd met de berichten in regio Oost.

[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

Het standaardbereik voor een vergrendeling is SingletonScope.Function, wat betekent dat het vergrendelingsbereik (het blob-leasepad) is gekoppeld aan de volledig gekwalificeerde functienaam. Als u functies wilt vergrendelen, geeft SingletonScope.Host u een bereik-id-naam op die hetzelfde is voor alle functies die u niet tegelijk wilt uitvoeren. In het volgende voorbeeld wordt slechts één exemplaar tegelijk uitgevoerd of AddItem RemoveItem uitgevoerd:

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

Lease-blobs weergeven

De WebJobs SDK maakt gebruik van Azure Blob-leases onder de dekking voor het implementeren van gedistribueerde vergrendeling. De lease-blobs die door Singleton worden gebruikt, zijn te vinden in de azure-webjobs-host container in het AzureWebJobsStorage opslagaccount onder het pad 'vergrendelingen'. Het lease-blobpad voor het eerste ProcessImage voorbeeld dat eerder wordt weergegeven, kan bijvoorbeeld zijn locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage. Alle paden bevatten de JobHost-id, in dit geval 061851c758f04938a4426aa9ab3869c0.

Asynchrone functies

Zie de Documentatie van Azure Functions voor informatie over het coden van asynchrone functies.

Annuleringstokens

Zie de Documentatie van Azure Functions over annuleringstokens en het probleemloos afsluiten voor informatie over het verwerken van annuleringstokens.

Meerdere exemplaren

Als uw web-app wordt uitgevoerd op meerdere exemplaren, wordt een doorlopende webtaak uitgevoerd op elk exemplaar, waarbij wordt geluisterd naar triggers en aanroepende functies. De verschillende triggerbindingen zijn ontworpen om efficiënt werk samen te delen tussen exemplaren, zodat u kunt uitschalen naar meer exemplaren, zodat u meer belasting kunt verwerken.

Hoewel sommige triggers kunnen leiden tot dubbele verwerking, kunnen wachtrij- en blobopslagtriggers voorkomen dat een functie meer dan één keer een wachtrijbericht of blob verwerkt. Zie Ontwerpen voor identieke invoer in de Documentatie van Azure Functions voor meer informatie.

De timertrigger zorgt er automatisch voor dat slechts één exemplaar van de timer wordt uitgevoerd, zodat u niet meer dan één functie-exemplaar op een bepaald gepland tijdstip uitvoert.

Als u ervoor wilt zorgen dat slechts één exemplaar van een functie wordt uitgevoerd, zelfs wanneer er meerdere exemplaren van de hostweb-app zijn, kunt u het Singleton kenmerk gebruiken.

Filters

Functiefilters (preview) bieden een manier om de pijplijn voor het uitvoeren van webtaken aan te passen met uw eigen logica. Filters zijn vergelijkbaar met ASP.NET Core-filters. U kunt ze implementeren als declaratieve kenmerken die worden toegepast op uw functies of klassen. Zie Functiefilters voor meer informatie.

Logboekregistratie en controle

We raden het logboekregistratieframework aan dat is ontwikkeld voor ASP.NET. In het artikel Aan de slag ziet u hoe u dit kunt gebruiken.

Logboekfiltering

Elk logboek dat door een ILogger exemplaar wordt gemaakt, heeft een bijbehorende Category en Level. LogLevel is een opsomming en de gehele code geeft het relatieve belang aan:

Logniveau Code
Trace 0
Fouten opsporen 1
Gegevens 2
Waarschuwing 3
Error 4
Kritiek 5
Geen 6

U kunt elke categorie onafhankelijk filteren op een bepaalde LogLevel. U wilt bijvoorbeeld alle logboeken voor verwerking van blobtriggers zien, maar alleen Error en hoger voor alle andere logboeken.

Versie 3.x

Versie 3.x van de SDK is afhankelijk van het filteren dat is ingebouwd in .NET Core. Met de LogCategories klasse kunt u categorieën definiëren voor specifieke functies, triggers of gebruikers. Het definieert ook filters voor specifieke hoststatussen, zoals Startup en Results. Hiermee kunt u de uitvoer van logboekregistratie verfijnen. Als er geen overeenkomst wordt gevonden in de gedefinieerde categorieën, valt het filter terug op de waarde bij het Default bepalen of het bericht moet worden gefilterd.

LogCategories vereist de volgende using-instructie:

using Microsoft.Azure.WebJobs.Logging;

In het volgende voorbeeld wordt een filter samengesteld dat standaard alle logboeken op het Warning niveau filtert. De Function en results categorieën (gelijk aan Host.Results in versie 2.x) worden gefilterd op het Error niveau. Het filter vergelijkt de huidige categorie met alle geregistreerde niveaus in het LogCategories exemplaar en kiest de langste overeenkomst. Dit betekent dat het Debug niveau dat is geregistreerd voor Host.Triggers overeenkomsten Host.Triggers.Queue of Host.Triggers.Blob. Hierdoor kunt u bredere categorieën beheren zonder dat u elke categorie hoeft toe te voegen.

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

Versie 2.x

In versie 2.x van de SDK gebruikt u de LogCategoryFilter klasse om filteren te beheren. De LogCategoryFilter eigenschap heeft een Default eigenschap met een initiële waarde van Information, wat betekent dat berichten op de Information, Warning, Errorof Critical niveaus worden geregistreerd, maar berichten op de Debug of Trace niveaus worden weggefilterd.

Net als bij LogCategories versie 3.x, met de CategoryLevels eigenschap kunt u logboekniveaus opgeven voor specifieke categorieën, zodat u de uitvoer van logboekregistratie kunt verfijnen. Als er geen overeenkomst wordt gevonden in de CategoryLevels woordenlijst, valt het filter terug op de waarde bij het Default bepalen of het bericht moet worden gefilterd.

In het volgende voorbeeld wordt een filter samengesteld dat standaard alle logboeken op niveau Warning filtert. De Function categorieën en Host.Results categorieën worden gefilterd op het Error niveau. De LogCategoryFilter huidige categorie wordt vergeleken met alle geregistreerde CategoryLevels en kiest de langste overeenkomst. Debug Het niveau waarvoor is geregistreerdHost.Triggers, komt dus overeen Host.Triggers.Queue met of Host.Triggers.Blob. Hierdoor kunt u bredere categorieën beheren zonder dat u elke categorie hoeft toe te voegen.

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

Aangepaste telemetrie voor Application Insights

Het proces voor het implementeren van aangepaste telemetrie voor Application Insights is afhankelijk van de SDK-versie. Zie Application Insights-logboekregistratie toevoegen voor meer informatie over het configureren van Application Insights.

Versie 3.x

Omdat versie 3.x van de WebJobs SDK is afhankelijk van de algemene .NET Core-host. Er is geen aangepaste telemetriefactory meer beschikbaar. U kunt echter aangepaste telemetrie toevoegen aan de pijplijn met behulp van afhankelijkheidsinjectie. Voor de voorbeelden in deze sectie zijn de volgende using instructies vereist:

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

Met de volgende aangepaste implementatie ITelemetryInitializer kunt u uw eigen ITelemetry toevoegen aan de standaardinstelling TelemetryConfiguration.

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

Roep ConfigureServices de opbouwfunctie aan om uw aangepaste ITelemetryInitializer aan de pijplijn toe te voegen.

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

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

Wanneer de TelemetryConfiguration constructie is uitgevoerd, worden alle geregistreerde typen ITelemetryInitializer opgenomen. Zie Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens voor meer informatie.

In versie 3.x, u hoeft de TelemetryClient host niet meer leeg te maken wanneer de host stopt. Het .NET Core-afhankelijkheidsinjectiesysteem verwijdert automatisch het geregistreerde ApplicationInsightsLoggerProvidersysteem, waardoor de TelemetryClient.

Versie 2.x

In versie 2.x, de TelemetryClient intern gemaakt door de Application Insights-provider voor de WebJobs SDK gebruikt ServerTelemetryChannel. Wanneer het Application Insights-eindpunt niet beschikbaar is of binnenkomende aanvragen beperkt, slaat dit kanaal aanvragen op in het bestandssysteem van de web-app en verzendt deze later opnieuw.

De TelemetryClient wordt gemaakt door een klasse die implementeert ITelemetryClientFactory. Dit is standaard de DefaultTelemetryClientFactory.

Als u een deel van de Application Insights-pijplijn wilt wijzigen, kunt u uw eigen ITelemetryClientFactorypijplijn opgeven en gebruikt de host uw klasse om een TelemetryClient. Deze code overschrijft DefaultTelemetryClientFactory bijvoorbeeld het wijzigen van een eigenschap van 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;
    }
}

Het SamplingPercentageEstimatorSettings object configureert adaptieve steekproeven. Dit betekent dat in bepaalde scenario's met grote volumes Application Insights een geselecteerde subset telemetriegegevens naar de server verzendt.

Nadat u de telemetriefactory hebt gemaakt, geeft u deze door aan de Application Insights-logboekregistratieprovider:

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

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

Volgende stappen

Dit artikel bevat codefragmenten die laten zien hoe u veelvoorkomende scenario's voor het werken met de WebJobs SDK kunt afhandelen. Zie azure-webjobs-sdk-samples voor volledige voorbeelden.