The TFS Aggregator is undoubtedly one of the most known and most useful tools for TFS. This comes to fill all the needs that can’t be covered using the traditional work item rules. Basically allows you to execute your own rules after each save.
Installation and Deployment
The TFS Aggregator is an open source project stored in https://github.com/tfsaggregator/tfsaggregator. You can download the code and deploy it by yourself or simply use the installer provided by the project. The installer will detect your TFS version and install for you the console app and the plugin.
How the Plugin Works?
A TFS Plugin is a dll installed under “C:\Program Files\Microsoft Team Foundation Server 14.0\Application Tier\Web Services\bin\Plugins” which is able to catch a variety of events occurring in TFS and execute an action. The TFS Aggregator catch the event “WorkItemChangedEvent” which occurs each time that work item is saved and execute the actions defined in the policies file.
What is the Console App?
The TFS Aggregator console app is an application developed to simulate the behavior of the aggregator plugin (execute the rules defined in the policies file when a work item is updated). It’s very useful for test the policies file before deploying it to the plugins folder.
How to Configure the Policies File
The file is composed of 3 sections: configuration section, rules section and policies section.
The configuration section is used to indicate the aggregator how it should be executed:
- rateLimiting: aggregator “time out”, to avoid infinite loops
- logging: logging type
- script: language used to write the rules
- authentication: save the changes using the same user or as the service user (impersonate)
- server: TFS server url (useful in low balancer environments)
In the rules section is where the actions to be executed are indicated. The rules are written directly in programming language (usually in C#). There are slight changes in the syntax but they are quite intuitive.
Regarding to the policies section, this is the place where you specify the scope in which each rule is applied. Each policy defines a single scope but may contain several rules.
How to Write a Rule
The rule header contains the rule name (must be unique because is used as id) and can contains two different attributes:
- appliesTo: Indicate which work item types will be affected by the rule
- hasField: Indicate that the rules will be applied to work items types that contains the specified field
The rule content specify the action to be executed when the rule is triggered. This action is written in programing language (usually C#) and must be inside of the CDATA element:
Regarding to the code, if you know the C# TFS API will be quite simple for you understand the syntax. Basically is the same thing but the Aggregator provides a set of objects and methods to help you with the hard work.
Aggregator Main Objects:
- Self: contain the work item which trigger the aggregator
- Fields: contain a list with all the work item fields
- Store: contain the object store (WorkItemStore in the C# TFS API)
- Logger: contain the method log used to write logs
- Library: contain two useful methods: SendEmail and GetEmailAddress
Aggregator Main Methods (Note: I will use the work item “self” to show the methods but any work item object contains this methods):
- Fields: can be used to retrieve all the fields or a specific one using: self.Fields[“Title”]
- Parent: retrieve the work item parent
- Children: retrieve a list with the work item childs
- HasParent: retrieve true or false
- HasChildren: retrieve true or false
- AddWorkItemLink: add a link
- AddHyperlink: add a hiperlink
- LastRevision: retrieve the a work item with the values before the last save
- MakeNewWorkItem: create a new work item
- GetGlobalList: retrieve the values of the specified Global List
Note: there is a very good examples and explanations in the official documentation https://tfsaggregator.github.io/using/
How to Write a Policy
Write a policy if a simple thing. Just specify the scope and indicate which rules should be applied in this scope. The policy header contains the attribute name (must be unique because is used as id) and its elements are the following:
- collectionScope: contains the collection affected by this policy
- projectScope: contains the team project (or team projects) affected by this policy
- ruleRef: specify a rule to be executed (you can add several rules to the same policy)
How Can I Test My Policies Using The Console App?
The aggregator console app allows you to execute a specified policies file to a specific work item by running the following command:
“C:\Program Files\TFS Aggregator\bin\TFSAggregator2.ConsoleApp.exe” -f <PoliciesFile> -c <CollectionUrl> -p <TeamProject> -n <WorkItemId>
“C:\Program Files\TFS Aggregator\bin\TFSAggregator2.ConsoleApp.exe” -f “C:\Users\myuser\Desktop\TFSAggregator2.ServerPlugin.policies” -c http://tfsserver:8080/tfs/DefaultCollection -p MyProject -n 859
How to Deploy My Policies?
After test your policies file using the console app, you will be ready to deploy it as a plugin (to run after each save). To implement the new policies file just paste it in the following path: “C:\Program Files\Microsoft Team Foundation Server 14.0\Application Tier\Web Services\bin\Plugins”
- When a rule is executed, the changes are not saved immediately. They are saved only at the end of the execution of all the rules (the aggregator uses a bulk save instead of several single saves)
- After the Aggregator is executed it will run again (but it’s logical, after all this is executed after each save no?)
- Uses the necessary conditions to avoid “infinite loops” (write the rules with this in mind)
- You can find a sample policies in the following path “C:\Program Files\TFS Aggregator\Samples”
- Check the official documentation here: https://tfsaggregator.github.io/intro/
- There is an option to use the TFS Aggregator as web service (but this version is still in beta)