Send messages to and receive messages from Azure Service Bus queues (TypeScript)

• C#
• Java
• JavaScript
• Python
• TypeScript

In this tutorial, you complete the following steps:

1. Create a Service Bus namespace, using the Azure portal.
2. Create a Service Bus queue, using the Azure portal.
3. Write a TypeScript ESM application to use the @azure/service-bus package to:
   1. Send a set of messages to the queue.
   2. Receive those messages from the queue.

Note

This quick start provides step-by-step instructions for a simple scenario of sending messages to a Service Bus queue and receiving them. You can find pre-built JavaScript and TypeScript samples for Azure Service Bus in the Azure SDK for JavaScript repository on GitHub.

Prerequisites

If you're new to the service, see Service Bus overview before you do this quickstart.

• An Azure subscription. To complete this tutorial, you need an Azure account. You can activate your MSDN subscriber benefits or sign-up for a free account.
• TypeScript 5+
• Node.js LTS

Passwordless (Recommended)

To use this quickstart with your own Azure account, you need:

• Install Azure CLI, which provides the passwordless authentication to your developer machine.
• Sign in with your Azure account at the terminal or command prompt with az login.
• Use the same account when you add the appropriate data role to your resource.
• Run the code in the same terminal or command prompt.
• Note down your queue name for your Service Bus namespace. You'll need that in the code.

Connection String

Note down the following, which you'll use in the code below:

• Service Bus namespace connection string
• Service Bus namespace queue you created

Note

This tutorial works with samples that you can copy and run using Node.js. For instructions on how to create a Node.js application, see Create and deploy a Node.js application to an Azure Website, or Node.js cloud service using Windows PowerShell.

Create a namespace in the Azure portal

To begin using Service Bus messaging entities in Azure, you must first create a namespace with a name that is unique across Azure. A namespace provides a scoping container for Service Bus resources (queues, topics, etc.) within your application.

To create a namespace:

1. Sign in to the Azure portal.

2. Navigate to the All services page.

3. On the left navigation bar, select Integration from the list of categories, hover the mouse over Service Bus, and then select + button on the Service Bus tile.

   

4. In the Basics tag of the Create namespace page, follow these steps:

   1. For Subscription, choose an Azure subscription in which to create the namespace.

   2. For Resource group, choose an existing resource group in which the namespace will live, or create a new one.

   3. Enter a name for the namespace. The namespace name should adhere to the following naming conventions:

      • The name must be unique across Azure. The system immediately checks to see if the name is available.
      • The name length is at least 6 and at most 50 characters.
      • The name can contain only letters, numbers, hyphens “-“.
      • The name must start with a letter and end with a letter or number.
      • The name doesn't end with “-sb“ or “-mgmt“.

   4. For Location, choose the region in which your namespace should be hosted.

   5. For Pricing tier, select the pricing tier (Basic, Standard, or Premium) for the namespace. For this quickstart, select Standard.

      Important

      If you want to use topics and subscriptions, choose either Standard or Premium. Topics/subscriptions aren't supported in the Basic pricing tier.

      If you selected the Premium pricing tier, specify the number of messaging units. The premium tier provides resource isolation at the CPU and memory level so that each workload runs in isolation. This resource container is called a messaging unit. A premium namespace has at least one messaging unit. You can select 1, 2, 4, 8 or 16 messaging units for each Service Bus Premium namespace. For more information, see Service Bus Premium Messaging.

   6. Select Review + create at the bottom of the page.

      

   7. On the Review + create page, review settings, and select Create.

5. Once the deployment of the resource is successful, select Go to resource on the deployment page.

   

6. You see the home page for your service bus namespace.

   

Create a queue in the Azure portal

1. On the Service Bus Namespace page, select Queues in the left navigational menu.

2. On the Queues page, select + Queue on the toolbar.

3. Enter a name for the queue, and leave the other values with their defaults.

4. Now, select Create.

   

Authenticate the app to Azure

This quick start shows you two ways of connecting to Azure Service Bus: passwordless and connection string.

The first option shows you how to use your security principal in Microsoft Entra ID and role-based access control (RBAC) to connect to a Service Bus namespace. You don't need to worry about having hard-coded connection string in your code or in a configuration file or in a secure storage like Azure Key Vault.

The second option shows you how to use a connection string to connect to a Service Bus namespace. If you are new to Azure, you may find the connection string option easier to follow. We recommend using the passwordless option in real-world applications and production environments. For more information, see Authentication and authorization. You can also read more about passwordless authentication on the overview page.

Passwordless (Recommended)

Assign roles to your Microsoft Entra user

When developing locally, make sure that the user account that connects to Azure Service Bus has the correct permissions. You'll need the Azure Service Bus Data Owner role in order to send and receive messages. To assign yourself this role, you'll need the User Access Administrator role, or another role that includes the Microsoft.Authorization/roleAssignments/write action. You can assign Azure RBAC roles to a user using the Azure portal, Azure CLI, or Azure PowerShell. Learn more about the available scopes for role assignments on the scope overview page.

The following example assigns the Azure Service Bus Data Owner role to your user account, which provides full access to Azure Service Bus resources. In a real scenario, follow the Principle of Least Privilege to give users only the minimum permissions needed for a more secure production environment.

Azure built-in roles for Azure Service Bus

For Azure Service Bus, the management of namespaces and all related resources through the Azure portal and the Azure resource management API is already protected using the Azure RBAC model. Azure provides the below Azure built-in roles for authorizing access to a Service Bus namespace:

• Azure Service Bus Data Owner: Enables data access to Service Bus namespace and its entities (queues, topics, subscriptions, and filters). A member of this role can send and receive messages from queues or topics/subscriptions.
• Azure Service Bus Data Sender: Use this role to give the send access to Service Bus namespace and its entities.
• Azure Service Bus Data Receiver: Use this role to give the receive access to Service Bus namespace and its entities.

If you want to create a custom role, see Rights required for Service Bus operations.

Add Microsoft Entra user to Azure Service Bus Owner role

Add your Microsoft Entra user name to the Azure Service Bus Data Owner role at the Service Bus namespace level. It will allow an app running in the context of your user account to send messages to a queue or a topic, and receive messages from a queue or a topic's subscription.

Important

In most cases, it will take a minute or two for the role assignment to propagate in Azure. In rare cases, it may take up to eight minutes. If you receive authentication errors when you first run your code, wait a few moments and try again.

1. If you don't have the Service Bus Namespace page open in the Azure portal, locate your Service Bus namespace using the main search bar or left navigation.

2. On the overview page, select Access control (IAM) from the left-hand menu.

3. On the Access control (IAM) page, select the Role assignments tab.

4. Select + Add from the top menu and then Add role assignment from the resulting drop-down menu.

   

5. Use the search box to filter the results to the desired role. For this example, search for Azure Service Bus Data Owner and select the matching result. Then choose Next.

6. Under Assign access to, select User, group, or service principal, and then choose + Select members.

7. In the dialog, search for your Microsoft Entra username (usually your user@domain email address) and then choose Select at the bottom of the dialog.

8. Select Review + assign to go to the final page, and then Review + assign again to complete the process.

Connection String

Get the connection string

Creating a new namespace automatically generates an initial Shared Access Signature (SAS) policy with primary and secondary keys, and primary and secondary connection strings that each grant full control over all aspects of the namespace. See Service Bus authentication and authorization for information about how to create rules with more constrained rights for regular senders and receivers.

A client can use the connection string to connect to the Service Bus namespace. To copy the primary connection string for your namespace, follow these steps:

1. On the Service Bus Namespace page, select Shared access policies on the left menu.

2. On the Shared access policies page, select RootManageSharedAccessKey.

3. In the Policy: RootManageSharedAccessKey window, select the copy button next to Primary Connection String, to copy the connection string to your clipboard for later use. Paste this value into Notepad or some other temporary location.

   

   You can use this page to copy primary key, secondary key, primary connection string, and secondary connection string.

Configure project

1. Create a project folder to contain the quickstart files.

2. In a terminal in the project folder, initialize the Node.js project.

   npm init -y
   

3. Open the package.json file in the project folder and add the property to configure ESM. Add this property after the version property:

   "type":"module",
   

4. In the package.json file, edit the scripts property to compile the TypeScript files. Add the build script.

   "scripts": {
       "build": "tsc"
   }
   

5. Create a tsconfig.json in the project file to configure the TypeScript ESM build and copy the following into the file:

   {
     "compilerOptions": {
       "module": "NodeNext",
       "target": "ESNext",
       "moduleResolution": "NodeNext",
   
       "outDir": "dist",
       "rootDir": "./src",
   
       "esModuleInterop": true,
       "skipLibCheck": true
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules", "dist"]
   }
   

6. Create a src folder in the project. This is where you'll place the TypeScript files created in this quickstart.

Use Node Package Manager (npm) to install the package

Passwordless

1. To install the required npm package(s) for Service Bus, open a command prompt that has npm in its path, change the directory to the folder where you want to have your samples and then run this command.

2. Install the following packages:

   npm install @azure/service-bus @azure/identity
   

Connection string

1. To install the required npm package(s) for Service Bus, open a command prompt that has npm in its path, change the directory to the folder where you want to have your samples and then run this command.

2. Install the following package:

   npm install @azure/service-bus
   

Send messages to a queue

The following sample code shows you how to send a message to a queue.

Passwordless

You must have signed in with the Azure CLI's az login in order for your local machine to provide the passwordless authentication required in this code.

1. Open your favorite editor, such as Visual Studio Code.

2. In the src folder, create a file called send.ts and paste the below code into it. This code sends the names of scientists as messages to your queue.

   Important

   The passwordless credential is provided with the DefaultAzureCredential.

   import {
       ServiceBusClient,
       ServiceBusSender,
       ServiceBusMessageBatch,
     } from "@azure/service-bus";
   import { DefaultAzureCredential } from "@azure/identity";
   
   // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
   const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
   
   // Passwordless credential
   const credential = new DefaultAzureCredential();
   
   // name of the queue
   const queueName = "<QUEUE NAME>"
   
   const messages = [
       { body: "Albert Einstein" },
       { body: "Werner Heisenberg" },
       { body: "Marie Curie" },
       { body: "Steven Hawking" },
       { body: "Isaac Newton" },
       { body: "Niels Bohr" },
       { body: "Michael Faraday" },
       { body: "Galileo Galilei" },
       { body: "Johannes Kepler" },
       { body: "Nikolaus Kopernikus" }
       ];
   
   async function main() {
       // create a Service Bus client using the passwordless authentication to the Service Bus namespace
       const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
   
       // createSender() can also be used to create a sender for a topic.
       const serviceBusSender: ServiceBusSender = serviceBusClient.createSender(queueName);
   
       try {
           // Tries to send all messages in a single batch.
           // Will fail if the messages cannot fit in a batch.
           // await sender.sendMessages(messages);
   
           // create a batch object
           let serviceBusMessageBatch: ServiceBusMessageBatch = await serviceBusSender.createMessageBatch();
           for (let i = 0; i < messages.length; i++) {
               // for each message in the array
   
               // try to add the message to the batch
               if (!serviceBusMessageBatch.tryAddMessage(messages[i])) {
                   // if it fails to add the message to the current batch
                   // send the current batch as it is full
                   await serviceBusSender.sendMessages(serviceBusMessageBatch);
   
                   // then, create a new batch
                   serviceBusMessageBatch = await serviceBusSender.createMessageBatch();
   
                   // now, add the message failed to be added to the previous batch to this batch
                   if (!serviceBusMessageBatch.tryAddMessage(messages[i])) {
                       // if it still can't be added to the batch, the message is probably too big to fit in a batch
                       throw new Error("Message too big to fit in a batch");
                   }
               }
           }
   
           // Send the last created batch of messages to the queue
           await serviceBusSender.sendMessages(serviceBusMessageBatch);
   
           console.log(`Sent a batch of messages to the queue: ${queueName}`);
   
           // Close the sender
           await serviceBusSender.close();
       } finally {
           await serviceBusSender.close();
       }
   }
   
   // call the main function
   main().catch((err) => {
       console.log("Error occurred: ", err);
       process.exit(1);
       });
   

3. Replace <SERVICE-BUS-NAMESPACE> with your Service Bus namespace.

4. Replace <QUEUE NAME> with the name of the queue.

5. Then run the command in a command prompt to execute this file.

   npm run build
   node dist/send.js
   

6. You should see the following output.

   Sent a batch of messages to the queue: myqueue
   

Connection string

1. Open your favorite editor, such as Visual Studio Code.

2. In the src folder, create a file called src/send.ts and paste the below code into it. This code sends the names of scientists as messages to your queue.

   import {
     ServiceBusClient,
     ServiceBusSender,
     ServiceBusMessageBatch,
   } from "@azure/service-bus";
   
   // connection string to your Service Bus namespace
   const connectionString = "<CONNECTION STRING TO SERVICE BUS NAMESPACE>";
   
   // name of the queue
   const queueName = "<QUEUE NAME>";
   
   const messages = [
     { body: "Albert Einstein" },
     { body: "Werner Heisenberg" },
     { body: "Marie Curie" },
     { body: "Steven Hawking" },
     { body: "Isaac Newton" },
     { body: "Niels Bohr" },
     { body: "Michael Faraday" },
     { body: "Galileo Galilei" },
     { body: "Johannes Kepler" },
     { body: "Nikolaus Kopernikus" },
   ];
   
   async function main() {
     // create a Service Bus client using the connection string to the Service Bus namespace
     const serviceBusClient = new ServiceBusClient(
       connectionString,
     );
   
     // createSender() can also be used to create a sender for a topic.
     const serviceBusSender: ServiceBusSender =
       serviceBusClient.createSender(queueName);
   
     try {
       // Tries to send all messages in a single batch.
       // Will fail if the messages cannot fit in a batch.
       // await sender.sendMessages(messages);
   
       // create a batch object
       let serviceBusMessageBatch: ServiceBusMessageBatch =
         await serviceBusSender.createMessageBatch();
       for (let i = 0; i < messages.length; i++) {
         // for each message in the array
   
         // try to add the message to the batch
         if (!serviceBusMessageBatch.tryAddMessage(messages[i])) {
           // if it fails to add the message to the current batch
           // send the current batch as it is full
           await serviceBusSender.sendMessages(serviceBusMessageBatch);
   
           // then, create a new batch
           serviceBusMessageBatch = await serviceBusSender.createMessageBatch();
   
           // now, add the message failed to be added to the previous batch to this batch
           if (!serviceBusMessageBatch.tryAddMessage(messages[i])) {
             // if it still can't be added to the batch, the message is probably too big to fit in a batch
             throw new Error("Message too big to fit in a batch");
           }
         }
       }
   
       // Send the last created batch of messages to the queue
       await serviceBusSender.sendMessages(serviceBusMessageBatch);
   
       console.log(`Sent a batch of messages to the queue: ${queueName}`);
   
       // Close the sender
       await serviceBusSender.close();
     } finally {
       await serviceBusClient.close();
     }
   }
   
   // call the main function
   main().catch((err) => {
     console.log("Error occurred: ", err);
     process.exit(1);
   });
   

3. Replace <CONNECTION STRING TO SERVICE BUS NAMESPACE> with the connection string to your Service Bus namespace.

4. Replace <QUEUE NAME> with the name of the queue.

5. Then run the command in a command prompt to execute this file.

   npm run build
   node dist/send.js
   

6. You should see the following output.

   Sent a batch of messages to the queue: myqueue
   

Receive messages from a queue

Passwordless

You must have signed in with the Azure CLI's az login in order for your local machine to provide the passwordless authentication required in this code.

1. Open your favorite editor, such as Visual Studio Code

2. In the src folder, create a file called receive.ts and paste the following code into it.

   import { delay, ServiceBusClient, ServiceBusMessage, ProcessErrorArgs, ServiceBusReceiver } from "@azure/service-bus";
   import { DefaultAzureCredential } from "@azure/identity";
   
   // Replace `<SERVICE-BUS-NAMESPACE>` with your namespace
   const fullyQualifiedNamespace = "<SERVICE-BUS-NAMESPACE>.servicebus.windows.net";
   
   // Passwordless credential
   const credential = new DefaultAzureCredential();
   
   // name of the queue
   const queueName = "<QUEUE NAME>"
   
    async function main() {
       // create a Service Bus client using the passwordless authentication to the Service Bus namespace
       const serviceBusClient = new ServiceBusClient(fullyQualifiedNamespace, credential);
   
       // createReceiver() can also be used to create a receiver for a subscription.
       const serviceBusReceiver: ServiceBusReceiver = serviceBusClient.createReceiver(queueName);
   
       // function to handle messages
       const myMessageHandler = async (
           messageReceived: ServiceBusMessage,
       ): Promise<void> => {
           console.log(`Received message: ${messageReceived.body}`);
       };
   
       // function to handle any errors
       const myErrorHandler = async (error: ProcessErrorArgs): Promise<void> => {
           console.log(error);
       };
   
       // subscribe and specify the message and error handlers
       serviceBusReceiver.subscribe({
           processMessage: myMessageHandler,
           processError: myErrorHandler,
       });
   
       // Waiting long enough before closing the sender to send messages
       await delay(20000);
   
       await serviceBusReceiver.close();
       await serviceBusReceiver.close();
   }
   // call the main function
   main().catch((err) => {
       console.log("Error occurred: ", err);
       process.exit(1);
    });
   

3. Replace <SERVICE-BUS-NAMESPACE> with your Service Bus namespace.

4. Replace <QUEUE NAME> with the name of the queue.

5. Then run the command in a command prompt to execute this file.

   npm run build
   node dist/receive.js
   

Connection string

1. Open your favorite editor, such as Visual Studio Code

2. In the src folder, create a file called receive.ts and paste the following code into it.

   import {
     delay,
     ProcessErrorArgs,
     ServiceBusClient,
     ServiceBusMessage,
     ServiceBusReceiver,
   } from "@azure/service-bus";
   
   // connection string to your Service Bus namespace
   const connectionString: string = "<CONNECTION STRING TO SERVICE BUS NAMESPACE>";
   
   // name of the queue
   const queueName: string = "<QUEUE NAME>";
   
   async function main(): Promise<void> {
     // create a Service Bus client using the connection string to the Service Bus namespace
     const serviceBusClient = new ServiceBusClient(
       connectionString,
     );
   
     // createReceiver() can also be used to create a receiver for a subscription.
     const serviceBusReceiver: ServiceBusReceiver =
       serviceBusClient.createReceiver(queueName);
   
     // function to handle messages
     const myMessageHandler = async (
       messageReceived: ServiceBusMessage,
     ): Promise<void> => {
       console.log(`Received message: ${messageReceived.body}`);
     };
   
     // function to handle any errors
     const myErrorHandler = async (error: ProcessErrorArgs): Promise<void> => {
       console.log(error);
     };
   
     // subscribe and specify the message and error handlers
     serviceBusReceiver.subscribe({
       processMessage: myMessageHandler,
       processError: myErrorHandler,
     });
   
     // Waiting long enough before closing the sender to send messages
     await delay(20000);
   
     await serviceBusReceiver.close();
     await serviceBusClient.close();
   }
   
   // call the main function
   main().catch((err: Error) => {
     console.log("Error occurred: ", err);
     process.exit(1);
   });
   

3. Replace <CONNECTION STRING TO SERVICE BUS NAMESPACE> with the connection string to your Service Bus namespace.

4. Replace <QUEUE NAME> with the name of the queue.

5. Then run the command in a command prompt to execute this file.

   npm run build
   node dist/receive.js
   

You should see the following output.

Received message: Albert Einstein
Received message: Werner Heisenberg
Received message: Marie Curie
Received message: Stephen Hawking
Received message: Isaac Newton
Received message: Niels Bohr
Received message: Michael Faraday
Received message: Galileo Galilei
Received message: Johannes Kepler
Received message: Nikolaus Kopernikus

On the Overview page for the Service Bus namespace in the Azure portal, you can see incoming and outgoing message count. You may need to wait for a minute or so and then refresh the page to see the latest values.

Select the queue on this Overview page to navigate to the Service Bus Queue page. You see the incoming and outgoing message count on this page too. You also see other information such as the current size of the queue, maximum size, active message count, and so on.

Troubleshooting

If you receive one of the following errors when running the passwordless version of the TypeScript code, make sure you are signed in via the Azure CLI command, az login and the appropriate role is applied to your Azure user account:

• 'Send' claim(s) are required to perform this operation
• 'Receive' claim(s) are required to perform this operation

Clean up resources

Navigate to your Service Bus namespace in the Azure portal, and select Delete on the Azure portal to delete the namespace and the queue in it.

Next steps

See the following documentation and samples:

• Azure Service Bus client library for JavaScript
• JavaScript samples
• TypeScript samples
• API reference documentation