Thursday, August 03, 2006

Work Item Migration via the WIT Web Service (Part 3/3)

Uploading through the Web Service requires sending an xml package through the Client Service that contains all the work item information. The xml package mentioned last post in insertWorkItem has the following format:

<Package Product=http://your_server:8080/WorkItemTracking/v1.0/ClientService.asmx DisableNotifications=”True” xmlns=””>
  <InsertWorkItem ObjectType=”WorkItem” BypassRules=”True”>
    <ComputedColumns>
      <ComputedColumn Column=”System.RevisedDate”>
    </ComputedColumns>
    <Columns>
      <Column Column=”System.WorkItemType”>
        <Value>Bug</Value>
      </Column>
      <Column Column=”System.AreaId”>
        <Value>40</Value>
      </Column>
      <Column Column=”System.CreatedBy” Type=”String"/>
    </Columns>
    <InsertText FieldName=”Microsoft.VSTS.CMMI.Analysis” FieldDisplayName=”Analysis”>text goes here </InsertText>
  </InsertWorkItem>
<
/Package>

Column values for System.WorkItemType and System.AreaId are absolutely required for web service update. These relate the work item to the database. Team Project is specified through the System.Area field, and not through the System.TeamProject field (not required). All other Column entries require a Type to accompany the field name.

Fields of type HTML or PlainText must be entered into parameters instead of through . Fields of type String have a character limit of 255.

The most valuable (from a migration-perspective) part of this xml package, and really the only reason to use the Web Service method instead of the OM to upload, is the BypassRules attribute. Setting this attribute value to True allows the State/Reason/Transition rules to be bypassed, as well as allowing values such as Created By/Date, Resolved By/Date, Closed By/Date to be programmatically set.

Note: Microsoft could release a new version of their WIT Web Service at any point in time and change the format of the Package document. This (and previous) posts are to provide an outline of the methodology for web service uploading of work items.

Monday, July 17, 2006

Work Item Migration via the WIT Web Service (Part 2/3)

The following is a wee snippet of the code that sends the work item information to the server:

/* first, create the ClientService object.
Path must be explicitly specified because another ClientService exists in the Microsoft.TeamFoundation.WorkItemTracking.Server namespace (and you don't want that one). */

Microsoft.TeamFoundation.WorkItemTracking.Proxy.ClientService clientService = new Microsoft.TeamFoundation.WorkItemTracking.Proxy.ClientService();

clientService.Url = http://your_server:8080/WorkItemTracking/v1.0/ClientService.asmx;

try
{
// send the package to the server for processing.
clientService.Update(Microsoft.TeamFoundation.WorkItemTracking.Proxy.ClientService.NewRequestId(), insertWorkItem.DocumentElement, outputXmlElement, metadataTHE, databaseStamp, metadataRowSets);
}
catch
{
/* Update will fail if the xml is formatted incorrectly, or if filling any of the fields on the server fails. If the Update fails, the WI will not have been saved on the server side, no data is entered. */
}

Note: This method will allow you to upload work items that are not entirely correct; for example, you may upload a work item of state “Closed” but not have uploaded a “Closed By” and “Closed Date” value. The VSTS UI will inform you of this when you view the WI through Team Explorer.

insertWorkItem is an XmlDocument formatted as described in Part 3. This xml package contains the "guts" of the work item.

metadataTHE is an array of type MetadataTableHaveEntry, which can be found in the Microsoft.TeamFoundation.WorkItemTracking.Proxy namespace. This array must be populated with the TableName and RowVersion information returned from a call to Enum.GetNames(typeof(Microsoft.TeamFoundation.WorkItemTracking.Server.MetadataTable))

outputXmlElement is an XmlElement, databaseStamp is a string, and metadataRowSets is an interface IMetadataRowSets found in the Microsoft.TeamFoundation.WorkItemTracking.Proxy namespace. These parameters should hold no value, as they are returned by the Update function call.

.oO(in the next part, more detailed information on the required XML package insertWorkItem...)

Wednesday, July 05, 2006

Work Item Migration via the WIT Web Service (Part 1/3)

The Work Item Object Model provides an excellent interface to programmatically create new work items. However, from a migration perspective, it fails miserably; primarily due to the “rules” that make VSTS work items so great. For example, you cannot use the OM to set values such as Created By and Created Date; they are automatically set to the current user and current DateTime. Nor can you set the State or Reason to anything other than the default initial value of “New” or “Proposed”, without repeatedly saving the work item and transitioning through the states according to your WI transition rules.

Obviously, if you are a developer trying to migrate work items from a legacy application to VSTS, this will not suit your needs, since your work items will have been created by a multitude of people, all in the past, and many of these work items are in a “closed” state. Luckily, there is a second method by which work items can be uploaded: the Work Item Tracking Web Service. Through the web service, there is a means to turn-off the rules that prohibit setting the following values at will: State, Reason, Created By/Date, Resolved By/Date, Closed By/Date.

Several class libraries are required that are not included with the developer install of VSTS, but are installed on the TFS machine, or through the SDK. Reference to these libraries is required. Their names and locations (on the TFS) are listed below:

C:\Program Files\Microsoft Visual Studio 2005 Team Foundation Server\Web Services\WorkItemTracking\bin
Microsoft.TeamFoundation.WorkItemTracking.Server.dll
Microsoft.TeamFoundation.WorkItemTracking.Server.Dataaccesslayer.dll
Microsoft.TeamFoundation.WorkItemTracking.Server.DataServices.dll

(from the VSTS SDKs)
C:\Program Files\Visual Studio 2005 SDK\\VisualStudioTeamSystemIntegration\Work Item Tracking
Microsoft.TeamFoundation.WorkItemTracking.Proxy.dll

Note: Uploading through the web service is dangerous, not very well documented, and not recommended. It should only be used in extreme/migration cases where the WI rules absolutely must be bypassed. Access to the webservice upload methods is only available to TFS users in the Service Account (ie: TFSSERVICE).

For a preliminary look at some of the functions available through the web service, you can visit:
http://your_vsts_server_name:8080/WorkItemTracking/v1.0/ClientService.asmx


.oO(in the next part, some code snippets...)

Thursday, June 15, 2006

Stuff in the pipe for Team Foundation Server

Brian Harry has a post highlighting what's in the upcoming SP1 for TFS in Stuff in the pipe for Team Foundation Server. My favourite enhancement is excerpted below:

"WIT Custom Control support - This is a cool new feature. It is a mechanism by which people can design work item forms that host custom controls. The data behind the controls can either be persisted in WIT fields or elsewhere. I'm hoping people go crazy with it and build some awesome custom controls."

This was one feature I really, really missed in the RTM version.

Tuesday, June 13, 2006

Taken for a ride.


Which two well-known Canadian Visual Studio public speakers were taken for a ride last week?

Hint: You can see them at Tech Ed this week, one of them at a book signing.



Friday, May 26, 2006

"Pending" Investigation

Ah, my first post. I am the infamous Marshall B., as mentioned in the welcome post. Despite the initial, my last name isn't actually ByRefObject (hmm... should I put in for a name change?). I'll do my best to share my wisdom with you, and by "wisdom" I mean the rough equivalent of doing a face plant after tripping over your coffee table, only to miraculously spot the ball of silly putty under the couch that you thought you'd never, ever see again.

I've been working on a PVCS to Team System Source Control utility, and I ran into a curious issue after stopping a migration part way through. When I went to run the next migration test, it almost immediatly produced an error, saying that it could not find one of the files to check-in. But when I stepped through the code to investigate the problem, I found I wasn't even asking it to add that file!

So what was the problem? Even though the Source Control page within the Visual Studio IDE showed no pending changes, a pending addition from the terminated migration I had done earlier was still hanging around, even though Visual Studio wasn't showing it. After clearing out the left-over pending change in my code, all was good.

So the moral of the story is just because you can't see it in Visual Studio doesn't mean it ain't there. That, and silly putty is always in the last place you look.

Thursday, May 25, 2006

TFS Licensing

When you buy an MSDN Premium (or formerly Universal) subscription, you get development licenses for a wide range of MS servers. These server licenses are only good for development and testing purposes, not for production use. The idea is that if you are developing a solution using these servers, you don't need to run out and purchase a full blown license for the server. This is a great idea to help keep costs down and promote MS Server based solutions.

The exception to the above is the Team Foundation Server. With the Premium subscription, you get a license to use a limited 5 user version of the server (Note: the limitation is on the number of users, not the functionality of the server) for what I would argue is production use. In other words, you can use the Version Control, Work Items and other features as if you bought the full server (as long as you stay within the 5 user limit). This is significantly different than the licensing for all of the other servers included with the Premium subscription.

So, what do you do if you want a server to develop and test the customisations that you are doing to your full-blown production TFS server? Well, if you have more than 5 developers or you want to test a solution with more than 5 users (including performing load testing), you need to buy a copy of the retail TFS server! That's right, no special development server license is available, you need to either use the 5 user edition or buy a full server license. Granted, the server isn't that expensive and you should already have the client licenses (Team Foundation Explorer), but it really would be nice to have a development licensed server.

Microsoft, are you listening?