Team Foundation Server – Eventing Service - Part 1 (Subscribing to events)

Posted by: Subodh Sohoni , on 4/14/2008, in Category VSTS & TFS
Views: 31933
Abstract: 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. In this two part series, we will take an overview of the events raised by TFS and how to subscribe to those events
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>&nbsp;&nbsp;&nbsp;&nbsp;Object ID: <variable name="ObjectId" /></div>
 <div>&nbsp;&nbsp;&nbsp;&nbsp;Action ID: <variable name="ActionId" /></div>
 <div>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SID: <variable name="Sid" /></div>
 <div>&nbsp;&nbsp;&nbsp;Entry type: <variable name="EntryType" /></div>
 <div>&nbsp;&nbsp;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.
If you liked the article,  Subscribe to my RSS Feed.
What Others Are Reading!
Was this article worth reading? Share it with fellow developers too. Thanks!
Share on LinkedIn
Share on Google+

Author
Subodh is a consultant and corporate trainer. He has overall 28+ years of experience. His specialization is Application Lifecycle Management and Team Foundation Server. He is Microsoft MVP – VS ALM, MCSD – ALM and MCT. He has conducted more than 300 corporate trainings and consulting assignments. He is also a Professional SCRUM Master. He guides teams to become Agile and implement SCRUM. Subodh is authorized by Microsoft to do ALM Assessments on behalf of Microsoft. Follow him on twitter @subodhsohoni


Page copy protected against web site content infringement 	by Copyscape




Feedback - Leave us some adulation, criticism and everything in between!
Comment posted by Ismail Ahmed Syed on Wednesday, August 25, 2010 12:55 AM
Hi,
     Can you please let me know.what priveleges are required to register an event (ie. Project Administrator, Collection Administrator or Server Administrator)?
Comment posted by Timothy Eichfeld on Friday, April 15, 2011 5:02 PM
This would be great, except IEventService does not even exist in TFS 2010 in Microsoft.TeamFoundation.dll in the Microsoft.TeamFoundation.Server namespace. (At least not in the binary I have) Im wondering how are we supposed to use it?

Categories

JOIN OUR COMMUNITY

POPULAR ARTICLES

FREE .NET MAGAZINES

Free DNC .NET Magazine

Tags

JQUERY COOKBOOK

jQuery CookBook