Quickstart: Send events to and receive events from Azure Event Hubs using .NET

Assign roles to your Microsoft Entra user

When developing locally, make sure that the user account that connects to Azure Event Hubs has the correct permissions. You'll need the Azure Event Hubs Data Owner role in order to send and receive messages. To assign yourself this role, you'll need the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. Learn more about the available scopes for role assignments on the scope overview page.

The following example assigns the Azure Event Hubs Data Owner role to your user account, which provides full access to Azure Event Hubs resources. In a real scenario, follow the Principle of Least Privilege to give users only the minimum permissions needed for a more secure production environment.

Azure built-in roles for Azure Event Hubs

For Azure Event Hubs, the management of namespaces and all related resources through the Azure portal and the Azure resource management API is already protected using the Azure RBAC model. Azure provides the below Azure built-in roles for authorizing access to an Event Hubs namespace:

• Azure Event Hubs Data Owner: Enables data access to Event Hubs namespace and its entities (queues, topics, subscriptions, and filters)
• Azure Event Hubs Data Sender: Use this role to give the sender access to Event Hubs namespace and its entities.
• Azure Event Hubs Data Receiver: Use this role to give the receiver access to Event Hubs namespace and its entities.

If you want to create a custom role, see Rights required for Event Hubs operations.

az servicebus namespace show -g '<your-event-hub-resource-group>' -n '<your-event-hub-name> --query id

az role assignment create --assignee "<user@domain>" \
--role "Azure Event Hubs Data Owner" \
--scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<your-event-hub-resource-group>" -Name "<your-event-hub-name>"

New-AzRoleAssignment -SignInName <user@domain> `
-RoleDefinitionName "Azure Event Hubs Data Owner" `
-Scope <yourStorageAccountId>

Launch Visual Studio and sign-in to Azure

You can authorize access to the service bus namespace using the following steps:

1. Launch Visual Studio. If you see the Get started window, select the Continue without code link in the right pane.

2. Select the Sign in button in the top right of Visual Studio.

   

3. Sign-in using the Microsoft Entra account you assigned a role to previously.

   

Get the connection string

Creating a new namespace automatically generates an initial Shared Access Signature (SAS) policy with primary and secondary keys and connection strings that each grant full control over all aspects of the namespace. See Event Hubs authentication and authorization for information about how to create rules with more constrained rights for regular senders and receivers.

A client can use the connection string to connect to the Event Hubs namespace. To copy the primary connection string for your namespace, follow these steps:

1. On the Event Hub Namespace page, select Shared access policies on the left menu.

2. On the Shared access policies page, select RootManageSharedAccessKey.

3. In the Policy: RootManageSharedAccessKey window, select the copy button next to Primary Connection String, to copy the connection string to your clipboard for later use. Paste this value into Notepad or some other temporary location.

   

   You can use this page to copy primary key, secondary key, primary connection string, and secondary connection string.

1. Select Tools > NuGet Package Manager > Package Manager Console from the menu.

2. Run the following commands to install Azure.Messaging.EventHubs and Azure.Identity NuGet packages. Press ENTER to run the second command.

   Install-Package Azure.Messaging.EventHubs
   Install-Package Azure.Identity
   

1. Select Tools > NuGet Package Manager > Package Manager Console from the menu.

2. Run the following command to install the Azure.Messaging.EventHubs NuGet package:

   Install-Package Azure.Messaging.EventHubs
   

1. Replace the existing code in the Program.cs file with the following sample code. Then, replace <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values for the EventHubProducerClient parameters with the names of your Event Hubs namespace and the event hub. For example: "spehubns0309.servicebus.chinacloudapi.cn" and "spehub".

   Here are the important steps from the code:

   1. Creates an EventHubProducerClient object using the namespace and the event hub name.
   2. Invokes the CreateBatchAsync method on the EventHubProducerClient object to create an EventDataBatch object.
   3. Add events to the batch using the EventDataBatch.TryAdd method.
   4. Sends the batch of messages to the event hub using the EventHubProducerClient.SendAsync method.

   using Azure.Identity;
   using Azure.Messaging.EventHubs;
   using Azure.Messaging.EventHubs.Producer;
   using System.Text;
   
   // number of events to be sent to the event hub
   int numOfEvents = 3;
   
   // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when events are being published or read regularly.
   // TODO: Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values
   EventHubProducerClient producerClient = new EventHubProducerClient(
       "<EVENT_HUB_NAMESPACE>.servicebus.chinacloudapi.cn",
       "<HUB_NAME>",
       new DefaultAzureCredential());
   
   // Create a batch of events 
   using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();
   
   for (int i = 1; i <= numOfEvents; i++)
   {
       if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
       {
           // if it is too large for the batch
           throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
       }
   }
   
   try
   {
       // Use the producer client to send the batch of events to the event hub
       await producerClient.SendAsync(eventBatch);
       Console.WriteLine($"A batch of {numOfEvents} events has been published.");
       Console.ReadLine();
   }
   finally
   {
       await producerClient.DisposeAsync();
   }
   

1. Replace the existing code in the Program.cs file with the following sample code. Then, replace the <CONNECTION_STRING> and <HUB_NAME> placeholder values for the EventHubProducerClient parameters.

   Here are the important steps from the code:

   1. Creates a EventHubProducerClient object using the primary connection string to the namespace and the event hub name.
   2. Invokes the CreateBatchAsync method on the EventHubProducerClient object to create a EventDataBatch object.
   3. Add events to the batch using the EventDataBatch.TryAdd method.
   4. Sends the batch of messages to the event hub using the EventHubProducerClient.SendAsync method.

   using Azure.Messaging.EventHubs;
   using Azure.Messaging.EventHubs.Producer;
   using System.Text;
   
   // number of events to be sent to the event hub
   int numOfEvents = 3;
   
   // The Event Hubs client types are safe to cache and use as a singleton for the lifetime
   // of the application, which is best practice when events are being published or read regularly.
   // TODO: Replace the <CONNECTION_STRING> and <HUB_NAME> placeholder values
   EventHubProducerClient producerClient = new EventHubProducerClient(
       "<CONNECTION_STRING>",
       "<HUB_NAME>");
   
   // Create a batch of events 
   using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();
   
   for (int i = 1; i <= numOfEvents; i++)
   {
       if (!eventBatch.TryAdd(new EventData(Encoding.UTF8.GetBytes($"Event {i}"))))
       {
           // if it is too large for the batch
           throw new Exception($"Event {i} is too large for the batch and cannot be sent.");
       }
   }
   
   try
   {
       // Use the producer client to send the batch of events to the event hub
       await producerClient.SendAsync(eventBatch);
       Console.WriteLine($"A batch of {numOfEvents} events has been published.");
       Console.ReadLine();
   }
   finally
   {
       await producerClient.DisposeAsync();
   }
   

When developing locally, make sure that the user account that is accessing blob data has the correct permissions. You'll need Storage Blob Data Contributor to read and write blob data. To assign yourself this role, you'll need to be assigned the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. You can learn more about the available scopes for role assignments on the scope overview page.

In this scenario, you'll assign permissions to your user account, scoped to the storage account, to follow the Principle of Least Privilege. This practice gives users only the minimum permissions needed and creates more secure production environments.

The following example will assign the Storage Blob Data Contributor role to your user account, which provides both read and write access to blob data in your storage account.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Get the connection string to the storage account

Note down the connection string and the container name. You use them in the code to receive events from the event hub.

1. Select Tools > NuGet Package Manager > Package Manager Console from the menu.

2. In the Package Manager Console window, confirm that EventHubsReceiver is selected for the Default project. If not, use the drop-down list to select EventHubsReceiver.

3. Run the following command to install the Azure.Messaging.EventHubs and the Azure.Identity NuGet packages. Press ENTER to run the last command.

   Install-Package Azure.Messaging.EventHubs
   Install-Package Azure.Messaging.EventHubs.Processor
   Install-Package Azure.Identity
   

1. Select Tools > NuGet Package Manager > Package Manager Console from the menu.

2. In the Package Manager Console window, confirm that EventHubsReceiver is selected for the Default project. If not, use the drop-down list to select EventHubsReceiver.

3. Run the following command to install the Azure.Messaging.EventHubs NuGet package:

   Install-Package Azure.Messaging.EventHubs
   Install-Package Azure.Messaging.EventHubs.Processor
   

1. Replace the existing code in the Program.cs file with the following sample code. Then, replace the <STORAGE_ACCOUNT_NAME> and <BLOB_CONTAINER_NAME> placeholder values for the BlobContainerClient URI. Replace the <EVENT_HUB_NAMESPACE> and <HUB_NAME> placeholder values for the EventProcessorClient as well.

   Here are the important steps from the code:

   1. Creates an EventProcessorClient object using the Event Hubs namespace and the event hub name. You need to build BlobContainerClient object for the container in the Azure storage you created earlier.
   2. Specifies handlers for the ProcessEventAsync and ProcessErrorAsync events of the EventProcessorClient object.
   3. Starts processing events by invoking the StartProcessingAsync on the EventProcessorClient object.
   4. Stops processing events after 30 seconds by invoking StopProcessingAsync on the EventProcessorClient object.

   using Azure.Identity;
   using Azure.Messaging.EventHubs;
   using Azure.Messaging.EventHubs.Consumer;
   using Azure.Messaging.EventHubs.Processor;
   using Azure.Storage.Blobs;
   using System.Text;
   
   // Create a blob container client that the event processor will use
   // TODO: Replace <STORAGE_ACCOUNT_NAME> and <BLOB_CONTATINAER_NAME> with actual names
   BlobContainerClient storageClient = new BlobContainerClient(
       new Uri("https://<STORAGE_ACCOUNT_NAME>.blob.core.chinacloudapi.cn/<BLOB_CONTAINER_NAME>"),
       new DefaultAzureCredential());
   
   // Create an event processor client to process events in the event hub
   // TODO: Replace the <EVENT_HUBS_NAMESPACE> and <HUB_NAME> placeholder values
   var processor = new EventProcessorClient(
       storageClient,
       EventHubConsumerClient.DefaultConsumerGroupName,
       "<EVENT_HUB_NAMESPACE>.servicebus.chinacloudapi.cn",
       "<HUB_NAME>",
       new DefaultAzureCredential());
   
   // Register handlers for processing events and handling errors
   processor.ProcessEventAsync += ProcessEventHandler;
   processor.ProcessErrorAsync += ProcessErrorHandler;
   
   // Start the processing
   await processor.StartProcessingAsync();
   
   // Wait for 30 seconds for the events to be processed
   await Task.Delay(TimeSpan.FromSeconds(30));
   
   // Stop the processing
   await processor.StopProcessingAsync();
   
   Task ProcessEventHandler(ProcessEventArgs eventArgs)
   {
       // Write the body of the event to the console window
       Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
       Console.ReadLine();
       return Task.CompletedTask;
   }
   
   Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
   {
       // Write details about the error to the console window
       Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
       Console.WriteLine(eventArgs.Exception.Message);
       Console.ReadLine();
       return Task.CompletedTask;
   }
   

1. Replace the existing code in the Program.cs file with the following sample code. Then, replace the <AZURE_STORAGE_CONNECTION_STRING> and <BLOB_CONTAINER_NAME> placeholder values for the BlobContainerClient URI. Replace the <EVENT_HUB_NAMESPACE_CONNECTION_STRING> and <HUB_NAME> placeholder values for the EventProcessorClient as well.

   Here are the important steps from the code:

   1. Creates an EventProcessorClient object using the primary connection string to the namespace and the event hub. You need to build BlobContainerClient object for the container in the Azure storage you created earlier.
   2. Specifies handlers for the ProcessEventAsync and ProcessErrorAsync events of the EventProcessorClient object.
   3. Starts processing events by invoking the StartProcessingAsync on the EventProcessorClient object.
   4. Stops processing events after 30 seconds by invoking StopProcessingAsync on the EventProcessorClient object.

   using Azure.Messaging.EventHubs;
   using Azure.Messaging.EventHubs.Consumer;
   using Azure.Messaging.EventHubs.Processor;
   using Azure.Storage.Blobs;
   using System.Text;
   
   // Create a blob container client that the event processor will use 
   BlobContainerClient storageClient = new BlobContainerClient(
       "<AZURE_STORAGE_CONNECTION_STRING>", "<BLOB_CONTAINER_NAME>");
   
   // Create an event processor client to process events in the event hub
   var processor = new EventProcessorClient(
       storageClient,
       EventHubConsumerClient.DefaultConsumerGroupName,
       "<EVENT_HUBS_NAMESPACE_CONNECTION_STRING>",
       "<HUB_NAME>");
   
   // Register handlers for processing events and handling errors
   processor.ProcessEventAsync += ProcessEventHandler;
   processor.ProcessErrorAsync += ProcessErrorHandler;
   
   // Start the processing
   await processor.StartProcessingAsync();
   
   // Wait for 30 seconds for the events to be processed
   await Task.Delay(TimeSpan.FromSeconds(30));
   
   // Stop the processing
   await processor.StopProcessingAsync();
   
   Task ProcessEventHandler(ProcessEventArgs eventArgs)
   {
       // Write the body of the event to the console window
       Console.WriteLine("\tReceived event: {0}", Encoding.UTF8.GetString(eventArgs.Data.Body.ToArray()));
       return Task.CompletedTask;
   }
   
   Task ProcessErrorHandler(ProcessErrorEventArgs eventArgs)
   {
       // Write details about the error to the console window
       Console.WriteLine($"\tPartition '{eventArgs.PartitionId}': an unhandled exception was encountered. This was not expected to happen.");
       Console.WriteLine(eventArgs.Exception.Message);
       return Task.CompletedTask;
   }