Enable duplicate message detection for an Azure Service Bus queue or a topic

  • Article

When you enable duplicate detection for a queue or topic, Azure Service Bus keeps a history of all messages sent to the queue or topic for a configure amount of time. During that interval, your queue or topic won't store any duplicate messages. Enabling this property guarantees exactly once delivery over a user-defined span of time. For more information, See Duplicate detection. This article shows you different ways to enable duplicate message detection for a Service Bus queue or a topic.

Note

  • The basic tier of Service Bus doesn't support duplicate detection. The standard and premium tiers support duplicate detection. For differences between these tiers, see Service Bus pricing.
  • You can't enable or disable duplicate detection after the queue or topic is created. You can only do so at the time of creating the queue or topic.

Using Azure portal

When creating a queue in the Azure portal, select Enable duplicate detection as shown in the following image. You can configure the size of the duplicate detection window when creating a queue or topic.

Enable duplicate detection at the time of the queue creation

When creating a topic in the Azure portal, select Enable duplicate detection as shown in the following image.

Enable duplicate detection at the time of the topic creation

You can also configure this setting for an existing queue or topic, if you had enabled duplicate detection at the time of creation.

Update duplicate detection window size for an existing queue or a topic

To change the duplicate detection window size for an existing queue or a topic, on the Overview page, select Change for Duplicate detection window.

Queue

Set duplicate detection window size for a queue

Topic

Set duplicate detection window size for a topic

Using Azure CLI

To create a queue with duplicate detection enabled, use the az servicebus queue create command with --enable-duplicate-detection set to true.

az servicebus queue create \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --enable-duplicate-detection true \
    --duplicate-detection-history-time-window P1D

To create a topic with duplicate detection enabled, use the az servicebus topic create command with --enable-duplicate-detection set to true.

az servicebus topic create \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name mytopic \
    --enable-duplicate-detection true \
    --duplicate-detection-history-time-window P1D

The above examples also set the size of the duplicate detection window by using the --duplicate-detection-history-time-window parameter. The window size is set to one day. The default value is 10 minutes and the maximum allowed value is seven days.

To update a queue with a new detection window size, use the az servicebus queue update command with the --duplicate-detection-history-time-window parameter. In this example, the window size is updated to seven days.

az servicebus queue update \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --duplicate-detection-history-time-window P7D

Similarly, to update a topic with a new detection window size, use the az servicebus topic update command with the --duplicate-detection-history-time-window parameter. In this example, the window size is updated to seven days.

az servicebus topic update \
    --resource-group myresourcegroup \
    --namespace-name mynamespace \
    --name myqueue \
    --duplicate-detection-history-time-window P7D

Using Azure PowerShell

To create a queue with duplicate detection enabled, use the New-AzServiceBusQueue command with -RequiresDuplicateDetection set to $True.

New-AzServiceBusQueue -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -QueueName myqueue `
    -RequiresDuplicateDetection $True `
    -DuplicateDetectionHistoryTimeWindow P1D

To create a topic with duplicate detection enabled, use the New-AzServiceBusTopic command with -RequiresDuplicateDetection set to true.

New-AzServiceBusTopic -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -Name mytopic `
    -RequiresDuplicateDetection $True
    -DuplicateDetectionHistoryTimeWindow P1D

The above examples also set the size of the duplicate detection window by using the -DuplicateDetectionHistoryTimeWindow parameter. The window size is set to one day. The default value is 10 minutes and the maximum allowed value is seven days.

To update a queue with a new detection window size, see the following example. In this example, the window size is updated to seven days.

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

$queue.DuplicateDetectionHistoryTimeWindow='P7D'

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

To update a topic with a new detection window size, see the following example. In this example, the window size is updated to seven days.

$topic=Get-AzServiceBusTopic -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -Name mytopic

$topic.DuplicateDetectionHistoryTimeWindow='P7D'

Set-AzServiceBusTopic -ResourceGroup myresourcegroup `
    -NamespaceName mynamespace `
    -Name mytopic `
    -TopicObj $topic

Using Azure Resource Manager template

To create a queue with duplicate detection enabled, set requiresDuplicateDetection to true in the queue properties section. For more information, see Microsoft.ServiceBus namespaces/queues template reference. Specify a value for the duplicateDetectionHistoryTimeWindow property to set the size of the duplicate detection window. In the following example, it's set to one day.

{
  "$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": {
            "requiresDuplicateDetection": true,
            "duplicateDetectionHistoryTimeWindow": "P1D"
          }
        }
      ]
    }
  ]
}

To create a topic with duplicate detection enabled, set requiresDuplicateDetection to true in the topic properties section. For more information, see Microsoft.ServiceBus namespaces/topics 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"
      }
    },
    "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": {
            "requiresDuplicateDetection": true,
            "duplicateDetectionHistoryTimeWindow": "P1D"
          }
        }
      ]
    }
  ]
}

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 below:

Note

On 30 September 2026, we'll retire the Azure Service Bus SDK libraries WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus, and com.microsoft.azure.servicebus, which don't conform to Azure SDK guidelines. We'll also end support of the SBMP protocol, so you'll no longer be able to use this protocol after 30 September 2026. Migrate to the latest Azure SDK libraries, which offer critical security updates and improved capabilities, before that date.

Although the older libraries can still be used beyond 30 September 2026, they'll no longer receive official support and updates from Azure. For more information, see the support retirement announcement.