TFS Event Filtering
With today's release of TfsAlert a question will no doubt get asked; what really is a Filter Expression? Short answer, an expression to filter events sent from TFS.
Long answer.
Formally known as Visual Studio Event Filter Language or VSEFL, it feels very much like a SQL expression and/or like WIQL. These filters are added with the creation of the subscription itself. This becomes really important when you're consuming any part of the TFS eventing system. Let's use TfsAlert for example. It's 100% driven by the TFS eventing system and while there are a number of events once can subscribe to lets just focus on two and further provide some concrete examples.
- CheckinEvent
- WorkItemChangedEvent
Lets also assume you have a TFS server which has more than one TFS project and more than one person using it. Given that when you startup TfsAlert without any subscription filters you're going to get a number of events, some of which I am sure you don't care about. The following questions usually come next. How can I
- filter a CheckinEvent for my set of team project(s)?
- filter only WorkItems assigned to me across any TFS project?
- filter WorkItems for my area?
A typical CheckinEvent filter usually looks something like the following:
" TeamProject = 'Project Name' "" TeamProject MATCH 'Project Name A|Project Name B' "
Those two expression actually answer that first question. The expression simply states we want to filter on TeamProject where the it either = 'Project Name' or MATCH all project which equal Project Name A or Project Name B. The "key" ( in this case TeamProject) is derived from that events schema. So what operators are available?
| = (equals) | String, Int, Enum, Date, Bool |
| < (less than) | Int, Enum, Date |
| <= | Int, Enum, Date |
| > (greater than) | Int, Enum, Date |
| >= | Int, Enum, Date |
| Under (Quickly match file specs) | String |
| Match (Regular Expression Match) | String |
| Like (Simple match) | String |
Matching is pretty easy and all completed on the server side before the event is ever sent. What you really need to understand is each particular events schema. That events schema ultimately defines the actual event and what you have the ability to filter on. When TFS installs you can find the default schemas @ %ProgramFiles%\Microsoft Visual Studio 2005 Team Foundation Server\Web Services\Services\v1.0\Transforms. You can further create your own event types, but I will save that for another post.
This release of TfsAlert will actually publish the message you've received to the event log just so you can easily look at it. This will really help when you want to build some filter expressions. This can also be turned off by setting the value attribute from 3 to 0.
<switches>
<add name="General" value="3" />
</switches>
Want to dive deeper, all the eventing information you ever wanted to know can be found @ https://msdn2.microsoft.com/en-us/library/aa398965.aspx