Chapter 6

Common Team Foundation Server Customizations

What's In This Chapter?

• Examining the Team Foundation Server Object Model
• Customizing Team Foundation Build
• Customizing Team Foundation Version Control
• Customizing Work Item Tracking
• Customizing the TFS Eventing Model

One of Microsoft's goals when Team Foundation Server (TFS) 2005 was first released was to make the platform extensible. Although Microsoft's intention was to provide a set of tools and guidance for conducting application lifecycle management using TFS, the company also knew that people and organizations already have their own methodologies. And although people may want to use TFS for their tooling, they still want to follow their own software development process.

So Microsoft provided several extensibility points within TFS to extend different aspects of the system as needed. It also provided an API that developers can use for creating custom applications to access and utilize different systems in TFS, such as work item tracking and version control.

As you've seen in previous chapters, TFS itself is made up of a variety of web services, so you might think that you could just write custom applications to utilize those web services. And you could, but that would not be considered best practice. Instead, you should make use of the APIs (which interact with the web services). This ensures that any customizations or extensions you create should be forward compatible with future versions of TFS.

This chapter is about some of the common ways you can customize Team Foundation Server. It's designed to be a high-level overview—to whet your appetite for the types of things you can do. As such, there are not many step-by-step examples of the customizations.

Object Models

To start off this talk on customization and extensibility, let's look at the available object models in Team Foundation Server. Although TFS is composed of several different web services, in general, you do not want to interact with the web services directly when building customizations to TFS. Instead, you want to use the different object models (that is, APIs) that are available to you to provide a level of abstraction between yourself and the TFS Web Services, as shown in Figure 6.1.

This ensures that as the web services in future versions of TFS are updated, any code you've written should continue to function as expected.

There are three main object models: client, server, and build process.

Client Object Model

You use the client object model for developing custom applications or extensions that will mostly run from a client-side perspective—for example, creating a custom work item control for the work item tracking system, or creating a custom application for accessing the version control system.

Some of the things you can do with the client object model include accessing Team Foundation Server and viewing team project and project collection information. You can also access all the different TFS subsystems, such as work item tracking, version control, and build. You can also use this object model to extend team projects, adding new functionality and extending Team Explorer.

Server Object Model

You use the server object model to develop applications that must run on the application tier. Typically this is used to integrate other tools or data from other applications with Team Foundation Server.

For example, you can use the server object model to create a custom data warehouse adapter, to store custom data in the TFS data warehouse. Or you can use the server object model to customize the eventing service in Team Foundation Server (more on this in the section “Team Foundation Server Event Service” later in this chapter).

Build Process Object Model

You use the build process object model to customize the Team Foundation build process. In most cases you use this object model to help build custom build workflow activities. You learn more about build customization later in this chapter.

Simple Object Model Example

This section demonstrates a simple example of connecting to Team Foundation Server and listing the project collection information it contains. This example shows you the basics of using the client object model, and you can use it as a basis for future customizations.

In Visual Studio, create a new C# console application, and name it Chapter6Example. First, you need to add a reference to the Microsoft.TeamFoundation.Common and Microsoft.TeamFoundation.Client assemblies. In Solution Explorer, right-click on the References folder and select Add Reference. Click the Browse button, and navigate to %ProgramFiles%Microsoft Visual Studio 11.0Common7IDEReferenceAssembliesv2.0. Select the two assemblies listed above and click Add. Click OK to close the Reference Assembly window.

Add the following using statements to Program.cs:

using System.Collections.ObjectModel;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.Framework.Common;
using Microsoft.TeamFoundation.Framework.Client;

Next, add the following code snippet into the Main method:

// Connect to Team Foundation Server
Uri tfsUri = new Uri("http://VSALM:8080/tfs");
TfsConfigurationServer tfsServer =
                TfsConfigurationServerFactory.GetConfigurationServer(tfsUri);
// Get team project collections
ReadOnlyCollection<CatalogNode> tpCollections = tfsServer.CatalogNode.QueryChildren(
                new[] { CatalogResourceTypes.ProjectCollection },
                false, CatalogQueryOptions.None);
// write out the team project collections
foreach (CatalogNode node in tpCollections)
{
      Guid nodeId = new Guid(node.Resource.Properties["InstanceId"]);
      TfsTeamProjectCollection tpCollection =
       tfsServer.GetTeamProjectCollection(nodeId);
Console.WriteLine("");
Console.Writeline("TFS: " + tfsURI);
Console.Writeline("");
Console.WriteLine("Collection: " + tpCollection.Name);
}

Build and run this console application and you should see output similar to Figure 6.2. You will be able to build off the preceding code to create your own extensions and customizations.

Java SDK for TFS

From its beginnings with Team Foundation Server 2005, TFS was designed with extensibility in mind. As such, Microsoft provided a .NET library (please see the previous section for more details) for interacting with and extending TFS.

Microsoft has extended this into the Java space, with the addition of the Team Foundation Server SDK for Java. This SDK enables you to extend TFS using Java just as easily as you can using .NET. One of the nice features of this is that it enables users of Team Explorer Everywhere to fully customize their development environments, either in or out of Eclipse. This enables you to create the same TFS extensions for both the .NET and Java developers in your organization.

The TFS Java SDK includes the following information:

• A redistributable JAR file containing the TFS APIs and the native code libraries used by the TFS API.
• Full API documentation in Javadoc format
• Code samples

From a licensing perspective, you can use the SDK in your own applications, redistributing the files at no charge. And you can create applications that run on any of the operating systems supported by the API.

Customizing Team Foundation Build

In Chapter 5 you learned about Team Foundation Build, the build process, and build process templates. The “out of the box” options for Team Foundation Build probably work for most people, at least initially. At some point though, you are going to want to modify the build process. This section discusses a couple of common ways for customizing Team Foundation Build.

Creating Custom Build Process Templates

In Chapter 5 you learned about the DefaultTemplate build process template, and how its preconfigured properties enable you to perform common build scenarios. However, to perform more complex build activities, such as being able to parallelize parts of the build across multiple build agents, or create MSI installers, you are going to have to customize the build process. To do this, you need to create a custom build process template.

To create a new build process template, start by editing the build definition. In the Process section of the dialog, click the New button near the top of the screen. This opens the New Build Process Template dialog, shown in Figure 6.3.

In the dialog, select Copy an Existing XAML File and point it to DefaultTemplate.xaml. Select the folder in which to create the new process template and enter the new filename—in this case, let's use NewBuildProcessTemplate.xaml.

This creates the file in version control. You can now start using this template when creating build definitions. You can also double-click the file from within Source Control Explorer to open it for editing (see Figure 6.4).

Team Foundation Server ships with a set of additional workflow activities related to the build process in the assembly Microsoft.TeamFoundation.Build.Workflow. This includes all the build-related activities called by the build process templates that ship with the product, along with several other activities that are useful when performing common build customizations.

If you look in Figure 6.4, you can see that a WriteBuildMessage activity has been added to the top of the build. You can see the properties for this activity in the properties window at the bottom right. The Display Name has been set to Log Welcome Message, and a message has been included to write to the build log.

Creating Custom Build Workflow Activities

As you saw in the previous section, it is possible to edit the build process template to build increased functionality. Sometimes, however, you may want to collect common workflow activities in a custom, re-usable Workflow Activity Library. Also, sometimes you might not want to simply build activities out of other activities, but also execute your own .NET code.

Team Foundation Build allows for this, enabling you to create your own Windows Workflow activity libraries in .NET 4.0, build them as a compiled assembly containing your activities, and then use them in your build process. The Team Build workflow activities are provided in this way.

There are four main ways to author a new activity:

• Write a new CodeActivity
• Write a new NativeActivity
• Compose your custom activity in XAML
• Compose your custom activity in code

The first two ways involve creating code using the Windows Workflow libraries. Although not incredibly complicated, it does require some exposure and knowledge of Windows Workflow programming.

The last two ways involve creating a new activity from existing activities. This is the best approach to take, when possible, for a few reasons. It re-uses well-tested code. The activities created are automatically cancelable by the workflow runtime, meaning that a build created with your activity can be stopped cleanly. They can be easily tracked as they execute. And finally, the process is comparably easy.

Customizing Team Foundation Version Control

Team Foundation Version Control is very powerful tool that works very well out of the box. It integrates well with Visual Studio and provides some enterprise-level features, such as branching and merging, and shelvesets. In addition to accessing Team Foundation Version Control from within Visual Studio, you can also access it from the command line, using the tf.exe tool.

One of the more common ways for customizing version control includes building custom check-in policies. You can also use the client object model to create your own custom applications for accessing the version control system.

Custom Check-in Policies

As you learned in Chapter 3, check-in policies provide a way for the team and individuals to effectively manage quality and workflow to the source management process used by the team. Check-in policies run on the actual client, and are configured at the team project level in Team Foundation Server.

You get several check-in policies out of the box with Team Foundation Server, and more can be added by installing the Team Foundation Power Tools. You also have the capability to create your own custom policy, using the client object model.

First, you have to build a custom policy class that derives from the PolicyBase base class in the Microsoft.TeamFoundation.VersionControl.Client namespace. When the policy is created, it needs to be installed on any machine that will be checking in code that will be affected by the check-in policy. Remember, check-in policies execute on the client side; as such, they must be present on the machine trying to execute the policy, or code cannot be checked in without overriding the policy.

Finally, after the policy has been deployed, it needs to be added to the team project. This ensures that the policy is evaluated each time a developer checks in a file to this team project.

Team Foundation Server Event Service

The EventService service in Team Foundation Server exposes a set of events that, when fired by TFS, can trigger other actions, such as sending an e-mail, or making a web service call to another application. The following events are registered by default for publishing within the service:

• Build Completion Event
• Build Status Changed Event
• BranchMovedEvent
• NodeCreatedEvent
• NodePropertiesChangedEvent
• NodeRenamedEvent
• NodesDeletedEvent
• ProjectCreatedEvent
• ProjectDeletedEvent
• CheckinEvent
• WorkItemChanged

You can make use of the BisSubscribe.exe, a TFS command-line tool, to subscribe to the events in the preceding list. When you subscribe to an event, you can either trigger a web service or send an e-mail. This enables you to receive notifications when certain events occur, or trigger other functionality to execute based off the event. The BisSubscribe.exe tool has filtering options available, which enables you to control exactly what types of events trigger what functionality.

You can also make use of the EventService service to create your own custom events that can be subscribed to. To do this, you need to create a class library that contains a class that represents the new event. After this class library has been built, you need to create an .xsd file that represents the event class. This is an XML schema file representing the event class that can be generated from the class library. This .xsd file will be placed on TFS, which then enables users to subscribe to the new event.

Customizing Work Item Tracking

You find out about the work item tracking system in Chapter 10. This system is used to help plan and track your software development projects. Out of all the areas in TFS, it is probably the one that is the most heavily customized; it helps to control the process and workflows you will use to develop your applications. You can do things such as make fields required or read-only, or change the workflow from moving from one state to the next.

The two main ways for customizing the work item tracking system are modifying the work item type definitions to follow your custom process, and creating custom work item controls for use on the work item form.

Modifying Work Item Type Definitions

A work item type definition is simply an XML file. This XML file is stored in Team Foundation Server as part of a process template, and defines the fields, workflows, and form layout for a particular type of work item, such as a Task or a Bug. There will be times when you want to customize a work item type, such as the Task work item, to contain custom fields, or to follow a workflow other than the default workflow.

There are two main tools you can use for modifying work item type definitions: the witadmin command-line tool and the Team Foundation Power Tools Process Template Editor.

You can use the witadmin command-line tool to export a work item type definition from Team Foundation Server into an XML text file. You can then open this XML file using your favorite XML/text editor of choice and make your customizations. Keep in mind this is an XML file, so if you mistype something or violate the XML schema, the changes will not load back into TFS. After you have finished your changes, you can use the witadmin tool to load the new work item type back into TFS, where it takes effect.

For those who want a more graphical interface for working with work item type definitions, you can use the Process Template Editor that is available with the Team Foundation Power Tools. The Process Template editor provides a complete GUI for working with all aspects of a process template, including work item type definitions.

Creating Custom Work Item Controls

You can also extend the work item tracking system to allow for custom user controls. These controls enable you to enhance the user interface and extend the workflow capabilities. You can bind custom controls to fields within a work item type, which enables users to view and edit data as needed. The controls can also read and write from external data sources, enabling you to query databases or web services for data to pull back and provide in the form.

Some examples of custom controls include a timesheet control for tracking time on a work item, or a web browser control for hosting a web page or passing values to that web page.

Custom controls act like any other control on a work item form. You can place them on the form, using the default design layout constraints, and you can use their values as part of a state change workflow.

There are some restrictions to be aware of when dealing with custom controls:

• Multiple value fields are not directly supported.
• You can't extend existing work item controls.
• The binaries for each custom control must be installed on the client computer.
• Custom controls not configured correctly or not installed must not cause the client to crash when accessing a work item type that uses that control.

One of the most important things to remember is that the custom controls must be deployed to individual client machines. Remember, the work item type definition is stored in Team Foundation Server. However, when you open a work item type that contains a custom user control, it tries to access the control assembly information on the local client machine. As such, the assembly that defines the custom user control must exist on the client machine.

For detailed information on building custom work item tracking controls, see the post “Work Item Tracking Custom Controls” by Gregg Boer at http://aka.ms/WITCustomControls.

Summary

In this chapter, you gained a high-level understanding of the different ways that Team Foundation Server can be extended and customized.

You learned about the different object models available within Team Foundation Server, and when to use them. You also saw a step-by-step example of using the client object model to connect to Team Foundation Server and list the project collections contained within.

You learned how to customize Team Foundation build, including the creation of custom build process templates, and custom build workflow activities. And you learned how to customize the version control process using custom check-in policies.

Finally, you saw how the eventing service in TFS works, and how you can customize it, as well as how you can modify the work item tracking system by using custom work item type definitions and custom work item controls.

In Chapter 7, you learn about the importance of engaging early and frequently with your software development project's stakeholders. You also learn about the tools that Microsoft and its partners have built to facilitate requirements management and collaboration among project stakeholders.