Registry / storage / botbuilder-azure-queues

botbuilder-azure-queues

library4.23.3-previewjsnpmunverified

BotBuilder storage bindings for Azure Queue services, part of the Microsoft Bot Framework SDK for JavaScript. Current version is 4.23.3-preview, released on a monthly cadence alongside the main botbuilder-js monorepo. This package provides AzureStorageQueue class for persisting bot state (user, conversation, custom) to Azure Storage Queues. It is distinct from botbuilder-azure-blobs (blob storage) and botbuilder-azure-cosmosdb (Cosmos DB storage). Supports Node.js 16+ with native ESM and CJS. Includes TypeScript type definitions. Key differentiator: queue-based storage for asynchronous, decoupled state management in bot dialogs.

storage

npm install botbuilder-azure-queues

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BOTBUILDER-AZURE-Q

botbuilder-azure-queues

storagejavascriptv4.23.3-preview

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AzureStorageQueue

✓ import { AzureStorageQueue } from 'botbuilder-azure-queues';

✗ const { AzureStorageQueue } = require('botbuilder-azure-queues');

ESM import is recommended; CommonJS require works but may lack TypeScript types in some environments.

default export

✓ import AzureStorageQueue from 'botbuilder-azure-queues';

✗ import * as AzureStorageQueue from 'botbuilder-azure-queues';

Only named export is officially supported; no default export exists.

StorageQueueOptions

✓ import { AzureStorageQueue, StorageQueueOptions } from 'botbuilder-azure-queues';

StorageQueueOptions is an interface for configuration; available as named export.

Shows how to create an AzureStorageQueue instance and integrate with ConversationState for bot dialog state persistence.

import { AzureStorageQueue } from 'botbuilder-azure-queues'; import { ConversationState, MemoryStorage, TurnContext } from 'botbuilder'; const queueName = 'bot-queue'; const connectionString = process.env.AZURE_STORAGE_CONNECTION_STRING ?? ''; const queueStorage = new AzureStorageQueue({ connectionString, queueName }); const conversationState = new ConversationState(queueStorage); // Use in bot: new Bot(conversationState).onTurn(async (context) => { ... }); // To persist state on each turn, use conversationState.saveChanges(context);

Debug

Known issues

breakingIn version 4.22.0, the constructor signature changed: new AzureStorageQueue({ connectionString, queueName }) replaced new AzureStorageQueue(connectionString, queueName).

fix

Use object parameter: new AzureStorageQueue({ connectionString, queueName })

affects: >=4.22.0

deprecatedStorageQueueOptions.queueName is deprecated; use StorageQueueOptions.queue instead.

fix

Replace queueName with queue in the options object.

affects: >=4.23.0

gotchaAzureStorageQueue requires the @azure/storage-queue package as a peer dependency; using incorrect versions can cause runtime errors.

fix

Ensure @azure/storage-queue is installed via npm install @azure/storage-queue

affects: *

gotchaDo not reuse the same queue name for different storage types (e.g., user and conversation state) unless you handle partitioning manually; otherwise, state may be overwritten.

fix

Use separate queue names for different state scopes, or implement a StorageKeyFactory that differentiates keys.

affects: *

Errors

Common errors & fixes

Error: getaddrinfo ENOTFOUND <storageaccount>.queue.core.windows.net

Invalid or unreachable Azure Storage account endpoint.

fix

Verify AZURE_STORAGE_CONNECTION_STRING environment variable is correct and the account exists.

TypeError: AzureStorageQueue is not a constructor

Import error: incorrectly imported the class as a default export or used wrong require syntax.

fix

Use named import: import { AzureStorageQueue } from 'botbuilder-azure-queues';

Error: QueueNotFound - The specified queue does not exist.

The queue name provided does not exist in the Azure Storage account.

fix

Create the queue manually in Azure portal or use createIfNotExists: new AzureStorageQueue({ connectionString, queueName, createQueueIfNotExists: true })

Upgrade

Version history

4.23.3-previewlatest on npm

Audit

Dependencies

@azure/storage-queuerequiredAzure Storage Queue client library for interacting with Azure Queue storage.

botbuilderrequiredCore BotBuilder framework for storage interfaces (StoreItems, StorageKeyFactory).

Agent activity

40 hits · last 30 days

node

Resources

githubhttps://github.com/Microsoft/botbuilder-js ↗

packagebotbuilder-azure-queues ↗

homepagehttps://github.com/Microsoft/botbuilder-js#readme ↗