ServiceBusSender interface

A Sender can be used to send messages, schedule messages to be sent at a later time and cancel such scheduled messages. Use the createSender function on the ServiceBusClient to instantiate a Sender. The Sender class is an abstraction over the underlying AMQP sender link.

Properties

entityPath

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

identifier

A name used to identify the sender. 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 sender or the client that created it has been closed.

Methods

cancelScheduledMessages(Long | Long[], OperationOptionsBase)

Cancels multiple messages that were scheduled to appear on a ServiceBus Queue/Subscription.

close()

Closes the underlying AMQP sender link. Once closed, the sender cannot be used for any further operations. Use the createSender function on the QueueClient or TopicClient to instantiate a new Sender

createMessageBatch(CreateMessageBatchOptions)

Creates an instance of ServiceBusMessageBatch to which one can add messages until the maximum supported size is reached. The batch can be passed to the <xref:send> method to send the messages to Azure Service Bus.

scheduleMessages(ServiceBusMessage | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[], Date, OperationOptionsBase)

Schedules given messages to appear on Service Bus Queue/Subscription at a later time.

sendMessages(ServiceBusMessage | ServiceBusMessageBatch | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[], OperationOptionsBase)

Sends the given messages after creating an AMQP Sender link if it doesn't already exist.

  • To send messages to a session and/or partition enabled Queue/Topic, set the sessionId and/or partitionKey properties respectively on the messages.
  • All messages passed to the same sendMessages() call should have the same sessionId (if using sessions) and the same partitionKey (if using partitions).

Note:

If you want to send messages of size greater than 1MB, please send individual messages instead of sending a batched message or an array of messages like below.

await sender.sendMessages(message);

This is because the batched messages are not capable of sending the larger messages yet. You'll hit the force detached error in this case otherwise. Read service-bus-premium-messaging#large-messages-support. More info at #23014.

Property Details

entityPath

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

entityPath: string

Property Value

string

identifier

A name used to identify the sender. 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 sender or the client that created it has been closed.

isClosed: boolean

Property Value

boolean

Method Details

cancelScheduledMessages(Long | Long[], OperationOptionsBase)

Cancels multiple messages that were scheduled to appear on a ServiceBus Queue/Subscription.

function cancelScheduledMessages(sequenceNumbers: Long | Long[], options?: OperationOptionsBase): Promise<void>

Parameters

sequenceNumbers

Long | Long[]

Sequence number or an array of sequence numbers of the messages to be cancelled.

options
OperationOptionsBase

Options bag to pass an abort signal or tracing options.

Returns

Promise<void>

close()

Closes the underlying AMQP sender link. Once closed, the sender cannot be used for any further operations. Use the createSender function on the QueueClient or TopicClient to instantiate a new Sender

function close(): Promise<void>

Returns

Promise<void>

createMessageBatch(CreateMessageBatchOptions)

Creates an instance of ServiceBusMessageBatch to which one can add messages until the maximum supported size is reached. The batch can be passed to the <xref:send> method to send the messages to Azure Service Bus.

function createMessageBatch(options?: CreateMessageBatchOptions): Promise<ServiceBusMessageBatch>

Parameters

options
CreateMessageBatchOptions

Configures the behavior of the batch.

  • maxSizeInBytes: The upper limit for the size of batch. The tryAdd function will return false after this limit is reached.

Returns

scheduleMessages(ServiceBusMessage | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[], Date, OperationOptionsBase)

Schedules given messages to appear on Service Bus Queue/Subscription at a later time.

function scheduleMessages(messages: ServiceBusMessage | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[], scheduledEnqueueTimeUtc: Date, options?: OperationOptionsBase): Promise<Long[]>

Parameters

messages

ServiceBusMessage | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[]

Message or an array of messages that need to be scheduled.

scheduledEnqueueTimeUtc

Date

The UTC time at which the messages should be enqueued.

options
OperationOptionsBase

Options bag to pass an abort signal or tracing options.

Returns

Promise<Long[]>

The sequence numbers of messages that were scheduled. You will need the sequence number if you intend to cancel the scheduling of the messages. Save the Long type as-is in your application without converting to number. Since JavaScript only supports 53 bit numbers, converting the Long to number will cause loss in precision.

sendMessages(ServiceBusMessage | ServiceBusMessageBatch | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[], OperationOptionsBase)

Sends the given messages after creating an AMQP Sender link if it doesn't already exist.

  • To send messages to a session and/or partition enabled Queue/Topic, set the sessionId and/or partitionKey properties respectively on the messages.
  • All messages passed to the same sendMessages() call should have the same sessionId (if using sessions) and the same partitionKey (if using partitions).

Note:

If you want to send messages of size greater than 1MB, please send individual messages instead of sending a batched message or an array of messages like below.

await sender.sendMessages(message);

This is because the batched messages are not capable of sending the larger messages yet. You'll hit the force detached error in this case otherwise. Read service-bus-premium-messaging#large-messages-support. More info at #23014.

function sendMessages(messages: ServiceBusMessage | ServiceBusMessageBatch | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[], options?: OperationOptionsBase): Promise<void>

Parameters

messages

ServiceBusMessage | ServiceBusMessageBatch | AmqpAnnotatedMessage | ServiceBusMessage[] | AmqpAnnotatedMessage[]

A single message or an array of messages or a batch of messages created via the createBatch() method to send.

options
OperationOptionsBase

Options bag to pass an abort signal or tracing options.

Returns

Promise<void>