Delen via

De Azure WebJobs SDK gebruiken voor gebeurtenisgestuurde achtergrondverwerking

In dit artikel wordt beschreven hoe u kunt werken met de Azure WebJobs SDK. Zie Aan de slag met de Azure WebJobs SDK om snel aan de slag te gaan met WebJobs.

WebJobs SDK-versies

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

  • 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 voor meer informatie.

Sommige voorbeelden in dit artikel worden geleverd voor zowel WebJobs versie 3.x als WebJobs versie 2.x.

Azure Functions is gebouwd 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 de WebJobs SDK gebruiken 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-gastheer

De WebJobs-host is een runtimecontainer voor functies. De host luistert naar triggers en roept functies aan. 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.

Deze architectuurwijziging 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. U kunt de host niet aanpassen door code te schrijven. In Azure Functions past u het hostgedrag aan 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. De WebJobs SDK vereist standaard een opslagverbinding met de naam AzureWebJobsStorage.

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. Deze methode is handig voor het configureren van op identiteit gebaseerde verbindingen. U kunt omgevingsvariabelen behandelen als een verzameling met behulp van een gedeeld voorvoegsel dat eindigt op dubbele onderstrepingstekens (__). Vervolgens kunt u naar de groep verwijzen door de verbindingsnaam in te stellen op dit voorvoegsel.

De eigenschap voor een Azure Blob Storage-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.

In het volgende voorbeeld ziet u 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.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>

Wanneer u WebJobs instelt in uw HostBuilder-exemplaar, moet u ervoor zorgen dat u een aanroep naar AddAzureStorageCoreServicestoevoegt. Met deze aanroep kunnen AzureWebJobsStorage en andere opslagtriggers en bindingen de identiteit gebruiken.

Hier volgt een voorbeeld:

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

Vervolgens kunt u de AzureWebJobsStorage verbinding configureren door omgevingsvariabelen (of toepassingsinstellingen in te stellen wanneer uw code wordt gehost in Azure App Service):

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

Als u uw configuratie op een andere manier dan omgevingsvariabelen opgeeft, zoals in een appsettings.json configuratiebestand, 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, is het de standaardinstelling om uw ontwikkelaarsidentiteit te gebruiken zoals beschreven voor DefaultAzureCredential.

Wanneer uw code wordt gehost in App Service, wordt de configuratie in het voorgaande voorbeeld 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 eigenschappen voor uw verbinding toevoegen om op te geven 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 een gestructureerde configuratie zou het volledige object vergelijkbaar zijn met dit voorbeeld:

{
    "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 AzureWebJobsStorage wordt gebruikt, moet roltoewijzingen hebben die het de rollen Opslagblobgegevenseigenaar, Bijdrager voor opslagwachtrijgegevens en Bijdrager voor opslagaccount verlenen. U kunt de rollen Inzender voor opslagwachtrijgegevens en Inzender voor opslagaccounts weglaten als u geen blobtriggers wilt gebruiken.

In de volgende tabel ziet u vooraf gedefinieerde rollen die wij aanraden wanneer u triggers gebruikt in bindingen bij normaal gebruik. Uw toepassing vereist mogelijk meer machtigingen, afhankelijk van de code die u schrijft.

Bindend Voorbeeld van ingebouwde rollen
Blobtrigger Eigenaarvan opslagblobgegevens enInzender voor opslagwachtrijgegevens
Zie ook de voorgaande vereisten voor AzureWebJobsStorage.
Blob (invoer) Gegevenslezer voor opslagblobs
Blob (uitvoer) Storage Blob Data-eigenaar
Wachtrijtrigger Storage Queue Data Reader, Storage Queue Data Message Processor
Wachtrij (uitvoer) Bijdrager voor opslagwachtrijgegevens, Berichtverzender voor opslagwachtrijgegevens
Servicebus-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, stellen de Service Bus-abonnementsresource niet beschikbaar als scope voor roltoewijzing. In deze scenario's kunt u in plaats daarvan de Azure CLI gebruiken. 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 voor verbindingsreeksen. In versie 2. x, u kunt uw eigen namen gebruiken voor deze verbindingsreeksen en u kunt ze elders opslaan. U kunt namen in code instellen met behulp van JobHostConfiguration, zoals in dit voorbeeld:

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 bestaat geen API om namen van verbindingsreeksen te wijzigen. Zie Webjobs ontwikkelen en implementeren met behulp van Visual Studio voor meer informatie.

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

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

In versie 3. x gebruikt u de standaard-ASP.NET Core-API's om de hostomgeving te wijzigen. 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. Stel config.IsDevelopment zo in dat het true retourneert wanneer het lokaal wordt uitgevoerd, door een lokale omgevingsvariabele met de naam AzureWebJobsEnv in te stellen die de waarde Development heeft.

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 eigenschap. 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, stromen door HttpClient met behulp van ServicePointManager. Nadat u de waarde hebt bereikt die is ingesteld in DefaultConnectionLimit, begint ServicePointManager aanvragen in de wachtrij te plaatsen voordat ze worden verzonden. Stel dat uw DefaultConnectionLimit code is ingesteld op 2 en dat uw code 1000 HTTP-aanvragen doet. In eerste instantie zijn slechts 2 aanvragen toegestaan voor het besturingssysteem. De andere 998 aanvragen worden in de wachtrij geplaatst totdat er ruimte voor hen is. Uw HttpClient kan een time-out krijgen omdat het lijkt alsof het de aanvraag heeft gedaan, maar de aanvraag is nooit door het besturingssysteem naar de bestemmingsserver verzonden. Mogelijk ziet u gedrag dat niet logisch lijkt: 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 die wordt alleen ondersteund door Basic- en hogere App Service-abonnementen.

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 600 heeft. Als u een niet-afhankelijke verbindingslimiet ServicePointManagerhebt, is de kans groter dat de drempelwaarde voor de sandbox-verbinding is bereikt en de site wordt afgesloten. In dat geval kan het instellen DefaultConnectionLimit op iets lagers, zoals 200, voorkomen dat dit scenario optreedt en nog steeds voldoende doorvoer toestaat.

De instelling moet worden geconfigureerd voordat er HTTP-aanvragen worden gedaan. Daarom moet de WebJobs-host de instelling niet automatisch aanpassen. Er kunnen HTTP-aanvragen optreden 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 wordt weergegeven in dit voorbeeld:

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

Aanleidingen

De WebJobs SDK ondersteunt dezelfde set triggers en binding die door Azure Functions wordt gebruikt. In de WebJobs SDK zijn triggers functiespecifiek en niet gerelateerd 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 ze 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 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 in de sample-workitems container te lezen. 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. Als u de configuratie van de app in Azure Portal bekijkt of aanvragen indient naar de site met geavanceerde hulpprogramma's, wordt de timer niet opnieuw ingesteld. 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 in het deelvenster Azure-configuratie van uw web-app. Met de instelling AlwaysOn kunt u ervoor zorgen dat dit soort webtaken betrouwbaar worden 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:

[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 hierop is de bestandstrigger en -binding (voor het lokale bestandssysteem), die azure Functions niet ondersteunt.

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:

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, installeer Microsoft.Azure.WebJobs.Extensions.CosmosDB en roep AddCosmosDB 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
  • Wachtrijopslag
  • Tabelopslag

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, installeer Microsoft.Azure.WebJobs.Extensions en roep UseTimers aan in de Main methode:

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

Als u de bestandsbinding wilt gebruiken, installeert u Microsoft.Azure.WebJobs.Extensions en roept u UseFiles aan.

Uitvoeringscontext

In WebJobs kunt u verbinding maken met een ExecutionContext exemplaar. Met deze binding kunt u toegang hebben tot ExecutionContext als een parameter in uw functiesignatuur. 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 aan ExecutionContext hangt af van uw SDK-versie.

Versie 3.x

Roep de AddExecutionContextBinding extensiemethode aan in de ConfigureWebJobs methode:

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. U kunt de binding gebruiken om een ExecutionContext parameter in uw functiehandtekening te definiëren:

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

Bindconfiguratie

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-trigger-configuratie (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 Azure Cosmos DB-binding voor meer informatie.

Azure 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 Event Hubs-binding voor meer informatie.

Configuratie van trigger voor wachtrijopslag

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 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 host.json v1.x-verwijzing 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 voor meer informatie SendGrid binding.

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

Voor meer informatie, zie Service Bus-binding.

Configuratie voor andere bindingen

Sommige trigger- en bindingstypen definiëren hun eigen aangepaste configuratietypen. U kunt bijvoorbeeld de bestandstrigger gebruiken om het hoofdpad op te geven 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. Bijvoorbeeld, in de volgende code creëert het pad voor het BlobTrigger-attribuut een expressie met de 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 bindingsuitdrukkingen

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 een wachtrijnaam toewijzen aan het kenmerk door tijdens de configuratie een aangepaste naamresolver door te geven. 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 (%):

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

In deze code gebruikt u een wachtrij met de naam logqueuetest in de testomgeving en een wachtrij met de naam logqueueprod in productie. In plaats van een in code vastgelegde wachtrijnaam geeft u de naam op van een vermelding in de appSettings verzameling.

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

Vanaf .NET Core 3.1 is voor het ConfigurationManager exemplaar dat u gebruikt het System.Configuration.ConfigurationManager NuGet-pakket vereist. Voor het voorbeeld is de volgende using instructie vereist:

using System.Configuration;

Uw NameResolver klasse haalt de wachtrijnaam op uit app-instellingen:

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:

 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 vervangingswaarden voor tijdelijke aanduidingen ophaalt uit de gewenste bron.

Binding tijdens uitvoeringstijd

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 invoerwachtrijbericht gebruikt en wordt een nieuw bericht gemaakt met dezelfde inhoud in een uitvoerwachtrij. De naam van de uitvoerwachtrij wordt door de code in het lichaam van de functie ingesteld.

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.

Informatie voor binding van referenties

De Documentatie van Azure Functions bevat naslaginformatie over elk bindingstype. De volgende informatie vindt u in elk bindingsreferentieartikel. (Dit voorbeeld is gebaseerd op een 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 een polling-algoritme of gifwachtrijverwerking.

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 de Azure Functions-runtime.

Kenmerken: Uitschakelen, time-out en Singleton

U kunt deze kenmerken gebruiken om functies te activeren, te annuleren en ervoor te zorgen dat slechts één exemplaar van een functie wordt uitgevoerd.

Kenmerk uitschakelen

Gebruik het Disable kenmerk om te 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 specifiek), wordt de functie niet uitgevoerd. In dat scenario creëert de runtime het logbericht 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.

Timeoutkenmerk

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 Timeout kenmerk. Time-out zorgt ervoor dat de functie na 15 seconden wordt geannuleerd. Wanneer het kenmerk Timeout en de parameter throwOnError is ingesteld op true, wordt de functieaanroep beëindigd door een uitzondering die wordt gegooid door de WebJobs SDK wanneer het timeout-interval wordt overschreden. De standaardwaarde van throwOnError is false. Wanneer het Timeout kenmerk wordt gebruikt, is het standaardgedrag het annuleren van de functieaanroep 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 Timeout kenmerk toepassen op klasseniveau of op 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.

Singleton-attribuut

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 Singleton kenmerk maakt gebruik van gedistribueerde vergrendeling om ervoor te zorgen dat slechts éé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 instantie. 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 de JobHost wordt gestart. Als drie uitgeschaalde exemplaren allemaal tegelijk beginnen, krijgt slechts één van de exemplaren de vergrendeling en wordt slechts één listener gestart.

Notitie

Zie de SingletonMode.Function voor meer informatie over hoe dit 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. Het vergrendelingsbereik (het blob-leasepad) is gekoppeld aan de volledige functienaam. Als u wilt vergrendelen over functies heen, specificeer SingletonScope.Host en gebruik een bereik-id-naam die hetzelfde is voor alle functies die u niet gelijktijdig wilt uitvoeren. In het volgende voorbeeld wordt slechts één exemplaar tegelijk uitgevoerd: AddItem of RemoveItem.

[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 om gedistribueerde vergrendelingen te implementeren. 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.

Annuleringstoken

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

Meerdere gevallen

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 en in samenwerking werk te delen tussen exemplaren, zodat u door uitschaling naar meer exemplaren meer belasting kunt verwerken.

Hoewel sommige triggers kunnen leiden tot dubbele verwerking, voorkomen wachtrij- en blobopslagtriggers automatisch dat een functie een wachtrijbericht of blob meer dan één keer 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.

Filteren

Functiefilters (preview) bieden een manier om de pijplijn voor het uitvoeren van webtaken aan te passen met behulp van uw eigen logica. Deze 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

U wordt aangeraden het logboekregistratieframework te gebruiken 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 is gemaakt, heeft bijbehorende Category en Level waarden. LogLevel is een opsomming en de gehele code geeft het relatieve belang aan:

Logniveau Code
Spoor 0
Fouten opsporen 1
Gegevens 2
Waarschuwing 3
Fout 4
Kritisch 5
Geen 6

U kunt elke categorie onafhankelijk filteren op een bepaalde LogLevel waarde. U wilt bijvoorbeeld alle logboeken voor de 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 filter dat is ingebouwd in .NET Core. Gebruik de LogCategories klasse om categorieën te definiëren voor specifieke functies, triggers of gebruikers. De LogCategories klasse definieert ook filters voor specifieke hoststatussen, zoals Startup en Results, zodat u de uitvoer van logboekregistratie kunt 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. Dus het Debug niveau dat geregistreerd is voor Host.Triggers overeenkomsten Host.Triggers.Queue of Host.Triggers.Blob. U kunt 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 Default waarde bij het bepalen van 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 vergelijkt de huidige categorie met alle geregistreerde CategoryLevels en kiest de langste overeenkomst. Dus het Debug niveau dat geregistreerd is voor Host.Triggers overeenkomsten Host.Triggers.Queue of Host.Triggers.Blob. U kunt 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 afhankelijk is van de generieke .NET Core-host, is een aangepaste telemetriefactory niet langer 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;

U kunt de volgende aangepaste implementatie ITelemetryInitializer gebruiken om uw eigen ITelemetry exemplaar toe te voegen aan de standaardinstelling TelemetryConfiguration.

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

Gebruik ConfigureServices in de bouwer om een aangepaste instantie ITelemetryInitializer toe te voegen aan de pijplijn.

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

Wanneer TelemetryConfiguration wordt samengesteld, worden alle geregistreerde typen ITelemetryInitializer opgenomen. Zie Application Insights-API voor aangepaste gebeurtenissen en metrische gegevens voor meer informatie.

In versie 3.x hoeft u TelemetryClient niet leeg te spoelen wanneer de host stopt. Het .NET Core-afhankelijkheidsinjectiesysteem ruimt automatisch het geregistreerde ApplicationInsightsLoggerProvider exemplaar op, waarmee het TelemetryClient wordt leeggemaakt.

Versie 2.x

In versie 2.x, het TelemetryClient exemplaar dat intern is 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.

TelemetryClient wordt gemaakt door een klasse die ITelemetryClientFactory implementeert. Deze klasse is DefaultTelemetryClientFactorystandaard .

Als u een deel van de pijplijn van Application Insights wilt wijzigen, kunt u een eigen exemplaar van ITelemetryClientFactory gebruiken. De host gebruikt vervolgens uw klasse om te bouwen TelemetryClient. Deze code overschrijft DefaultTelemetryClientFactory om een eigenschap van ServerTelemetryChannel te wijzigen:

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. In dit scenario verzendt Applications Insights in bepaalde scenario's met grote volumes een geselecteerde subset telemetriegegevens naar de server.

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

Verwante inhoud

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.