Team Foundation Server – Eventing Service - Part 1 (Subscribing to events)
Visual Studio Team System exposes number of opportunities to extend its features and functionality. Responding to events published by the Team Foundation Server (TFS) is one of the extensibility opportunities which may be used most extensively. TFS is a hive of activities related to configuration management, source control, work item tracking, builds etc. These activities can be treated as events and it is possible to write event handlers for each of these events. By handling such events we will be able to automate the tasks related to management of the project. For example, we can subscribe to Checkin event where the subscribing webservice will fire a build using a TFSBuild.exe command line tool to implement continuous integration (CI). Another example can be of creating a .msi for output of build once the build completion event fires. A very interesting case could be to spawn workitems say of the type tasks in response to event of creation of other type of workitem like a scenario and link the spawned workitems to the scenario like workitem.
This article discusses:
- The events raised by TFS
- Using BisSubscribe.exe
- Filtering the events
- How a subscription can be created for an email
- How to create a subscription for a webservice
- Creating a subscription programmatically
Part 2 of this article will discuss raising and publishing the events which are not published by TFS when it is installed.
Subscribing to events
TFS uses implementation of publisher – subscriber paradigm in which certain registered events are published when they are raised. Notification of those events, as and when they are raised, is made to the subscribers. TFS registers the subscription in its database. The process of registering a subscription for an event can be done either using a command line tool named BisSubscribe.exe or it can be done programmatically using the Team Foundation Object Model that is published by Microsoft. Subscriptions can be of two types. First type of subscription is an email subscription in which a preconfigured email is sent to the email address mentioned in the subscription. The second type of subscription is of a webservice which has a method named Notify. A parameter of Notify method provides the event specific data.
List of published events
When TFS is installed, numbers of events are registered for publishing. The list of them is as follows:
|
Build Completion Event
|
NodesDeletedEvent
|
|
Build Status Changed Event
|
ProjectCreatedEvent
|
|
BranchMovedEvent
|
ProjectDeletedEvent
|
|
NodeCreatedEvent
|
CheckinEvent
|
|
NodePropertiesChangedEvent
|
WorkItemChanged
|
|
NodeRenamedEvent
|
|
Note: Node related events refer to iterations and areas in the team project.
Using BisSubscribe.exe
BisSubscribe.exe is a command line tool available with the installation of TFS. It takes following arguments:
eventType – Type of the event for which the subscription is being made. E.g. CheckinEvent, WorkItemChangedEvent.
address – Either the email address to which the notification email should be sent E.g. user@domain.com or the URL of the webservice to be called e.g. http://TFS_Name/SubscribingWebService/Service.asmx
deliveryType – This can be either of EmailHtml, EmailPlaintext if the subscription is for email or Soap is the subscription is for webservice method.
server / domain – Name of TFS or http address of the TFS with port number (typically 8080).
filter – Optional filter expression which allows TFS to notify only events which match that filter
Filtering the events
Events can be filtered using some criterion in such a way that the events which fulfill that criterion only are notified to the subscriber. TFS uses a special language for setting the filter expressions. This filtering language may contain Event subtypes containing any number of simple fields. For example, E-mail me for Defect events when the ‘Defect Owner field = “user1” AND the Status field <> “Resolved”’”. It may contain normal equality checking operators, =, <>, <,>,<=,>=. It also additionally contains operators for matching with regular expression (Match) or for simple match (Like). An expression can be simple with only one operator or complex with multiple operators and sub expressions. Complex expression is formed with operators like AND, OR e.g. “Team Project = ‘Project 1’ AND PolicyOverrideComment <> ‘’ ”
Creating a email type of subscription
Example of creating an email type of subscription using BisSubscribe.exe tool where email needs to be in plain text would be
>C:\Program Files\Microsoft Visual Studio 2005 Team Foundation Server\TF Setup\BisSubscribe.exe /eventType BuildCompletionEvent /address tfsservice@vsts.local /deliveryType EmailPlaintext /domain http://tfsrtm:8080
If the email can be in html format with a filter for the Team Project named SEED_Automation then the same command would be
>C:\Program Files\Microsoft Visual Studio 2005 Team Foundation Server\TF Setup\BisSubscribe.exe /eventType BuildCompletionEvent /filter “Team Project=’SEED_Automation’” /address tfsservice@vsts.local /deliveryType EmailHtml /domain http://tfsrtm:8080
The template which will be used to create the email may look like this:
<html>
<head><title>TFS Security Subsystem Notification</title></head>
<body style="font-family:courier new; font-size:12px;">
<div>An access control list has been changed.</div>
<br />
<div> Object ID: <variable name="ObjectId" /></div>
<div> Action ID: <variable name="ActionId" /></div>
<div> SID: <variable name="Sid" /></div>
<div> Entry type: <variable name="EntryType" /></div>
<div> Change type: <variable name="ChangeType" /></div>
</body>
</html>
It may also be given in the .xsl format. If both are present then the precedence will be given to template.
Creating a subscription for webservice
A webservice which subscribes to an event needs to have a method with following signature:
[SoapDocumentMethod(Action = "http://Microsoft.VisualStudio.Bis/Notify", RequestNamespace = "http://Microsoft.VisualStudio.Bis")]
[WebMethod]
public void Notify(string eventXml)
{
//Write your custom code here
//Use eventXml to extract event related fields and their values
}
Once such a webservice is ready, the subscription can be created with the command
>C:\Program Files\Microsoft Visual Studio 2005 Team Foundation Server\TF Setup\BisSubscribe.exe /eventType BuildCompletionEvent /filter “Team Project=’SEED_Automation’” /address http://TFS_Name/MyWebService/Service.asmx /deliveryType Soap /domain http://tfsrtm:8080
Creating the subscription programmatically
We may create the subscription of all types programmatically instead of using the BisSubscribe tool. The code of the method which adds the subscription may look like this:
{
IEventService eventEndpoint = (IEventService)server.GetService(typeof(IEventService));
DeliveryPreference delPrev = new DeliveryPreference();
delPrev.Type = DeliveryType.EmailHtml;
delPrev.Schedule = DeliverySchedule.Immediate;
delPrev.Address = txtDeliveryAddress.Text;
string userId = txtDomain.Text + @"\" + txtUsername.Text;
eventEndpoint.SubscribeEvent(userId, "CheckinEvent", "TeamProject = '" + cboProject.SelectedItem + "' AND PolicyOverrideComment <> '' ", delPrev);
}
The object model for this code is provided through the components Microsoft.TeamFoundation.dll, Microsoft.TeamFoundation.Client.dll and Microsoft.TeamFoundation.Common.dll.
Conclusion
This article provided an overview of how to achieve automation in project management when working with TFS. It described the process for subscribing to the published events using a tool BisSubscribe.exe as well as to do it programmatically. In the Part 2 of this article we will take a walkthrough of creating and publishing the event which can be subscribed to by others.
I hope this article was useful and I thank you for viewing it.
This article has been editorially reviewed by Suprotim Agarwal.
C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.
We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).
Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.
Click here to Explore the Table of Contents or Download Sample Chapters!
Was this article worth reading? Share it with fellow developers too. Thanks!
Subodh is a Trainer and consultant on Azure DevOps and Scrum. He has an experience of over 33 years in team management, training, consulting, sales, production, software development and deployment. He is an engineer from Pune University and has done his post-graduation from IIT, Madras. He is a Microsoft Most Valuable Professional (MVP) - Developer Technologies (Azure DevOps), Microsoft Certified Trainer (MCT), Microsoft Certified Azure DevOps Engineer Expert, Professional Scrum Developer and Professional Scrum Master (II). He has conducted more than 300 corporate trainings on Microsoft technologies in India, USA, Malaysia, Australia, New Zealand, Singapore, UAE, Philippines and Sri Lanka. He has also completed over 50 consulting assignments - some of which included entire Azure DevOps implementation for the organizations.
He has authored more than 85 tutorials on Azure DevOps, Scrum, TFS and VS ALM which are published on
www.dotnetcurry.com.Subodh is a regular speaker at Microsoft events including Partner Leadership Conclave.You can connect with him on
LinkedIn .