GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

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.

Ciza · 0 points · 27 views 0 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-typescript_skills_azure-servicebus-ts-e58528d.zip · 9 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-typescript/skills/azure-servicebus-ts
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git 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

  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:

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.

No comments yet.

Reviews (0)

No reviews yet.