Table of Contents

Class MessageSession

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

Represents a message session that allows grouping of related messages for processing in a single transaction.

public abstract class MessageSession : MessageReceiver
Inheritance
MessageSession
Inherited Members

Properties

IsExclusiveMode

public bool IsExclusiveMode { get; protected set; }

Property Value

bool

LastPeekedSequenceNumber

Gets or sets the last peeked sequence number in the session.

public override long LastPeekedSequenceNumber { get; }

Property Value

long

The last peeked sequence number in the session.

LockToken

public Guid? LockToken { get; protected set; }

Property Value

Guid?

The lock token

LockedUntilUtc

Gets or sets the date and time at which the message session is unlocked.

public DateTime LockedUntilUtc { get; protected set; }

Property Value

DateTime

The date and time for the message session to be locked.

Path

Gets the path of the queue or topic, relative to the MessagingFactory base address.

public override string Path { get; }

Property Value

string

A string representing the path of the queue or topic.

PrefetchCount

Gets or sets the number of messages that the message receiver can simultaneously request.

public override int PrefetchCount { get; set; }

Property Value

int

The number of messages that the message receiver can simultaneously request.

SessionId

Gets or sets the message session identifier.

public virtual string SessionId { get; protected set; }

Property Value

string

The message session identifier.

SupportsGetRuntimeEntityDescription

protected override bool SupportsGetRuntimeEntityDescription { get; }

Property Value

bool

Methods

GetState()

Gets the state of the message session.

public Stream GetState()

Returns

Stream

The stream from which the state information is persisted.

GetStateAsync()

Asynchronously gets the state of the message session.

public Task<Stream> GetStateAsync()

Returns

Task<Stream>

The stream from which the state information is persisted.

OnAbandon(TrackingContext, IEnumerable<Guid>, IDictionary<string, object>, TimeSpan)

Abandons a peek locked message.

protected override void OnAbandon(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, IDictionary<string, object> propertiesToModify, TimeSpan timeout)

Parameters

trackingContext TrackingContext

TrackingContext to use.

lockTokens IEnumerable<Guid>

The lock tokens.

propertiesToModify IDictionary<string, object>
timeout TimeSpan

The timeout.

OnAbort()

Aborts the message session.

protected override void OnAbort()

OnBeginAbandon(TrackingContext, IEnumerable<Guid>, IDictionary<string, object>, bool, TimeSpan, AsyncCallback, object)

Executes the begin abandon action.

protected override IAsyncResult OnBeginAbandon(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, IDictionary<string, object> propertiesToModify, bool fromSync, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext
lockTokens IEnumerable<Guid>

The lock tokens.

propertiesToModify IDictionary<string, object>

The properties to add for the abandon action.

fromSync bool
timeout TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnBeginClose(TimeSpan, AsyncCallback, object)

Begins an asynchronous operation to close the communication object for the message session.

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

Parameters

timeout TimeSpan

The time span interval the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous operation to close the communication object for the message session.

OnBeginComplete(TrackingContext, IEnumerable<ArraySegment<byte>>, bool, TimeSpan, AsyncCallback, object)

Executes upon calling the OnComplete or BeginComplete operation.

protected override IAsyncResult OnBeginComplete(TrackingContext trackingContext, IEnumerable<ArraySegment<byte>> deliveryTags, bool fromSync, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The context information associated by a transaction tracking this operation.

deliveryTags IEnumerable<ArraySegment<byte>>

A collection of delivery tags.

fromSync bool

The start of the synchronization.

timeout TimeSpan

The time span interval the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

AnIAsyncResult that references the asynchronous operation to close the communication object for the message session.

OnBeginComplete(TrackingContext, IEnumerable<Guid>, bool, TimeSpan, AsyncCallback, object)

Executes upon calling the OnComplete or BeginComplete operation.

protected override IAsyncResult OnBeginComplete(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, bool fromSync, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The context information associated by a transaction tracking this operation.

lockTokens IEnumerable<Guid>

The collection of lock tokens bound to the locked message instances.

fromSync bool

The start of the synchronization.

timeout TimeSpan

The time span interval the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

AnIAsyncResult that references the asynchronous operation to close the communication object for the message session.

OnBeginDeadLetter(TrackingContext, IEnumerable<Guid>, IDictionary<string, object>, string, string, bool, TimeSpan, AsyncCallback, object)

Executes the begin move to dead letter queue action.

protected override IAsyncResult OnBeginDeadLetter(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, IDictionary<string, object> propertiesToModify, string deadLetterReason, string deadLetterErrorDescription, bool fromSync, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

TrackingContext to use.

lockTokens IEnumerable<Guid>

The lock tokens.

propertiesToModify IDictionary<string, object>

message properties to modify.

deadLetterReason string

The reason for deadlettering the message.

deadLetterErrorDescription string

The description information for deadlettering the message.

fromSync bool

true if this was called from a sync method.

timeout TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnBeginDefer(TrackingContext, IEnumerable<Guid>, IDictionary<string, object>, bool, TimeSpan, AsyncCallback, object)

Executes the begin defer action.

protected override IAsyncResult OnBeginDefer(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, IDictionary<string, object> propertiesToModify, bool fromSync, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

TrackingContext to use.

lockTokens IEnumerable<Guid>

The lock tokens.

propertiesToModify IDictionary<string, object>

message properties to modify.

fromSync bool
timeout TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

OnBeginGetState(TrackingContext, TimeSpan, AsyncCallback, object)

Executes the begin get state action.

protected abstract IAsyncResult OnBeginGetState(TrackingContext trackingContext, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The TrackingContext to use.

timeout TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnBeginOpen(TimeSpan, AsyncCallback, object)

Executes upon calling the OnOpen operation of the message receiver.

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

Parameters

timeout TimeSpan

The time span interval the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

An IAsyncResult that references the asynchronous operation to open a communication object for the message session.

OnBeginPeek(TrackingContext, long, int, TimeSpan, AsyncCallback, object)

Executes upon calling the OnPeek or BeginPeek operation.

protected override IAsyncResult OnBeginPeek(TrackingContext trackingContext, long fromSequenceNumber, int messageCount, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The context information associated by a transaction tracking this operation.

fromSequenceNumber long

The sequence number to peek from the session.

messageCount int

The number of message in the operation.

timeout TimeSpan

The time span interval the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

AnIAsyncResult that references the asynchronous operation to peek a communication of the message session.

OnBeginRenewLock(TrackingContext, TimeSpan, AsyncCallback, object)

Executes upon calling the RenewLock or BeginRenewLock operation.

protected abstract IAsyncResult OnBeginRenewLock(TrackingContext trackingContext, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The context information associated by a transaction tracking this operation.

timeout TimeSpan

The time span interval the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

AnIAsyncResult that references the asynchronous operation to get the state of the operation.

OnBeginRenewMessageLocks(TrackingContext, IEnumerable<Guid>, bool, TimeSpan, AsyncCallback, object)

Executes upon calling the OnBegin operation for lock messages.

protected override IAsyncResult OnBeginRenewMessageLocks(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, bool fromSync, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The context information associated by a transaction tracking this operation.

lockTokens IEnumerable<Guid>

The collection of lock tokens bound to the locked message instances.

fromSync bool

The start of the synchronization.

timeout TimeSpan

The time span the operation waits before it 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 state information about the asynchronous operation.

Returns

IAsyncResult

AnIAsyncResult that references the asynchronous operation to renew processing of lock messages.

OnBeginSetState(TrackingContext, Stream, TimeSpan, AsyncCallback, object)

Executes the begin set state action.

protected abstract IAsyncResult OnBeginSetState(TrackingContext trackingContext, Stream sessionState, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

The TrackingContext to use.

sessionState Stream

The state.

timeout TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnBeginTryReceive(TrackingContext, IEnumerable<long>, TimeSpan, AsyncCallback, object)

Executes the begin try receive action.

protected override IAsyncResult OnBeginTryReceive(TrackingContext trackingContext, IEnumerable<long> receipts, TimeSpan timeout, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

TrackingContext to use.

receipts IEnumerable<long>

The receipts.

timeout TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnBeginTryReceive(TrackingContext, int, TimeSpan, AsyncCallback, object)

Executes the begin try receive action.

protected override IAsyncResult OnBeginTryReceive(TrackingContext trackingContext, int messageCount, TimeSpan serverWaitTime, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

TrackingContext to use.

messageCount int

Number of messages.

serverWaitTime TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnBeginTryReceive2(TrackingContext, int, TimeSpan, AsyncCallback, object)

Executes the begin try receive action.

protected override IAsyncResult OnBeginTryReceive2(TrackingContext trackingContext, int messageCount, TimeSpan serverWaitTime, AsyncCallback callback, object state)

Parameters

trackingContext TrackingContext

TrackingContext to use.

messageCount int

Number of messages.

serverWaitTime TimeSpan

The timeout.

callback AsyncCallback

The callback.

state object

The state.

Returns

IAsyncResult

.

OnComplete(TrackingContext, IEnumerable<Guid>, TimeSpan)

Completes a peek locked message.

protected override void OnComplete(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, TimeSpan timeout)

Parameters

trackingContext TrackingContext

TrackingContext to use.

lockTokens IEnumerable<Guid>

The lock tokens.

timeout TimeSpan

The timeout.

OnDeadLetter(TrackingContext, IEnumerable<Guid>, IDictionary<string, object>, string, string, TimeSpan)

Moves a message to the dead letter queue.

protected override void OnDeadLetter(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, IDictionary<string, object> propertiesToModify, string deadLetterReason, string deadLetterErrorDescription, TimeSpan timeout)

Parameters

trackingContext TrackingContext
lockTokens IEnumerable<Guid>
propertiesToModify IDictionary<string, object>
deadLetterReason string
deadLetterErrorDescription string
timeout TimeSpan

OnDefer(TrackingContext, IEnumerable<Guid>, IDictionary<string, object>, TimeSpan)

Defers a message.

protected override void OnDefer(TrackingContext trackingContext, IEnumerable<Guid> lockTokens, IDictionary<string, object> propertiesToModify, TimeSpan timeout)

Parameters

trackingContext TrackingContext

TrackingContext to use.

lockTokens IEnumerable<Guid>

The lock tokens.

propertiesToModify IDictionary<string, object>

message properties to modify.

timeout TimeSpan

The timeout.

OnEndAbandon(IAsyncResult)

Ends an asynchronous operation to abandon the message and relinquish its lock.

protected override void OnEndAbandon(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to abandon the messages and relinquish its lock.

OnEndClose(IAsyncResult)

Ends an asynchronous operation to close the communication object for the message session.

protected override void OnEndClose(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to close the communication object for the message session.

OnEndComplete(IAsyncResult)

Executes the end complete operation of the message receiver.

protected override void OnEndComplete(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to complete receiving of messages.

OnEndDeadLetter(IAsyncResult)

Executes the end deadletter operation of the message receiver.

protected override void OnEndDeadLetter(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to move undelivered messages to the deadletter queue.

OnEndDefer(IAsyncResult)

Executes the end defer operation of the message receiver.

protected override void OnEndDefer(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to suspend processing of messages.

OnEndGetState(IAsyncResult)

Executes upon calling the OnGetState or EndGetState operation.

protected abstract Stream OnEndGetState(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to get the state of the message session.

Returns

Stream

The stream from which the state information is persisted.

OnEndOpen(IAsyncResult)

Ends the asynchronous operation to open a communication object for the message session.

protected override void OnEndOpen(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to open a communication object for the message session.

OnEndPeek(IAsyncResult)

Executes upon calling the EndPeek operation.

protected override IEnumerable<BrokeredMessage> OnEndPeek(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to peek a communication of the message session.

Returns

IEnumerable<BrokeredMessage>

The list of message from the session.

OnEndRenewLock(IAsyncResult)

Executes the EndRenewLock operation of the message receiver.

protected abstract DateTime OnEndRenewLock(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to get the state of the message session.

Returns

DateTime

The date and time when the renewal of lock ends.

OnEndRenewMessageLocks(IAsyncResult)

Executes the EndRenew action for message locks.

protected override IEnumerable<DateTime> OnEndRenewMessageLocks(IAsyncResult result)

Parameters

result IAsyncResult

The result of the operation.

Returns

IEnumerable<DateTime>

An IEnumerable<T> of locked messages..

OnEndSetState(IAsyncResult)

Ends the asynchronous operation to set the state of the message session.

protected abstract void OnEndSetState(IAsyncResult result)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to set the state of the message session.

OnEndTryReceive(IAsyncResult, out IEnumerable<BrokeredMessage>)

Executes the end try receive operation of the message receiver.

protected override bool OnEndTryReceive(IAsyncResult result, out IEnumerable<BrokeredMessage> messages)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to try to receive messages.

messages IEnumerable<BrokeredMessage>

When this method returns, contains the received message collection.

Returns

bool

true if it succeeds; false if it fails.

OnEndTryReceive2(IAsyncResult, out IEnumerable<BrokeredMessage>)

Executes the end try receive operation of the message receiver.

protected override bool OnEndTryReceive2(IAsyncResult result, out IEnumerable<BrokeredMessage> messages)

Parameters

result IAsyncResult

An IAsyncResult that references the asynchronous operation to try to receive messages.

messages IEnumerable<BrokeredMessage>

When this method returns, contains the received message collection.

Returns

bool

true if it succeeds; false if it fails.

OnGetState(TrackingContext, TimeSpan)

Executes the get state action.

protected virtual Stream OnGetState(TrackingContext trackingContext, TimeSpan timeout)

Parameters

trackingContext TrackingContext

The TrackingContext to use.

timeout TimeSpan

The timeout.

Returns

Stream

.

OnRenewLock(TrackingContext, TimeSpan)

Executes the RenewLock action for message locks.

protected virtual DateTime OnRenewLock(TrackingContext trackingContext, TimeSpan timeout)

Parameters

trackingContext TrackingContext

The context information associated by a transaction tracking this operation.

timeout TimeSpan

The time span interval the operation waits before it times out.

Returns

DateTime

The time span the operation waits before it times out.

OnSetState(TrackingContext, Stream, TimeSpan)

Executes the set state action.

protected virtual void OnSetState(TrackingContext trackingContext, Stream stream, TimeSpan timeout)

Parameters

trackingContext TrackingContext

The TrackingContext to use.

stream Stream

The stream.

timeout TimeSpan

The timeout.

OnTryReceive(TrackingContext, IEnumerable<long>, TimeSpan, out IEnumerable<BrokeredMessage>)

Executes the try receive action.

protected override bool OnTryReceive(TrackingContext trackingContext, IEnumerable<long> receipts, TimeSpan timeout, out IEnumerable<BrokeredMessage> messages)

Parameters

trackingContext TrackingContext

TrackingContext to use.

receipts IEnumerable<long>

The receipts.

timeout TimeSpan

The timeout.

messages IEnumerable<BrokeredMessage>

the output message (out)

Returns

bool

OnTryReceive(TrackingContext, int, TimeSpan, out IEnumerable<BrokeredMessage>)

Executes the try receive action.

protected override bool OnTryReceive(TrackingContext trackingContext, int messageCount, TimeSpan serverWaitTime, out IEnumerable<BrokeredMessage> messages)

Parameters

trackingContext TrackingContext

TrackingContext to use.

messageCount int

The number of messages.

serverWaitTime TimeSpan

The server wait time before it times out.

messages IEnumerable<BrokeredMessage>

returned messages.

Returns

bool

ProcessException(Exception)

protected Exception ProcessException(Exception exception)

Parameters

exception Exception

Returns

Exception

RenewLock()

Specifies the time period within which the host renews its lock on a message.

public void RenewLock()

Exceptions

MessagingException

If IsTransient is true, you can retry the operation immediately.

MessagingCommunicationException

You can retry the operation immediately.

TimeoutException

You can retry the operation immediately.

SessionLockLostException

Thrown instead of MessageLockLostException if the message is from a MessageSession.

RenewLockAsync()

Specifies the time period within which the host renews its lock on a message.

public Task RenewLockAsync()

Returns

Task

The host that is being locked.

SetState(Stream)

Sets the state of the message session.

public void SetState(Stream sessionState)

Parameters

sessionState Stream

The stream to which the state information is persisted.

SetStateAsync(Stream)

Asynchronously sets the state of the message session.

public Task SetStateAsync(Stream sessionState)

Parameters

sessionState Stream

The stream to which the state information is persisted.

Returns

Task

The state of the message session.