イベント ドリブンのバックグラウンド処理に Azure WebJobs SDK を使用する方法How to use the Azure WebJobs SDK for event-driven background processing

この記事は、Azure WebJobs SDK を使用する方法のガイダンスを提供します。This article provides guidance on how to work with the Azure WebJobs SDK. WebJobs をすぐに使い始めたい場合は、「イベント ドリブンのバックグラウンド処理で Azure WebJobs SDK の使用を開始する」をご覧ください。To get started with WebJobs right away, see Get started with the Azure WebJobs SDK for event-driven background processing.

WebJobs SDK のバージョンWebJobs SDK versions

WebJobs SDK のバージョン 3.x とバージョン 2.x には、重要な違いがあります。These are the key differences between version 3.x and version 2.x of the WebJobs SDK:

  • バージョン 3.x では、.NET Core のサポートが追加されています。Version 3.x adds support for .NET Core.
  • バージョン 3.x では、WebJobs SDK で必要となるストレージ バインディング拡張機能を明示的にインストールする必要があります。In version 3.x, you need to explicitly install the Storage binding extension required by the WebJobs SDK. バージョン 2.x では、ストレージのバインドは SDK に含まれていました。In version 2.x, the Storage bindings were included in the SDK.
  • .NET Core (3.x) プロジェクト用の Visual Studio のツールは、.NET Framework (2.x) プロジェクト用のツールと異なります。Visual Studio tooling for .NET Core (3.x) projects differs from tooling for .NET Framework (2.x) projects. 詳しくは、「Visual Studio を使用して Web ジョブを開発してデプロイする - Azure App Service」をご覧ください。To learn more, see Develop and deploy WebJobs using Visual Studio - Azure App Service.

可能な場合は、バージョン 3.x とバージョン 2.x 両方の例が提供されています。When possible, examples are provided for both version 3.x and version 2.x.

注意

Azure Functions は WebJobs SDK でビルドされており、この記事では Azure Functions ドキュメントの一部のトピックへのリンクが提供されています。Azure Functions is built on the WebJobs SDK, and this article provides links to Azure Functions documentation for some topics. Functions と WebJobs SDK の以下の違いに注意してください。Note these differences between Functions and the WebJobs SDK:

  • Azure Functions バージョン 2.x は WebJobs SDK バージョン 3.x に対応しており、Azure Functions 1.x は WebJobs SDK 2.x に対応しています。Azure Functions version 2.x corresponds to WebJobs SDK version 3.x, and Azure Functions 1.x corresponds to WebJobs SDK 2.x. ソース コード リポジトリでは、WebJobs SDK の番号付けが使用されています。Source code repositories use the WebJobs SDK numbering.
  • Azure Functions C# クラス ライブラリのサンプル コードは、WebJobs SDK プロジェクトに FunctionName 属性が必要ないということ以外は、WebJobs SDK コードに類似しています。Sample code for Azure Functions C# class libraries is like WebJobs SDK code, except you don't need a FunctionName attribute in a WebJobs SDK project.
  • バインドの種類の一部は、HTTP (Webhook) や (HTTP に基づく) Event Grid などの Functions でのみサポートされます。Some binding types are supported only in Functions, like HTTP (Webhooks) and Event Grid (which is based on HTTP).

詳しくは、WebJobs SDK と Azure Functions の比較に関するページをご覧ください。For more information, see Compare the WebJobs SDK and Azure Functions.

WebJobs ホストWebJobs host

このホストは、関数のランタイム コンテナーです。The host is a runtime container for functions. トリガーをリッスンして関数を呼び出します。It listens for triggers and calls functions. バージョン 3.x では、ホストは IHost の実装です。In version 3.x, the host is an implementation of IHost. バージョン 2.x では、JobHost オブジェクトを使用します。In version 2.x, you use the JobHost object. コードでホスト インスタンスを作成し、その動作をカスタマイズするコードを書きます。You create a host instance in your code and write code to customize its behavior.

これが、直接 WebJobs SDK を使用することと、Azure Functions によって間接的に使用することの主な違いです。This is a key difference between using the WebJobs SDK directly and using it indirectly through Azure Functions. Azure Functions では、サービスがホストを制御するので、コードを書いてホストをカスタマイズすることはできません。In Azure Functions, the service controls the host, and you can't customize the host by writing code. Azure Functions では、host.json ファイルの設定を使用してホスト動作をカスタマイズできます。Azure Functions lets you customize host behavior through settings in the host.json file. これらの設定はコードではなく文字列なので、行うことができるカスタマイズの種類が制限されます。Those settings are strings, not code, and this limits the kinds of customizations you can do.

ホスト接続文字列Host connection strings

WebJobs SDK では、Azure Storage と Azure Service Bus の接続文字列は、ローカルで実行するときは local.settings.json ファイルで検索され、Azure で実行するときは WebJob の環境で検索されます。The WebJobs SDK looks for Azure Storage and Azure Service Bus connection strings in the local.settings.json file when you run locally, or in the environment of the WebJob when you run in Azure. 既定で、AzureWebJobsStorage という名前のストレージ接続文字列設定が必要です。By default, a storage connection string setting named AzureWebJobsStorage is required.

SDK のバージョン 2.x を使用すると、これらの接続文字列に独自の名前を使用したり、それらを他の場所に格納したりできます。Version 2.x of the SDK lets you use your own names for these connection strings or store them elsewhere. 次に示すように、JobHostConfiguration を使用してコードで名前を設定できます。You can set names in code using the JobHostConfiguration, as shown here:

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

バージョン 3.x では、既定の .NET Core 構成 API が使用されるため、接続文字列の名前を変更する API はありません。Because version 3.x uses the default .NET Core configuration APIs, there is no API to change connection string names.

ホスト開発設定Host development settings

ローカル開発をより効率的にするために、開発モードでホストを実行できます。You can run the host in development mode to make local development more efficient. 開発モードで実行しているときに変更されるいくつかの設定を以下に示します。Here are some of the settings that are changed when you run in development mode:

プロパティProperty 開発設定Development setting
Tracing.ConsoleLevel TraceLevel.Verbose でログ出力を最大化します。TraceLevel.Verbose to maximize log output.
Queues.MaxPollingInterval キューのメソッドがすぐにトリガーされるように、値は低くしてあります。A low value to ensure queue methods are triggered immediately.
Singleton.ListenerLockPeriod 素早い反復開発の支援は 15 秒です。15 seconds to aid in rapid iterative development.

開発モードを有効にするプロセスは、SDK のバージョンによって異なります。The process for enabling development mode depends on the SDK version.

バージョン 3.xVersion 3.x

バージョン 3.x では、標準の ASP.NET Core API が使用されます。Version 3.x uses the standard ASP.NET Core APIs. HostBuilder インスタンスで UseEnvironment メソッドを呼び出します。Call the UseEnvironment method on the HostBuilder instance. 次の例のように、development という名前の文字列を渡します。Pass a string named development, as in this example:

static void Main()
{
    var builder = new HostBuilder();
    builder.UseEnvironment("development");
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
            });
    var host = builder.Build();
    using (host)
    {
        host.Run();
    }
}

バージョン 2.xVersion 2.x

JobHostConfiguration クラスには、開発モードを有効にする UseDevelopmentSettings メソッドがあります。The JobHostConfiguration class has a UseDevelopmentSettings method that enables development mode. 次の例では、開発設定を使用する方法を示します。The following example shows how to use development settings. ローカル環境で実行したときは config.IsDevelopmenttrue を返すようにするには、AzureWebJobsEnv という名前で値が Development のローカル環境変数を設定します。To make config.IsDevelopment return true when it runs locally, set a local environment variable named AzureWebJobsEnv with the value Development.

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

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

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

コンカレント接続の管理 (バージョン 2.x)Managing concurrent connections (version 2.x)

バージョン 3.x では、接続制限は既定で無限接続に設定されます。In version 3.x, the connection limit defaults to infinite connections. 何らかの理由でこの制限を変更する必要がある場合は、WinHttpHandler クラス の MaxConnectionsPerServer プロパティを使用できます。If for some reason you need to change this limit, you can use the MaxConnectionsPerServer property of the WinHttpHandler class.

バージョン 2.x では、ServicePointManager.DefaultConnectionLimit API を使用して、ホストへのコンカレント接続の数を制御します。In version 2.x, you control the number of concurrent connections to a host by using the ServicePointManager.DefaultConnectionLimit API. バージョン 2.x では、WebJobs ホストを開始する前に、この値を既定値の 2 から増加してください。In 2.x, you should increase this value from the default of 2 before starting your WebJobs host.

HttpClient を使用することで関数から送信するすべての HTTP 要求は、ServicePointManager を通過します。All outgoing HTTP requests that you make from a function by using HttpClient flow through ServicePointManager. DefaultConnectionLimit で設定されている値に達した後は、ServicePointManager では送信する前に要求をキューに格納するようになります。After you reach the value set in DefaultConnectionLimit, ServicePointManager starts queueing requests before sending them. たとえば、DefaultConnectionLimit が 2 に設定されていて、コードが 1,000 個の HTTP 要求を行ったとします。Suppose your DefaultConnectionLimit is set to 2 and your code makes 1,000 HTTP requests. 最初、OS への送信が許可されるのは 2 個の要求のみです。Initially, only two requests are allowed through to the OS. その他の 998 個は、余裕ができるまでキューされたままになります。The other 998 are queued until there’s room for them. つまり、要求を行ったように見えても、OS によって宛先サーバーに要求が送信されなかったため、HttpClient がタイムアウトする可能性があります。That means your HttpClient might time out because it appears to have made the request, but the request was never sent by the OS to the destination server. 従って、ローカルの HttpClient は、要求を完了するのに 10 秒間かかっているのに、サービスはどの要求も 200 ミリ秒で返しているというような、あまり意味をなさないように見える動作が目撃されることがあります。So you might see behavior that doesn't seem to make sense: your local HttpClient is taking 10 seconds to complete a request, but your service is returning every request in 200 ms.

ASP.NET アプリケーションの既定値は Int32.MaxValue であり、これは Basic またはそれ以降の App Service プランで実行されている WebJobs で適切に動作します。The default value for ASP.NET applications is Int32.MaxValue, and that's likely to work well for WebJobs running in a Basic or higher App Service Plan. WebJobs は通常、Always On の設定を必要としており、これは Basic またはそれ以降の App Service プランでのみサポートされています。WebJobs typically need the Always On setting, and that's supported only by Basic and higher App Service Plans.

Web ジョブが Free または Shared App Service プランで実行されている場合、アプリケーションは、現在 300 の接続制限を持つ App Service サンドボックスにより制限されています。If your WebJob is running in a Free or Shared App Service Plan, your application is restricted by the App Service sandbox, which currently has a connection limit of 300. ServicePointManager の設定がバインドなしの接続制限の場合、サンドボックスの接続がしきい値に達し、サイトがシャット ダウンする可能性が高くなります。With an unbound connection limit in ServicePointManager, it's more likely that the sandbox connection threshold will be reached and the site will shut down. その場合は、DefaultConnectionLimitの設定を 50 または 100 のようにより低いものにすることで、これを防ぎつつ十分なスループットを可能にします。In that case, setting DefaultConnectionLimit to something lower, like 50 or 100, can prevent this from happening and still allow for sufficient throughput.

あらゆる HTTP 要求が行われる前に、この設定を構成する必要があります。The setting must be configured before any HTTP requests are made. このため、WebJobs ホストでは設定を自動的に調整しないでください。For this reason, the WebJobs host shouldn't adjust the setting automatically. ホストが開始する前に HTTP 要求が発生する可能性があり、予期しない動作を招くことがあります。There could be HTTP requests that occur before the host starts, which could lead to unexpected behavior. 最善の方法は、次に示すように、JobHost を初期化する前に Main メソッドですぐに値を設定することです。The best approach is to set the value immediately in your Main method before initializing JobHost, as shown here:

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

関数は、パブリック メソッドである必要があり、1 つのトリガー属性または NoAutomaticTrigger 属性を必要とします。Functions must be public methods and must have one trigger attribute or the NoAutomaticTrigger attribute.

自動トリガーAutomatic triggers

自動トリガーは、イベントに応答して関数を呼び出します。Automatic triggers call a function in response to an event. Azure Queue Storage に追加されるメッセージによってトリガーされる次の例のような関数について考えます。Consider this example of a function that's triggered by a message added to Azure Queue storage. それは、Azure Blob Storage から BLOB を読み取ることで応答します。It responds by reading a blob from Azure Blob storage:

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

QueueTrigger 属性は、キュー メッセージが myqueue-items キューに出現するたびに関数を呼び出すようランタイムに通知します。The QueueTrigger attribute tells the runtime to call the function whenever a queue message appears in the myqueue-items queue. Blob 属性は、キュー メッセージを使用して sample-workitems コンテナー内の BLOB を読み取るようランタイムに通知します。The Blob attribute tells the runtime to use the queue message to read a blob in the sample-workitems container. myQueueItem パラメーターで関数に渡されるキュー メッセージの内容は、BLOB の名前です。The content of the queue message, passed in to the function in the myQueueItem parameter, is the name of the blob.

注意

Web アプリは、20 分間アクティビティがないとタイムアウトする可能性があります。A web app can time out after 20 minutes of inactivity. タイマーがリセットされるのは、実際の Web アプリに要求があった場合のみです。Only requests to the actual web app reset the timer. Azure portal でアプリの構成を表示したり、高度なツールのサイト (https://<app_name>.scm.azurewebsites.net) に対して要求を行っても、タイマーはリセットされません。Viewing the app's configuration in the Azure portal or making requests to the advanced tools site (https://<app_name>.scm.azurewebsites.net) don't reset the timer. アプリが継続的またはスケジュールに従って (タイマー トリガー) Web ジョブを実行する場合は、Always On を有効にして、Web ジョブが確実に実行されるようにします。If your app runs continuous or scheduled (Timer trigger) WebJobs, enable Always On to ensure that the WebJobs run reliably. この機能は、Basic、Standard、および Premium の価格レベルでのみ利用できます。This feature is available only in the Basic, Standard, and Premium pricing tiers.

手動トリガーManual triggers

関数を手動でトリガーするには、次に示すように、NoAutomaticTrigger 属性を使用します。To trigger a function manually, use the NoAutomaticTrigger attribute, as shown here:

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

関数を手動でトリガーするプロセスは、SDK のバージョンによって異なります。The process for manually triggering the function depends on the SDK version.

バージョン 3.xVersion 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();
    }
}

バージョン 2.xVersion 2.x

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

入出力バインドInput and output bindings

入力バインドは、Azure やサード パーティ サービスからのデータをコードに使用できるようにする宣言方法を提供します。Input bindings provide a declarative way to make data from Azure or third-party services available to your code. 出力バインドは、データを更新する方法を提供します。Output bindings provide a way to update data. WebJobs SDK の使用開始に関するページでは、それぞれの例が示されています。The Get started article shows an example of each.

出力バインドに対してメソッドの戻り値を使用するには、属性をメソッドの戻り値に適用します。You can use a method return value for an output binding by applying the attribute to the method return value. Azure 関数の戻り値の使用」の例をご覧ください。See the example in Using the Azure Function return value.

バインドの種類Binding types

バインドの種類をインストールして管理するプロセスは、バージョン 3.x またはバージョン 2.x のどちらの SDK を使用しているかによって異なります。The process for installing and managing binding types depends on whether you're using version 3.x or version 2.x of the SDK. 特定のバインドの種類用にインストールするパッケージは、Azure Functions のそのバインドの種類の参照資料の「パッケージ」セクションで見つけることができます。You can find the package to install for a particular binding type in the "Packages" section of that binding type's Azure Functions reference article. 例外は (ローカル ファイル システム用の) Files トリガーとバインドで、これは Azure Functions ではサポートされていません。An exception is the Files trigger and binding (for the local file system), which isn't supported by Azure Functions.

バージョン 3.xVersion 3.x

バージョン 3.xMicrosoft.Azure.WebJobs.Extensions.Storage では、ストレージのバインドは パッケージに含まれています。In version 3.x, the storage bindings are included in the Microsoft.Azure.WebJobs.Extensions.Storage package. 次に示すように、ConfigureWebJobs メソッドで AddAzureStorage 拡張メソッドを呼び出します。Call the AddAzureStorage extension method in the ConfigureWebJobs method, as shown here:

static void Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddAzureStorage();
            });
    var host = builder.Build();
    using (host)
    {
        host.Run();
    }
}

他のトリガーやバインドの種類を使用するには、それらを含む NuGet パッケージをインストールして、拡張で実装されている Add<binding> 拡張メソッドを呼び出します。To use other trigger and binding types, install the NuGet package that contains them and call the Add<binding> extension method implemented in the extension. たとえば、Azure Cosmos DB バインドを使用する場合は、次のように、Microsoft.Azure.WebJobs.Extensions.CosmosDB をインストールして AddCosmosDB を呼び出します。For example, if you want to use an Azure Cosmos DB binding, install Microsoft.Azure.WebJobs.Extensions.CosmosDB and call AddCosmosDB, like this:

static void Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddCosmosDB();
            });
    var host = builder.Build();
    using (host)
    {
        host.Run();
    }
}

コア サービスの一部である Timer トリガーまたは Files バインドを使用するには、それぞれ AddTimers 拡張メソッドまたは AddFiles 拡張メソッドを呼び出します。To use the Timer trigger or the Files binding, which are part of core services, call the AddTimers or AddFiles extension methods, respectively.

バージョン 2.xVersion 2.x

次のトリガーおよびバインドの種類は、Microsoft.Azure.WebJobs パッケージのバージョン 2.x に含まれています。These trigger and binding types are included in version 2.x of the Microsoft.Azure.WebJobs package:

  • BLOB ストレージBlob storage
  • ストレージQueue storage
  • テーブル ストレージTable storage

その他の種類のトリガーやバインドを使用するには、それらを含む NuGet パッケージをインストールして、JobHostConfiguration オブジェクトの Use<binding> メソッドを呼び出します。To use other trigger and binding types, install the NuGet package that contains them and call a Use<binding> method on the JobHostConfiguration object. たとえば、Timer トリガーを使用する場合は、次のように、Microsoft.Azure.WebJobs.Extensions をインストールして、Main メソッドで UseTimers を呼び出します。For example, if you want to use a Timer trigger, install Microsoft.Azure.WebJobs.Extensions and call UseTimers in the Main method, as shown here:

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

Files バインドを使用するには、Microsoft.Azure.WebJobs.Extensions をインストールして UseFiles を呼び出します。To use the Files binding, install Microsoft.Azure.WebJobs.Extensions and call UseFiles.

ExecutionContextExecutionContext

WebJobs を使用すると、ExecutionContext にバインドできます。WebJobs lets you bind to an ExecutionContext. このバインディングを使用すると、関数シグネチャのパラメーターとして ExecutionContext にアクセスできます。With this binding, you can access the ExecutionContext as a parameter in your function signature. たとえば、次のコードはコンテキスト オブジェクトを使用して呼び出し ID にアクセスします。その呼び出し ID を使用すると、特定の関数呼び出しによって生成されたすべてのログを関連付けることができます。For example, the following code uses the context object to access the invocation ID, which you can use to correlate all logs produced by a given function invocation.

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

ExecutionContext にバインドするプロセスは、SDK のバージョンによって異なります。The process for binding to the ExecutionContext depends on your SDK version.

バージョン 3.xVersion 3.x

次に示すように、ConfigureWebJobs メソッドで AddExecutionContextBinding 拡張メソッドを呼び出します。Call the AddExecutionContextBinding extension method in the ConfigureWebJobs method, as shown here:

static void Main()
{
    var builder = new HostBuilder();
    builder.ConfigureWebJobs(b =>
            {
                b.AddAzureStorageCoreServices();
                b.AddExecutionContextBinding();
            });
    var host = builder.Build();
    using (host)
    {
        host.Run();
    }
}

バージョン 2.xVersion 2.x

先述した Microsoft.Azure.WebJobs.Extensions パッケージは、UseCore メソッドを呼び出すことによって登録できる特別なバインドの種類も提供しています。The Microsoft.Azure.WebJobs.Extensions package mentioned earlier also provides a special binding type that you can register by calling the UseCore method. このバインドを使用すると、関数シグネチャで ExecutionContext パラメーターを定義でき、それは次のように有効化されます。This binding lets you define an ExecutionContext parameter in your function signature, which is enabled like this:

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

バインド構成Binding configuration

一部のトリガーとバインドの動作を構成することができます。You can configure the behavior of some triggers and bindings. それらを構成するプロセスは、SDK のバージョンによって異なります。The process for configuring them depends on the SDK version.

  • バージョン 3.x: ConfigureWebJobsAdd<Binding> メソッドを 呼び出すときに、構成を設定します。Version 3.x: Set configuration when the Add<Binding> method is called in ConfigureWebJobs.
  • バージョン 2.x: JobHost に渡す構成オブジェクトでプロパティを設定することにより、構成を設定します。Version 2.x: Set configuration by setting properties in a configuration object that you pass in to JobHost.

これらのバインド固有の設定は、Azure Functions の host.json プロジェクト ファイルでの設定と同等です。These binding-specific settings are equivalent to settings in the host.json project file in Azure Functions.

次のバインドを構成できます。You can configure the following bindings:

Azure CosmosDB トリガーの構成 (バージョン 3.x)Azure CosmosDB trigger configuration (version 3.x)

次の例では、Azure Cosmos DB トリガーを構成する方法を示します。This example shows how to configure the Azure Cosmos DB trigger:

static void 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)
    {

        host.Run();
    }
}

詳しくは、Azure CosmosDB のバインドに関する記事をご覧ください。For more details, see the Azure CosmosDB binding article.

Event Hubs トリガーの構成 (バージョン 3.x)Event Hubs trigger configuration (version 3.x)

次の例では、Event Hubs トリガーを構成する方法を示します。This example shows how to configure the Event Hubs trigger:

static void 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)
    {

        host.Run();
    }
}

詳しくは、Event Hubs のバインドに関する記事をご覧ください。For more details, see the Event Hubs binding article.

Queue Storage トリガーの構成Queue storage trigger configuration

以下の例では、Queue Storage トリガーを構成する方法を示します。These examples show how to configure the Queue storage trigger:

バージョン 3.xVersion 3.x

static void 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)
    {

        host.Run();
    }
}

詳しくは、Queue Storage のバインドに関する記事をご覧ください。For more details, see the Queue storage binding article.

バージョン 2.xVersion 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();
}

詳しくは、host.json v1.x のリファレンスをご覧ください。For more details, see the host.json v1.x reference.

SendGrid バインドの構成 (バージョン 3.x)SendGrid binding configuration (version 3.x)

次の例では、SendGrid 出力バインドを構成する方法を示します。This example shows how to configure the SendGrid output binding:

static void 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)
    {

        host.Run();
    }
}

詳しくは、SendGrid のバインドに関する記事をご覧ください。For more details, see the SendGrid binding article.

Service Bus トリガーの構成 (バージョン 3.x)Service Bus trigger configuration (version 3.x)

次の例では、Service Bus トリガーを構成する方法を示します。This example shows how to configure the Service Bus trigger:

static void 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)
    {

        host.Run();
    }
}

詳しくは、Service Bus のバインドに関する記事をご覧ください。For more details, see the Service Bus binding article.

その他のバインドの構成Configuration for other bindings

一部のトリガーとバインドの種類では、独自のカスタム構成の種類が定義されています。Some trigger and binding types define their own custom configuration types. たとえば、次の例に示すように、File トリガーを使用して、監視するルート パスを指定することができます。For example, the File trigger lets you specify the root path to monitor, as in these examples:

バージョン 3.xVersion 3.x

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

        host.Run();
    }
}

バージョン 2.xVersion 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();
}

バインド式Binding expressions

属性コンス トラクターのパラメーターでは、さまざまなソースからの値に解決する式を使用することができます。In attribute constructor parameters, you can use expressions that resolve to values from various sources. たとえば、次のコードで BlobTrigger 属性のパスは、filename という名前の式を作成します。For example, in the following code, the path for the BlobTrigger attribute creates an expression named filename. これが出力バインドに使用されると、filename はトリガーする BLOB の名前に解決します。When used for the output binding, filename resolves to the name of the triggering 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}");
    // ...
}

バインド式の詳細については、Azure Functions ドキュメント内のバインド式とパターンを参照してください。For more information about binding expressions, see Binding expressions and patterns in the Azure Functions documentation.

カスタム バインド式Custom binding expressions

キュー名、BLOB 名、コンテナー、テーブル名をハードコーディングではなく、コードに指定する場合もあります。Sometimes you want to specify a queue name, a blob name or container, or a table name in code rather than hard-coding it. たとえば、構成ファイルや環境変数で QueueTrigger 属性のキュー名を指定するとします。For example, you might want to specify the queue name for the QueueTrigger attribute in a configuration file or environment variable.

これは、NameResolver オブジェクトを JobHostConfiguration オブジェクトに渡すことでできます。You can do that by passing a NameResolver object in to the JobHostConfiguration object. プレースホルダーをトリガーやバインド属性コンストラクターのパラメーターに含めると、これらのプレースホルダーの代わりに使用する実際の値が NameResolver コードにより提供されます。You include placeholders in trigger or binding attribute constructor parameters, and your NameResolver code provides the actual values to be used in place of those placeholders. 次に示すように、プレースホルダーはパーセント (%) 記号で囲んで示します。You identify placeholders by surrounding them with percent (%) signs, as shown here:

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

このコードを使用すると、logqueuetest という名前のキューをテスト環境で使用でき、logqueueprod という名前のキューを実稼働環境で使用できます。This code lets you use a queue named logqueuetest in the test environment and one named logqueueprod in production. キュー名をハードコードする代わりに、appSettings コレクションのエントリの名前を指定します。Instead of a hard-coded queue name, you specify the name of an entry in the appSettings collection.

カスタムの名前を提供しない場合、既定の NameResolver が使用されます。There's a default NameResolver that takes effect if you don't provide a custom one. 既定値は、アプリの設定や環境変数から値を取得します。The default gets values from app settings or environment variables.

次のように、NameResolver クラスでは appSettings からキューの名前が取得されます。Your NameResolver class gets the queue name from appSettings, as shown here:

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

バージョン 3.xVersion 3.x

リゾルバーは、依存関係インジェクションを使用して構成します。You configure the resolver by using dependency injection. これらのサンプルには、次の using ステートメントが必要です。These samples require the following using statement:

using Microsoft.Extensions.DependencyInjection;

次の例のように、HostBuilderConfigureServices 拡張メソッドを呼び出すことによって、リゾルバーを追加します。You add the resolver by calling the ConfigureServices extension method on HostBuilder, as in this example:

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

バージョン 2.xVersion 2.x

次に示すように、NameResolver クラスを JobHost オブジェクトに渡します。Pass your NameResolver class in to the JobHost object, as shown here:

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

Azure Functions では、次の例に示すように、アプリの設定から値を取得するために INameResolver が実装されます。Azure Functions implements INameResolver to get values from app settings, as shown in the example. WebJobs SDK を直接使用する場合は、お好みのソースからプレースホルダーの置換値を取得するカスタム実装を記述できます。When you use the WebJobs SDK directly, you can write a custom implementation that gets placeholder replacement values from whatever source you prefer.

実行時のバインドBinding at runtime

QueueBlobTable などのバインド属性を使用する前に関数で何らかの処理を行う必要がある場合は、IBinder インターフェイスを使用できます。If you need to do some work in your function before you use a binding attribute like Queue, Blob, or Table, you can use the IBinder interface.

次の例では、入力キュー メッセージを取得して同じ内容の新しい出力キュー メッセージを作成します。The following example takes an input queue message and creates a new message with the same content in an output queue. 出力キュー名は、関数本体のコードによって設定されます。The output queue name is set by code in the body of the function.

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

詳細については、Azure Functions ドキュメント内の実行時のバインドを参照してください。For more information, see Binding at runtime in the Azure Functions documentation.

バインド参照情報Binding reference information

Azure Functions のドキュメントでは、各バインドの種類に関する参照情報が提供されています。The Azure Functions documentation provides reference information about each binding type. 各バインド参照記事には、以下の情報が記載されています。You'll find the following information in each binding reference article. (この例は、Storage キューに基づいています。)(This example is based on Storage queue.)

  • パッケージPackages. WebJobs SDK プロジェクトにバインドのサポートを含めるためにインストールする必要のあるパッケージです。The package you need to install to include support for the binding in a WebJobs SDK project.
  • Examples. コード サンプルです。Code samples. C# クラス ライブラリの例は、WebJobs SDK に適用されます。The C# class library example applies to the WebJobs SDK. FunctionName 属性は単に省略します。Just omit the FunctionName attribute.
  • 属性Attributes. バインドの種類に使用する属性です。The attributes to use for the binding type.
  • 構成Configuration. 属性のプロパティとコンストラクターのパラメーターの説明です。Explanations of the attribute properties and constructor parameters.
  • [使用状況]:Usage. どの種類にバインドできるかとバインドの動作方法に関する情報です。The types you can bind to and information about how the binding works. 例: ポーリング アルゴリズム、有害キュー処理。For example: polling algorithm, poison queue processing.

バインドの参照記事の一覧については、Azure Functions のトリガーとバインドに関する記事の「サポートされるバインディング」をご覧ください。For a list of binding reference articles, see "Supported bindings" in the Triggers and bindings article for Azure Functions. その一覧では、HTTP、Webhook、Event Grid のバインドは、Azure Functions でのみサポートされており、WebJobs SDK ではサポートされていません。In that list, the HTTP, Webhooks, and Event Grid bindings are supported only by Azure Functions, not by the WebJobs SDK.

Disable 属性Disable attribute

Disable 属性は、関数がトリガーされるかどうかを制御します。The Disable attribute lets you control whether a function can be triggered.

次の例では、アプリ設定 Disable_TestJob の値が 1 または True (大文字小文字の区別なし) の場合、関数は実行されません。In the following example, if the app setting Disable_TestJob has a value of 1 or True (case insensitive), the function won't run. その場合、ランタイムが関数 'Functions.TestJob' が無効ですというログ メッセージを作成します。In that case, the runtime creates a log message Function 'Functions.TestJob' is disabled.

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

Azure portal でアプリ設定の値を変更すると、WebJobs が再起動され、新しい設定が取得されます。When you change app setting values in the Azure portal, the WebJob restarts to pick up the new setting.

属性は、パラメーター、メソッド、またはクラス レベルで宣言できます。The attribute can be declared at the parameter, method, or class level. 設定名には、バインド式を含めることもできます。The setting name can also contain binding expressions.

Timeout 属性Timeout attribute

Timeout 属性は、関数が指定した時間内に完了しない場合にキャンセルします。The Timeout attribute causes a function to be canceled if it doesn't finish within a specified amount of time. 次の例では、関数は Timeout 属性なしで 1 日間実行されます。In the following example, the function would run for one day without the Timeout attribute. Timeout があると、関数は 15 秒後に取り消されます。Timeout causes the function to be canceled after 15 seconds.

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

クラスまたはメソッド レベルで Timeout 属性を適用し、JobHostConfiguration.FunctionTimeout を使用してグローバル タイムアウトを指定することができます。You can apply the Timeout attribute at the class or method level, and you can specify a global timeout by using JobHostConfiguration.FunctionTimeout. クラス レベルまたはメソッド レベルのタイムアウトは、グローバル タイムアウトをオーバーライドします。Class-level or method-level timeouts override global timeouts.

Singleton 属性Singleton attribute

Singleton 属性を使用すると、ホスト Web アプリの複数のインスタンスがある場合でも、関数の 1 つのインスタンスのみが実行されます。The Singleton attribute ensures that only one instance of a function runs, even when there are multiple instances of the host web app. これは、分散ロックを使用することにより行われます。It does this by using distributed locking.

次の例では、常に ProcessImage 関数の単一のインスタンスのみが実行されます。In this example, only a single instance of the ProcessImage function runs at any given time:

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

SingletonMode.ListenerSingletonMode.Listener

一部のトリガーには、コンカレンシー管理の組み込みサポートがあります。Some triggers have built-in support for concurrency management:

  • QueueTriggerQueueTrigger. JobHostConfiguration.Queues.BatchSize1 に設定します。Set JobHostConfiguration.Queues.BatchSize to 1.
  • ServiceBusTriggerServiceBusTrigger. ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls1 に設定します。Set ServiceBusConfiguration.MessageOptions.MaxConcurrentCalls to 1.
  • FileTriggerFileTrigger. FileProcessor.MaxDegreeOfParallelism1 に設定します。Set FileProcessor.MaxDegreeOfParallelism to 1.

これらの設定を使用すると、単一のインスタンスで、関数がシングルトンとして実行されるようになります。You can use these settings to ensure that your function runs as a singleton on a single instance. Web アプリが複数のインスタンスにスケールアウトするとき、関数の単一のインスタンスのみが実行されるようにするには、関数にリスナー レベルのシングルトン ロック ([Singleton(Mode = SingletonMode.Listener)]) を適用します。To ensure that only a single instance of the function is running when the web app scales out to multiple instances, apply a listener-level singleton lock on the function ([Singleton(Mode = SingletonMode.Listener)]). リスナー ロックは、JobHost の起動時に取得されます。Listener locks are acquired when the JobHost starts. 3 つのスケール アウト インスタンスのすべてが同時に開始すると、1 つのインスタンスのみがロックを取得して、1 つのみがリスナーを開始します。If three scaled-out instances all start at the same time, only one of the instances acquires the lock and only one listener starts.

スコープ値Scope values

シングルトンで "スコープ式/値" を指定することができます。You can specify a scope expression/value on a singleton. 式/値により、特定スコープでの関数のすべての実行がシリアル化されることが保証されます。The expression/value ensures that all executions of the function at a specific scope will be serialized. この方法で詳細なロックを実装すると、要件によって指示されたように他の呼び出しをシリアル化すると同時に、関数のある程度の並列処理が可能になります。Implementing more granular locking in this way can allow for some level of parallelism for your function while serializing other invocations as dictated by your requirements. たとえば、次のコードでは、スコープ式は、受信メッセージの Region 値 にバインドしています。For example, in the following code, the scope expression binds to the Region value of the incoming message. キューに 3 つのメッセージが含まれ、それぞれ East、East、West リージョンである場合、East リージョンのメッセージは順次実行されますが、West リージョンのメッセージは East のメッセージと並列に実行されます。When the queue contains three messages in regions East, East, and West respectively, the messages that have region East are run serially while the message with region West is run in parallel with those in East.

[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.HostSingletonScope.Host

ロックの既定スコープは SingletonScope.Function です。つまり、ロック スコープ (BLOB のリース パス) は、関数の完全修飾名に関連付けられています。The default scope for a lock is SingletonScope.Function, meaning the lock scope (the blob lease path) is tied to the fully qualified function name. 複数の関数にわたってロックするには、SingletonScope.Host を指定して、同時に実行したくない関数すべてと同じスコープ ID 名を使用します。To lock across functions, specify SingletonScope.Host and use a scope ID name that's the same across all functions that you don't want to run simultaneously. 次の例では、 AddItem または RemoveItemの1 つのみのインスタンス が一度に実行されます。In the following example, only one instance of AddItem or RemoveItem runs at a time:

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

リース BLOB のビューViewing lease blobs

WebJobs SDK は、バックグラウンドで Azure BLOB リースを使用して、分散ロックを実装します。The WebJobs SDK uses Azure blob leases under the covers to implement distributed locking. Singleton により使用されるリース BLOB は、パス "locks" にある AzureWebJobsStorage ストレージ アカウント内の azure-webjobs-host コンテナーにあります。The lease blobs used by Singleton can be found in the azure-webjobs-host container in the AzureWebJobsStorage storage account under the path "locks". たとえば、先に示した最初の ProcessImage の例のリース BLOB パスは、locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage です。For example, the lease blob path for the first ProcessImage example shown earlier might be locks/061851c758f04938a4426aa9ab3869c0/WebJobs.Functions.ProcessImage. どのパスにも JobHost ID が含まれています。この場合は、061851c758f04938a4426aa9ab3869c0 になります。All paths include the JobHost ID, in this case 061851c758f04938a4426aa9ab3869c0.

Async 関数Async functions

Async 関数のコードを書く方法については、Azure Functions のドキュメントをご覧ください。For information about how to code async functions, see the Azure Functions documentation.

キャンセル トークンCancellation tokens

キャンセル トークンを処理する方法については、Azure Functions ドキュメントのキャンセル トークンと正常なシャットダウンを参照してください。For information about how to handle cancellation tokens, see the Azure Functions documentation on cancellation tokens and graceful shutdown.

複数のインスタンスMultiple instances

Web アプリが複数のインスタンス上で稼働している場合、継続的な Web ジョブは各インスタンスで実行され、トリガーをリッスンして関数の呼び出しを行います。If your web app runs on multiple instances, a continuous WebJob runs on each instance, listening for triggers and calling functions. 各種のトリガー バインドは、インスタンス間で協調して作業を効率的に共有するよう設計されているので、より多くのインスタンスにスケール アウトすると、より多くの負荷を処理することができます。The various trigger bindings are designed to efficiently share work collaboratively across instances, so that scaling out to more instances allows you to handle more load.

一部のトリガーで二重の処理が発生する可能性がありますが、キューと BLOB ストレージ トリガーでは、関数がキュー メッセージや BLOB を 2 回以上処理することが自動的に防止されます。While some triggers may result in double-processing, queue and blob storage triggers automatically prevent a function from processing a queue message or blob more than once. 詳細については、Azure Functions ドキュメントの同一入力のための設計に関する記事を参照してください。For more information, see Designing for identical input in the Azure Functions documentation.

タイマー トリガーは、指定された時刻に常に 1 つを超える関数のインスタンスが実行しないように、自動的に タイマーの1 つのインスタンスのみが実行するようにします。The timer trigger automatically ensures that only one instance of the timer runs, so you don't get more than one function instance running at a given scheduled time.

ホスト Web アプリの複数のインスタンスがある場合でも、関数の 1 つのインスタンスのみを実行するには Singleton 属性を使用できます。If you want to ensure that only one instance of a function runs even when there are multiple instances of the host web app, you can use the Singleton attribute.

フィルターFilters

関数のフィルター (プレビュー) は、独自のロジックで WebJobs 実行パイプラインをカスタマイズする方法を提供します。Function Filters (preview) provide a way to customize the WebJobs execution pipeline with your own logic. フィルターは ASP.NET Core フィルターに似ています。Filters are similar to ASP.NET Core filters. 関数またはクラスに適用される宣言型の属性として実装することができます。You can implement them as declarative attributes that are applied to your functions or classes. 詳細については、関数フィルターを参照してください。For more information, see Function Filters.

ログ記録と監視Logging and monitoring

ASP.NET 用に開発されたログ記録フレームワークをお勧めします。We recommend the logging framework that was developed for ASP.NET. 使用方法については、使用の開始に関する記事をご覧ください。The Get started article shows how to use it.

ログのフィルタリングLog filtering

ILogger インスタンスによって作成されたすべてのログには、関連付けられた CategoryLevel があります。Every log created by an ILogger instance has an associated Category and Level. LogLevel は列挙型で、整数コードは次のような相対的な重要度を示します。LogLevel is an enumeration, and the integer code indicates relative importance:

LogLevelLogLevel コードCode
TraceTrace 00
デバッグDebug 11
InformationInformation 22
警告Warning 33
ErrorError 44
重大Critical 55
なしNone 66

各カテゴリを特定の LogLevel に個別にフィルター処理できます。You can independently filter each category to a particular LogLevel. たとえば、BLOB トリガー処理のすべてのログを表示するが、それ以外に関しては Error 以降のみを表示するなどが可能です。For example, you might want to see all logs for blob trigger processing but only Error and higher for everything else.

バージョン 3.xVersion 3.x

SDK のバージョン 3.x は、.NET Core に組み込まれているフィルタリングに依存しています。Version 3.x of the SDK relies on the filtering built into .NET Core. LogCategories クラスを使用すると、特定の関数、トリガー、またはユーザーのカテゴリを定義することができます。The LogCategories class lets you define categories for specific functions, triggers, or users. また、特定のホストの状態 (StartupResults など) のフィルターも定義されています。It also defines filters for specific host states, like Startup and Results. これにより、ログ記録の出力を微調整できます。This enables you to fine-tune the logging output. 定義されたカテゴリ内で一致するものが見つからない場合、メッセージをフィルターするかどうかを決めるときに、フィルターは Default 値に戻ります。If no match is found within the defined categories, the filter falls back to the Default value when deciding whether to filter the message.

LogCategories には、次の using ステートメントが必要です。LogCategories requires the following using statement:

using Microsoft.Azure.WebJobs.Logging; 

次の例では、既定で Warning レベルのすべてのログをフィルター処理するフィルターを構築します。The following example constructs a filter that, by default, filters all logs at the Warning level. Function および results カテゴリ (バージョン 2.xHost.Results と同等) は、Error レベルでフィルタリングされます。The Function and results categories (equivalent to Host.Results in version 2.x) are filtered at the Error level. フィルターは、現在のカテゴリを、LogCategories インスタンス内のすべての登録済みレベルと比較して、最も長い一致を選択します。The filter compares the current category to all registered levels in the LogCategories instance and chooses the longest match. つまり、Host.Triggers に登録されている Debug レベルは、Host.Triggers.QueueHost.Triggers.Blob に一致します。This means that the Debug level registered for Host.Triggers matches Host.Triggers.Queue or Host.Triggers.Blob. これにより、カテゴリを 1 つずつ追加しなくても、より幅広いカテゴリを制御できます。This allows you to control broader categories without needing to add each one.

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

バージョン 2.xVersion 2.x

SDK のバージョン 2.x では、LogCategoryFilter クラスを使用してフィルター処理を制御します。In version 2.x of the SDK, you use the LogCategoryFilter class to control filtering. LogCategoryFilter には Default プロパティがあり、初期値は Information です。つまり、InformationWarningErrorCritical レベルのメッセージはすべてログに記録されますが、Debug または Trace レベルのメッセージは除外されます。The LogCategoryFilter has a Default property with an initial value of Information, meaning that any messages at the Information, Warning, Error, or Critical levels are logged, but any messages at the Debug or Trace levels are filtered away.

バージョン 3.xLogCategories と同様に、CategoryLevels プロパティを使用すると特定のカテゴリのログ レベルを指定できるため、ロギング出力を微調整することができます。As with LogCategories in version 3.x, the CategoryLevels property allows you to specify log levels for specific categories so you can fine-tune the logging output. CategoryLevels ディクショナリ内で一致するものが見つからない場合、メッセージをフィルターするかどうかを決定する際に、フィルターが Default 値にフォールバックします。If no match is found within the CategoryLevels dictionary, the filter falls back to the Default value when deciding whether to filter the message.

次の例は、既定値で Warning レベルのすべてのログをフィルタリングするフィルターを構築します。The following example constructs a filter that by default filters all logs at the Warning level. Function および Host.Results カテゴリは、Error レベルでフィルター処理されます。The Function and Host.Results categories are filtered at the Error level. LogCategoryFilter は現在のカテゴリを、登録されているすべての CategoryLevels と比較して、最長一致を選択します。The LogCategoryFilter compares the current category to all registered CategoryLevels and chooses the longest match. したがって、Host.Triggers に登録されている Debug レベルは、Host.Triggers.Queue または Host.Triggers.Blob と一致します。So the Debug level registered for Host.Triggers will match Host.Triggers.Queue or Host.Triggers.Blob. これにより、カテゴリを 1 つずつ追加しなくても、より幅広いカテゴリを制御できます。This allows you to control broader categories without needing to add each one.

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

Application Insights のカスタム テレメトリCustom telemetry for Application Insights

Application Insights 用のカスタム テレメトリを実装するプロセスは、SDK のバージョンによって異なります。The process for implementing custom telemetry for Application Insights depends on the SDK version. Application Insights の構成方法については、「Application Insights ログの追加」を参照してください。To learn how to configure Application Insights, see Add Application Insights logging.

バージョン 3.xVersion 3.x

WebJobs SDK のバージョン 3.x は、.NET Core 汎用ホストに依存しているため、カスタム テレメトリ ファクトリは提供されなくなりました。Because version 3.x of the WebJobs SDK relies on the .NET Core generic host, a custom telemetry factory is no longer provided. ただし、依存関係インジェクションを使用してカスタム テレメトリをパイプラインに追加できます。But you can add custom telemetry to the pipeline by using dependency injection. このセクションの例には、次の using ステートメントが必要です。The examples in this section require the following using statements:

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

次の ITelemetryInitializer のカスタム実装を使用すると、独自の ITelemetry を既定の TelemetryConfiguration に追加することができます。The following custom implementation of ITelemetryInitializer lets you add your own ITelemetry to the default TelemetryConfiguration.

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

ビルダーで ConfigureServices を呼び出して、カスタム ITelemetryInitializer をパイプラインに追加します。Call ConfigureServices in the builder to add your custom ITelemetryInitializer to the pipeline.

static void 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)
    {

        host.Run();
    }
}

TelemetryConfiguration が構築されるとき、ITelemetryInitializer のすべての登録されている種類が組み込まれます。When the TelemetryConfiguration is constructed, all registered types of ITelemetryInitializer are included. 詳しくは、「カスタムのイベントとメトリックのための Application Insights API」をご覧ください。To learn more, see Application Insights API for custom events and metrics.

バージョン 3.x では、ホストが停止するときに TelemetryClient をフラッシュする必要がなくなりました。In version 3.x, you no longer have to flush the TelemetryClient when the host stops. .NET Core 依存関係インジェクション システムが、登録されている ApplicationInsightsLoggerProvider を自動的に破棄し、それにより TelemetryClient がフラッシュされます。The .NET Core dependency injection system automatically disposes of the registered ApplicationInsightsLoggerProvider, which flushes the TelemetryClient.

バージョン 2.xVersion 2.x

バージョン 2.x では、WebJobs SDK 用に Application Insights プロバイダーによって内部で作成された TelemetryClient では、ServerTelemetryChannel が使用されます。In version 2.x, the TelemetryClient created internally by the Application Insights provider for the WebJobs SDK uses ServerTelemetryChannel. Application Insights のエンドポイントが使用できない、または着信要求のスロットリングが行われている場合、このチャンネルが Web アプリのファイル システムで要求を保存して、後でこれらを再送信します。When the Application Insights endpoint is unavailable or throttling incoming requests, this channel saves requests in the web app's file system and resubmits them later.

TelemetryClient は、ITelemetryClientFactory を実装するクラスによって作成されます。The TelemetryClient is created by a class that implements ITelemetryClientFactory. 既定で、これは DefaultTelemetryClientFactory です。By default, this is the DefaultTelemetryClientFactory.

Application Insights パイプラインの一部を変更する場合、独自の ITelemetryClientFactory を提供できます。そして、ホストは提供されたクラスを使用して TelemetryClient を構築します。If you want to modify any part of the Application Insights pipeline, you can supply your own ITelemetryClientFactory, and the host will use your class to construct a TelemetryClient. たとえば、次のコードでは DefaultTelemetryClientFactory がオーバーライドされて、ServerTelemetryChannel のプロパティが変更されます。For example, this code overrides DefaultTelemetryClientFactory to modify a property of 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;
    }
}

SamplingPercentageEstimatorSettings オブジェクトでは、アダプティブ サンプリングが構成されます。The SamplingPercentageEstimatorSettings object configures adaptive sampling. つまり、特定の大規模なシナリオでは、Application Insights はテレメトリ データの選択されたサブセットをサーバーに送信します。This means that in certain high-volume scenarios, Applications Insights sends a selected subset of telemetry data to the server.

テレメトリ ファクトリを作成した後、Application Insights のログ プロバイダーにそれを渡します。After you create the telemetry factory, you pass it in to the Application Insights logging provider:

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

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

次のステップNext steps

この記事では、WebJobs SDK を操作するための一般的なシナリオの処理方法を示すコード スニペットを提供しました。This article has provided code snippets that show how to handle common scenarios for working with the WebJobs SDK. 完全なサンプルは、azure-webjobs-sdk-samples を参照してください。For complete samples, see azure-webjobs-sdk-samples.