針對 Azure 服務匯流排佇列和訂閱啟用訊息到期的無效信件處理

Azure 服務匯流排的主題佇列和訂閱提供次要的子佇列，稱為「無效信件佇列」(DLQ)。 無效信件佇列並不需要明確建立，且無法刪除或在主要實體以外管理。 無效信件佇列的目的，是保留無法傳遞至任何收件者的訊息，或是無法加以處理的訊息。 如需詳細資訊，請參閱服務匯流排無效信件佇列的概觀。 本文說明為服務匯流排佇列和訂閱啟用無效信件處理的不同方式。

使用 Azure 入口網站

在 Azure 入口網站中建立為主題建立佇列或訂閱時，請選取 [在訊息到期時啟用無效信件處理]，如下列範例所示。

建立已啟用無效信件處理的佇列

建立已啟用無效信件處理的訂閱

為現有佇列更新訊息到期設定的無效信件處理

在服務匯流排佇列的 [概觀] 頁面上，針對訊息到期設定的 [無效信件處理] 設定目前的值。 在下列範例中，目前的值為 [已停用]。 您可以在快顯視窗中啟用或停用訊息到期的無效信件處理。

為現有訂閱更新訊息到期設定的無效信件處理

在服務匯流排訂閱的 [概觀] 頁面上，針對訊息到期設定的 [無效信件處理] 設定目前的值。 在下列範例中，目前的值為 [已停用]。 您可以在快顯視窗中啟用或停用訊息到期的無效信件處理。

使用 Azure CLI

若要建立已啟用訊息到期時使用無效信件處理的佇列，請使用 az servicebus queue create 命令，並將 --enable-dead-lettering-on-message-expiration 設定為 true。

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 設定為 true。

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 設定為 true。

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 設定為 true。

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 參數指定佇列或主題，Event Grid 會自動將無效訊息轉送至該佇列或主題。 範例如下：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 設定為 $True。

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

若要為現有佇列啟用訊息到期時使用無效信件處理的設定，請使用 Set-AzServiceBusQueue 命令，如下列範例所示。

$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 設定為 $True。

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 參數指定佇列或主題，Event Grid 會自動將無效訊息轉送至該佇列或主題。

使用 Azure Resource Manager 範本

若要建立已啟用訊息到期時使用無效信件處理的佇列，請在佇列屬性區段中將 deadLetteringOnMessageExpiration 設定為 true。 如需詳細資訊，請參閱 Microsoft.ServiceBus 命名空間/佇列範本參考。

{
  "$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
          }
        }
      ]
    }
  ]
}

若要建立已啟用訊息到期時使用無效信件處理的主題訂閱，請在佇列屬性區段中將 deadLetteringOnMessageExpiration 設定為 true。 如需詳細資訊，請參閱 Microsoft.ServiceBus 命名空間/主題/訂用帳戶範本參考。

{
  "$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
              }
            }
          ]
        }
      ]
    }
  ]
}

注意

如果您為 forwardDeadLetteredMessagesTo 屬性指定佇列或主題，Event Grid 會自動將無效訊息轉送至該佇列或主題。

下一步

請以您所選擇的語言嘗試各式範例，以探索 Azure 服務匯流排的功能。

• 適用於 .NET (最新版) 的 Azure 服務匯流排用戶端程式庫範例
• 適用於 JAVA (最新版) 的 Azure 服務匯流排用戶端程式庫範例
• 適用於 Python 的 Azure 服務匯流排用戶端程式庫範例
• 適用於 JavaScript 的 Azure 服務匯流排用戶端程式庫範例
• 適用於 TypeScript 的 Azure 服務匯流排用戶端程式庫範例

請在下方尋找舊版 .NET 和 JAVA 用戶端程式庫的範例：

• 適用於 .NET (舊版) 的 Azure 服務匯流排用戶端程式庫範例
• 適用於 JAVA (舊版) 的 Azure 服務匯流排用戶端程式庫範例

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。 我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。 請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但這些程式庫將無法繼續收到 Microsoft 的官方支援和更新。 如需詳細資訊，請參閱支援淘汰公告。