Azure Service Bus topics are used to deliver messages to multiple subscribers. By default a copy of the message is sent to each subscription. But this behavior can be changed by adding rules or filters to the subscription. When a subscription is created, a default rule is added to the subscription. The default rule is a TrueFilter which means all the messages will be delivered to the subscription.

Each message has a set of system properties. The application that is sending the message can also add custom properties. Both the system and custom properties can be used to define subscription rules.

SQL filters lets you specify a simple SQL expression as a filter. The SQL expression can contain null checks, logical and relational operators and pattern matching using LIKE. Correlation filters check for equality and can contain both the system and custom properties.

Adding a new filter or rule

A subscription can have more than one rule. If a message satisfies at least one of the rules, then the message is routed to the subscription. When adding a new filter make sure you delete the existing default filter or else the subscription will receive all the messages.

ARM Template snippet for Service Bus topic with a SQL filter is shown below. The messages that satisfy the condition specified in the sqlExpression property will be routed to the subscription.

{
    "type": "Microsoft.ServiceBus/namespaces",
    "name": "[parameters('serviceBusNamespaceName')]",
    "apiVersion": "2017-04-01",
    "location": "[parameters('location')]",
    "properties": {},
    "resources": [
        {
            "type": "topics",
            "name": "[parameters('serviceBusTopicName')]",
            "apiVersion": "2017-04-01",
            "properties": {
                "path": "[parameters('serviceBusTopicName')]"
            },
            "resources": [
                {
                    "type": "subscriptions",
                    "name": "[parameters('serviceBusTopicSubscriptionName')]",
                    "apiVersion": "2017-04-01",
                    "properties": {},
                    "resources": [
                        {
                            "type": "Rules",
                            "name": "[concat(parameters('serviceBusTopicSubscriptionName'), '-filter')]",
                            "apiVersion": "2017-04-01",
                            "properties": {
                                "action": {},
                                "filterType": "SqlFilter",
                                "sqlFilter": {
                                    "sqlExpression": "CustomProperty =  'value'"
                                }
                            },
                            "dependsOn": [
                                "[parameters('serviceBusTopicSubscriptionName')]"
                            ]
                        }
                    ],
                    "dependsOn": [
                        "[parameters('serviceBusTopicName')]"
                    ]
                }
            ],
            "dependsOn": [
                "[concat('Microsoft.ServiceBus/namespaces/', parameters('serviceBusNamespaceName'))]"
            ]
        }
    ]
}

ARM Template snippet for Service Bus topic with a Correlation filter is shown below. The messages with the value of demo for the system property label will be routed to the subscription.

{
    "type": "Microsoft.ServiceBus/namespaces",
    "name": "[parameters('serviceBusNamespaceName')]",
    "apiVersion": "2017-04-01",
    "location": "[parameters('location')]",
    "properties": {},
    "resources": [
        {
            "type": "topics",
            "name": "[parameters('serviceBusTopicName')]",
            "apiVersion": "2017-04-01",
            "properties": {
                "path": "[parameters('serviceBusTopicName')]"
            },
            "resources": [
                {
                    "type": "subscriptions",
                    "name": "[parameters('serviceBusTopicSubscriptionName')]",
                    "apiVersion": "2017-04-01",
                    "properties": {},
                    "resources": [
                        {
                            "type": "Rules",
                            "name": "[concat(parameters('serviceBusTopicSubscriptionName'), '-filter')]",
                            "apiVersion": "2017-04-01",
                            "properties": {
                                "action": {},
                                "filterType": "CorrelationFilter",
                                "correlationFilter": {
                                    "label": "demo"
                                }
                            },
                            "dependsOn": [
                                "[parameters('serviceBusTopicSubscriptionName')]"
                            ]
                        }
                    ],
                    "dependsOn": [
                        "[parameters('serviceBusTopicName')]"
                    ]
                }
            ],
            "dependsOn": [
                "[concat('Microsoft.ServiceBus/namespaces/', parameters('serviceBusNamespaceName'))]"
            ]
        }
    ]
}

Filter actions

Filter actions are like SQL UPDATE statements. The SET keyword is used to both add and update custom properties. System properties can only be updated. In order to update a system property prefix the property name with sys.. When you add a filter with an action to a subscription, a new message is created for each message received by the subscription. The newly created message will be a copy of the original message except it will have updated or new properties and also the name of the filter that resulted in the message being created.

ARM Template snippet for the action property

"action": {
    "sqlExpression": "SET CustomProperty = 'value'"
}

The sqlExpression will update the value of the custom property called CustomProperty if it is already present else a new custom property will be added.

The rules can’t be added or updated via the Azure portal. You can install Service Bus Explorer to view the rules.