Microsoft.ServiceBus.Messaging

Azure Service Bus .NET Framework samples

This repository contains the official set of samples for the Azure Service Bus service (Standard and Premium), illustrating all core features of Service Bus queues and Service Bus topics. This samples all use the WindowsAzure.ServiceBus NuGet package for the full .NET Framework.

Setup

First, clone this git repository locally.

The samples require creating an Azure subscription if you don't have one. You also need
a Service Bus namespace, and a simple basic topology of a few exemplary queues, topics, and subscriptions. To set those up, with an Azure Service Bus "Standard" namespace, just click the button below and follow the further instructions on the Azure Portal:

The free Azure subscription offer includes a service credit that will take you very far with all your experiments. The prorated monthly base fee for Service Bus Standard includes a generous allocation of message operations, and you can even run a large Service Bus Premium namespace with 4 Messaging Units for several days.

You can also deploy the resource manager template from the command line:

Setup using PowerShell

The PowerShell setup is functionally equivalent. You first create a resource group and then deploy the resource manager template:

New-AzureRmResourceGroup -Name {rg-name} -Location "Central US"
New-AzureRmResourceGroupDeployment \
      -Name {deployment-name} \
      -ResourceGroupName {rg-name}
      -TemplateFile scripts/azuredeploy.json \
      -serviceBusNamespaceName {service-bus-namespace-name} 

Exploring and running the samples

To make running the samples straightforward, there is a Powershell (Azure PS) script in scripts that will obtain the namespace connection string from your current Azure subscription, assume the entity names configured in the deployed templates, and export those into a configuration file in your user directory, eliminating the need to pass arguments on the command line.

The Powershell script is scripts/setupenv.ps1. It needs to be called with the name of the Resource Group and the Service Bus namespace name as ordinal arguments.

Run the Powershell script from the scripts directory with

./setupenv.ps1 {rg-name} {service-bus-namespace-name} 

Common Considerations

Most samples use shared entry-point boilerplate code that loads the configuration and then launches the sample's Program.Run() instance methods.

All samples use the asynchronous, task-based programming model of the .NET Framework and therefore the xAsync overloads of the respective Service Bus API methods. Since nearly all Service Bus operations result in network I/O, using the asynchronous programming model is strongly encouraged at all times as it yields significantly more efficient execution at runtime.

As you are exploring the samples, you should keep in mind that these samples are not aiming to show the simplest way to use the Service Bus API, but rather the recommended, most robust, and most efficient way to use the Service Bus API. The samples are therefore more explicit and take more lines of code than the simplest use of the API would. Distributed systems, and especially cloud systems, are dynamic environments and the samples reflect this reality.

Samples

Getting Started

• Getting Started with Queues - The QueuesGettingStarted sample illustrates the basic send and receive gestures for interacting with a previously provisioned Service Bus Queue. Most other samples in this repository are derivatives of this basic sample.
• Getting Started with Topics - The TopicsGettingStarted sample illustrates the basic gestures for sending messages into Topics and receiving them from Subscriptions.

Message Handling

• Senders and Receivers with Queues - The SendersReceiversWithQueues sample shows how to use the MessagingFactoryfor explicit connection management and the generic MessageSender and MessageReceiver abstractions with queues.
• Senders and Receivers with Topics - The SendersReceiversWithTopics sample is a variation of the SendersReceiversWithQueues sample and shows how nearly identical code can be use with queues and topics when using the MessageSender and MessageReceiver abstractions.
• Receive Loop - ReceiveLoop shows how to use an explicit receive loop with a queues instead of the recommended, callback-based OnMessage(Async) API used in the "getting started" sample.
• Message Prefetching - The Prefetch sample shows the difference between having "prefetch" turned on or off for the receiver. Prefetch is a background receive operation that acquires messages into a buffer before the application itself calls Receive and therefore optimizes and often accelerates the message flow.
• Duplicate Detection - The sample for DuplicateDetection illustrates how Service Bus suppresses the secound and all further messages sent with an identical MessageId when sent during a defined duplicate detection time window when the RequiresDuplicateDetection flag is turned on for a Queue or Topic.
• Message Browsing - MessageBrowse shows how to enumerate all messages residing in a Queue or Subscription without receiving or locking them. This method also allows finding deferred and scheduled messages.
• Auto Forward - AutoForward illustrates how and why to use automatic forwarding between entities in Service Bus.

Topics and Subscriptions

• Topic Filters - The TopicFilters sample illustrates how to create and configure filters on Topic Subscriptions.
• Priority Subscriptions - the sample PrioritySubscriptions shows how to model a "priority queue" pattern with a Topic, with each priority tier having its own Topic Subscription.

Partitioned Entities

• Partitioned Queues - PartitionedQueues are largely identical in handling to "regular" queues (and are the default option when creating new queues via the Azure portal), but are more resilient against slowdowns in the backend storage system. This sample illustrates some special considerations to keep in mind for partitioned queues.

Error and Transaction Handling

• Deadletter Queues - The DeadletterQueue sample shows how to use the deadletter queue for setting aside messages that cannot be processed, and how to receive from the deadletter queue to inspect, repair, and resubmit such messages.
• Time To Live - The TimeToLive example shows the basic functionality of the TimeToLive option for messages as well as handling of the deadletter queue where messages can optionally be stored by the system as they expire.
• Atomic Transactions - Service Bus supports wrapping AtomicTransactions scopes around a range of operations, allowing for such groups of operations to either jointly succeed or fail, enabling creating more robust business applications in the cloud.
• Durable Senders - The DurableSender sample shows how to make client applications robust against frequent network link failures.
• Geo Replication - The GeoReplication sample illustrates how to route messages through two distinct entities, possibly located in different namespaces in different datacenters, to limit the application's availability risk.

Session and Workflow Management Features

• Sessions - The Sessions sample shows how to enforce strict ordered processing for messages originating from a particular context, and how to multiplex multiple distinct contexts over a single Queue or a Subscription.
• Deferral - The Deferral sample shows how to postpone processing of received messages by deferral, which allows pushing messages back into a Queue or Subscription so that they can be picked up directly as the processor is ready to handle them.
• Session State - The SessionState sample shows how to keep track of processing a workflow using the session state feature.

Windows Communication Foundation (WCF) Binding

• NetMessagingBinding - The NetMessagingBinding sample shows how to use Service Bus queues and Topics seamlessly the context of WCF applications using the NetMessagingBinding.
• Sessions with the NetMessagingBinding - The NetMessagingSession sample shows how to use Service Bus sessions with the NetMessagingBinding.