Edit

Share via

Azure Event Grid bindings for Azure Functions

This reference shows how to connect to Azure Event Grid using Azure Functions triggers and bindings.

Event Grid is an Azure service that sends HTTP requests to notify you about events that happen in publishers. A publisher is the service or resource that originates the event. For example, an Azure blob storage account is a publisher, and a blob upload or deletion is an event. Some Azure services have built-in support for publishing events to Event Grid.

Event handlers receive and process events. Azure Functions is one of several Azure services that have built-in support for handling Event Grid events. Functions provides an Event Grid trigger, which invokes a function when an event is received from Event Grid. A similar output binding can be used to send events from your function to an Event Grid custom topic.

You can also use an HTTP trigger to handle Event Grid Events. To learn more, see Receive events to an HTTP endpoint. We recommend using the Event Grid trigger over HTTP trigger.

Action Type
Run a function when an Event Grid event is dispatched Trigger
Sends an Event Grid event Output binding
Control the returned HTTP status code HTTP endpoint

Install extension

The extension NuGet package you install depends on the C# mode you're using in your function app:

Functions execute in an isolated C# worker process. To learn more, see Guide for running C# Azure Functions in an isolated worker process.

The functionality of the extension varies depending on the extension version:

Add the extension to your project by installing the NuGet package, version 3.x.

Install bundle

To be able to use this binding extension in your app, make sure that the host.json file in the root of your project contains this extensionBundle reference:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

In this example, the version value of [4.0.0, 5.0.0) instructs the Functions host to use a bundle version that is at least 4.0.0 but less than 5.0.0, which includes all potential versions of 4.x. This notation effectively maintains your app on the latest available minor version of the v4.x extension bundle.

When possible, you should use the latest extension bundle major version and allow the runtime to automatically maintain the latest minor version. You can view the contents of the latest bundle on the extension bundles release page.

If your app requires you to use a previous extension version, you might need to instead specify a previous bundle version. You can review the bundle releases to locate a bundle that contains a version of this extension that can be used by your app. For more information, see Azure Functions extension bundles. ::: zone-end

Considerations for the Event Grid extension:

  • Event Grid extension versions earlier than 3.x don't support CloudEvents schema. To consume this schema, instead use an HTTP trigger.
  • The Event Grid output binding is only available for Functions 2.x and higher.

Binding types

The binding types supported for .NET depend on both the extension version and C# execution mode, which can be one of the following:

An isolated worker process class library compiled C# function runs in a process isolated from the runtime.

Choose a version to see binding type details for the mode and version.

The isolated worker process supports parameter types according to the tables below. Support for binding to Stream, and to types from Azure.Messaging is in preview.

Event Grid trigger

When you want the function to process a single event, the Event Grid trigger can bind to the following types:

Type Description
JSON serializable types Functions tries to deserialize the JSON data of the event into a plain-old CLR object (POCO) type.
string The event as a string.
BinaryData1 The bytes of the event message.
CloudEvent1 The event object. Use when Event Grid is configured to deliver using the CloudEvents schema.
EventGridEvent1 The event object. Use when Event Grid is configured to deliver using the Event Grid schema.

When you want the function to process a batch of events, the Event Grid trigger can bind to the following types:

Type Description
CloudEvent[]1,
EventGridEvent[]1,
string[],
BinaryData[]1		 An array of events from the batch. Each entry represents one event.

1 To use these types, you need to reference Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 or later and the common dependencies for SDK type bindings.

Event Grid output binding

When you want the function to write a single event, the Event Grid output binding can bind to the following types:

Type Description
string The event as a string.
byte[] The bytes of the event message.
JSON serializable types An object representing a JSON event. Functions tries to serialize a plain-old CLR object (POCO) type into JSON data.

When you want the function to write multiple events, the Event Grid output binding can bind to the following types:

Type Description
T[] where T is one of the single event types An array containing multiple events. Each entry represents one event.

For other output scenarios, create and use an EventGridPublisherClient with other types from Azure.Messaging.EventGrid directly. See Register Azure clients for an example of using dependency injection to create a client type from the Azure SDK.

host.json settings

The Event Grid trigger uses a webhook HTTP request, which can be configured using the same host.json settings as the HTTP Trigger.

Next steps