azure-servicebus-ts
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.
Install
npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-typescript/skills/azure-servicebus-ts
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
git clone https://github.com/microsoft/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Azure Service Bus SDK for TypeScript
Enterprise messaging with queues, topics, and subscriptions.
Installation
npm install @azure/service-bus @azure/identity
Environment Variables
SERVICEBUS_NAMESPACE=<namespace>.servicebus.windows.net
SERVICEBUS_QUEUE_NAME=my-queue
SERVICEBUS_TOPIC_NAME=my-topic
SERVICEBUS_SUBSCRIPTION_NAME=my-subscription
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
Authentication
import { ServiceBusClient } from "@azure/service-bus";
import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();
const fullyQualifiedNamespace = process.env.SERVICEBUS_NAMESPACE!;
const client = new ServiceBusClient(fullyQualifiedNamespace, credential);
Core Workflow
Send Messages to Queue
const sender = client.createSender("my-queue");
// Single message
await sender.sendMessages({
body: { orderId: "12345", amount: 99.99 },
contentType: "application/json",
});
// Batch messages
const batch = await sender.createMessageBatch();
batch.tryAddMessage({ body: "Message 1" });
batch.tryAddMessage({ body: "Message 2" });
await sender.sendMessages(batch);
await sender.close();
Receive Messages from Queue
const receiver = client.createReceiver("my-queue");
// Receive batch
const messages = await receiver.receiveMessages(10, { maxWaitTimeInMs: 5000 });
for (const message of messages) {
console.log(`Received: ${message.body}`);
await receiver.completeMessage(message);
}
await receiver.close();
Subscribe to Messages (Event-Driven)
const receiver = client.createReceiver("my-queue");
const subscription = receiver.subscribe({
processMessage: async (message) => {
console.log(`Processing: ${message.body}`);
// Message auto-completed on success
},
processError: async (args) => {
console.error(`Error: ${args.error}`);
},
});
// Stop after some time
setTimeout(async () => {
await subscription.close();
await receiver.close();
}, 60000);
Topics and Subscriptions
// Send to topic
const topicSender = client.createSender("my-topic");
await topicSender.sendMessages({
body: { event: "order.created", data: { orderId: "123" } },
applicationProperties: { eventType: "order.created" },
});
// Receive from subscription
const subscriptionReceiver = client.createReceiver("my-topic", "my-subscription");
const messages = await subscriptionReceiver.receiveMessages(10);
Message Sessions
// Send session message
const sender = client.createSender("session-queue");
await sender.sendMessages({
body: { step: 1, data: "First step" },
sessionId: "workflow-123",
});
// Receive session messages
const sessionReceiver = await client.acceptSession("session-queue", "workflow-123");
const messages = await sessionReceiver.receiveMessages(10);
// Get/set session state
const state = await sessionReceiver.getSessionState();
await sessionReceiver.setSessionState(Buffer.from(JSON.stringify({ progress: 50 })));
await sessionReceiver.close();
Dead-Letter Handling
// Move to dead-letter
await receiver.deadLetterMessage(message, {
deadLetterReason: "Validation failed",
deadLetterErrorDescription: "Missing required field: orderId",
});
// Process dead-letter queue
const dlqReceiver = client.createReceiver("my-queue", { subQueueType: "deadLetter" });
const dlqMessages = await dlqReceiver.receiveMessages(10);
for (const msg of dlqMessages) {
console.log(`DLQ Reason: ${msg.deadLetterReason}`);
// Reprocess or log
await dlqReceiver.completeMessage(msg);
}
Scheduled Messages
const sender = client.createSender("my-queue");
// Schedule for future delivery
const scheduledTime = new Date(Date.now() + 60000); // 1 minute from now
const sequenceNumber = await sender.scheduleMessages(
{ body: "Delayed message" },
scheduledTime
);
// Cancel scheduled message
await sender.cancelScheduledMessages(sequenceNumber);
Message Deferral
// Defer message for later
await receiver.deferMessage(message);
// Receive deferred message by sequence number
const deferredMessage = await receiver.receiveDeferredMessages(message.sequenceNumber!);
await receiver.completeMessage(deferredMessage[0]);
Peek Messages (Non-Destructive)
const receiver = client.createReceiver("my-queue");
// Peek without removing
const peekedMessages = await receiver.peekMessages(10);
for (const msg of peekedMessages) {
console.log(`Peeked: ${msg.body}`);
}
Key Types
import {
ServiceBusClient,
ServiceBusSender,
ServiceBusReceiver,
ServiceBusSessionReceiver,
ServiceBusMessage,
ServiceBusReceivedMessage,
ProcessMessageCallback,
ProcessErrorCallback,
} from "@azure/service-bus";
Receive Modes
// Peek-Lock (default) - message locked until completed/abandoned
const receiver = client.createReceiver("my-queue", { receiveMode: "peekLock" });
await receiver.completeMessage(message); // Remove from queue
await receiver.abandonMessage(message); // Return to queue
await receiver.deferMessage(message); // Defer for later
await receiver.deadLetterMessage(message); // Move to DLQ
// Receive-and-Delete - message removed immediately
const receiver = client.createReceiver("my-queue", { receiveMode: "receiveAndDelete" });
Best Practices
- Use Microsoft Entra Token Credential - Use
DefaultAzureCredentialfor local development; useManagedIdentityCredentialorWorkloadIdentityCredentialfor production - Reuse clients - Create
ServiceBusClientonce, share across senders/receivers - Close resources - Always close senders/receivers when done
- Handle errors - Implement
processErrorcallback for subscription receivers - Use sessions for ordering - When message order matters within a group
- Configure dead-letter - Always handle DLQ messages
- Batch sends - Use
createMessageBatch()for multiple messages
Reference Documentation
For detailed patterns, see:
- Queues vs Topics Patterns - Queue/topic patterns, sessions, receive modes, message settlement
- Error Handling and Reliability - ServiceBusError codes, DLQ handling, lock renewal, graceful shutdown
Files (skills)
-
references
-
error-handling.md 11.3 KB
Loading… -
queues-topics.md 9.5 KB
Loading…
-
-
SKILL.md 7.1 KB
--- name: azure-servicebus-ts description: 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. license: MIT metadata: author: Microsoft version: "1.0.0" package: '@azure/service-bus' --- # Azure Service Bus SDK for TypeScript Enterprise messaging with queues, topics, and subscriptions. ## Installation ```bash npm install @azure/service-bus @azure/identity ``` ## Environment Variables ```bash SERVICEBUS_NAMESPACE=<namespace>.servicebus.windows.net SERVICEBUS_QUEUE_NAME=my-queue SERVICEBUS_TOPIC_NAME=my-topic SERVICEBUS_SUBSCRIPTION_NAME=my-subscription AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production ``` ## Authentication ```typescript import { ServiceBusClient } from "@azure/service-bus"; import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity"; // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential> const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]}); // Or use a specific credential directly in production: // See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes // const credential = new ManagedIdentityCredential(); const fullyQualifiedNamespace = process.env.SERVICEBUS_NAMESPACE!; const client = new ServiceBusClient(fullyQualifiedNamespace, credential); ``` ## Core Workflow ### Send Messages to Queue ```typescript const sender = client.createSender("my-queue"); // Single message await sender.sendMessages({ body: { orderId: "12345", amount: 99.99 }, contentType: "application/json", }); // Batch messages const batch = await sender.createMessageBatch(); batch.tryAddMessage({ body: "Message 1" }); batch.tryAddMessage({ body: "Message 2" }); await sender.sendMessages(batch); await sender.close(); ``` ### Receive Messages from Queue ```typescript const receiver = client.createReceiver("my-queue"); // Receive batch const messages = await receiver.receiveMessages(10, { maxWaitTimeInMs: 5000 }); for (const message of messages) { console.log(`Received: ${message.body}`); await receiver.completeMessage(message); } await receiver.close(); ``` ### Subscribe to Messages (Event-Driven) ```typescript const receiver = client.createReceiver("my-queue"); const subscription = receiver.subscribe({ processMessage: async (message) => { console.log(`Processing: ${message.body}`); // Message auto-completed on success }, processError: async (args) => { console.error(`Error: ${args.error}`); }, }); // Stop after some time setTimeout(async () => { await subscription.close(); await receiver.close(); }, 60000); ``` ### Topics and Subscriptions ```typescript // Send to topic const topicSender = client.createSender("my-topic"); await topicSender.sendMessages({ body: { event: "order.created", data: { orderId: "123" } }, applicationProperties: { eventType: "order.created" }, }); // Receive from subscription const subscriptionReceiver = client.createReceiver("my-topic", "my-subscription"); const messages = await subscriptionReceiver.receiveMessages(10); ``` ## Message Sessions ```typescript // Send session message const sender = client.createSender("session-queue"); await sender.sendMessages({ body: { step: 1, data: "First step" }, sessionId: "workflow-123", }); // Receive session messages const sessionReceiver = await client.acceptSession("session-queue", "workflow-123"); const messages = await sessionReceiver.receiveMessages(10); // Get/set session state const state = await sessionReceiver.getSessionState(); await sessionReceiver.setSessionState(Buffer.from(JSON.stringify({ progress: 50 }))); await sessionReceiver.close(); ``` ## Dead-Letter Handling ```typescript // Move to dead-letter await receiver.deadLetterMessage(message, { deadLetterReason: "Validation failed", deadLetterErrorDescription: "Missing required field: orderId", }); // Process dead-letter queue const dlqReceiver = client.createReceiver("my-queue", { subQueueType: "deadLetter" }); const dlqMessages = await dlqReceiver.receiveMessages(10); for (const msg of dlqMessages) { console.log(`DLQ Reason: ${msg.deadLetterReason}`); // Reprocess or log await dlqReceiver.completeMessage(msg); } ``` ## Scheduled Messages ```typescript const sender = client.createSender("my-queue"); // Schedule for future delivery const scheduledTime = new Date(Date.now() + 60000); // 1 minute from now const sequenceNumber = await sender.scheduleMessages( { body: "Delayed message" }, scheduledTime ); // Cancel scheduled message await sender.cancelScheduledMessages(sequenceNumber); ``` ## Message Deferral ```typescript // Defer message for later await receiver.deferMessage(message); // Receive deferred message by sequence number const deferredMessage = await receiver.receiveDeferredMessages(message.sequenceNumber!); await receiver.completeMessage(deferredMessage[0]); ``` ## Peek Messages (Non-Destructive) ```typescript const receiver = client.createReceiver("my-queue"); // Peek without removing const peekedMessages = await receiver.peekMessages(10); for (const msg of peekedMessages) { console.log(`Peeked: ${msg.body}`); } ``` ## Key Types ```typescript import { ServiceBusClient, ServiceBusSender, ServiceBusReceiver, ServiceBusSessionReceiver, ServiceBusMessage, ServiceBusReceivedMessage, ProcessMessageCallback, ProcessErrorCallback, } from "@azure/service-bus"; ``` ## Receive Modes ```typescript // Peek-Lock (default) - message locked until completed/abandoned const receiver = client.createReceiver("my-queue", { receiveMode: "peekLock" }); await receiver.completeMessage(message); // Remove from queue await receiver.abandonMessage(message); // Return to queue await receiver.deferMessage(message); // Defer for later await receiver.deadLetterMessage(message); // Move to DLQ // Receive-and-Delete - message removed immediately const receiver = client.createReceiver("my-queue", { receiveMode: "receiveAndDelete" }); ``` ## Best Practices 1. **Use Microsoft Entra Token Credential** - Use `DefaultAzureCredential` for local development; use `ManagedIdentityCredential` or `WorkloadIdentityCredential` for production 2. **Reuse clients** - Create `ServiceBusClient` once, share across senders/receivers 3. **Close resources** - Always close senders/receivers when done 4. **Handle errors** - Implement `processError` callback for subscription receivers 5. **Use sessions for ordering** - When message order matters within a group 6. **Configure dead-letter** - Always handle DLQ messages 7. **Batch sends** - Use `createMessageBatch()` for multiple messages ## Reference Documentation For detailed patterns, see: - [Queues vs Topics Patterns](references/queues-topics.md) - Queue/topic patterns, sessions, receive modes, message settlement - [Error Handling and Reliability](references/error-handling.md) - ServiceBusError codes, DLQ handling, lock renewal, graceful shutdown
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.