Azure WebJobs EventGrid client library for .NET

This extension provides functionality for receiving Event Grid webhook calls in Azure Functions, allowing you to easily write functions that respond to any event published to Event Grid.

Getting started

Install the package

Install the Event Grid extension withNuGet:

dotnet add package Microsoft.Azure.WebJobs.Extensions.EventGrid

Prerequisites

You must have anAzure subscription and an Azure resource group with a custom Event Grid topic or domain. Follow thisstep-by-step tutorial to register the Event Grid resource provider and create Event Grid topics using theAzure portal. There is asimilar tutorial usingAzure CLI.

Authenticate the Client

In order for the extension publish events, you will need theendpoint of the Event Grid topic and acredential, which can be created using the topic's access key.

You can find the endpoint for your Event Grid topic either in theAzure Portal or by using theAzure CLI snippet below.

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

The access key can also be found through theportal, or by using the Azure CLI snippet below:

az eventgrid topic key list --name <your-resource-name> --resource-group <your-resource-group-name> --query "key1"

Key concepts

Using Event Grid output binding

Please follow thebinding tutorial to learn about using this extension for publishing EventGrid events.

Using Event Grid trigger

Please follow thetutorial to learn about triggering an Azure Function when an event is published.

Examples

Functions that uses Event Grid output binding

If you are using the EventGrid schema for your topic, you can output EventGridEvents.

public static class EventGridEventBindingFunction{    [FunctionName("EventGridEventBindingFunction")]    public static async Task<IActionResult> RunAsync(        [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,        [EventGrid(TopicEndpointUri = "EventGridEndpoint", TopicKeySetting = "EventGridKey")] IAsyncCollector<EventGridEvent> eventCollector)    {        EventGridEvent e = new EventGridEvent(await req.ReadAsStringAsync(), "IncomingRequest", "IncomingRequest", "1.0.0");        await eventCollector.AddAsync(e);        return new OkResult();    }}

If you are using the CloudEvent schema for your topic, you can output CloudEvents.

public static class CloudEventBindingFunction{    [FunctionName("CloudEventBindingFunction")]    public static async Task<IActionResult> RunAsync(        [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,        [EventGrid(TopicEndpointUri = "EventGridEndpoint", TopicKeySetting = "EventGridKey")] IAsyncCollector<CloudEvent> eventCollector)    {        CloudEvent e = new CloudEvent("IncomingRequest", "IncomingRequest", await req.ReadAsStringAsync());        await eventCollector.AddAsync(e);        return new OkResult();    }}

It is also possible to use Azure Identity with the output binding. To do so, set theConnection property to the name of your app setting that contains your Event Grid Topic endpoint along with a set of optional Identity information that is described in detailhere. When setting theConnection property, theTopicEndpointUri andTopicKeySetting properties should NOT be set.

public static class CloudEventOutputBindingWithIdentityFunction{    [FunctionName("CloudEventOutputBindingWithIdentityFunction")]    public static async Task<IActionResult> RunAsync(        [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,        [EventGrid(Connection = "MyConnection")] IAsyncCollector<CloudEvent> eventCollector)    {        CloudEvent e = new CloudEvent("IncomingRequest", "IncomingRequest", await req.ReadAsStringAsync());        await eventCollector.AddAsync(e);        return new OkResult();    }}

For local development, use thelocal.settings.json file to store the connection information:

{  "Values": {    "myConnection__topicEndpointUri": "{topicEndpointUri}"  }}

When deployed, use theapplication settings to store this information.

You can also output a string or JObject and the extension will attempt to parse into the correct strongly typed event.

Functions that uses Event Grid trigger

You can also create a function that will be executed whenever an event is delivered to your topic. Depending on the schema you have selected for your Azure Function event subscription, you can bind to eitherEventGridEvent orCloudEvent:

public static class EventGridEventTriggerFunction{    [FunctionName("EventGridEventTriggerFunction")]    public static void Run(        ILogger logger,        [EventGridTrigger] EventGridEvent e)    {        logger.LogInformation("Event received {type} {subject}", e.EventType, e.Subject);    }}

And if your subscription is configured with the CloudEvent schema:

public static class CloudEventTriggerFunction{    [FunctionName("CloudEventTriggerFunction")]    public static void Run(        ILogger logger,        [EventGridTrigger] CloudEvent e)    {        logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);    }}

It is also possible to bind to an array of events. This is useful if you havebatching enabled for your Event Grid Subscription.

public static class EventGridEventBatchTriggerFunction{    [FunctionName("EventGridEventBatchTriggerFunction")]    public static void Run(        ILogger logger,        [EventGridTrigger] EventGridEvent[] events)    {        foreach (EventGridEvent eventGridEvent in events)        {            logger.LogInformation("Event received {type} {subject}", eventGridEvent.EventType, eventGridEvent.Subject);        }    }}

Similarly, for subscriptions configured with the CloudEvent schema:

public static class CloudEventBatchTriggerFunction{    [FunctionName("CloudEventBatchTriggerFunction")]    public static void Run(        ILogger logger,        [EventGridTrigger] CloudEvent[] events)    {        foreach (CloudEvent cloudEvent in events)        {            logger.LogInformation("Event received {type} {subject}", cloudEvent.Type, cloudEvent.Subject);        }    }}

Troubleshooting

Please refer toMonitor Azure Functions for troubleshooting guidance.

Next steps

Read theintroduction to Azure Function orcreating an Azure Function guide.

Contributing

See ourCONTRIBUTING.md for details on building,testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions requireyou to agree to a Contributor License Agreement (CLA) declaring that you havethe right to, and actually do, grant us the rights to use your contribution. Fordetails, visitcla.microsoft.com.

This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQor contactopencode@microsoft.com with anyadditional questions or comments.