Skip to content

Latest commit

 

History

History
280 lines (239 loc) · 12.5 KB

enable-dead-letter.md

File metadata and controls

280 lines (239 loc) · 12.5 KB
Raw
title description ms.topic ms.custom ms.date
Enable dead lettering for Azure Service Bus queues and subscriptions
This article explains how to enable dead lettering for queues and subscriptions by using Azure portal, PowerShell, CLI, and programming languages (C#, Java, Python, and JavaScript)
how-to
devx-track-azurepowershell, devx-track-azurecli, devx-track-arm-template, devx-track-python
11/09/2022

Enable dead lettering on message expiration for Azure Service Bus queues and subscriptions

Azure Service Bus queues and subscriptions for topics provide a secondary subqueue, called a dead-letter queue (DLQ). The dead-letter queue doesn't need to be explicitly created and can't be deleted or managed independent of the main entity. The purpose of the dead-letter queue is to hold messages that can't be delivered to any receiver, or messages that couldn't be processed. For more information, See Overview of Service Bus dead-letter queues. This article shows you different ways to enable dead lettering for Service Bus queues and subscriptions.

Using Azure portal

When creating a queue or a subscription for a topic in the Azure portal, select Enable dead lettering on message expiration as shown in the following examples.

Create a queue with dead lettering enabled

:::image type="content" source="./media/enable-dead-letter/create-queue.png" alt-text="Enable dead lettering at the time of the queue creation":::

Create a subscription with dead lettering enabled

:::image type="content" source="./media/enable-dead-letter/create-subscription.png" alt-text="Enable dead lettering at the time of the subscription creation":::

Update the dead lettering on message expiration setting for an existing queue

On the Overview page for your Service Bus queue, select the current value for the Dead lettering on message expiration setting. In the following example, the current value is Disabled. You can enable or disable dead lettering on message expiration in the popup window.

:::image type="content" source="./media/enable-dead-letter/queue-configuration.png" alt-text="Enable dead-lettering on message expiration for an existing queue":::

Update the dead lettering on message expiration setting for an existing subscription

On the Overview page for your Service Bus subscription, select the current value for the Dead lettering on message expiration setting. In the following example, the current value is Disabled. You can enable or disable dead lettering on message expiration in the popup window.

:::image type="content" source="./media/enable-dead-letter/subscription-configuration.png" alt-text="Enable dead-lettering on message expiration for an existing subscription":::

Using Azure CLI

To create a queue with dead lettering on message expiration enabled, use the az servicebus queue create command with --enable-dead-lettering-on-message-expiration set to true.

az servicebus queue create \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --enable-dead-lettering-on-message-expiration true

To enable the dead lettering on message expiration setting for an existing queue, use the az servicebus queue update command with --enable-dead-lettering-on-message-expiration set to true.

az servicebus queue update \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --enable-dead-lettering-on-message-expiration true

To create a subscription to a topic with dead lettering on message expiration enabled, use the az servicebus topic subscription create command with --enable-dead-lettering-on-message-expiration set to true.

az servicebus topic subscription create \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --topic-name mytopic \
    --name mysubscription \
    --enable-dead-lettering-on-message-expiration true

To enable the dead lettering on message expiration setting for a subscription to a topic, use the az servicebus topic subscription update command with --enable-dead-lettering-on-message-expiration set true.

az servicebus topic subscription update \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --topic-name mytopic \
    --name mysubscription \
    --enable-dead-lettering-on-message-expiration true

Note

If you specify a queue or topic by using the --forward-dead-lettered-messages-to parameter, Service Bus automatically forwards dead-lettered messages to that queue or topic. Here's an example: az servicebus queue create --resource-group mysbusrg --namespace-name mysbusns --name myqueue --enable-dead-lettering-on-message-expiration true --forward-dead-lettered-messages-to myqueue2.

Using Azure PowerShell

To create a queue with dead lettering on message expiration enabled, use the New-AzServiceBusQueue command with -DeadLetteringOnMessageExpiration set to $True.

New-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue `
    -DeadLetteringOnMessageExpiration $True

To enable the dead lettering on message expiration setting for an existing queue, use the Set-AzServiceBusQueue command as shown in the following example.

$queue=Get-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue 

$queue.DeadLetteringOnMessageExpiration=$True

Set-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue `
    -QueueObj $queue

To create a subscription for a topic with dead lettering on message expiration enabled, use the New-AzServiceBusSubscription command with -DeadLetteringOnMessageExpiration set to $True.

New-AzServiceBusSubscription -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -TopicName mytopic `
    -SubscriptionName mysubscription `
    -DeadLetteringOnMessageExpiration $True

To enable the dead lettering on message expiration setting for an existing subscription, see the following example.

$subscription=Get-AzServiceBusSubscription -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -TopicName mytopic `
    -SubscriptionName mysub

$subscription.DeadLetteringOnMessageExpiration=$True

Set-AzServiceBusSubscription -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -Name mytopic `
    -SubscriptionName mysub `
    -SubscriptionObj $subscription

Note

If you specify a queue or topic by using the -ForwardDeadLetteredMessagesTo parameter, Event Grid automatically forwards dead-lettered messages to that queue or topic.

Using Azure Resource Manager template

To create a queue with dead lettering on message expiration enabled, set deadLetteringOnMessageExpiration in the queue properties section to true. For more information, see Microsoft.ServiceBus namespaces/queues template reference.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "serviceBusNamespaceName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Service Bus namespace"
      }
    },
    "serviceBusQueueName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Queue"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.ServiceBus/namespaces",
      "apiVersion": "2018-01-01-preview",
      "name": "[parameters('serviceBusNamespaceName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard"
      },
      "properties": {},
      "resources": [
        {
          "type": "Queues",
          "apiVersion": "2017-04-01",
          "name": "[parameters('serviceBusQueueName')]",
          "dependsOn": [
            "[resourceId('Microsoft.ServiceBus/namespaces', parameters('serviceBusNamespaceName'))]"
          ],
          "properties": {
            "deadLetteringOnMessageExpiration": true
          }
        }
      ]
    }
  ]
}

To create a subscription for a topic with dead lettering on message expiration enabled, set deadLetteringOnMessageExpiration in the queue properties section to true. For more information, see Microsoft.ServiceBus namespaces/topics/subscriptions template reference.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "service_BusNamespace_Name": {
      "type": "string",
      "metadata": {
        "description": "Name of the Service Bus namespace"
      }
    },
    "serviceBusTopicName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Topic"
      }
    },
    "serviceBusSubscriptionName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Subscription"
      }
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    }
  },
  "resources": [
    {
      "apiVersion": "2018-01-01-preview",
      "name": "[parameters('service_BusNamespace_Name')]",
      "type": "Microsoft.ServiceBus/namespaces",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard"
      },
      "properties": {},
      "resources": [
        {
          "apiVersion": "2017-04-01",
          "name": "[parameters('serviceBusTopicName')]",
          "type": "topics",
          "dependsOn": [
            "[resourceId('Microsoft.ServiceBus/namespaces/', parameters('service_BusNamespace_Name'))]"
          ],
          "properties": {
            "maxSizeInMegabytes": 1024
          },
          "resources": [
            {
              "apiVersion": "2017-04-01",
              "name": "[parameters('serviceBusSubscriptionName')]",
              "type": "Subscriptions",
              "dependsOn": [
                "[parameters('serviceBusTopicName')]"
              ],
              "properties": {
                "deadLetteringOnMessageExpiration": true
              }
            }
          ]
        }
      ]
    }
  ]
}

Note

If you specify a queue or topic for the forwardDeadLetteredMessagesTo property, Event Grid automatically forwards dead-lettered messages to that queue or topic.

Next steps

Try the samples in the language of your choice to explore Azure Service Bus features.

Find samples for the older .NET and Java client libraries:

[!INCLUDE service-bus-track-0-and-1-sdk-support-retirement]