ServiceBusReceiver interface

Package:

@azure/service-bus

A receiver that does not handle sessions.

Properties

entityPath	Path of the entity for which the receiver has been created.
identifier	A name used to identify the receiver. This can be used to correlate logs and exceptions. If not specified or empty, a random unique one will be generated.
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.

Methods

abandonMessage(ServiceBusReceivedMessage, {[key: string]: number | boolean | string | Date | null})	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]: number | boolean | string | Date | null})	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]: number | boolean | string | Date | null})	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.
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.
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

identifier

A name used to identify the receiver. This can be used to correlate logs and exceptions. If not specified or empty, a random unique one will be generated.

identifier: 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"

Method Details

abandonMessage(ServiceBusReceivedMessage, {[key: string]: number | boolean | string | Date | null})

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]: number | boolean | string | Date | null}): Promise<void>

Parameters

message

ServiceBusReceivedMessage

propertiesToModify

{[key: string]: number | boolean | string | Date | null}

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(): Promise<void>

Returns

Promise<void>

completeMessage(ServiceBusReceivedMessage)

Removes the message from Service Bus.

function completeMessage(message: ServiceBusReceivedMessage): Promise<void>

Parameters

message

ServiceBusReceivedMessage

Returns

Promise<void>

deadLetterMessage(ServiceBusReceivedMessage, DeadLetterOptions & {[key: string]: number | boolean | string | Date | null})

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]: number | boolean | string | Date | null}): Promise<void>

Parameters

message

ServiceBusReceivedMessage

options

DeadLetterOptions & {[key: string]: number | boolean | string | Date | null}

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

Returns

Promise<void>

deferMessage(ServiceBusReceivedMessage, {[key: string]: number | boolean | string | Date | null})

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]: number | boolean | string | Date | null}): Promise<void>

Parameters

message

ServiceBusReceivedMessage

propertiesToModify

{[key: string]: number | boolean | string | Date | null}

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.

function getMessageIterator(options?: GetMessageIteratorOptions): AsyncIterableIterator<ServiceBusReceivedMessage>

Parameters

options

GetMessageIteratorOptions

A set of options to control the receive operation.

• abortSignal: The signal to use to abort the ongoing operation.

Returns

AsyncIterableIterator<ServiceBusReceivedMessage>

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): Promise<ServiceBusReceivedMessage[]>

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

Promise<ServiceBusReceivedMessage[]>

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): Promise<ServiceBusReceivedMessage[]>

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

Promise<ServiceBusReceivedMessage[]>

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): Promise<ServiceBusReceivedMessage[]>

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

Promise<ServiceBusReceivedMessage[]>

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): Promise<Date>

Parameters

message

ServiceBusReceivedMessage

Returns

Promise<Date>

New lock token expiry date and time in UTC format.

subscribe(MessageHandlers, SubscribeOptions)

Streams messages to message handlers.

function subscribe(handlers: MessageHandlers, options?: SubscribeOptions): { close() => Promise<void> }

Parameters

handlers

MessageHandlers

A handler that gets called for messages and errors.

options

SubscribeOptions

Options for subscribe.

Returns

{ close() => Promise<void> }

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