对 Azure Service Bus 队列和订阅启用消息过期处理的死信功能

Azure Service Bus队列和主题的订阅提供一个辅助子队列，称为死信队列（DLQ）。死信队列不需要显式创建，并且不能删除或独立于主实体进行管理。死信队列的用途是存放无法传递给任何接收方的消息或无法处理的消息。有关详细信息，请参阅Service Bus 死信队列概述。本文介绍了为 Service Bus 队列和订阅启用死信处理的不同方法。

使用 Azure 门户

在 Azure 门户中为主题创建队列或订阅时，请选择 启用消息过期时的死信处理，如下例所示。

创建启用死信队列功能的队列

在创建队列时启用死信

启用死信功能的订阅创建

在创建订阅时启用死信

更新现有队列中消息过期的死信处理设置

在Service Bus队列的 Overview 页上，在邮件过期设置上选择 Dead lettering 的当前值。在以下示例中，当前值为“禁用”。你可以在弹出窗口中启用或禁用消息过期时的死信队列。

为现有队列启用消息过期后的死信处理

更新现有订阅中消息过期的死信处理设置

在Service Bus订阅的 Overview 页上，在邮件过期设置上为 Dead lettering 选择当前值。在以下示例中，当前值为“禁用”。你可以在弹出窗口中启用或禁用消息过期时的死信队列。

为现有订阅启用消息过期死信

使用Azure CLI

若要创建已启用消息过期死信的队列，请使用命令将 az servicebus queue create 设置为 --enable-dead-lettering-on-message-expiration。

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

若要为现有队列启用消息过期死信处理，请使用命令，并将 az servicebus queue update 设置为 --enable-dead-lettering-on-message-expiration。

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

若要创建启用消息过期死信处理功能的主题订阅，请使用命令将 az servicebus topic subscription create 设置为 --enable-dead-lettering-on-message-expiration。

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

若要为主题订阅启用消息过期死信设置，请使用命令将 az servicebus topic subscription update 设置为 --enable-dead-lettering-on-message-expiration。

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

注意

如果使用 --forward-dead-lettered-messages-to 参数指定队列或主题，Service Bus 会自动将已标记为死信的消息转发到该队列或主题。下面是一个示例：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。

使用 Azure PowerShell

若要创建已启用消息过期死信的队列，请使用命令将 New-AzServiceBusQueue 设置为 -DeadLetteringOnMessageExpiration。

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

若要为现有队列启用消息过期时的死信功能，请使用命令，如下列示例所示。

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

$queue.DeadLetteringOnMessageExpiration=$True

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

若要为启用消息过期死信的主题创建订阅，请使用命令，并将New-AzServiceBusSubscription设置为-DeadLetteringOnMessageExpiration。

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

若要为现有订阅启用消息过期死信设置，请参阅下方示例。

$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

注意

如果使用 -ForwardDeadLetteredMessagesTo 参数指定队列或主题，事件网格会自动将死信消息转发到该队列或主题。

使用模板

要创建启用消息过期死信处理的队列，请在“队列属性”部分中将设置为 deadLetteringOnMessageExpiration。有关详细信息，请参阅 Microsoft.ServiceBus 命名空间/队列模板参考。

Bicep
ARM 模板

@description('Name of the Service Bus namespace')
param serviceBusNamespaceName string

@description('Name of the Queue')
param serviceBusQueueName string

@description('Location for all resources.')
param location string = resourceGroup().location

resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = {
  name: serviceBusNamespaceName
  location: location
  sku: {
    name: 'Standard'
  }

  resource queue 'queues' = {
    name: serviceBusQueueName
    properties: {
      deadLetteringOnMessageExpiration: true
    }
  }
}

{
  "$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": "2024-01-01",
      "name": "[parameters('serviceBusNamespaceName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard"
      },
      "resources": [
        {
          "type": "queues",
          "apiVersion": "2024-01-01",
          "name": "[parameters('serviceBusQueueName')]",
          "dependsOn": [
            "[parameters('serviceBusNamespaceName')]"
          ],
          "properties": {
            "deadLetteringOnMessageExpiration": true
          }
        }
      ]
    }
  ]
}

若要 为启用消息过期死信处理的主题创建订阅，请在订阅属性部分中将deadLetteringOnMessageExpiration 设置为 true。有关详细信息，请参阅 Microsoft.ServiceBus 命名空间/主题/订阅模板参考。

Bicep
ARM 模板

@description('Name of the Service Bus namespace')
param serviceBusNamespaceName string

@description('Name of the Topic')
param serviceBusTopicName string

@description('Name of the Subscription')
param serviceBusSubscriptionName string

@description('Location for all resources.')
param location string = resourceGroup().location

resource serviceBusNamespace 'Microsoft.ServiceBus/namespaces@2024-01-01' = {
  name: serviceBusNamespaceName
  location: location
  sku: {
    name: 'Standard'
  }

  resource topic 'topics' = {
    name: serviceBusTopicName
    properties: {
      maxSizeInMegabytes: 1024
    }

    resource subscription 'subscriptions' = {
      name: serviceBusSubscriptionName
      properties: {
        deadLetteringOnMessageExpiration: true
      }
    }
  }
}

{
  "$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"
      }
    },
    "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": [
    {
      "type": "Microsoft.ServiceBus/namespaces",
      "apiVersion": "2024-01-01",
      "name": "[parameters('serviceBusNamespaceName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard"
      },
      "resources": [
        {
          "type": "topics",
          "apiVersion": "2024-01-01",
          "name": "[parameters('serviceBusTopicName')]",
          "dependsOn": [
            "[parameters('serviceBusNamespaceName')]"
          ],
          "properties": {
            "maxSizeInMegabytes": 1024
          },
          "resources": [
            {
              "type": "subscriptions",
              "apiVersion": "2024-01-01",
              "name": "[parameters('serviceBusSubscriptionName')]",
              "dependsOn": [
                "[parameters('serviceBusTopicName')]"
              ],
              "properties": {
                "deadLetteringOnMessageExpiration": true
              }
            }
          ]
        }
      ]
    }
  ]
}

注意

如果为 forwardDeadLetteredMessagesTo 属性指定队列或主题，Event Grid 会自动将死信消息转发到该队列或主题。

后续步骤

尝试使用所选语言的示例来探索Azure Service Bus功能。

Azure Service Bus 客户端库示例（.NET 最新版）
Azure Service Bus 用于 Java 的客户端库示例（最新版）
Azure Service Bus 客户端库 Python 示例
适用于 JavaScript 的 Azure Service Bus 客户端库示例
typeScript 的 Azure Service Bus 客户端库示例

查找较旧的.NET和Java客户端库的示例：

注意

2026 年 9 月 30 日，我们将停用 Azure Service Bus SDK 库 WindowsAzure.ServiceBus Microsoft.Azure。ServiceBus 和 com.microsoft。azure.servicebus 不符合Azure SDK准则。我们还将结束对 SBMP 协议的支持，因此在 2026 年 9 月 30 日之后，你将无法再使用此协议。在该日期之前迁移到最新的 Azure SDK 库，这些库提供关键的安全更新和改进的功能。

尽管旧库仍可在 2026 年 9 月 30 日以后使用，但它们将不再从Azure获得官方支持和更新。有关详细信息，请参阅支持停用公告。

Last updated on 2026-03-10

Compartilhar via