How To: Create Custom Check-in Policies in Visual Studio Team Foundation Server

  • Article

 

patterns & practices Developer Center

Team Development with Visual Studio Team Foundation Server

Retired Content

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

J.D. Meier, Jason Taylor, Prashant Bansode, Alex Mackman, and Kevin Jones
Microsoft Corporation

September 2007

Applies To

  • Microsoft® Visual Studio® 2005 Team Foundation Server (TFS)
  • Microsoft Visual Studio Team System

Summary

This How To article walks you through the process of creating, registering, and applying a custom check-in policy for TFS. Check-in polices allow you to run rules whenever a developer attempts to check-in a source file, in order to ensure that the source file being checked-in meets a specified set of criteria. As an example, this How To article uses a custom policy to enforce that check-in comments are supplied with all check-ins. To implement a custom check-in policy, you create a class that derives from PolicyBase and implements the IPolicyDefinition and IPolicyEvaluation interfaces. You register the policy assembly in the Microsoft Windows® registry and you apply the policy to your team project.

Contents

  • Objectives
  • Overview
  • Before You Begin
  • Summary of Steps
  • Step 1 – Create and Build a Custom Policy Class.
  • Step 2 – Register the Custom Policy Class in the Windows Registry
  • Step 3 – Apply the Custom Policy.
  • Step 4 – Validate the Custom Policy.
  • Additional Considerations

Objectives

  • Learn what a custom check-in policy is
  • Learn how to create, register, and apply custom check-in policies.

Overview

Check-in policies enforce constraints whenever files are checked into source control. Team Foundation Server provides a number of out-of-box check-in policies including policies to check that unit tests have run and been passed, policies to perform static code analysis to ensure that code meets coding standards and .NET guidelines, and policies to check that work items are associated with check ins. The Microsoft Visual Studio 2005 Team Foundation Power Tool also provides a number of additional check-in policies. In this How To article, you will learn how to create, register, and apply a custom policy. The example policy ensures that developers supply check-in comments whenever they check in a file.

Before You Begin

Note that, to create a check-in policy, you must have the Manipulate security settings permission set to Allow.

Summary of Steps

  • Step 1 – Create and Build a Custom Policy Class
  • Step 2 – Register the Custom Policy in the Windows Registry
  • Step 3 – Apply the Custom Policy
  • Step 4 – Validate the Custom Policy

Step 1 – Create and Build a Custom Policy Class

In this initial step, you create a custom policy class by deriving from the PolicyBase base class in the Microsoft.TeamFoundation.VersionControl.Client namespace. By deriving from this base class, your class implements the IPolicyDefinition and IPolicyEvaluation interfaces. The example policy code below forces a developer to supply check-in comments whenever he or she checks in a source file.

  1. Use Visual Studio to create a new Visual C#® class library project.
  2. Add an assembly reference to System.Windows.Forms.dll. You use this assembly to display message boxes.
  3. Add an assembly reference to Microsoft.TeamFoundation.VersionControl.Client.dll. By default, this is installed in the following folder:
    \Program Files\Visual Studio 2005 Team Foundation Server\Tools
  4. Replace your skeleton class code implementation with the following source. Note that the class derives from the PolicyBase base class and is marked as serializable.
using System;
using System.Windows.Forms;
using Microsoft.TeamFoundation.VersionControl.Client;

[Serializable]
public class CheckForCommentsPolicy : PolicyBase
{
    public override string Description
    {
        get { return "Remind users to add meaningful comments to their checkins"; 

    }

    // This is a string that is stored with the policy definition on the source
    // control server. If a user does not have the policy plug-in installed, this string
    // is displayed.  You can use this to explain to the user how they should 
            // install the policy plug-in.
    public override string InstallationInstructions
    {
        get { return "To install this policy, read InstallInstructions.txt."; }
    }

    // This string identifies the type of policy. It is displayed in the 
 // policy list when you add a new policy to a Team Project.
    public override string Type
    {
        get { return "Check for Comments Policy"; }
    }

    // This string is a description of the type of policy. It is displayed 
    // when you select the policy in the Add Check-in Policy dialog box.
    public override string TypeDescription
    {
        get { return "This policy will prompt the user to decide whether or not they should be allowed to check in."; }
    }

    // This method is called by the policy framework when you create 
    // a new check-in policy or edit an existing check-in policy.
    // You can use this to display a UI specific to this policy type 
    // allowing the user to change the parameters of the policy.
    public override bool Edit(IPolicyEditArgs args)
    {
        // Do not need any custom configuration
        return true;
    }

    // This method performs the actual policy evaluation. 
    // It is called by the policy framework at various points in time
    // when policy should be evaluated. In this example, the method 
    // is invoked when various asyc events occur that may have 
    // invalidated the current list of failures.
    public override PolicyFailure[] Evaluate()
    {
        string proposedComment = PendingCheckin.PendingChanges.Comment;
        if (String.IsNullOrEmpty(proposedComment))
        {
            return new PolicyFailure[] {
                new PolicyFailure("Please provide some comments about your check-in", this) };
        }
        else
        {
            return new PolicyFailure[0];
        }
    }

    // This method is called if the user double-clicks on 
    // a policy failure in the UI. In this case a message telling the user 
    // to supply some comments is displayed.
    public override void Activate(PolicyFailure failure)
    {
        MessageBox.Show("Please provide comments for your check-in.", "How to fix your policy failure");
    }

    // This method is called if the user presses F1 when a policy failure 
    // is active in the UI. In this example, a message box is displayed.
    public override void DisplayHelp(PolicyFailure failure)
    {
        MessageBox.Show("This policy helps you to remember to add comments to your check-ins.", "Prompt Policy Help");
    }
}

Step 2 – Register the Custom Policy in the Windows Registry

In this step, you add an entry to the Windows registry so that your policy appears in the Add Check-in Policy dialog box. Note that you must install the policy assembly on any computer that needs to reference the assembly. This includes the computer of the team project’s administrator who needs to associate the policy with the team project and on all of your team members’ computers where the policy is actually evaluated.

Important: The policy is evaluated on the client when a developer checks in a file.

  1. Start Regedit.exe and locate the following key HKEY_LOCAL_MACHINE\Software\Microsoft\VisualStudio\8.0\TeamFoundation\SourceControl\Checkin Policies
    The registered policies are listed in the right pane.
  2. Right-click in the right-hand pane, point to New, and then click String Value.
  3. Type the name of your custom policy dynamic link library (DLL), without the DLL extension; CheckForCommentsPolicy in the above example.
    Important: The new string name must match your DLL filename exactly, without the DLL extension.
  4. Double-click the new string value and set its value to the fully qualified path and filename to the .dll containing your custom policy.

Step 3 – Apply the Custom Policy

In this step you add the custom policy to your team project. This ensures that the policy is evaluated each time a developer checks in a file to this team project.

  1. In Team Explorer, right-click your team project, point to Team Project Settings and then click Source Control.
  2. Click the Check-in Policy tab and then click Add.
  3. Select your custom Check for Comments Policy and click OK and then OK again.

The policy is now applied each time a developer checks a file into this team project.

Step 4 – Validate the Custom Policy

In this step, you check-in a source file to ensure that the custom policy works correctly.

  1. Make a change to a source file and then check-in the file without supplying a check-in comment.
  2. Verify that the check-in is prevented because the policy rule is not satisfied.
  3. Add some comments and complete the check-in. With a supplied comment the check-in should work successfully and you will not see a policy failure notification.

Additional Resources

patterns & practices Developer Center