A trigger binding is a binding that listens for external events and causes a job function to be invoked when they occur. To understand how the binding fits into the larger binding process, see The Binding Process.
Binding Provider
A factory pattern is used to create trigger bindings. An ITriggerBindingProvider is the factory and is used to create ITriggerBinding instances. Take a look at SampleTriggerAttributeBindingProvider as an example. It's TryCreateAsync method is called by the runtime for all job parameters, giving it a chance to return a binding. In general the implementation of TryCreateAsync will:
- inspect the ParameterInfo to see if it has the specific binding attribute applied to it (in this case SampleTriggerAttribute)
- determine whether the parameter Type is supported by the binding
- if so, the provider constructs and returns an ITriggerBinding for the parameter
Binding
An ITriggerBinding instance is what is used by the runtime bind process to do all the heavy lifting. It implements the following methods.
BindAsync
This method is responsible for binding to a parameter for a particular function invocation. This includes performing any conversions required from the runtime parameter value to the trigger value type (in the case of SampleTrigger, converting to a SampleTriggerValue). For example, this conversion process is used when a function is replayed/run from the Dashboard - the input from the Dashboard will be a string, and that string needs to be converted to the correct trigger value type.
CreateListenerAsync
The runtime will call this method to create the listener for the trigger event source. A ListenerFactoryContext object is passed to the method. It contains a ITriggeredFunctionExecutor instance, which is what the listener uses to call back into the runtime when an event is triggered. When the listener fires it calls back into the runtime with a trigger value. The runtime will then flow that value back through BindAsync during the bind process when the function is invoked.
BindingDataContract
This property returns the the binding data contract the that the binding exposes. This is how the binding exposes binding parameters that can be used in binding expressions of other parameter attributes. A good example of this can be seen in FileTriggerBinding. Consider the following job function:
public static void ImportFile(
[FileTrigger(@"import\{name}", "*.dat", autoDelete: true)] FileStream file,
[Blob(@"processed/{name}")] CloudBlockBlob output,
string name)
{
...
}
The binding data contract will capture and include the "name" parameter from the "import\{name}" binding expression. That value will then be available to the bind process of other parameters, in this case both to the BlobAttribute container expression "processed/{name}" as well as the "string name" parameter. At runtime the actual file name that caused the trigger to fire will be flowed to all these other bindings using this contract. The file trigger also adds a "FileTrigger" binding parameter of type FileSystemEventArgs. This allows a job function to define a parameter "FileSystemEventArgs fileTrigger" which will be bound to the FileSystemEventArgs that caused the function to be triggered. You'll see a similar pattern in all the built in bindings. A list of the "Binding Parameters" for the various bindings can be found in the WebJobs SDK Quick Reference.
The counterpart to the binding contract is the binding data which is is produced during BindAsync according to the contract and returned via the ITriggerData returned from BindAsync. The binding data is a Dictionary<string, object> of values corresponding to the binding contract, and is what the runtime uses to get binding values. The binding data from the various parameters of a function are accumulated and made available to all other bindings.
Another good example is the POCO Type binding support of the WebHooks trigger binding. This binding demonstrates how to use BindingDataProvider to handle binding contract operations. If you are creating a trigger binding that needs to bind to general user POCO Types, you can follow this example.
ToParameterDescriptor
This method is responsible for returning a ParameterDescriptor describing the trigger parameter. Among other things, the ParameterDescriptor is the mechanism used to integrate with the WebJobs SDK Dashboard - it can return ParameterDisplayHints which dictate how the parameter is shown in the Dashboard.