Azure Functions C# スクリプト開発者向けリファレンスAzure Functions C# script developer reference

Azure Functions の C# スクリプト エクスペリエンスは、Azure WebJobs SDK に基づいています。The C# script experience for Azure Functions is based on the Azure WebJobs SDK. データは、メソッドの引数を使用して C# 関数に渡されます。Data flows into your C# function via method arguments. 引数名は function.jsonで指定され、関数のロガーやキャンセル トークンなどにアクセスするための定義済みの名前があります。Argument names are specified in function.json, and there are predefined names for accessing things like the function logger and cancellation tokens.

この記事では、「 Azure Functions developer reference (Azure Functions 開発者向けリファレンス)」を既に読んでいることを前提としています。This article assumes that you've already read the Azure Functions developer reference.

C# クラス ライブラリの使用の詳細については、「Using .NET class libraries with Azure Functions」(Azure Functions での .NET クラス ライブラリの使用) を参照してください。For information on using C# class libraries, see Using .NET class libraries with Azure Functions.

.csx のしくみHow .csx works

.csx の形式では、"定型" の記述が少なく、C# 関数のみの記述に重点が置かれています。The .csx format allows you to write less "boilerplate" and focus on writing just a C# function. 通常どおり、すべてのアセンブリ参照と名前空間をファイルの先頭に含めます。Include any assembly references and namespaces at the beginning of the file as usual. 名前空間およびクラスにすべてをラップするのではなく、Run メソッドを定義するだけです。Instead of wrapping everything in a namespace and class, just define a Run method. Plain Old CLR Object (POCO) オブジェクトを定義する場合など、クラスを含める必要がある場合は、同じファイル内にクラスを含めることができます。If you need to include any classes, for instance to define Plain Old CLR Object (POCO) objects, you can include a class inside the same file.

引数へのバインドBinding to arguments

function.json 構成の name プロパティを通じて、さまざまなバインドが C# 関数にバインドされます。The various bindings are bound to a C# function via the name property in the function.json configuration. 各バインドには、独自のサポートされている型があります。たとえば、blob のトリガーでは、文字列、POCO、または CloudBlockBlob がサポートされます。Each binding has its own supported types; for instance, a blob trigger can support a string, a POCO, or a CloudBlockBlob. サポートされる型は、各バインドの参照に記載されています。The supported types are documented in the reference for each binding. POCO オブジェクトでは、各プロパティに getter と setter が定義されている必要があります。A POCO object must have a getter and setter defined for each property.

public static void Run(string myBlob, out MyClass myQueueItem)
{
    log.Verbose($"C# Blob trigger function processed: {myBlob}");
    myQueueItem = new MyClass() { Id = "myid" };
}

public class MyClass
{
    public string Id { get; set; }
}

ヒント

HTTP または webhook のバインディングを使用する予定がある場合は、不適切な HttpClient のインスタンス化によって生じるおそれのあるポートの枯渇を防止してください。If you plan to use the HTTP or WebHook bindings, plan to avoid port exhaustion that can be caused by improper instantiation of HttpClient. 詳細については、「Improper Instantiation antipattern (不適切なインスタンス化の防止策)」の記事を参照してください。For more information, review the article Improper Instantiation antipattern.

出力バインドのメソッド戻り値の使用Using method return value for output binding

出力バインドにメソッド戻り値を使用できます。そのためには、function.json の名前 $return を使用します。You can use a method return value for an output binding, by using the name $return in function.json:

{
    "type": "queue",
    "direction": "out",
    "name": "$return",
    "queueName": "outqueue",
    "connection": "MyStorageConnectionString",
}
public static string Run(string input, TraceWriter log)
{
    return input;
}

複数の出力値の書き込みWriting multiple output values

出力バインドに複数の値を書き込むには、ICollector 型または IAsyncCollector 型を使用します。To write multiple values to an output binding, use the ICollector or IAsyncCollector types. これらの型は、メソッド完了時に出力バインドに書き込まれる、書き込み専用接続です。These types are write-only collections that are written to the output binding when the method completes.

この例では、ICollector を使用して複数のキュー メッセージを同じキューに書き込みます。This example writes multiple queue messages into the same queue using ICollector:

public static void Run(ICollector<string> myQueueItem, TraceWriter log)
{
    myQueueItem.Add("Hello");
    myQueueItem.Add("World!");
}

ログの記録Logging

出力を C# のストリーミング ログにログ記録するために、TraceWriter 型の引数を含めます。To log output to your streaming logs in C#, include an argument of type TraceWriter. これの名前を logにすることをお勧めします。We recommend that you name it log. Azure Functions では Console.Write を使用しないでください。Avoid using Console.Write in Azure Functions.

TraceWriterAzure Web ジョブ SDK で定義されます。TraceWriter is defined in the Azure WebJobs SDK. TraceWriter のログ レベルは、host.json で構成できます。The log level for TraceWriter can be configured in host.json.

public static void Run(string myBlob, TraceWriter log)
{
    log.Info($"C# Blob trigger function processed: {myBlob}");
}

非同期Async

関数を非同期にするには、async キーワードを使用して Task オブジェクトを返します。To make a function asynchronous, use the async keyword and return a Task object.

public async static Task ProcessQueueMessageAsync(
        string blobName,
        Stream blobInput,
        Stream blobOutput)
{
    await blobInput.CopyToAsync(blobOutput, 4096, token);
}

キャンセル トークンCancellation token

一部の操作では、グレースフル シャットダウンが必要です。Some operations require graceful shutdown. クラッシュに対応するコードを記述するのが最善の方法ですが、グレースフル シャットダウンの要求を処理する場合は、CancellationToken 型の引数を定義します。While it's always best to write code that can handle crashing, in cases where you want to handle graceful shutdown requests, you define a CancellationToken typed argument. CancellationToken は、ホストのシャット ダウンがトリガーされることを通知するために用意されています。A CancellationToken is provided to signal that a host shutdown is triggered.

public async static Task ProcessQueueMessageAsyncCancellationToken(
        string blobName,
        Stream blobInput,
        Stream blobOutput,
        CancellationToken token)
    {
        await blobInput.CopyToAsync(blobOutput, 4096, token);
    }

名前空間のインポートImporting namespaces

名前空間をインポートする必要がある場合は、 using 句を使用して、通常どおりにインポートできます。If you need to import namespaces, you can do so as usual, with the using clause.

using System.Net;
using System.Threading.Tasks;

public static Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)

次の名前空間は自動的にインポートされるため、オプションとなります。The following namespaces are automatically imported and are therefore optional:

  • System
  • System.Collections.Generic
  • System.IO
  • System.Linq
  • System.Net.Http
  • System.Threading.Tasks
  • Microsoft.Azure.WebJobs
  • Microsoft.Azure.WebJobs.Host

外部アセンブリの参照Referencing external assemblies

フレームワークのアセンブリには、 #r "AssemblyName" ディレクティブを使用して参照を追加します。For framework assemblies, add references by using the #r "AssemblyName" directive.

#r "System.Web.Http"

using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

public static Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)

次のアセンブリは、Azure Functions をホストしている環境によって自動的に追加されます。The following assemblies are automatically added by the Azure Functions hosting environment:

  • mscorlib
  • System
  • System.Core
  • System.Xml
  • System.Net.Http
  • Microsoft.Azure.WebJobs
  • Microsoft.Azure.WebJobs.Host
  • Microsoft.Azure.WebJobs.Extensions
  • System.Web.Http
  • System.Net.Http.Formatting

次のアセンブリは、単純な名前で参照できます (たとえば、#r "AssemblyName")。The following assemblies may be referenced by simple-name (for example, #r "AssemblyName"):

  • Newtonsoft.Json
  • Microsoft.WindowsAzure.Storage
  • Microsoft.ServiceBus
  • Microsoft.AspNet.WebHooks.Receivers
  • Microsoft.AspNet.WebHooks.Common
  • Microsoft.Azure.NotificationHubs

カスタム アセンブリの参照Referencing custom assemblies

カスタム アセンブリを参照するために、共有アセンブリまたはプライベート アセンブリのいずれかを使用できます。To reference a custom assembly, you can use either a shared assembly or a private assembly:

  • 共有アセンブリは、関数アプリ内のすべての関数にわたって共有されます。Shared assemblies are shared across all functions within a function app. カスタム アセンブリを参照するには、そのアセンブリを関数アプリにアップロードします (たとえば、関数アプリのルートの bin フォルダーにアップロード)。To reference a custom assembly, upload the assembly to your function app, such as in a bin folder in the function app root.
  • プライベート アセンブリは、特定の関数のコンテキストの一部であり、異なるバージョンのサイドローディングをサポートします。Private assemblies are part of a given function's context, and support side-loading of different versions. プライベート アセンブリを関数ディレクトリ の bin フォルダーにアップロードする必要があります。Private assemblies should be uploaded in a bin folder in the function directory. #r "MyAssembly.dll" などのファイル名を使用して参照します。Reference using the file name, such as #r "MyAssembly.dll".

関数フォルダーにファイルをアップロードする方法については、パッケージ管理の次のセクションを参照してください。For information on how to upload files to your function folder, see the following section on package management.

監視対象のディレクトリWatched directories

関数のスクリプト ファイルを含むディレクトリは、アセンブリの変更を自動的に監視されています。The directory that contains the function script file is automatically watched for changes to assemblies. その他のディレクトリでアセンブリの変更を監視するには、host.jsonwatchDirectories の一覧にそのディレクトリを追加します。To watch for assembly changes in other directories, add them to the watchDirectories list in host.json.

NuGet パッケージを使用するUsing NuGet packages

NuGet パッケージを C# 関数で使用するには、project.json ファイルを関数アプリのファイル システムにある関数のフォルダーにアップロードします。To use NuGet packages in a C# function, upload a project.json file to the function's folder in the function app's file system. Microsoft.ProjectOxford.Face バージョン 1.1.0 への参照を追加する project.json ファイルの例を次に示します。Here is an example project.json file that adds a reference to Microsoft.ProjectOxford.Face version 1.1.0:

{
  "frameworks": {
    "net46":{
      "dependencies": {
        "Microsoft.ProjectOxford.Face": "1.1.0"
      }
    }
   }
}

.NET Framework 4.6 のみがサポートされているので、次に示すように project.json ファイルが net46 を指定していることを確認します。Only the .NET Framework 4.6 is supported, so make sure that your project.json file specifies net46 as shown here.

project.json ファイルをアップロードすると、ランタイムによってパッケージが取得され、パッケージ アセンブリに参照が自動的に追加されます。When you upload a project.json file, the runtime gets the packages and automatically adds references to the package assemblies. #r "AssemblyName" ディレクティブを追加する必要はありません。You don't need to add #r "AssemblyName" directives. NuGet パッケージで定義されている型を使用するには、必要な using ステートメントを run.csx ファイルに追加します。To use the types defined in the NuGet packages, add the required using statements to your run.csx file.

Functions ランタイムでは、NuGet は project.jsonproject.lock.json を比較して作業を復元します。In the Functions runtime, NuGet restore works by comparing project.json and project.lock.json. ファイルの日付と時刻のタイムスタンプが一致しない場合は、NuGet 復元が実行され、NuGet は更新されたパッケージをダウンロードします。If the date and time stamps of the files do not match, a NuGet restore runs and NuGet downloads updated packages. ただし、ファイルの日付と時刻のタイムスタンプが一致した場合、NuGet は復元を実行しません。However, if the date and time stamps of the files do match, NuGet does not perform a restore. したがって、NuGet がパッケージの復元をスキップするため、project.lock.json はデプロイされません。Therefore, project.lock.json should not be deployed as it causes NuGet to skip package restore. ロック ファイルのデプロイを回避するには、project.lock.json.gitignore ファイルに追加します。To avoid deploying the lock file, add the project.lock.json to the .gitignore file.

カスタムの NuGet フィードを使用するには、関数アプリのルートにある Nuget.Config ファイルでフィードを指定します。To use a custom NuGet feed, specify the feed in a Nuget.Config file in the Function App root. 詳しくは、「NuGet の動作の構成」をご覧ください。For more information, see Configuring NuGet behavior.

Project.json ファイルの使用Using a project.json file

  1. Azure ポータルで関数を開きます。Open the function in the Azure portal. [ログ] タブには、パッケージのインストールの出力が表示されます。The logs tab displays the package installation output.
  2. project.json ファイルをアップロードするには、「Azure Functions developer reference (Azure Functions 開発者向けリファレンス)」の「関数アプリ ファイルを更新する方法」にあるいずれかの方法を利用してください。To upload a project.json file, use one of the methods described in the How to update function app files in the Azure Functions developer reference topic.
  3. project.json ファイルがアップロードされた後、関数のストリーミング ログの出力は次の例のようになります。After the project.json file is uploaded, you see output like the following example in your function's streaming log:
2016-04-04T19:02:48.745 Restoring packages.
2016-04-04T19:02:48.745 Starting NuGet restore
2016-04-04T19:02:50.183 MSBuild auto-detection: using msbuild version '14.0' from 'D:\Program Files (x86)\MSBuild\14.0\bin'.
2016-04-04T19:02:50.261 Feeds used:
2016-04-04T19:02:50.261 C:\DWASFiles\Sites\facavalfunctest\LocalAppData\NuGet\Cache
2016-04-04T19:02:50.261 https://api.nuget.org/v3/index.json
2016-04-04T19:02:50.261
2016-04-04T19:02:50.511 Restoring packages for D:\home\site\wwwroot\HttpTriggerCSharp1\Project.json...
2016-04-04T19:02:52.800 Installing Newtonsoft.Json 6.0.8.
2016-04-04T19:02:52.800 Installing Microsoft.ProjectOxford.Face 1.1.0.
2016-04-04T19:02:57.095 All packages are compatible with .NETFramework,Version=v4.6.
2016-04-04T19:02:57.189
2016-04-04T19:02:57.189
2016-04-04T19:02:57.455 Packages restored.

環境変数Environment variables

環境変数またはアプリ設定値を取得するには、次のコード例のように、 System.Environment.GetEnvironmentVariableを使用します。To get an environment variable or an app setting value, use System.Environment.GetEnvironmentVariable, as shown in the following code example:

public static void Run(TimerInfo myTimer, TraceWriter log)
{
    log.Info($"C# Timer trigger function executed at: {DateTime.Now}");
    log.Info(GetEnvironmentVariable("AzureWebJobsStorage"));
    log.Info(GetEnvironmentVariable("WEBSITE_SITE_NAME"));
}

public static string GetEnvironmentVariable(string name)
{
    return name + ": " +
        System.Environment.GetEnvironmentVariable(name, EnvironmentVariableTarget.Process);
}

.csx コードの再利用Reusing .csx code

他の .csx ファイルで定義されたクラスとメソッドを、run.csx ファイルで使用できます。You can use classes and methods defined in other .csx files in your run.csx file. そのためには、run.csx ファイル内で #load ディレクティブを使用します。To do that, use #load directives in your run.csx file. 次の例では、MyLogger という名前のログ記録ルーチンが myLogger.csx 内で共有され、#load ディレクティブを使用して run.csx に読み込まれます。In the following example, a logging routine named MyLogger is shared in myLogger.csx and loaded into run.csx using the #load directive:

run.csxの例:Example run.csx:

#load "mylogger.csx"

public static void Run(TimerInfo myTimer, TraceWriter log)
{
    log.Verbose($"Log by run.csx: {DateTime.Now}");
    MyLogger(log, $"Log by MyLogger: {DateTime.Now}");
}

mylogger.csxの例:Example mylogger.csx:

public static void MyLogger(TraceWriter log, string logtext)
{
    log.Verbose(logtext);
}

共有された .csx の使用は、POCO オブジェクトを使用して関数間の引数を厳密に型宣言する場合の一般的なパターンです。Using a shared .csx is a common pattern when you want to strongly type your arguments between functions using a POCO object. 次の簡略化された例では、HTTP トリガーとキュー トリガーが Order という名前の POCO オブジェクトを共有して、注文データを厳密に型宣言しています。In the following simplified example, an HTTP trigger and queue trigger share a POCO object named Order to strongly type the order data:

例: HTTP トリガーの run.csxExample run.csx for HTTP trigger:

#load "..\shared\order.csx"

using System.Net;

public static async Task<HttpResponseMessage> Run(Order req, IAsyncCollector<Order> outputQueueItem, TraceWriter log)
{
    log.Info("C# HTTP trigger function received an order.");
    log.Info(req.ToString());
    log.Info("Submitting to processing queue.");

    if (req.orderId == null)
    {
        return new HttpResponseMessage(HttpStatusCode.BadRequest);
    }
    else
    {
        await outputQueueItem.AddAsync(req);
        return new HttpResponseMessage(HttpStatusCode.OK);
    }
}

例: キュー トリガーの run.csxExample run.csx for queue trigger:

#load "..\shared\order.csx"

using System;

public static void Run(Order myQueueItem, out Order outputQueueItem,TraceWriter log)
{
    log.Info($"C# Queue trigger function processed order...");
    log.Info(myQueueItem.ToString());

    outputQueueItem = myQueueItem;
}

例: order.csxExample order.csx:

public class Order
{
    public string orderId {get; set; }
    public string custName {get; set;}
    public string custAddress {get; set;}
    public string custEmail {get; set;}
    public string cartId {get; set; }

    public override String ToString()
    {
        return "\n{\n\torderId : " + orderId +
                  "\n\tcustName : " + custName +             
                  "\n\tcustAddress : " + custAddress +             
                  "\n\tcustEmail : " + custEmail +             
                  "\n\tcartId : " + cartId + "\n}";             
    }
}

#load ディレクティブで相対パスを使用できます。You can use a relative path with the #load directive:

  • #load "mylogger.csx" によって、関数フォルダーにあるファイルが読み込まれます。#load "mylogger.csx" loads a file located in the function folder.
  • #load "loadedfiles\mylogger.csx" によって、関数フォルダー内のフォルダーにあるファイルが読み込まれます。#load "loadedfiles\mylogger.csx" loads a file located in a folder in the function folder.
  • #load "..\shared\mylogger.csx" によって、関数フォルダーと同じレベル ( wwwrootの直下) にあるフォルダーのファイルが読み込まれます。#load "..\shared\mylogger.csx" loads a file located in a folder at the same level as the function folder, that is, directly under wwwroot.

#load ディレクティブは、.csx (C# スクリプト) ファイルでのみ機能し、.cs ファイルでは機能しません。The #load directive works only with .csx (C# script) files, not with .cs files.

命令型のバインドを利用した実行時のバインドBinding at runtime via imperative bindings

C# および他の .NET 言語では、function.json宣言型のバインドではなく命令型のバインド パターンを使用できます。In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json. 命令型のバインドは、設計時ではなくランタイム時にバインド パラメーターを計算する必要がある場合に便利です。Imperative binding is useful when binding parameters need to be computed at runtime rather than design time. このパターンを使用すると、サポートされている入力バインドと出力バインドに関数コード内でバインドできます。With this pattern, you can bind to supported input and output binding on-the-fly in your function code.

次のように命令型のバインドを定義します。Define an imperative binding as follows:

  • 必要な命令型のバインドの function.json にエントリを含めないでください。Do not include an entry in function.json for your desired imperative bindings.
  • 入力パラメーター Binder binder または IBinder binder を渡します。Pass in an input parameter Binder binder or IBinder binder.
  • 次の C# パターンを使用してデータ バインドを実行します。Use the following C# pattern to perform the data binding.
using (var output = await binder.BindAsync<T>(new BindingTypeAttribute(...)))
{
    ...
}

BindingTypeAttribute はバインドを定義する .NET 属性、T はそのバインドの種類でサポートされている入力または出力の型です。BindingTypeAttribute is the .NET attribute that defines your binding and T is the input or output type that's supported by that binding type. Tout パラメーター型 (out JObject など) にすることはできません。T also cannot be an out parameter type (such as out JObject). たとえば、Mobile Apps テーブルの出力バインドは 6 種類の出力をサポートしますが、T に使用できるのは ICollector または IAsyncCollector のみです。For example, the Mobile Apps table output binding supports six output types, but you can only use ICollector or IAsyncCollector for T.

次のコード例は、実行時に BLOB パスが定義された Storage Blob の出力バインドを作成し、この BLOB に文字列を書き込みます。The following example code creates a Storage blob output binding with blob path that's defined at run time, then writes a string to the blob.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host.Bindings.Runtime;

public static async Task Run(string input, Binder binder)
{
    using (var writer = await binder.BindAsync<TextWriter>(new BlobAttribute("samples-output/path")))
    {
        writer.Write("Hello World!!");
    }
}

BlobAttributeStorage Blob の入力バインドまたは出力バインドを定義します。TextWriter はサポートされている出力バインドの種類です。BlobAttribute defines the Storage blob input or output binding, and TextWriter is a supported output binding type. 前のコード例では、コードは、関数アプリのメイン ストレージ アカウント接続文字列 (AzureWebJobsStorage) のアプリケーション設定を取得します。In the previous code sample, the code gets the app setting for the function app's main Storage account connection string (which is AzureWebJobsStorage). ストレージ アカウントに使用するカスタム アプリ設定を指定するには、StorageAccountAttribute を追加し、属性の配列を BindAsync<T>() に渡します。You can specify a custom app setting to use for the Storage account by adding the StorageAccountAttribute and passing the attribute array into BindAsync<T>(). たとえば、次のように入力します。For example,

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host.Bindings.Runtime;

public static async Task Run(string input, Binder binder)
{
    var attributes = new Attribute[]
    {    
        new BlobAttribute("samples-output/path"),
        new StorageAccountAttribute("MyStorageAccount")
    };

    using (var writer = await binder.BindAsync<TextWriter>(attributes))
    {
        writer.Write("Hello World!");
    }
}

次の表に、各バインドの種類の .NET 属性と、それらが定義されているパッケージを示します。The following table lists the .NET attributes for each binding type and the packages in which they are defined.

バインドBinding AttributeAttribute 参照の追加Add reference
Cosmos DBCosmos DB Microsoft.Azure.WebJobs.DocumentDBAttribute #r "Microsoft.Azure.WebJobs.Extensions.DocumentDB"
Event HubsEvent Hubs Microsoft.Azure.WebJobs.ServiceBus.EventHubAttributeMicrosoft.Azure.WebJobs.ServiceBusAccountAttributeMicrosoft.Azure.WebJobs.ServiceBus.EventHubAttribute, Microsoft.Azure.WebJobs.ServiceBusAccountAttribute #r "Microsoft.Azure.Jobs.ServiceBus"
Mobile AppsMobile Apps Microsoft.Azure.WebJobs.MobileTableAttribute #r "Microsoft.Azure.WebJobs.Extensions.MobileApps"
Notification HubsNotification Hubs Microsoft.Azure.WebJobs.NotificationHubAttribute #r "Microsoft.Azure.WebJobs.Extensions.NotificationHubs"
Service BusService Bus Microsoft.Azure.WebJobs.ServiceBusAttributeMicrosoft.Azure.WebJobs.ServiceBusAccountAttributeMicrosoft.Azure.WebJobs.ServiceBusAttribute, Microsoft.Azure.WebJobs.ServiceBusAccountAttribute #r "Microsoft.Azure.WebJobs.ServiceBus"
ストレージ キューStorage queue Microsoft.Azure.WebJobs.QueueAttributeMicrosoft.Azure.WebJobs.StorageAccountAttributeMicrosoft.Azure.WebJobs.QueueAttribute, Microsoft.Azure.WebJobs.StorageAccountAttribute
Storage BlobStorage blob Microsoft.Azure.WebJobs.BlobAttributeMicrosoft.Azure.WebJobs.StorageAccountAttributeMicrosoft.Azure.WebJobs.BlobAttribute, Microsoft.Azure.WebJobs.StorageAccountAttribute
ストレージ テーブルStorage table Microsoft.Azure.WebJobs.TableAttributeMicrosoft.Azure.WebJobs.StorageAccountAttributeMicrosoft.Azure.WebJobs.TableAttribute, Microsoft.Azure.WebJobs.StorageAccountAttribute
TwilioTwilio Microsoft.Azure.WebJobs.TwilioSmsAttribute #r "Microsoft.Azure.WebJobs.Extensions.Twilio"

次のステップNext steps

詳細については、次のリソースを参照してください。For more information, see the following resources: