Table of Contents

Class TopicClient

Namespace
Microsoft.ServiceBus.Messaging
Assembly
Microsoft.ServiceBus.dll

An anchor class used to access a TopicDescription to perform run-time operations.

public abstract class TopicClient : ClientEntity
Inheritance
TopicClient
Inherited Members

Examples

// Create settings for the MessagingFactory (for rutime operations)
MessagingFactorySettings factorySettings = new MessagingFactorySettings()
{
   NetMessagingTransportSettings = new NetMessagingTransportSettings(),
   Credential = TransportClientCredentialBase.CreateSharedSecretCredential(IssuerName, IssuerKey),
};

// Create the MessagingFactory
MessagingFactory factory = 
MessagingFactory.Create(myServiceBusNamespace, factorySettings);

//********************************************************************************
//                          Sending messages to a Topic
//********************************************************************************

// Create topic client
TopicClient myTopicClient = factory.CreateTopicClient(myTopic);

// Create a sender
//MessageSender myMessageSender = myTopicClient.CreateSender(SendMode.Default);

// Send messages
List <object> Issues = new List <object>();
foreach (var issue in Issues)
{
   myMessageSender.Send(new BrokeredMessage(issue));
}

Properties

IsSubQueue

Gets or sets a value that indicates whether the message receiver is created from a subqueue.

protected bool IsSubQueue { get; }

Property Value

bool

true if the message receiver is created from a subqueue; otherwise, false.

MessagingFactory

Gets or sets the messaging factory that was used in creating this TopicClient object.

public MessagingFactory MessagingFactory { get; }

Property Value

MessagingFactory

The messaging factory that was used in creating this TopicClient object.

Path

Gets or sets the full pathname of the file.

public string Path { get; }

Property Value

string

The full pathname of the file.

Methods

CancelScheduledMessageAsync(long)

Cancels a scheduled message

public Task CancelScheduledMessageAsync(long sequenceNumber)

Parameters

sequenceNumber long

Returned on scheduling a message.

Returns

Task

Create(string)

Creates a new instance of TopicClient.

public static TopicClient Create(string path)

Parameters

path string

The path.

Returns

TopicClient

The created TopicClient.

Remarks

This method will attempt to retrieve the connection string information from either app.config, or web.config files. User must supply the connection string using the "AppSettings" section of the configuration. The format of the section is as follows:

        <pre><code class="lang-csharp"></code></pre>

CreateFromConnectionString(string)

Creates a new instance of TopicClient using the specified connection string.

public static TopicClient CreateFromConnectionString(string connectionString)

Parameters

connectionString string

The connection string to use.

Returns

TopicClient

Returns TopicClient.

Remarks

This method expects the connection string supplied has entity level information such as the entity path and authentication information supplied.

CreateFromConnectionString(string, string)

Creates a new instance of TopicClient using the specified connection string and path to the topic. Use this overload only when the connection string does not use the EntityPath property.

public static TopicClient CreateFromConnectionString(string connectionString, string path)

Parameters

connectionString string

The connection string to use.

path string

The path.

Returns

TopicClient

The created TopicClient.

Remarks

This method should only be used with a connection string that has namespace level authentication because the connection string supplied should not have entity level information associated with it.

Exceptions

ArgumentException

Thrown when the format of the parameters is incorrect.

FormatTransferDeadLetterPath(string)

A utility method that, given the topic path and subscription name, forms a full path that points to the dead letter queue of the topic's transfer topic.

public static string FormatTransferDeadLetterPath(string topicPath)

Parameters

topicPath string

The topic path.

Returns

string

Returns a string representing a full path that points to the dead letter queue of the transfer topic of the specified topic. This path can be used in receiver creation or in URI formation (such as a REST URI).

OnAbort()

Executes the abort action.

protected override void OnAbort()

OnBeginClose(TimeSpan, AsyncCallback, object)

Executes the begin close action.

protected override IAsyncResult OnBeginClose(TimeSpan timeout, AsyncCallback callback, object state)

Parameters

timeout TimeSpan

The wait time before the operation times out.

callback AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state object

A user-defined object that contains information about the receive operation. This object is passed to the EndClose delegate when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous Close operation.

OnBeginCreateSender(TimeSpan, AsyncCallback, object)

Executes the begin create sender action.

protected abstract IAsyncResult OnBeginCreateSender(TimeSpan timeout, AsyncCallback callback, object state)

Parameters

timeout TimeSpan

The wait time before the operation times out.

callback AsyncCallback

An AsyncCallback delegate that references the method to invoke when the operation is complete.

state object

A user-defined object that contains information about the receive operation. This object is passed to the Microsoft.ServiceBus.Messaging.TopicClient.EndCreateSender(System.IAsyncResult) when the operation is complete.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous parent method.

OnClose(TimeSpan)

Executes the close action.

protected override void OnClose(TimeSpan timeout)

Parameters

timeout TimeSpan

The wait time before the operation times out.

OnEndClose(IAsyncResult)

Executes the end close action.

protected override void OnEndClose(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous Close operation.

OnEndCreateSender(IAsyncResult)

Executes the end create sender action.

protected abstract MessageSender OnEndCreateSender(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous parent method.

Returns

MessageSender

The newly created MessageSender object.

Peek()

Peeks a BrokeredMessage from current queue/topic.

public BrokeredMessage Peek()

Returns

BrokeredMessage

return the peeked BrokeredMessage. A null is return if peek operation cannot obtain the message within OperationTimeout.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

Peek(long)

Peeks a BrokeredMessage from current queue/topic.

public BrokeredMessage Peek(long fromSequenceNumber)

Parameters

fromSequenceNumber long

The sequence number of message to start peeking from.

Returns

BrokeredMessage

return the peeked BrokeredMessage. A null is return if peek operation cannot obtain the message within OperationTimeout.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

PeekAsync() 

public Task<BrokeredMessage> PeekAsync()

Returns

Task<BrokeredMessage>

PeekAsync(long) 

public Task<BrokeredMessage> PeekAsync(long fromSequenceNumber)

Parameters

fromSequenceNumber long

Returns

Task<BrokeredMessage>

PeekBatch(int)

Peeks a BrokeredMessage from current queue/topic.

public IEnumerable<BrokeredMessage> PeekBatch(int messageCount)

Parameters

messageCount int

The maximum number of messages to peek.

Returns

IEnumerable<BrokeredMessage>

return a list of peeked BrokeredMessages. An empty list is returned if peek operation cannot obtain the message within OperationTimeout.

Remarks

A Null can be return by this API if operation exceeded the timeout specified, or the operations succeeded but there are no more messages to be received.

PeekBatch(long, int) 

public IEnumerable<BrokeredMessage> PeekBatch(long fromSequenceNumber, int messageCount)

Parameters

fromSequenceNumber long
messageCount int

Returns

IEnumerable<BrokeredMessage>

PeekBatchAsync(int) 

public Task<IEnumerable<BrokeredMessage>> PeekBatchAsync(int messageCount)

Parameters

messageCount int

Returns

Task<IEnumerable<BrokeredMessage>>

PeekBatchAsync(long, int) 

public Task<IEnumerable<BrokeredMessage>> PeekBatchAsync(long fromSequenceNumber, int messageCount)

Parameters

fromSequenceNumber long
messageCount int

Returns

Task<IEnumerable<BrokeredMessage>>

ScheduleMessageAsync(BrokeredMessage, DateTimeOffset)

Sends a scheduled message

public Task<long> ScheduleMessageAsync(BrokeredMessage message, DateTimeOffset scheduleEnqueueTimeUtc)

Parameters

message BrokeredMessage

Message to be scheduled

scheduleEnqueueTimeUtc DateTimeOffset

Time of enqueue

Returns

Task<long>

Sequence number that is needed for cancelling.

Send(BrokeredMessage)

Sends a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalSender.

public void Send(BrokeredMessage message)

Parameters

message BrokeredMessage

The message to send.

Exceptions

TimeoutException

Thrown when operation times out. Timeout period is initialized through the OperationTimeout to avoid this exception if timeout value is relatively low.

ArgumentException

Thrown when the BrokeredMessage is null.

InvalidOperationException

Thrown if the message has already been sent by a TopicClient or MessageSender once already.

OperationCanceledException

Thrown if the client entity has been closed or aborted.

UnauthorizedAccessException

Thrown if there is an I/O or security error.

SerializationException

Thrown when an error occurs during serialization or deserialization.

MessagingEntityNotFoundException

Thrown if the topic does not exist.

MessagingException

Thrown if there is a messaging error.

SendAsync(BrokeredMessage)

Asynchronously sends a message using the Microsoft.ServiceBus.Messaging.QueueClient.InternalSender.

public Task SendAsync(BrokeredMessage message)

Parameters

message BrokeredMessage

The message to send.

Returns

Task

The asynchronous result of the operation.

SendBatch(IEnumerable<BrokeredMessage>)

Sends a set of brokered messages (for batch processing).

public void SendBatch(IEnumerable<BrokeredMessage> messages)

Parameters

messages IEnumerable<BrokeredMessage>

The messages to send.

SendBatchAsync(IEnumerable<BrokeredMessage>)

Asynchronously sends a set of brokered messages (for batch processing).

public Task SendBatchAsync(IEnumerable<BrokeredMessage> messages)

Parameters

messages IEnumerable<BrokeredMessage>

The messages to send.

Returns

Task

The asynchronous result of the operation.

See Also

MessagingFactory