Service Bus

Introduction

Azure Service Bus is a fully managed enterprise message broker that supports queues and publish/subscribe topics. It helps decouple distributed systems and build reliable asynchronous messaging workflows. Service Bus is commonly used for command processing, event distribution, and integration between independent services. For more information, see What is Azure Service Bus?

LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Service Bus. This page covers the management of namespaces and messaging entities; to send and receive messages, see Service Bus Data Plane. The supported APIs are available on our API Coverage section, which provides information on the extent of Service Bus’s integration with LocalStack.

Getting started

This guide is designed for users new to Service Bus and assumes basic knowledge of the Azure CLI and our lstk az proxy.

Launch LocalStack using your preferred method. For more information, see Introduction to LocalStack for Azure. Once the container is running, enable Azure CLI interception by running:

lstk az start-interception

This command points the az CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API. To revert this configuration, run:

lstk az stop-interception

This reconfigures the az CLI to send commands to the official Azure management REST API.

Create a resource group

Create a resource group to contain your Service Bus resources:

az group create \
  --name rg-servicebus-demo \
  --location westeurope

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-servicebus-demo",
  "location": "westeurope",
  "managedBy": null,
  "name": "rg-servicebus-demo",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}

Create a Service Bus namespace

Create a Service Bus namespace in the resource group:

az servicebus namespace create \
  --resource-group rg-servicebus-demo \
  --name sbnsdoc83 \
  --location westeurope \
  --sku Standard

{
  ...
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-servicebus-demo/providers/Microsoft.ServiceBus/namespaces/sbnsdoc83",
  ...
  "location": "westeurope",
  ...
  "name": "sbnsdoc83",
  ...
  "provisioningState": "Succeeded",
  ...
  "serviceBusEndpoint": "https://sbnsdoc83.servicebus.azure.localhost.localstack.cloud:4511/",
  "sku": {
    "name": "Standard",
    "tier": "Standard"
  },
  ...
}

Get and list namespaces:

az servicebus namespace show \
  --resource-group rg-servicebus-demo \
  --name sbnsdoc83

az servicebus namespace list \
  --resource-group rg-servicebus-demo

Create and inspect a queue

Create a queue in the namespace:

az servicebus queue create \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --name orders-queue

{
  ...
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-servicebus-demo/providers/Microsoft.ServiceBus/namespaces/sbnsdoc83/queues/orders-queue",
  "location": "westeurope",
  ...
  "maxSizeInMegabytes": 1024,
  "messageCount": 0,
  "name": "orders-queue",
  ...
  "status": "Active",
  ...
}

Get and list queues:

az servicebus queue show \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --name orders-queue

{
  "accessedAt": "0001-01-01T00:00:00.000000Z",
  "autoDeleteOnIdle": "P10675199DT2H48M5.4775807S",
  "countDetails": {
    "activeMessageCount": 0,
    "deadLetterMessageCount": 0,
    "scheduledMessageCount": 0,
    "transferDeadLetterMessageCount": 0,
    "transferMessageCount": 0
  },
  ...
  "name": "orders-queue",
  ...
  "status": "Active",
  "type": "Microsoft.ServiceBus/namespaces/queues",
  ...
}

az servicebus queue list \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83

[
  {
    "accessedAt": "0001-01-01T00:00:00.000000Z",
    "autoDeleteOnIdle": "P10675199DT2H48M5.4775807S",
    "countDetails": {
      "activeMessageCount": 0,
      "deadLetterMessageCount": 0,
      "scheduledMessageCount": 0,
      "transferDeadLetterMessageCount": 0,
      "transferMessageCount": 0
    },
    ...
    "name": "orders-queue",
    ...
    "status": "Active",
    "type": "Microsoft.ServiceBus/namespaces/queues",
    ...
  }
]

Create topic and subscription

Create a topic and a subscription:

az servicebus topic create \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --name orders-topic

az servicebus topic subscription create \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --topic-name orders-topic \
  --name orders-sub

{
  ...
  "name": "orders-topic",
  ...
  "status": "Active",
  "subscriptionCount": 0,
  ...
}
{
  ...
  "messageCount": 0,
  "name": "orders-sub",
  ...
  "status": "Active",
  ...
}

Get and list subscriptions:

az servicebus topic subscription show \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --topic-name orders-topic \
  --name orders-sub

{
  "accessedAt": "0001-01-01T00:00:00.000000Z",
  "autoDeleteOnIdle": "P10675199DT2H48M5.4775807S",
  "countDetails": {
    "activeMessageCount": 0,
    "deadLetterMessageCount": 0,
    "scheduledMessageCount": 0,
    "transferDeadLetterMessageCount": 0,
    "transferMessageCount": 0
  },
  ...
  "name": "orders-sub",
  ...
  "status": "Active",
  "type": "Microsoft.ServiceBus/namespaces/topics/subscriptions",
  ...
}

az servicebus topic subscription list \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --topic-name orders-topic

[
  {
    "accessedAt": "0001-01-01T00:00:00.000000Z",
    "autoDeleteOnIdle": "P10675199DT2H48M5.4775807S",
    "countDetails": {
      "activeMessageCount": 0,
      "deadLetterMessageCount": 0,
      "scheduledMessageCount": 0,
      "transferDeadLetterMessageCount": 0,
      "transferMessageCount": 0
    },
    ...
    "name": "orders-sub",
    ...
    "status": "Active",
    "type": "Microsoft.ServiceBus/namespaces/topics/subscriptions",
    ...
  }
]

Create and list subscription rules

Create a SQL filter rule for the subscription:

az servicebus topic subscription rule create \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --topic-name orders-topic \
  --subscription-name orders-sub \
  --name high-priority \
  --filter-sql-expression "priority = 'high'"

{
  ...
  "filterType": "SqlFilter",
  ...
  "name": "high-priority",
  ...
  "sqlFilter": {
    "compatibilityLevel": 20,
    "sqlExpression": "priority = 'high'"
  },
  ...
}

List rules for the subscription:

az servicebus topic subscription rule list \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --topic-name orders-topic \
  --subscription-name orders-sub

[
  {
    ...
    "filterType": "SqlFilter",
    ...
    "name": "high-priority",
    ...
    "sqlFilter": {
      "compatibilityLevel": 20,
      "sqlExpression": "priority = 'high'"
    },
    ...
  }
]

Create and manage namespace authorization rules

Create an authorization rule:

az servicebus namespace authorization-rule create \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --name app-policy \
  --rights Listen Send

{
  ...
  "name": "app-policy",
  ...
  "rights": [
    "Listen",
    "Send"
  ],
  ...
}

List authorization rules:

az servicebus namespace authorization-rule list \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83

List and regenerate keys:

az servicebus namespace authorization-rule keys list \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --name app-policy

az servicebus namespace authorization-rule keys renew \
  --resource-group rg-servicebus-demo \
  --namespace-name sbnsdoc83 \
  --name app-policy \
  --key PrimaryKey

{
  "keyName": "app-policy",
  "primaryConnectionString": "Endpoint=sb://sbnsdoc83.servicebus.azure.localhost.localstack.cloud:4511/;SharedAccessKeyName=app-policy;SharedAccessKey=...;UseDevelopmentEmulator=true",
  ...
  "secondaryConnectionString": "Endpoint=sb://sbnsdoc83.servicebus.azure.localhost.localstack.cloud:4511/;SharedAccessKeyName=app-policy;SharedAccessKey=...;UseDevelopmentEmulator=true",
  ...
}
{
  "keyName": "app-policy",
  "primaryConnectionString": "Endpoint=sb://sbnsdoc83.servicebus.azure.localhost.localstack.cloud:4511/;SharedAccessKeyName=app-policy;SharedAccessKey=...;UseDevelopmentEmulator=true",
  ...
  "secondaryConnectionString": "Endpoint=sb://sbnsdoc83.servicebus.azure.localhost.localstack.cloud:4511/;SharedAccessKeyName=app-policy;SharedAccessKey=...;UseDevelopmentEmulator=true",
  ...
}

Features

The Service Bus emulator supports the following management capabilities:

Namespaces and messaging entities: Namespaces, queues, topics, subscriptions, and subscription rules can be created, read, updated, listed, and deleted through Azure Resource Manager, with the properties and defaults Azure returns.
Create-or-update semantics: Creating a namespace, queue, topic, subscription, or rule that already exists updates it in place and keeps its child resources, keys, and messages, as in Azure.
Azure’s validation rules: Changing a property that is fixed at creation, such as requiresSession, requiresDuplicateDetection, or enablePartitioning, is rejected, and so are a lock duration above five minutes, an express entity with duplicate detection, and a forwarding destination that does not exist, with Azure’s error messages.
Message counts: messageCount, sizeInBytes, and countDetails report the active, scheduled, dead-lettered, and transfer dead-lettered messages the broker holds for each queue and subscription.
Subscription rules: SQL filters with optional SQL actions and correlation filters decide which messages a subscription receives, and a SQL expression the broker cannot parse is rejected when the rule is created.
Authorization rules and keys: Namespace, queue, and topic authorization rules carry the Listen, Send, and Manage rights, and their keys can be listed and regenerated. The connection strings point at the emulator.
Local authentication: A namespace with disableLocalAuth set refuses shared access signatures and accepts Microsoft Entra tokens only, as in Azure.
Message broker: The emulator runs a Service Bus message broker for the Azure SDKs, the HTTP API, and the Atom management API, described in Service Bus Data Plane.

Limitations

Geo-disaster recovery and migration are not supported: Listing disaster recovery configurations returns an empty list, and pairing namespaces, failing over, and migrating a Standard namespace to Premium are not supported.
Network rules are not enforced: IP rules, virtual network rules, and the default action of a namespace’s network rule set are stored and returned, but the emulator does not filter connections by them.
Quotas are not enforced: The emulator does not enforce namespace quotas, such as the number of entities in a namespace or the maximum size of an entity.
RBAC enforcement is opt-in: By default, management operations succeed regardless of role assignments. Set LS_AZURE_ENFORCE_RBAC to check them against the caller’s role assignments.

Samples

The following samples demonstrate how to use Service Bus with LocalStack for Azure:

API Coverage

51 of 83 operations implemented

Operation ▲	Implemented ▼

Page 1 of 0

Was this page helpful?