Filtering Team Foundation Server Events

Article
11/16/2012

Filtering is done in-memory. This provides maximum speed and flexibility as each event arrives. Filters are stored in the database as serialized XML.

Event Filters

E-mail me for Defect events when the Defect Project field = "Visual Studio," "Word," or "Excel."

E-mail me for Check-in events when the Check-in Files field is Under "\dd\project1" OR the Files field is Under "\dd\project1."

E-mail me for Defect events when the Defect Owner field = "user1" AND the Status field <> "Resolved."

Event subtypes

TFS supports event subtypes that contain any number of simple fields.

Events subtypes can have sequences and other complex types. You can use XPath notation to reference fields such as "myObject/myfield." Referencing a sequence in an expression causes a match if one or more of the objects in the sequence match. You can also use XPath functions to query the document.

Fields must be enclosed in quotation marks ("), or a "Syntax Error in Exception" error will be caused.

Operators

For each field, the subscriber can select to filter by using one of the predicates in the following table.

Predicate	Applies to Fields of Type
= (equals)	String, Int, Date
< (less than)	Int, Date
<=	Int, Date
> (greater than)	Int, Date
>=	Int, Date
Under (Quickly match file specs)	String
Match (Regular Expression Match)	String

Equals can apply to a single value or to a range of values. You can combine less than or equal to and greater than or equal to select ranges of values.

Under and Match are special string matching conditions. Under is for the common case that you must match strings such as file paths that are hierarchical in nature. Match enables the subscriber to enter a regular expression that matches a given event string.

Combinations

You can combine filters with both and and or expressions. You can negate a condition with not.

The following example accepts only those events where the owner is "user1" and the file is in the eQA folder or a subfolder.

Owner equals "user1" and
Files under "\devdiv\vset\eQA"

You can use parentheses to form combinations of any arbitrary complexity. See the Advanced Filtering section for more details.

Advanced Filters

Team System enables filter specification in the Visual Studio Event Filter Language (VSEFL). VSEFL is a simple language. The expression syntax is modeled after SQL expressions. It has some additional operations that add flexibility and performance improvements. This allows you to create filters of any arbitrary complexity, such as:

Status <> Resolved AND (
Owner MATCH "user1|user2|user3" 
OR
Files UNDER "\\dd\vset\estudio;\\dd\vset\eDev"
)

This simple expression language is defined by the following production rules in Extended Backus-Naur Form (EBNF) format. Terminal symbols are expressed in capital letters, and non-terminal symbols are expressed in camel notation. If we have S as the starting symbol:

S -> Expr5
Expr5 -> Expr4 ("OR" Expr4)*
Expr4 -> Expr3 ("AND" Expr3)*
Expr3 -> "NOT"? Expr2
Expr2-> Expr1 | ‘(‘ Expr5 ‘)’ 
Expr1 -> FieldName BooleanOperator (IntLiteral | StringLiteral | DateExpr | "NULL")
DateExpr -> DateLiteral | "TODAY" (AddOperator IntLiteral)?
BooleanOperator -> "<" | ">" | "=" | "<=" | ">=" | "<>" | "UNDER" | "MATCH" | "LIKE" 
AddOperator -> "+" | "-"

This grammar gives precedence to NOT, then AND, then OR, in ways similar to many other languages.

The following examples are invalid VSEFL. They will be flagged as errors when submitted to the Subscribe method.

Example	Reason
Owner ( MATCH "expr"	Syntax error
StatusInt = OR < 3	Syntax error, should use <=
StatusInt LIKE 3	Type mismatch

Event Filter Evaluation

Below is the sequence of steps for asynchronous event evaluation.

The event arrives from a Web Method call. Each of the fields is in XML.
The event is first stored in the event table of the database.
Each subscription stays in memory. Each subscription for that event type is evaluated iteratively against the event. Matches generate a notification.
Each subscriber has a queue of notifications. A new notification goes into the subscriber’s queue. The subscriber is notified of the events in order.
When the server restarts, it checks for any existing events in the table left over from previous runs and processes them immediately.