QueueClient Class

[This is prerelease documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Provides client access to a queue.

Namespace: Microsoft.ServiceBus
Assembly: Microsoft.ServiceBus (in microsoft.servicebus.dll)

Usage

    Dim instance As QueueClient

Syntax

'Declaration
Public NotInheritable Class QueueClient
public sealed class QueueClient
public ref class QueueClient sealed
public final class QueueClient
public final class QueueClient

Remarks

The .NET Service Bus supports only Full Trust code access security.

QueueClient provides access to a Service Bus Queue. It allows you to retrieve and send messages and to perform management tasks, such as extending the Queue’s lifetime or deleting the Queue. The QueueClient uses the Windows Communication Foundation Message class as a message abstraction.

Service Bus Queues are hosted on the Service Bus at a particular location in the Service Bus namespace. The Queue stores sent messages for later retrieval by single consumer or multiple, competing consumers. The QueueClient sends and retrieves SOAP 1.1 and SOAP 1.2 messages.

QueueClient is not the only means by which messages can be sent into a Service Bus Queue. You can also send a message using the NET.TCP protocol via a client channel with NetOnewayRelayBinding. You can also use the HTTP(S) protocol via a client channel that leverages the WS2007HttpRelayBinding. Clients that are not based on the Windows Communication Foundation, but which support SOAP 1.1 or SOAP 1.2 over HTTP(S) can submit messages into a Service Bus Queue if they implement the [[SOAP authentication and authorization protocol for Service Bus endpoints]]. If the Queue’s Authorization policy element is configured such that the queue allows unauthorized senders, any SOAP 1.1 or SOAP 1.2 HTTP(S) client based on a standards-compliant Web services stack can immediately send messages into the Queue.

Instances of QueueClient cannot be created directly. To obtain a reference to a QueueClient you need to call CreateQueue if you want to create a new queue, or GetQueue to access an existing Service Bus Queue.

QueueClient allows you to send messages into the Queue, and provides two ways to retrieve message from the Queue. The Retrieve methods allow for destructive reads. If Retrieve or RetrieveMultiple(Int32) is used, any retrieved messages are immediately deleted from the service-side Queue when they are acquired and before they are sent to the receiving QueueClient. This allows for single-roundtrip message retrieval, but does not provide resilience against message loss should the connection between the service and the client break as the message(s) is returned to the client or if the client fails processing the message.

If PeekLock or PeekLockMultiple(Int32) is used, any acquired messages are locked and hidden from view so that they no longer appear at the head of the service-side Queue before they are returned to the receiving QueueClient. When the receiver has processed the message it must call DeleteLockedMessage for the message to indicate that it has consumed and processed the message. If the receiver cannot process the message it should call ReleaseLock for the message to restore the message into the Queue. If the client fails to delete a locked message retrieved through a PeekLock or PeekLockMultiple(Int32) call, the message is automatically restored into the Queue after 60 seconds. This pattern provides resilience against message loss if the message were to be lost in transfer or if the receiver were unable to process the message due to unexpected events.

Inheritance Hierarchy

System.Object
  Microsoft.ServiceBus.QueueClient

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows XP Home Edition, Windows XP Professional, Windows Server 2003 , Windows Server 2008, and Windows 2000

Target Platforms

See Also

Reference

QueueClient Members
Microsoft.ServiceBus Namespace