Azure Service Bus client library for Javascript (Preview)

Azure Service Bus is a highly-reliable cloud messaging service from Microsoft.

Use the client library @azure/service-bus in your application to

• Send messages to an Azure Service Bus Queue or Topic
• Receive messages from an Azure Service Bus Queue or Subscription

Resources for the v7.0.0-preview.6 of @azure/service-bus:

Source code | Package (npm) | API Reference Documentation | Product documentation | Samples

NOTE: This document has instructions, links and code snippets for the preview of the next version of the @azure/service-bus package which has different APIs than the stable version. To use the stable version of the library use the below resources.

Source code or Readme for v1.1.9 | Package for v1.1.9 (npm) | API Reference Documentation for v1.1.9 | Samples for @azure/service-bus v1.1.x

We also provide a migration guide for users familiar with the stable package that would like to try the preview: migration guide to move from Service Bus V1 to Service Bus V7 Preview

Getting Started

Install the package

Install the preview version for the Azure Service Bus client library using npm

npm install @azure/service-bus@next

Prerequisites

You must have an Azure subscription and a Service Bus Namespace to use this package. If you are using this package in a Node.js application, then use Node.js 8.x or higher.

Configure Typescript

TypeScript users need to have Node type definitions installed:

npm install @types/node

You also need to enable compilerOptions.allowSyntheticDefaultImports in your tsconfig.json. Note that if you have enabled compilerOptions.esModuleInterop, allowSyntheticDefaultImports is enabled by default. See TypeScript's compiler options handbook for more information.

JavaScript Bundle

To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our bundling documentation.

Authenticate the client

Interaction with Service Bus starts with an instance of the ServiceBusClient class.

You can instantiate this class using its constructors:

• Create using a connection string
  • This method takes the connection string to your Service Bus instance. You can get the connection string from the Azure portal.
• Create using a TokenCredential
  • This method takes the host name of your Service Bus instance and a credentials object that you need to generate using the @azure/identity library. The host name is of the format name-of-service-bus-instance.servicebus.windows.net. If you're using an own implementation of the TokenCredential interface against AAD, then set the "scopes" for service-bus to be ["https://servicebus.azure.net//user_impersonation"] to get the appropriate token.

Key concepts

Once you've initialized a ServiceBusClient, you can interact with these resources within a Service Bus Namespace:

• Queues: Allows for sending and receiving messages. Often used for point-to-point communication.
• Topics: As opposed to Queues, Topics are better suited to publish/subscribe scenarios. A topic can be sent to, but requires a subscription, of which there can be multiple in parallel, to consume from.
• Subscriptions: The mechanism to consume from a Topic. Each subscription is independent, and receives a copy of each message sent to the topic. Rules and Filters can be used to tailor which messages are received by a specific subscription.

For more information about these resources, see What is Azure Service Bus?.

To interact with these resources, one should be familiar with the following SDK concepts:

• Send messages, to a queue or topic, using a Sender created using ServiceBusClient.createSender().
• Receive messages, from either a queue or a subscription, using a Receiver created using ServiceBusClient.createReceiver().
• Receive messages, from session enabled queues or subscriptions, using a SessionReceiver created using ServiceBusClient.createSessionReceiver().

Please note that the Queues, Topics and Subscriptions should be created prior to using this library.

Examples

The following sections provide code snippets that cover some of the common tasks using Azure Service Bus

• Send messages
• Receive messages
• Settle a message
• Send messages using Sessions
• Receive messages from Sessions
• Manage resources of a service bus namespace
• Additional samples

Send messages

Once you have created an instance of a ServiceBusClient class, you can get a Sender using the createSender method.

This gives you a sender which you can use to send messages.

const sender = serviceBusClient.createSender("my-queue");

// sending a single message
await sender.sendMessages({
  body: "my-message-body"
});

// sending multiple messages
await sender.sendMessages([
  {
    body: "my-message-body"
  },
  {
    body: "another-message-body"
  }
]);

Receive messages

Once you have created an instance of a ServiceBusClient class, you can get a Receiver using the createReceiver method.

const receiver = serviceBusClient.createReceiver("my-queue");

There are two receiveModes available.

• "peekLock" - In peekLock mode, the receiver has a lock on the message for the duration specified on the queue.
• "receiveAndDelete" - In receiveAndDelete mode, messages are deleted from Service Bus as they are received.

If the receiveMode is not provided in the options, it defaults to the "peekLock" mode. You can also settle the messages received in "peekLock" mode.

You can use this receiver in one of 3 ways to receive messages:

Get an array of messages

Use the receiveMessages function which returns a promise that resolves to an array of messages.

const myMessages = await receiver.receiveMessages(10);

Subscribe using a message handler

Use the subscribe method to set up message handlers and have it running as long as you need.

When you are done, call receiver.close() to stop receiving any more messages.

const myMessageHandler = async (message) => {
  // your code here
};
const myErrorHandler = async (error) => {
  console.log(error);
};
receiver.subscribe({
  processMessage: myMessageHandler,
  processError: myErrorHandler
});

Use async iterator

Use the getMessageIterator to get an async iterator over messages

for await (let message of receiver.getMessageIterator()) {
  // your code here
}

Settle a message

Once you receive a message you can call complete(), abandon(), defer() or deadletter() on it based on how you want to settle the message.

To learn more, please read Settling Received Messages

Send messages using Sessions

Using sessions requires you to create a session enabled Queue or Subscription. You can read more about how to configure this feature in the portal here.

In order to send messages to a session, use the ServiceBusClient to create a sender using createSender. This gives you a sender which you can use to send messages.

When sending the message, set the sessionId property in the message to ensure your message lands in the right session.

const sender = serviceBusClient.createSender("my-session-queue");
await sender.sendMessages({
  body: "my-message-body",
  sessionId: "my-session"
});

You can read more about how sessions work here.

Receive messages from Sessions

Using sessions requires you to create a session enabled Queue or Subscription. You can read more about how to configure this feature in the portal here.

Unlike non-session-enabled Queues or Subscriptions, only a single receiver can read from a session at any time. This is enforced by locking a session, which is handled by Service Bus. Conceptually, this is similar to how message locking works when using peekLock mode - when a message (or session) is locked your receiver has exclusive access to it.

In order to open and lock a session, use an instance of ServiceBusClient to create a SessionReceiver using createSessionReceiver.

There are two ways of choosing which session to open:

1. Specify a sessionId, which locks a named session.

   const receiver = await serviceBusClient.createSessionReceiver("my-session-queue", {
     sessionId: "my-session"
   });

2. Do not specify a session id. In this case Service Bus will find the next available session that is not already locked.

   const receiver = await serviceBusClient.createSessionReceiver("my-session-queue");

   You can find the name of the session via the sessionId property on the SessionReceiver. If the receiveMode is not provided in the options, it defaults to the "peekLock" mode. You can also settle the messages received in "peekLock" mode.

Once the receiver is created you can use choose between 3 ways to receive messages:

• Get an array of messages
• Subscribe using a message handler
• Use async iterator

You can read more about how sessions work here.

Manage resources of a service bus namespace

ServiceBusAdministrationClient lets you manage a namespace with CRUD operations on the entities(queues, topics, and subscriptions) and on the rules of a subscription.

• Supports authentication with a service bus connection string as well as with the AAD credentials from @azure/identity similar to the ServiceBusClient.

// Get the connection string from the portal
// OR
// use the token credential overload, provide the host name of your Service Bus instance and the AAD credentials from the @azure/identity library
const serviceBusAdministrationClient = new ServiceBusAdministrationClient("<connectionString>");

// Similarly, you can create topics and subscriptions as well.
const createQueueResponse = await serviceBusAdministrationClient.createQueue(queueName);
console.log("Created queue with name - ", createQueueResponse.name);

const queueRuntimeProperties = await serviceBusAdministrationClient.getQueueRuntimeProperties(
  queueName
);
console.log("Number of messages in the queue = ", queueRuntimeProperties.totalMessageCount);

await serviceBusAdministrationClient.deleteQueue(queueName);

• Sample for reference - administrationClient.ts

Troubleshooting

AMQP Dependencies

The Service Bus library depends on the rhea-promise library for managing connections, sending and receiving messages over the AMQP protocol.

Enable logs

You can set the following environment variable to get the debug logs when using this library.

• Getting debug logs from the Service Bus SDK

export DEBUG=azure*

• Getting debug logs from the Service Bus SDK and the protocol level library.

export DEBUG=azure*,rhea*

• If you are not interested in viewing the message transformation (which consumes lot of console/disk space) then you can set the DEBUG environment variable as follows:

export DEBUG=azure*,rhea*,-rhea:raw,-rhea:message,-azure:core-amqp:datatransformer

• If you are interested only in errors, then you can set the DEBUG environment variable as follows:

export DEBUG=azure:service-bus:error,azure-core-amqp:error,rhea-promise:error,rhea:events,rhea:frames,rhea:io,rhea:flow

Logging to a file

1. Set the DEBUG environment variable as shown above
2. Run your test script as follows:

• Logging statements from your test script go to out.log and logging statements from the sdk go to debug.log.

  node your-test-script.js > out.log 2>debug.log

• Logging statements from your test script and the sdk go to the same file out.log by redirecting stderr to stdout (&1), and then redirect stdout to a file:

  node your-test-script.js >out.log 2>&1

• Logging statements from your test script and the sdk go to the same file out.log.

    node your-test-script.js &> out.log

Next Steps

Please take a look at the samples directory for detailed examples on how to use this library to send and receive messages to/from Service Bus Queues, Topics and Subscriptions.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.