Azure Servicebus Ts

1---
2name: azure-servicebus-ts
3description: Build messaging applications using Azure Service Bus SDK for JavaScript (@azure/service-bus). Use when implementing queues, topics/subscriptions, message sessions, dead-letter handling, or enterprise messaging patterns.
4package: "@azure/service-bus"
5---
6 
7# Azure Service Bus SDK for TypeScript
8 
9Enterprise messaging with queues, topics, and subscriptions.
10 
11## Installation
12 
13```bash
14npm install @azure/service-bus @azure/identity
15```
16 
17## Environment Variables
18 
19```bash
20SERVICEBUS_NAMESPACE=<namespace>.servicebus.windows.net
21SERVICEBUS_QUEUE_NAME=my-queue
22SERVICEBUS_TOPIC_NAME=my-topic
23SERVICEBUS_SUBSCRIPTION_NAME=my-subscription
24```
25 
26## Authentication
27 
28```typescript
29import { ServiceBusClient } from "@azure/service-bus";
30import { DefaultAzureCredential } from "@azure/identity";
31 
32const fullyQualifiedNamespace = process.env.SERVICEBUS_NAMESPACE!;
33const client = new ServiceBusClient(fullyQualifiedNamespace, new DefaultAzureCredential());
34```
35 
36## Core Workflow
37 
38### Send Messages to Queue
39 
40```typescript
41const sender = client.createSender("my-queue");
42 
43// Single message
44await sender.sendMessages({
45  body: { orderId: "12345", amount: 99.99 },
46  contentType: "application/json",
47});
48 
49// Batch messages
50const batch = await sender.createMessageBatch();
51batch.tryAddMessage({ body: "Message 1" });
52batch.tryAddMessage({ body: "Message 2" });
53await sender.sendMessages(batch);
54 
55await sender.close();
56```
57 
58### Receive Messages from Queue
59 
60```typescript
61const receiver = client.createReceiver("my-queue");
62 
63// Receive batch
64const messages = await receiver.receiveMessages(10, { maxWaitTimeInMs: 5000 });
65for (const message of messages) {
66  console.log(`Received: ${message.body}`);
67  await receiver.completeMessage(message);
68}
69 
70await receiver.close();
71```
72 
73### Subscribe to Messages (Event-Driven)
74 
75```typescript
76const receiver = client.createReceiver("my-queue");
77 
78const subscription = receiver.subscribe({
79  processMessage: async (message) => {
80    console.log(`Processing: ${message.body}`);
81    // Message auto-completed on success
82  },
83  processError: async (args) => {
84    console.error(`Error: ${args.error}`);
85  },
86});
87 
88// Stop after some time
89setTimeout(async () => {
90  await subscription.close();
91  await receiver.close();
92}, 60000);
93```
94 
95### Topics and Subscriptions
96 
97```typescript
98// Send to topic
99const topicSender = client.createSender("my-topic");
100await topicSender.sendMessages({
101  body: { event: "order.created", data: { orderId: "123" } },
102  applicationProperties: { eventType: "order.created" },
103});
104 
105// Receive from subscription
106const subscriptionReceiver = client.createReceiver("my-topic", "my-subscription");
107const messages = await subscriptionReceiver.receiveMessages(10);
108```
109 
110## Message Sessions
111 
112```typescript
113// Send session message
114const sender = client.createSender("session-queue");
115await sender.sendMessages({
116  body: { step: 1, data: "First step" },
117  sessionId: "workflow-123",
118});
119 
120// Receive session messages
121const sessionReceiver = await client.acceptSession("session-queue", "workflow-123");
122const messages = await sessionReceiver.receiveMessages(10);
123 
124// Get/set session state
125const state = await sessionReceiver.getSessionState();
126await sessionReceiver.setSessionState(Buffer.from(JSON.stringify({ progress: 50 })));
127 
128await sessionReceiver.close();
129```
130 
131## Dead-Letter Handling
132 
133```typescript
134// Move to dead-letter
135await receiver.deadLetterMessage(message, {
136  deadLetterReason: "Validation failed",
137  deadLetterErrorDescription: "Missing required field: orderId",
138});
139 
140// Process dead-letter queue
141const dlqReceiver = client.createReceiver("my-queue", { subQueueType: "deadLetter" });
142const dlqMessages = await dlqReceiver.receiveMessages(10);
143for (const msg of dlqMessages) {
144  console.log(`DLQ Reason: ${msg.deadLetterReason}`);
145  // Reprocess or log
146  await dlqReceiver.completeMessage(msg);
147}
148```
149 
150## Scheduled Messages
151 
152```typescript
153const sender = client.createSender("my-queue");
154 
155// Schedule for future delivery
156const scheduledTime = new Date(Date.now() + 60000); // 1 minute from now
157const sequenceNumber = await sender.scheduleMessages(
158  { body: "Delayed message" },
159  scheduledTime
160);
161 
162// Cancel scheduled message
163await sender.cancelScheduledMessages(sequenceNumber);
164```
165 
166## Message Deferral
167 
168```typescript
169// Defer message for later
170await receiver.deferMessage(message);
171 
172// Receive deferred message by sequence number
173const deferredMessage = await receiver.receiveDeferredMessages(message.sequenceNumber!);
174await receiver.completeMessage(deferredMessage[0]);
175```
176 
177## Peek Messages (Non-Destructive)
178 
179```typescript
180const receiver = client.createReceiver("my-queue");
181 
182// Peek without removing
183const peekedMessages = await receiver.peekMessages(10);
184for (const msg of peekedMessages) {
185  console.log(`Peeked: ${msg.body}`);
186}
187```
188 
189## Key Types
190 
191```typescript
192import {
193  ServiceBusClient,
194  ServiceBusSender,
195  ServiceBusReceiver,
196  ServiceBusSessionReceiver,
197  ServiceBusMessage,
198  ServiceBusReceivedMessage,
199  ProcessMessageCallback,
200  ProcessErrorCallback,
201} from "@azure/service-bus";
202```
203 
204## Receive Modes
205 
206```typescript
207// Peek-Lock (default) - message locked until completed/abandoned
208const receiver = client.createReceiver("my-queue", { receiveMode: "peekLock" });
209await receiver.completeMessage(message);   // Remove from queue
210await receiver.abandonMessage(message);    // Return to queue
211await receiver.deferMessage(message);      // Defer for later
212await receiver.deadLetterMessage(message); // Move to DLQ
213 
214// Receive-and-Delete - message removed immediately
215const receiver = client.createReceiver("my-queue", { receiveMode: "receiveAndDelete" });
216```
217 
218## Best Practices
219 
2201. **Use Entra ID auth** - Avoid connection strings in production
2212. **Reuse clients** - Create `ServiceBusClient` once, share across senders/receivers
2223. **Close resources** - Always close senders/receivers when done
2234. **Handle errors** - Implement `processError` callback for subscription receivers
2245. **Use sessions for ordering** - When message order matters within a group
2256. **Configure dead-letter** - Always handle DLQ messages
2267. **Batch sends** - Use `createMessageBatch()` for multiple messages
227 
228## Reference Documentation
229 
230For detailed patterns, see:
231 
232- [Queues vs Topics Patterns](references/queues-topics.md) - Queue/topic patterns, sessions, receive modes, message settlement
233- [Error Handling and Reliability](references/error-handling.md) - ServiceBusError codes, DLQ handling, lock renewal, graceful shutdown
234