What you need to know to use the Process Template API

Developing an application using the Team Foundation Server Process Template feature is not an easy task, mainly because of the lack of documentation and sample around it.

As I had to deal with it when writing the WITSynchronizer I guess I can share some experience out there.

Using the IProcessTemplates interface

Let’s start by the beginning, you have your Team Foundation Server object and want to get the IProcessTemplates interface.
The GetService() method can do that for you:

// Get the Process Template interface
IProcessTemplates ptp = (IProcessTemplates)tfs.GetService(typeof(IProcessTemplates));

The MSDN documentation about this interface is pretty much the list of its members, so let’s describe a bit more what you can do with them.

int AddTemplate(string name, string description, string metadata, string state)

This method is used to add a new Process Template in your TFS, it’s only the declaration of the new Process Template, the content will have to be upload with another method.

  • name: the name of your Process Template (the one you see in the combo box when creating a new Team Project)
  • description: the description of your Process Template (the one you see in the description field when creating a new Team Project)
  • metadata: the “OuterXML” of the metadata XML element in the ProcessTemplate.xml file of your Template. You can’t pull this off manually, you have to take what’s come out of the Process Template editor.
  • state: I don’t know all the possible values, but the “visible” one is the one you want to get your Template correctly.

void AddUpdateTemplate(string name, string description, string metadata, string state, string zipFileName)

This method is used apparently to add a new Process Template (and uploading its content) or updating an existing one.

The first four parameters are the same as the AddTemplate() method.

  • zipFileName: the full path and filename of the zipped version of you Process Template folder. Beware that you can’t zip this file with WinZip or any kind of Zip Library. The only one I could use successfully is the ICSharpCode.SharpZipLib with the FastZip class.

TemplateHeader[] DeleteTemplate( int templateId)

Delete a template from its ID, you can get the ID calling the TemplateHeaders() method and using the TemplateId field, or by calling GetTemplateIndex().

string GetTemplateData(int methodologyIndex)

This method will download the Template Data as a temporary zipped file and returns you the full path and file name.

So you better have to delete the file once you’re done with it!

Basically, unzip the file and you get all the content of your Process Template.

  • methodologyIndex: the index can be retrieved calling the GetTemplateIndex() method or using the TemplateHeader structure.

int GetTemplateIndex(string name)

Get the ID of a Template from its name. I guess this method is named incorrectly because what you have in return is the Template’s Id.

XmlNode GetTemplateNames()

This method returns an XML Node listing all the Process Templates and their corresponding Id.

TemplateHeader[] MakeDefaultTemplate(int templateId)

Make the Template of the given ID the default one.

TemplateHeader[] TemplateHeaders()

Return an array describing all the Process Template. You will find in this structure all the general information (Name, Description, State, Rank, Metadata, ID)

void UploadMethodology(string filename, int templateId)

Upload a new version of the methodology in an existing Process Template.

  • Filename: the full path and file name of the Zipped file containing the content of the Process Template to upload.
  • templateId: the ID of the template to update.

My ProcessTemplate class

If you want to do some basic operations with Process Template, you can use the little class I wrote for the WITSynchronizer. It’s far from being complete and perfect, but it is easy to use…

You can download the class here.

Construction

You can create a ProcessTemplate instance with three possible ways:

  1. By giving the directory where the Process Template is stored.
  2. By giving the zipped file you got by calling GetTemplateData().
  3. By giving a TeamFoundationServer object and the name of the Process Template.

The class will handle the cleanup of the resource it created (nothing for the first constructor, the directory for the second constructor, the zip file and the directory for the third).

Features

  • Get/Set the name and description of the Process Template.
  • List all the Work Item Type definitions.
  • List all the Work Item Query definitions.
  • Get the XML document of a given Work Item Type definition.
  • Get the XML document of a given Work Item Query definition.
  • Add/update a Work Item Type definition.
  • Add/update a Work Item Query definition.
  • Upload the Process Template back to the Team Foundation Server.

Leave a Reply