Azure ServiceBus Filters

In an Azure ServiceBus you can create multiple subscriptions for one topic. Such a subscription has the possibility to filter messages. So only the messages that match the criterias are “forwarded” to the subscription. Let’s have look on how filters work.

In this post I will use the ServiceBus Explorer to connect to an existing ServiceBus namespace. If you want to know how to create a ServiceBus namespace, a topic plus subscription and connect to it with the ServiceBus explorer – then read my previous blog post about it: How to create a topic with testdata in Azure ServiceBus

What are filters in ServiceBus?

Let’s assume that you have a ServiceBus and a topic. You already created a subscription which is kind of a virtual queue. This subscriptions contains a copy of the data that you send to the ServiceBus. You can create multiple subscriptions and use them for different purposes. You can use one of them for your application, one to forward the messages to the notification hub, one to create a backup of all data in the blob or table storage and one to have the most important messages available. But how to filter on the most important messages?

The subscriptions in the ServiceBus allow you to set a filter/rule on it. You can use such a rule to filter out all messages that are not relevant for you. I would directly start to create a filter, but the first question is:

How to test filters?

Use the ServiceBus Explorer to connect to your ServiceBus and receive some messages from your subscription. You should now find a magnifier icon on the right to the “Message List”. Click that icon and you can start to test your filters:



The expression allows you to filter for properties of the BrokeredMessage object by using “sys.Property”. You can also filter for custom properties by using “user.Property” or just “Property”. Here are some samples for filters:

  • sys.Label LIKE ‘%Bus%’
    • Filters all messages that contains the string “Bus” in the Label of the BrokeredMessage object.
  • user.Country = ‘Austria’
    • same as: Country = ‘Austria’
  • Exists([My Date])
    • Returns items that have the custom property “My Date”. You need to enclose the property name with square brackets if the property name contains a space.
  • UserName = ‘armin’
  • UserName != ‘armin’
  • sys.Size < 1000
  • Costs > 500 AND Costs < 5000
  • myId = 12
  • sys.ForcePersistence = false
  • sys.Size < 1000 AND sys.Label LIKE ‘Service%’ and (city = ‘Vienna’ OR city = ‘Graz’)
  • sys.Size < 100 * sys.SequenceNumber
  • UserName + Country <> ‘arminAustria’
  • UserName IS NULL
  • UserName IS NOT NULL
  • Tags IN (‘azure’, ‘servicebus’, ‘codehollow’)

You can find more information about the expressions in SqlFilter.SqlExpression.

Filter DateTime values

I tried a lot of different ways and researched a long time and it seems that this is currently not possible. One workaround is to use unix timestamps as custom properties in the message. Those are represented by 32-bit integer values and you can simply filter on that.

Update 21 Jul, 2016
The datetime filter works when you set them via code (Powershell/C#). It’s currently just not possible to set it via ServiceBus Explorer. The datetime filter is e.g.:

var filter = new SqlFilter("datetime >= @datetime");
filter.Parameters.Add("@datetime", DateTime.Parse("2016-06-06"));

Update 12 Sep, 2016
I wrote a blot post about how to set datetime filters via Powershell or C#. You can find it here: Azure ServiceBus: working with datetime filters

Configure the filter for the ServiceBus subscription

If you already have the final filter expression, then it’s quite easy to set this filter expression. You can set the “Default Filter” when you create a new subscription in Azure ServiceBus Explorer. If you want to change an existing filter, expand the subscription, expand the rules, delete the existing $Default rule and add a new one with your filter expression.

What about multiple rules?

You can configure multiple filters for your ServiceBus, but only the $Default one is used to filter the data that will be in the subscription. You can create additional filters and use them with actions to set values. An example for that would be:

  • Filter: Tags IN (‘Azure’, ‘ServiceBus’)
  • Action: SET Priority = ‘High’

Additional Information

How to use Service Bus topics and subscriptions:
ServiceBus explorer:


2 Responses

  1. About filters working with date time values, a friend of mine pointed me to a solution:

    var filter = new SqlFilter(” datetime >= @datetime”);
    filter.Parameters.Add(“@datetime”, DateTime.Parse(“2016-06-06”));

    var m = new BrokeredMessage();
    m.Properties[“datetime”] = DateTime.Now;

    • Thanks a lot! I always tried it with the service bus explorer and the filter for datetime doesn’t work with it. I tested it now with PowerShell and it works like a charm.

Leave a Reply

Your email address will not be published. Required fields are marked *