Team System: check-in notes and policies

In the January 2007 issue of this column, I began to discuss the team Foundation Server (TFS) versioning API that was provided using the Microsoft®word 2003 add-in. More than a year later, I'm here to give you the fifth part, and also the last part of the special discussion about versioning APIs and Word add-ons (I didn't really think there would be so many parts).

You may recall that in a previous column we mentioned that the add-in currently supports Check-in, Check-out, undo pending changes, and the ability to associate work items with check-in. In my latest column, I have analyzed check-in notes and check-in policies in detail. This month, I'll show you how to add check-in notes and check-in policy support to the Word add-in. In addition, you will learn how to handle check-in conflicts. If you haven't read the rest of this series (listed in the sidebar, "the first four parts of this series"), make sure you read the contents first.

Check-in notes

A check-in note is a free-form text field that can be associated with a check-in. You can mark Check-in notes as mandatory and control the order in which they appear in the Visual studio® check-in dialog box. In order to simulate this behavior in a Word add-in, you must obtain a list of check-in notes for the active team project, sort the list, and display a label and text box for each check-in note.

The Versioncontrolserver object exposes the Getcheckinnotedefinitions method, which accepts an array of team project names and returns an array of Checkinnotefielddefinition objects. Each Checkinnotefielddefinition instance exposes the name of the check-in note, the display order, whether it is required, and the server item string property. Getcheckinnotedefinitions will return the list of items in an approximate random order. In the test, I found that regardless of the order in which the team project references were passed into the method, the description is sorted by the check-in note name and grouped by team project name. Therefore, suppose you define two team projects using the default description group, one called Msf-agile, and the other is Msf-cmmi, as shown in Figure 1. If you create a check-in note called build Master and add it to the Msf-cmmi team project, it will appear in the first position in the list.

Figure 1 The result of calling Getcheckinnotedefinitions

/tr>

	team project
code reviewer	msf-agile
code reviewer	msf-cmmi
performance reviewer	msf-agile
performance reviewer	msf-cmmi
security reviewer	msf-agile
security reviewer	msf-cmmi

The Tfsvcutil class created for Word add-ins provides two new shared methods that you can use to retrieve Check-in notes: Getallcheckinnotesbyteamprojectname and Getallcheckinnotesbyitemlocalpath. You can use either of these methods to obtain an unmodified list of team project Checkinnotefielddefinitions, if any.

Check-in notes that support check-in dialogs need to add a toggle button below the existing work item buttons, add a panel as a container, and add labels and text boxes to each check-in note. (Code downloads provide a simple implementation example.) However, adding check-in notes support for the Check-in dialog box only solves some of the challenges. You also need to enforce the required instructions by adding code. check-in policies and conflict detection require some changes in the way the Tfsvcutil class is checked in and the support code works.