Team Foundation Version Control Extensibility

Extensibility has been a constant theme throughout this book concerning Team Foundation Server, and Team Foundation Version Control is no exception. TFVC gives you the ability to build your own custom check-in policies, allowing you to implement your specific organization rules concerning how items are checked into the repository. As well, TFVC makes use of the Team Foundation Server Object Model. While you won't learn much about that in this chapter, you make use of it in future chapters where continuous integration and Team Build are discussed. Finally, Microsoft has provided a MSSCCI Provider for Team Foundation Version Control, allowing you to access TFVC from older development environments, such as Visual Studio 2003. This allows you to take advantage of the version control system in Team Foundation Server, without having to immediately port all your development over to Visual Studio 2005.

Custom Check-In Policies

One of the nice things about check-in policies is that you can create your own for almost any situation for which you want to write some code. Basically, a custom check-in policy is just a managed .NET assembly containing one or more classes. These classes are added to the Windows Registry, allowing Team Foundation Server Version Control to find and manage the check-in policies. The Visual Studio SDK has some detailed documentation concerning creating a custom check-in policy.

Included with the code for this chapter is a Policies.zip file. This file contains a custom check-in policy project called PendingCheckinComments. The purpose of this policy is to force the user to enter comments in the Pending Checkins window, before allowing the modified code to be checked in. Unzip this code to the C:\Policies directory; then open the PendingCheckinComments solution file in VS 2005 to view the code. This project is just a C# Class Library project.

There is only one class in this project, called Comment.cs. This class implements your custom check-in policy. You should be able to take this class file, and use it as a template for creating your own custom policies. While we won't go into detail about every aspect of this file, we need to point out a couple of things to you concerning this custom policy.

You need to add the following using statements to any custom policy you make:

 using System.Windows.Forms; using Microsoft.TeamFoundation.VersionControl.Client; using System.Collections; using System.IO; 

You will have to add a reference to System.Windows.Form. As well, you will need to add a reference to C:\Program Files\Microsoft Visual Studio 8\Common7\IDE\PrivateAssemblies\Microsoft.TeamFoundationVersionControl.Client.dll.

A custom policy is persisted as a serialized .NET object. As such, it needs to be marked with the [Serializable] attribute. The class also needs to inherit from PolicyBase, which defines the basic policy interface.

 [Serializable] public class Comments : PolicyBase { ... } 

Important

Some of methods for PolicyBase are abstract and therefore you have to define them. One easy way to create these is to right-click PolicyBase and select Implement Abstract Class.

Notice the list of strings at the top of the class:

 static string pType = "Pending Checkin Comments Policy"; static string pDescription = "This policy ensures that the pending comments field has comments."; static string pInstallationInstructions = "None available at this time."; static string pTypeDescription = pType + " Description"; static string pDisposedMessage = pType + " Object has been disposed."; static string pHelp = "No help available at this time"; static string pMessage = "Pending Checkin comments are empty."; 

These strings contain the different messages and text strings that a custom policy might need. Listing them all in one place makes it easy to find and modify them.

All the methods listed in Comments.cs need to be implemented as listed. Most of the methods listed in Comments.cs will be the same regardless of your custom policy. The main method, which does your work for you, is the PolicyFailure method:

 public override PolicyFailure[] Evaluate() { //If this object has been disposed of, throw an exception if (this.Disposed) { throw new ObjectDisposedException(pType, pDisposedMessage); } //Create an array list of policy failures ArrayList policyFailures = new ArrayList(); //If the Pending Changes Comment field is empty if (this.PendingCheckin.PendingChanges.Comment.Length == 0) { //Create a new policy failure object and add it to the collection PolicyFailure failure = new PolicyFailure(pMessage, this); policyFailures.Add(failure); } //Return the policy failures collection return (PolicyFailure[])policyFailures.ToArray(typeof(PolicyFailure)); } 

This is the method you will be modifying to implement your custom logic for your check-in policy. For the example code, the first thing you do is check to see if the custom check-in object has been disposed of. If it has, then you throw an exception:

 //If this object has been disposed of, throw an exception if (this.Disposed) { throw new ObjectDisposedException(pType, pDisposedMessage); } 

Next, you create an array list to hold any policy failures that may occur:

 //Create an array list of policy failures ArrayList policyFailures = new ArrayList(); 

Then you check to see if the Pending Changes comment field is empty. If it is, you create a new policy failure object, and add it to the array list:

 //If the Pending Changes Comment field is empty if (this.PendingCheckin.PendingChanges.Comment.Length == 0) { //Create a new policy failure object and add it to the collection PolicyFailure failure = new PolicyFailure(pMessage, this); policyFailures.Add(failure); } 

Finally, you return the array list of policy failures. If the array list has at least one member, the policy will be violated, and you will be warned:

 //Return the policy failures collection return (PolicyFailure[])policyFailures.ToArray(typeof(PolicyFailure)); 

All the other methods in this class can pretty much be cut and pasted from policy to policy, as they should rarely change, if ever.

Be aware that the Edit method must return a true value:

 public override bool Edit(IPolicyEditArgs policyEditArgs) { //This function must return true, due to a bug in V1 return true; } 

Due to a bug in version 1 of Team Foundation Server, if you do not have this method return a true value, then you will not be able to add your custom check-in policy to your source control settings in Team Explorer.

Once you have created your policy (or in this case, unzipped it) and compiled it, you have to add a registry key for your policy, so Visual Studio Team System will see it and use it. To do this, open a command prompt and type regedit to run the registry editor. Drill down to the following registry key:

 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\TeamFoundation\SourceControl\ Checkin Policies 

Add a new string value with the same name as your DLL, but without the .dll extension. For this example, add a new string value with a name of PendingCheckinComments. Double-click this string value, and enter the full path to the DLL file. If you have unzipped the included code to the specified directory, this path should be:

 C:\Policies\PendingCheckinComments\PendingCheckinComments\bin\Debug\ PendingCheckinComments.dll 

Once you have added this path, you can close the registry editor.

All right, you have now created a check-in policy, and have associated it with Visual Studio. Let's see the policy in action.

1. Open Visual Studio and go to one of your Team Projects. Right-click the project, and select Team Project Settings⇨Source Control. This opens the Source Control Settings window for that team project.

2. Click the Check-in Policy tab; then click the Add button to add a Check-in Policy to this Team Project. You see a window similar to Figure 12-25. As you can see, the policy you have created, Pending Checkin Comment Policy, is listed in the window.

3. Select your custom policy and click OK. You will now see the policy listed in the Check-in Policy tab of the Source Control Settings window.

4. Create a new console application, and associate it with the team project you just enabled your custom policy on. Open the Pending Changes window, and click the Policy Warnings button. Figure 12-26 shows you that you are violating a check-in policy, because you do not have any comments in the comments field.

Figure 12-25

Figure 12-26

If you try to check in your changes, you will be warned that you are violating a check-in policy. You always have the option to override a check-in policy, but this is not recommended.

Object Model

Team Foundation Version Control contains its own rich object model, built off the Team Foundation Server Object Model. You learned the basics of using this object model in Chapter 9. Utilizing the object model, you can interact with all aspects of the version control system. Everything you can do with the Source Control Explorer you can also do with the object model. You will learn more about using the object model in the next chapter, when you look at how to implement continuous integration with Team Build.

MSSCCI Provider

The Microsoft Source Code Control Interface, or MSSCCI, was brought into being with Visual SourceSafe, and is now supported by many different IDEs. Microsoft recognized that many developers would like to use the more powerful version control located in Team Foundation Server but would not be able to immediately begin development using Visual Studio Team System. As such, they created a MSSCCI client for Team Foundation Version Control, allowing users of older IDEs the ability to interface with Team Foundation Version Control.

The provider can be downloaded from the Microsoft Download site at microsoft.com/downloads/ details.aspx?FamilyId=&displaylang=en. While this MSSCCI client was developed by Microsoft, it is not officially supported. However, Microsoft is very interested in seeing the client succeed, and has provided a special e-mail address, tfsmsscci@microsoft .com, for you to provide feedback on the client. As well, the Team Foundation Server Version Control forum (http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=478&SiteID=1) located at the MSDN Forums (http://forums.microsoft.com/MSDN) is a great place to get questions answered and provide feedback for this MSSCCI client.

The MSSCCI client works with the following products:

• Visual Studio 2003

• Visual C++ 6 SP6

• Visual Basic 6 SP6

• Visual Foxpro 9 SP1

• Microsoft Access 2003 SP2

• SQL Server Management Studio

• Sparx Systems Enterprise Architect

• Sybase Powerbuilder 10.5

Important

You must have Team Explorer installed on your machine, before you install the MSSCCI client.

As you start to use the MSSCCI provider in your IDE of choice, you'll notice that many of the screens and windows are remarkably similar to their Visual Studio 2005 counterparts. Microsoft has done a nice job of integrating the dialogs and windows from VS 2005, making it very intuitive to use.

There are a couple of gotchas that you need to watch out for. First, the code analysis and the testing check-in policies are not going to work. These policies rely on pieces of Visual Studio Team System to run, so it makes sense they would not work in a non-VSTS environment. Requiring a check-in to be associated with a work item will still work though, as will most custom check-in policies.

A second issue to watch for is if you have multiple MSSCCI providers installed on one machine, for example the VSS MSSCCI client and the TFS MSSCCI client. There will be times when you need to switch between one provider or the other. Ed Hintz, on his blog at http://blogs.msdn.com/edhintz/archive/2006/04/10/572826.aspx, gives the details on how to handle this issue. Basically, you need to set the value of the ProviderRegKey in the registry at HKEY_LOCAL_MACHINE\Software\ SourceCodeControlProvider to a value listed under the Installed SCCProviders key.

Let's look at a quick example of using the MSSCCI provider. Take a machine that you have Visual Studio 2003 installed on. Install Team Explorer on the machine, then download and install the Team Foundation Server MSSCCI client. Following the instructions from Ed Hintz's blog, make sure the registry is configured to use Team Foundation Server.

1. Open Visual Studio 2003 and create a new console application. Now that you have a new project created, you need to add it to Team Foundation Version Control.

2. Select File⇨Source Control⇨Add Solution To Source Control. You are prompted to connect to a Team Foundation Server, with a dialog box very similar to that used in Visual Studio 2005. You can select a server from the drop-down list box, or click the Servers button and add a new server.

3. Next, you need to choose a team project and folder to put the application in. You can also select a local workspace to map to this folder. Once you are done, click OK.

4. The Check-in window opens. In this window, as normal, you can view the files that are being checked in. You can enter comments. You can associate the changeset with a work item. You can enter check-in notes, and even view policy warnings. Figure 12-27 shows an example of this window.

   As you can see, it looks exactly like the window from Visual Studio 2005. Click the check-in button to check the files in.

5. Now open Visual Studio 2005. Using Team Explorer, open the Source Control Explorer for the team project you added the project to. You can see the folders that were added, and can see the files, the associated work items, everything. You can have most of the power and functionality of Team Foundation Version Control, yet continue to develop in the environment you are most comfortable in. It is the best of both worlds.

Figure 12-27