Write a Listener for a Windows Azure Solution
[Applies to: Microsoft Dynamics CRM 2011]
This topic describes how to write a listener that can read and process Microsoft Dynamics CRM 2011 messages that are posted to the Windows Azure Service Bus. As a prerequisite, you should familiarize yourself with how to write a Windows Azure Service Bus listener before trying to learn the specifics of a Microsoft Dynamics CRM listener. For more information, see the Windows Azure Service Bus documentation and sample code.
In This Topic
Write a Queue Listener
Write a One-way, Two-way, or REST Listener
Write a Queue Listener
A message queue is a repository of messages received at a service bus endpoint. A queue listener is an application that reads and processes these queued messages. Because the service bus messages are stored in a queue, a listener does not have to be actively listening in order for messages to be received in the queue. A queue listener can be started after messages have arrived in the queue and still process those messages. Other types of listeners discussed in the next section must be actively listening or they will miss the opportunity to read a message. These messages can originate from Microsoft Dynamics CRM or from some other source. When writing a queue listener, it is important to check each message header action to determine if the message originated from Microsoft Dynamics CRM.
You can do a destructive message read using Receive in ReceiveAndDelete mode, where the message is read and removed from the queue, or a non-destructive read using PeekLock mode, where the message is read but still available in the queue. The persistent queue listener sample code provided in this SDK does a destructive read. For more information about reading messages from a queue see How to Receive Messages from a Queue.
A topic is similar to a queue but implements a publish/subscribe model. One or more listeners can subscribe to the topic and receive messages from its queue. For more information, see Queues, Topics, and Subscriptions.
Support for persistent queues and topics is new for Microsoft Dynamics CRM 2011 Update Rollup 12 and Microsoft Dynamics CRM December 2012 Service Update. To use these new contracts, you must write your listener applications using the Windows Azure SDK v1.7 or 1.8. The Windows Azure AppFabric SDK V1.0 is now included in the Windows Azure SDK.
Message buffer queues are deprecated and will not be supported in a future release of the Microsoft Dynamics CRM SDK.
Use of queues and topics in your multi-systems software design can result in the decoupling of systems. If the listener application ever becomes unavailable, the message delivery from Microsoft Dynamics CRM will still succeed and the listener application can continue processing the queue message when it is back online. For more information, see Queues, Topics, and Subscriptions.
Update a Message Buffer Listener to Use Persistent Queues
The following procedure lists the generic steps you would follow to update a listener application that retrieves message from a message buffer to one that receives message from a persistent queue.
How to Update a Message Buffer Listener to Use Persistent Queues
On the Windows Azure portal and in the same solution, create a queue in the same path as was used for the message buffer.
Install the Windows Azure SDK v1.7 or 1.8 on your development box.
Update the listener code by removing the message buffer related classes and methods, and then replace them with QueueClient and Receive. Be sure to use the desired read mode: RetrieveAndDelete or PeekLock. For more information about reading messages from a queue, see Queues, Topics, and Subscriptions.
Build the listener application.
No Microsoft Dynamics CRM configuration changes are necessary as long as the queue endpoint uses the same solution path that the message buffer had used.
Write a One-way, Two-way, or REST Listener
In addition to the queue listener described previously, you can write a listener for three other service bus contracts that are supported by Microsoft Dynamics CRM: one-way, two-way, and REST. A one-way listener can read and process a message posted to the service bus. A two-way listener can do the same but can also return a string of some information back to Microsoft Dynamics CRM. A REST listener is the same as the two-way listener except that it works with a REST endpoint. Notice that these listeners must be actively listening at a service endpoint to read a message sent over the service bus. If the listener is not listening when Microsoft Dynamics CRM attempts to post a message to the service bus, the message does not get sent.
Writing a listener is structured around what is known as ABC: address, binding, and contract. The following information identifies the ABCs of a one-way listener.
After your listener is registered with an endpoint, the listener’s Execute method is invoked whenever a message is posted to the service bus by Microsoft Dynamics CRM. The Execute method does not return any data from the method call. For more information, see the one-way listener sample, Sample: One-Way Listener.
A two-way listener is coded in a similar fashion as a one-way listener. The ABCs of a two-way listener are as follows:
For this two-way contract, the Execute method returns a string from the method call. For more information, see the two-way listener sample, Sample: Two-Way Listener.
A REST listener is coded in a similar fashion as a two-way listener. The ABCs of a REST listener are as follows:
For the REST contract, the Execute method returns a string from the method call. Refer to the REST listener sample, Sample: REST Listener, for more information. Notice that in the REST listener sample, a WebServiceHost is instantiated and not a ServiceHost as was done in the two-way sample.
When using the out-of-box (ServiceBusPlugin) plug-in with a two-way or REST listener, any string data returned from the listener is not used by the plug-in. However, a custom Azure aware plug-in could make use of this information.
When you run the listener samples, the issuer secret you are prompted for is the Windows Azure Service Bus management key. The WS2007 Federation HTTP binding uses “token” mode and the WS-Trust 1.3 protocol.
New in Microsoft Dynamics CRM 2011 Update Rollup 12 and Microsoft Dynamics CRM December 2012 Service Update is a property bag of extra information added to each brokered message Properties property sent from Microsoft Dynamics CRM 2011. The property bag, available with persistent queue and topic contract endpoints, contains the following information.
Calling user ID
Initiating user ID
Entity logical name
This information identifies the organization, user, entity, and message request being processed by Microsoft Dynamics CRM that resulted in the service bus message being posted. Your listener code can choose to process a message it receives based on this information. For more information, see Sample: Execute Multiple Requests.
Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.