Monday, August 25, 2008

Custom TFS Task to Change WorkItem State

I recently had to create a custom task to update the state all work items associated with a changeset were in. Here is the code I came up with to accomplish this.

First we start of by creating a general class that includes a few properties. The properties will allow us to pass in variables to the task. LocalPath and BuildURI are variables which TFS build provides for you. I also included the using statements you need to have for this task.

   1: using Microsoft.Build.Utilities;
   2: using Microsoft.TeamFoundation.Client;
   3: using Microsoft.TeamFoundation.VersionControl.Client;
   4: using Microsoft.TeamFoundation.WorkItemTracking.Client;
   5: using Microsoft.TeamFoundation.Build.Client;
   8: namespace MyCustomStuff.TFS.Tasks
   9: {
  10:     public class UpdateWorkItemStatus : Task
  11:     {
  12:         // A value for each one of these properties must be supplied in the XML build file. 
  13:         // LocalPath and BUILDURI can use the MSBuild variables of $(TeamFoundationServerURL) and $(BuildURI)
  14:         [Required]
  15:         public string LocalPath { get; set; }
  16:         [Required]
  17:         public string BuildURI { get; set; }
  18:         [Required]
  19:         public string NewStatus { get; set; }
  21:         // This is the status the work item must be in for the status to be updated. This prevents us from updating all 
  22:         // workitems that where checked in associated to a buid.
  23:         public string ConditionalStatus { get; set; }
  25:         public override bool Execute()
  26:         {
  28:         }
  29:     }
  30: }

Now we are set up and ready to build out the task. What I wanted to do was connected to TFS and get a list of all the workitems associated with the build that was just run (this is why you have to pass in the Build URI). If you insert the follow code in the line 27 from above you get a working custom task.

   1: try
   2: {
   3:     // Get the TFS server
   4:     TeamFoundationServer server = TeamFoundationServerFactory.GetServer(LocalPath);
   7:     // Get the WorkItem store
   8:     WorkItemStore wiStore = (WorkItemStore)server.GetService(typeof(WorkItemStore));
   9:     //BuildStore buildServer = (IBuildServer)server.GetService(typeof(IBuildServer));
  10:     IBuildServer buildServer = (IBuildServer)server.GetService(typeof(IBuildServer));
  11:     IBuildDetail build = buildServer.GetAllBuildDetails(new Uri(BuildURI, UriKind.Absolute));
  13:     List<IWorkItemSummary> assocWorkItems = InformationNodeConverters.GetAssociatedWorkItems(build);
  14:     EventLog.WriteEntry("UpdateWorkItemStatus", string.Format(string.Format("Found {0} workitems for Build {1} : BuildURI = {2} LocalPath = {3}",assocWorkItems.Count, build.BuildNumber, BuildURI,LocalPath), EventLogEntryType.Information));
  16:     // Loop through each work item and update the status
  17:     foreach (IWorkItemSummary wItem in assocWorkItems)
  18:     {
  19:         WorkItem wi = wiStore.GetWorkItem(wItem.WorkItemId);
  20:         // Only update the work Item if no conditional status was provided or if the conditional status matches
  21:         if (ConditionalStatus == string.Empty || wi.State.ToLower().Trim() == ConditionalStatus.ToLower().Trim())
  22:         {
  23:             EventLog.WriteEntry("UpdateWorkItemStatus", string.Format("WorkItem {0} was updated from {1} to {2}", wItem.Id, wItem.Status, NewStatus), EventLogEntryType.Information);
  24:             // Update the state and add a note in the history stating the build process made this change.
  25:             wi.History.Insert(0, string.Format("Build process changed state from {0} to {1}", ConditionalStatus, NewStatus));
  26:             wi.State = NewStatus;
  27:             wi.Save();
  28:         }
  29:     }
  31:     return true;
  32: }
  33: catch (Exception ex)
  34: {
  35:     EventLog.WriteEntry("UpdateWorkItemStatus", ex.Message, EventLogEntryType.Error);
  36:     return false;
  37: }

For this task I get the list of all workitems associated with the changeset and loop through that list. As I loop through I get the details for each workitem and than perform a check to see rather or not I should update the workitem. If the workitem's state matches the conditional state parameter that was passed in, than I update the workitem to the new state which was also passed in to my task. That is all there is to it. Now lets take a look at how you call it via your TFS build script.

Once you build the above code and deploy it to your build server you can call that task from any TFS build which uses that build server. To call the task you have to make a couple additions to the XML in your TFS build. First you need to add a node that says you are using a new task:

   1: <!-- This is the custom task that will update all associated work items to a new status -->
   2: <UsingTask TaskName="UpdateWorkItemStatus" AssemblyFile="$(MSBuildExtensionsPath)\MyCustomTFSTask.dll"/>

This allows the rest of your build process to now call a custom task of "UpdateWorkItemStatus." The $(MSBuildExtensionsPath) is a global parameter in TFS build and is for the MSBuild folder under the Program Files directory. This location is a useful place to put custom target files (For example, your targets files could be installed at \Program Files\MSBuild\). Now all you need to do is call the task after the build is done. To do this you would think you could use the "AfterBuild" target but you cannot (at least I have never gotten it to work). You actually need to use the "TeamBuild" target. This target is fired off after the build has completed and can be called with the follow XML.

   1: <Target Name="TeamBuild" Condition=" '$(IsDesktopBuild)'!='true' "
   2:           DependsOnTargets="$(TeamBuildDependsOn)">
   3:     <Message Text="TeamBuild is firing!"/>
   4:     <!-- Now update all associated work items to the right status -->
   5:     <UpdateWorkItemStatus NewStatus="Sys Test" LocalPath="$(TeamFoundationServerUrl)" BuildURI="$(BuildUri)" ConditionalStatus="Dev Complete" />
   7:  </Target>
This is where you declare the value of all your parameters. Now each time at team build fires off any associated workitem that is a match will be updated.