Developing and debugging Server Side Event Handlers in TFS 2010


Update 2012-01-23: Added note about .NET framework

Martin Hinshelwood wrote an excellent post recently  http://nakedalm.com/team-foundation-server-2010-event-handling-with-subscribers/ ) about a new type of integration
available in TFS 2010, namely server side event handlers, that is executed within the TFS context. I wasn’t aware of this new feature and as Martin notes, there doesn’t seem to be any material/documentation of it at all.

Previously, when you wanted some custom action to be executed when some event occurs in TFS (check-in, build completed…) you wrote a web/WCF service with a predefined signature and subscribed to the event using bissubscribe.exe.
Usually you want to get more information from TFS than what is available in the event itself so you would have to use the TFS client object model to make new requests back to TFS to get that information.
The deployment of these web services is always a bit of a hassle, especially around security. Also there is no way to affect the event itself, e.g. to stop the event from finishing depending on some condition. This can be done using
server side events.

The deployment of a server side event handler couldn’t be simpler, just drop the assembly containing the event handlers into the Plugins folder of TFS, which is located at 
C:Program FilesMicrosoft Team Foundation Server 2010Application TierWeb ServicesbinPlugins. TFS monitors this directory from any change and will restart itself automatically, so the latest version will
always be executed.

In this first post on this subject, I will describe how to set up your development environment to make it easy to both deploy and debug your event handler. 

  1. Install TFS 2010
    I recommend that you install a local copy of TFS 2010 on your development machine. For this scenario, you only need the Basic version which is a breeze to install. It took me about 10-15 minutes to install and configure it the last time I did it.
    This will make your TFS development and customization much more efficient than using a share remote server, and you can pretty much assault it as much as you want since it is your private server! Ler
  2. Run Visual Studio 2010 as admin
    To be able to deploy your event handler automatically (see next step), you need to run Visual Studio in administration mode
  3. Create the Event Handler project
    To setup the project, create a standard C# class library.
    Note that the project must be .NET 3.5 (or lower), NOT .NET 4.0 since TFS is running on .NET 2.0 it can’t load a .NET 4.0 assembly in the same app domain.

    Martin has written about what you need to reference in his post. Since he was using VB.NET in his sample, I thought that I include a C# version of a minimal WorkItemChanged event handler: 

    using System;
using System.Diagnostics;
using Microsoft.TeamFoundation.Common;
using Microsoft.TeamFoundation.Framework.Server;
using Microsoft.TeamFoundation.WorkItemTracking.Server;

namespace TFSServerEventHandler
{
    public class WorkItemChangedEventHandler : ISubscriber 
    {
        public Type[] SubscribedTypes()
        {
            return new Type[1]{typeof(WorkItemChangedEvent)};
        }

        public EventNotificationStatus ProcessEvent(TeamFoundationRequestContext requestContext, NotificationType notificationType, object notificationEventArgs, 
                                                    out int statusCode, out string statusMessage, out ExceptionPropertyCollection properties)   
        {
            statusCode = 0;
            properties = null;
            statusMessage = String.Empty;
            try
            {
                if (notificationType == NotificationType.Notification && notificationEventArgs is WorkItemChangedEvent)
                {
                    WorkItemChangedEvent ev = notificationEventArgs as WorkItemChangedEvent;
                    EventLog.WriteEntry("WorkItemChangedEventHandler", "WorkItem " + ev.WorkItemTitle + " was modified");
                }

            }
            catch (Exception)
            {
            }
            return EventNotificationStatus.ActionPermitted;
        }

        public string Name
        {
            get { return "WorkItemChangedEventHandler"; }
        }

        public SubscriberPriority Priority
        {
            get { return SubscriberPriority.Normal; }
        }
    }
}

    This event handler doesn’t do enything interesting, but just logs information about the modified work item in the event log.

  4. Deploy your event handler

    Open the project properties and go to the Build tab. Modify the Output Path by browsing to the Plugins directory (see above). This will result in a new

    deployment of your event handler every time you build. Neat! 🙂

    If you look in the Event log after you compile your project, you will see entries from TFS Services that looks like this:

     image


    As you can see, TFS has noticed that a new version of the event handler has been dropped in the plugins folder and therefor it is performing a restart. You will notice that TFS becomes temporarily unavailable while this happens.

    Try modifying a work item and verify that information about it is written in the event log. (Note: You will need to create a event source called “WorkItemChangedEventHandler”, otherwise the EventLog.WriteEntry call will fail.

  5. Debug the event handler

    Since these types of events aren’t very well documented it’s useful to debug the event handlers just to find out how your handler is called and what the parameters contain.

    To do this, to to the Debug menu och select Attach to Process. Check both Show processes from all users and Show processes in all sessions and locate the w3wp process that hosts TFS.

    image

    Select Attach to start the debugging session. Set a break point in the ProcessEvent method and then modify a work item in TFS. This should cause your event handler to be executed immediately:

     

    image

0 thoughts on “Developing and debugging Server Side Event Handlers in TFS 2010”

  1. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#547417

    Hello Jacob:

    This is very helpful. I’m trying to implement a custom check-in event handler and trying to leverage your idea. Our check-in handler should extract some meta data from the checked-in file and push it to application database. I exactly followed your approach for CheckinEvent with no luck. For some reason, it does not break the debug point. However, when I ran your sample for “WorkItemChangedEvent” is works just fine. Am I missing something? Appreciate your feedback. Please see below the my code:

    using System;
    using System.Diagnostics;
    using Microsoft.TeamFoundation.Common;
    using Microsoft.TeamFoundation.Framework.Server;
    using Microsoft.TeamFoundation.VersionControl.Common;
    using Microsoft.TeamFoundation.WorkItemTracking.Server;

    namespace TFSServerEventHandler
    {
    public class CheckinEventHandler : ISubscriber
    {
    public Type[] SubscribedTypes()
    {
    return new Type[1] {typeof(CheckinEvent) };
    }

    public EventNotificationStatus ProcessEvent(TeamFoundationRequestContext requestContext, NotificationType notificationType, object notificationEventArgs,
    out int statusCode, out string statusMessage, out ExceptionPropertyCollection properties)
    {

    statusCode = 0;
    properties = null;
    statusMessage = String.Empty;
    try
    {
    {
    CheckinEvent ev = notificationEventArgs as CheckinEvent;
    EventLog.WriteEntry(“ChekinEventHandler”, “CheckinComment ” + ev.Comment );
    }

    }
    catch (Exception)
    {
    }
    return EventNotificationStatus.ActionPermitted;
    }

    public string Name
    {

    get { return “CheckinEventHandler”; }
    }

    public SubscriberPriority Priority
    {
    get { return SubscriberPriority.Normal; }
    }
    }
    }

    Reply

  4. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#562144

    I am trying to get this sample working but for some reason it doesn’t seem to fire this event at all. And I used exactly the same code as in the post? Any ideas what might be stopping it? Also trying to remotely debug and breakpoints don’t get hit?

    Note for Stephen: have you compiled your plug in in debug and copied the .pdb file over?

    Reply

  5. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#562146

    Me again: ignore the first part of my post from before – i ended up getting it working. I also got the Check in Event working if anyone is interested. Code below – One thing I had to do though to succesfully debug it was put System.Diagnostics.Debugger.Break(); in the code – without it it wouldn’t break ever?

    using System;
    using System.Diagnostics;
    using Microsoft.TeamFoundation.Common;
    using Microsoft.TeamFoundation.Framework.Server;
    using Microsoft.TeamFoundation.WorkItemTracking.Server;
    using Microsoft.TeamFoundation.VersionControl.Common;
    using Microsoft.TeamFoundation.VersionControl.Server;

    namespace TFSCheckInEventHandler
    {
    public class TFSCheckInEventHandler : ISubscriber
    {
    public Type[] SubscribedTypes()
    {
    return new Type[1] { typeof(CheckinNotification) };
    }

    public EventNotificationStatus ProcessEvent(TeamFoundationRequestContext requestContext, NotificationType notificationType, object notificationEventArgs,
    out int statusCode, out string statusMessage, out ExceptionPropertyCollection properties)
    {
    statusCode = 0;
    //System.Diagnostics.Debugger.Break();
    properties = null;
    statusMessage = String.Empty;
    try
    {
    if (notificationType == NotificationType.Notification && notificationEventArgs is CheckinNotification)
    {
    CheckinNotification ev = notificationEventArgs as CheckinNotification;
    }
    }
    catch (Exception)
    {
    }
    return EventNotificationStatus.ActionPermitted;
    }

    public string Name
    {
    get { return “TFSCheckInEventHandler”; }
    }

    public SubscriberPriority Priority
    {
    get { return SubscriberPriority.Normal; }
    }
    }
    }

    Reply

  11. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#605350

    I was able to successfully record all the CheckinNotification properties to a file when a checkin was performed on TFS via a custom plugin. (thanks)
    Currently I want to know the project name of the checkin. I currently preface the comment with the project name, but I am looking for an automatic way of retrieving this information.
    If anyone has any ideas please let me know.
    Have a great day!
    Bill

    Reply

  16. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#613474

    I followed the steps you listed but when I try to debug the code by attaching to the process, I get the following error eventhough the project is .NET 3.5.

    {“Microsoft SharePoint is not supported with version 4.0.30319.261 of the Microsoft .Net Runtime.”}

    I have tried creating new project from scratch to make sure it is .NET 3.5 based, but it gives same error.

    Any idea or suggestion?

    Reply

  24. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#624560

    where can I get those 2012 assemblies? We have a 2010 production server but we plan to migrate soon so I installed a tfs 2012 express on my dev machine. But your example doesn’t work against that version when compiled with 2010 assemblies. Unfortunately I cannot find the needed assemblies on my local server. Maybe because it’s an express version?

    Reply

  29. Originally posted on: http://geekswithblogs.net/jakob/archive/2010/10/27/devleoping-and-debugging-server-side-event-handlers-in-tfs-2010.aspx#634645

    it was a good article.
    I have sued this in my sample application and here is what I need.
    Ima ble to capture events, but only after saving the work item.
    So when I change a state from new to close and click save, the event is fired. But the work item is already saved, and history for the work item is logged. now the event handler changes the status from close to new, due to some business logic, and again the history is logged. I would like to eliminate two history events, which would confuse the developer.
    It typically means, I should not be capturing the workitem event, but event of the field. in my case status field on change. Let me know if any one has any insight in this direction. Any help is appreciated.

    Reply

Leave a Reply

Your email address will not be published.