ServiceBusSessionReceiver interface

A receiver that handles sessions, including renewing the session lock.

Extends

Properties

entityPath

Path of the entity for which the receiver has been created.

isClosed

Returns true if either the receiver or the client that created it has been closed.

receiveMode

The receive mode used to create the receiver.

sessionId

The session ID.

sessionLockedUntilUtc

The time in UTC until which the session is locked. Every time renewSessionLock() is called, this time gets updated to current time plus the lock duration as specified during the Queue/Subscription creation. Will return undefined until a AMQP receiver link has been successfully set up for the session.

Methods

abandonMessage(ServiceBusReceivedMessage, [key: string]: any)

The lock held on the message by the receiver is let go, making the message available again in Service Bus for another receive operation.

close()

Closes the receiver. Once closed, the receiver cannot be used for any further operations. Use the createReceiver() method on the ServiceBusClient to create a new Receiver.

completeMessage(ServiceBusReceivedMessage)

Removes the message from Service Bus.

deadLetterMessage(ServiceBusReceivedMessage, DeadLetterOptions & [key: string]: any)

Moves the message to the deadletter sub-queue. To receive a deadletted message, create a new QueueClient/SubscriptionClient using the path for the deadletter sub-queue.

deferMessage(ServiceBusReceivedMessage, [key: string]: any)

Defers the processing of the message. Save the sequenceNumber of the message, in order to receive it message again in the future using the receiveDeferredMessage method.

getMessageIterator(GetMessageIteratorOptions)

Returns an iterator that can be used to receive messages from Service Bus. If the iterator is not able to fetch a new message in over a minute, undefined will be returned.

getSessionState(OperationOptionsBase)

Gets the state of the Session. For more on session states, see | Session State

peekMessages(number, PeekMessagesOptions)

Peek the next batch of active messages (including deferred but not deadlettered messages) on the queue or subscription without modifying them.

  • The first call to peekMessages() fetches the first active message. Each subsequent call fetches the subsequent message.
  • Unlike a "received" message, "peeked" message is a read-only version of the message. It cannot be Completed/Abandoned/Deferred/Deadlettered.
receiveDeferredMessages(Long | Long[], OperationOptionsBase)

Returns a promise that resolves to an array of deferred messages identified by given sequenceNumbers.

receiveMessages(number, ReceiveMessagesOptions)

Returns a promise that resolves to an array of messages received from Service Bus.

renewMessageLock(ServiceBusReceivedMessage)

Renews the lock on the message for the duration as specified during the Queue/Subscription creation.

  • Check the lockedUntilUtc property on the message for the time when the lock expires.
  • If a message is not settled (using either complete(), defer() or deadletter(), before its lock expires, then the message lands back in the Queue/Subscription for the next receive operation.
renewSessionLock(OperationOptionsBase)

Renews the lock on the session.

setSessionState(any, OperationOptionsBase)

Sets the state on the Session. For more on session states, see | Session State

subscribe(MessageHandlers, SubscribeOptions)

Streams messages to message handlers.

Property Details

entityPath

Path of the entity for which the receiver has been created.

entityPath: string

Property Value

string

isClosed

Returns true if either the receiver or the client that created it has been closed.

isClosed: boolean

Property Value

boolean

receiveMode

The receive mode used to create the receiver.

receiveMode: "peekLock" | "receiveAndDelete"

Property Value

"peekLock" | "receiveAndDelete"

sessionId

The session ID.

sessionId: string

Property Value

string

sessionLockedUntilUtc

The time in UTC until which the session is locked. Every time renewSessionLock() is called, this time gets updated to current time plus the lock duration as specified during the Queue/Subscription creation. Will return undefined until a AMQP receiver link has been successfully set up for the session.

sessionLockedUntilUtc: Date

Property Value

Date

Method Details

abandonMessage(ServiceBusReceivedMessage, [key: string]: any)

The lock held on the message by the receiver is let go, making the message available again in Service Bus for another receive operation.

function abandonMessage(message: ServiceBusReceivedMessage, propertiesToModify?: [key: string]: any)

Parameters

propertiesToModify

[key: string]: any

The properties of the message to modify while abandoning the message.

Returns

Promise<void>

close()

Closes the receiver. Once closed, the receiver cannot be used for any further operations. Use the createReceiver() method on the ServiceBusClient to create a new Receiver.

function close()

Returns

Promise<void>

completeMessage(ServiceBusReceivedMessage)

Removes the message from Service Bus.

function completeMessage(message: ServiceBusReceivedMessage)

Parameters

Returns

Promise<void>

deadLetterMessage(ServiceBusReceivedMessage, DeadLetterOptions & [key: string]: any)

Moves the message to the deadletter sub-queue. To receive a deadletted message, create a new QueueClient/SubscriptionClient using the path for the deadletter sub-queue.

function deadLetterMessage(message: ServiceBusReceivedMessage, options?: DeadLetterOptions & [key: string]: any)

Parameters

options

DeadLetterOptions & [key: string]: any

The DeadLetter options that can be provided while rejecting the message.

Returns

Promise<void>

deferMessage(ServiceBusReceivedMessage, [key: string]: any)

Defers the processing of the message. Save the sequenceNumber of the message, in order to receive it message again in the future using the receiveDeferredMessage method.

function deferMessage(message: ServiceBusReceivedMessage, propertiesToModify?: [key: string]: any)

Parameters

propertiesToModify

[key: string]: any

The properties of the message to modify while deferring the message

Returns

Promise<void>

getMessageIterator(GetMessageIteratorOptions)

Returns an iterator that can be used to receive messages from Service Bus. If the iterator is not able to fetch a new message in over a minute, undefined will be returned.

function getMessageIterator(options?: GetMessageIteratorOptions)

Parameters

options
GetMessageIteratorOptions

A set of options to control the receive operation.

  • maxWaitTimeInMs: The time to wait to receive the message in each iteration.
  • abortSignal: The signal to use to abort the ongoing operation.

Returns

AsyncIterableIterator<ServiceBusReceivedMessage>

getSessionState(OperationOptionsBase)

Gets the state of the Session. For more on session states, see | Session State

function getSessionState(options?: OperationOptionsBase)

Parameters

options
OperationOptionsBase

Options bag to pass an abort signal or tracing options.

Returns

Promise<any>

The state of that session

peekMessages(number, PeekMessagesOptions)

Peek the next batch of active messages (including deferred but not deadlettered messages) on the queue or subscription without modifying them.

  • The first call to peekMessages() fetches the first active message. Each subsequent call fetches the subsequent message.
  • Unlike a "received" message, "peeked" message is a read-only version of the message. It cannot be Completed/Abandoned/Deferred/Deadlettered.
function peekMessages(maxMessageCount: number, options?: PeekMessagesOptions)

Parameters

maxMessageCount

number

The maximum number of messages to peek.

options
PeekMessagesOptions

Options that allow to specify the maximum number of messages to peek, the sequenceNumber to start peeking from or an abortSignal to abort the operation.

Returns

receiveDeferredMessages(Long | Long[], OperationOptionsBase)

Returns a promise that resolves to an array of deferred messages identified by given sequenceNumbers.

function receiveDeferredMessages(sequenceNumbers: Long | Long[], options?: OperationOptionsBase)

Parameters

sequenceNumbers

Long | Long[]

The sequence number or an array of sequence numbers for the messages that need to be received.

options
OperationOptionsBase

Options bag to pass an abort signal or tracing options.

Returns

A list of messages identified by the given sequenceNumbers or an empty list if no messages are found.

receiveMessages(number, ReceiveMessagesOptions)

Returns a promise that resolves to an array of messages received from Service Bus.

function receiveMessages(maxMessageCount: number, options?: ReceiveMessagesOptions)

Parameters

maxMessageCount

number

The maximum number of messages to receive.

options
ReceiveMessagesOptions

A set of options to control the receive operation.

  • maxWaitTimeInMs: The maximum time to wait for the first message before returning an empty array if no messages are available.
  • abortSignal: The signal to use to abort the ongoing operation.

Returns

A promise that resolves with an array of messages.

renewMessageLock(ServiceBusReceivedMessage)

Renews the lock on the message for the duration as specified during the Queue/Subscription creation.

  • Check the lockedUntilUtc property on the message for the time when the lock expires.
  • If a message is not settled (using either complete(), defer() or deadletter(), before its lock expires, then the message lands back in the Queue/Subscription for the next receive operation.
function renewMessageLock(message: ServiceBusReceivedMessage)

Parameters

Returns

Promise<Date>

New lock token expiry date and time in UTC format.

renewSessionLock(OperationOptionsBase)

Renews the lock on the session.

function renewSessionLock(options?: OperationOptionsBase)

Parameters

Returns

Promise<Date>

setSessionState(any, OperationOptionsBase)

Sets the state on the Session. For more on session states, see | Session State

function setSessionState(state: any, options?: OperationOptionsBase)

Parameters

state

any

The state that needs to be set.

options
OperationOptionsBase

Options bag to pass an abort signal or tracing options.

Returns

Promise<void>

subscribe(MessageHandlers, SubscribeOptions)

Streams messages to message handlers.

function subscribe(handlers: MessageHandlers, options?: SubscribeOptions)

Parameters

handlers
MessageHandlers

A handler that gets called for messages and errors.

options
SubscribeOptions

Options for subscribe.

Returns

Object

An object that can be closed, sending any remaining messages to handlers and stopping new messages from arriving.