Skip to content

Binding Extensions Overview

Jump to bottom
David Ebbo edited this page Jun 23, 2018 · 35 revisions

Note: the page you are probably looking for is https://github.com/Azure/azure-webjobs-sdk/wiki/Creating-custom-input-and-output-bindings. The information below describes an older extensibility mode, which still works, but is not recommended in most scenarios. One exception is that the newer model does not support Triggers. However, be aware that custom triggers are generally not supported if you use Azure Functions in Consumption mode.

The core WebJobs SDK contains bindings for Queues, Blobs, Tables, ServiceBus Queues, etc. However, there are many other potential sources of data for the SDK to bind to, and they can't all be baked into the core SDK. However, the SDK exposes an extensibility model that allows 3rd party extensions to be written. When registered, these extensions are integrated into the SDK binding pipeline in the same way the built in bindings are, meaning they enjoy the same level of support, Dashboard integration, etc. We've also moved the existing ServiceBus bindings to this extensibility model to prove it out.

There are two main types of binding extensions:

  • Trigger Bindings are bindings that monitor external event sources and cause a job function to be executed when they occur. An example is the QueueTriggerAttribute binding (e.g. [QueueTrigger("myqueue")]).
  • Non-Trigger Bindings are bindings to an external storage system. An example is the TableAttribute binding (e.g. [Table("mytable")]) which allows a job function to read/write to an Azure Storage Table.

These pages are a short tutorial on how to write your own binding extensions. The fully functional binding extensions contained in this repository serve as code samples on how to write extensions. This repo also includes a project Sample.Extension containing template extensions that demonstrate the minimum scaffolding necessary to get binding extensions up and running. The ExtensionsSample driver app exercises these sample bindings, so you can debug through them, etc. It is recommended that you use these templates as a starting point by copying them and modifying them for your domain. For example, say you want to write a new "Foo" trigger binding you would do the following:

  1. Create a new class library to hold your extension(s) (e.g. WebJobs.Foo). This is the library that your users will reference to use your new binding.
  2. Reference the Microsoft.Azure.WebJobs.Extensions nuget package
  3. Copy files SampleTriggerAttribute.cs, SampleTriggerAttributeBindingProvider.cs and SampleJobHostConfigurationExtensions.cs to your WebJobs.Foo class library project
  4. Modify the SampleJobHostConfigurationExtensions.cs file by removing binding types that you didn't copy over (you'll get compilation errors)
  5. Add a console driver app to the solution to test your new extension, having it reference WebJobs.Foo, and also adding a nuget package reference to Microsoft.Azure.WebJobs (the same version that is referenced by WebJobs.Foo)
  6. In Program.cs, new up a JobHost and start it, ensuring that you call config.UseSample(). See Program.cs for an example.
  7. Add a new class Functions.cs to the driver project, make it public static, and add a job function using the SampleTrigger attribute. See SampleSamples.cs for an example.
  8. Finally, set a breakpoint in the job function, set the Driver project as the startup project and debug
  9. Your job function will get hit every 5 seconds! Now that you have something up and running, you can rename the classes/files for your domain, and begin implementing your domain specifics. The details below will help with that.

While the above template can get you up and running quickly, you will likely want to understand the details. Authoring an extension boils down to the following steps:

Clone this wiki locally