Introduction

com.microsoft.tfs.sdk.samples.checkinpolicy is an Eclipse Java project that demonstrates the basics of check-in policy development for Team Explorer Everywhere. It should be imported into an Eclipse instance where Team Explorer Everywhere is installed.

The sample project source code in this project demonstrates the following:

Sample Walkthrough

This section will help you configure Eclipse, import, build, debug, and deploy the sample plug-in project. Developing your own custom check-in policy plug-in follows similar steps. If you have developed Eclipse plug-ins before and are familiar with the general process, you can import the sample project and include it a debug/run configuration with the Team Explorer Everywhere plug-ins to test it. First-time plug-in developers are encouraged to follow the steps below.

Note:

Your Eclipse installation must include Eclipse plug-in development features to work with this sample. The Eclipse products that can develop plug-ins are known as Eclipse for RCP/Plug-in Developers. Plug-in development capabilities of other Eclipse-based IDEs including Rational and Adobe products vary.

If your IDE does not support plug-in development features, you can use a supported version of the basic Eclipse IDE to develop your check-in policy, then deploy to a different IDE. Plug-in development features are not required for deployment.

1. Configure Eclipse

Ensure your configured Target Platform includes the correct version of Team Explorer Everywhere. You can configure your Target Platform in the Plug-in Development > Target Platform area of the Eclipse preferences. Make sure all of the com.microsoft.tfs.* plug-ins and its dependencies are checked

2. Import the Sample Project

Use Eclipse's File > Import... menu item to import this sample project into your Eclipse workspace.

3. Build

The sample project may build automatically after it is imported, depending on your Eclipse settings. If the sample project does not build without errors, check Eclipse's Problems view. Also, make sure your target platform includes the Team Explorer Everywhere plug-ins.

4. Test

Create a debug configuration that includes the sample plug-in

  1. Create a new Eclipse Application debug configuration (Run > Debug Configurations...).
  2. With your new configuration selected, select the Plug-ins tab of the configuration dialog and make sure the com.microsoft.tfs.sdk.samples.checkinpolicy plug-in is listed and checked. In newer versions of Eclipse you may have to change the Launch with option to with selected plug-ins only in order to see the sample plug-in.
  3. Click Debug to launch another Eclipse instance.
  4. When Eclipse starts, verify the sample check-in policy is available: choose Help > Team Explorer Support..., select the Diagnostic Data tab, then select the Team Explorer > Available Check-in Policies area.

Configure a team project to use the sample check-in policy (requires AdminProjectRights to the team project)

  1. In the Eclipse instance that is being debugged, open the Team Explorer view (Window > Show View > Other... > Team Foundation Server > Team Explorer).
  2. In the Team Explorer view, click on Settings page and choose Check-in Policies
  3. In the Check-in Policies dialog, click Add..., select the sample policy, then click OK. Configure the policy if the configuration dialog appears and click OK.
  4. Click OK to close the check-in policies dialog, saving the configuration to the team project.

Trigger policy evaluation

In the Eclipse instance that is being debugged, open the Pending Changes page (Window > Show View > Other... > Team Foundation Server, click on Pending Changes page). Create some pending changes by checking out one or more files. Expand Actions dropdown list and choose Evaluate Check-in Policies.

Rhe Policy Warnings section on the top of the Pending Changes page shows the current warnings ("failures" returned by policies). If a pending change contains the substring you configured the sample policy to reject, you should see an item in the warnings list.

You can set breakpoints in the sample code and trigger them while the debugged Eclipse runs by manually evaluating policies. Exit the debugged Eclipse when you are finished testing.

5. Deploy to Eclipse

Since check-in policies for Team Explorer Everywhere are simply Eclipse plug-ins, they can be deployed to a target IDE using any method it supports. Refer to Eclipse documentation on building and deploying plug-ins for more information.

A simple method of deployment is to export the plug-in project to a deployable plug-in, the output of which can be copied into the dropins directory (or plugins directory for older Eclipse versions) of the target IDE.

  1. In Package Explorer, right-click on the sample plug-in project and choose Export....
  2. In the dialog that appears, select Plug-in Development > Deployable plug-ins and fragments as the destination and click Next.
  3. Choose your preferred output format and name, then complete the wizard.

The process for installing your exported plug-in into a target IDE is specific to the target IDE, but most support a dropins directory. If you exported to a directory, copy all the plug-ins that were written to the plugins subdirectory of the output directory to the dropins directory in the target IDE, then restart the target IDE. If the target IDE does not have a dropins directory, copy the files to the plugins directory instead. See the target IDE's documentation on installing additional plug-ins for more information.

Creating a New Policy Plug-in

Creating a check-in policy plug-in from scratch is easy. You can use the plug-in development wizards provided with Eclispe to get started, and you can always reference the sample policy project and source code for the basics. Instructions in this section may refer to features and labels specific to Eclipse 3.6, but similar functionality is available in all version of Eclipse 3.2 and newer. We'll create a policy that checks "code quality" in this example. Simply change the names for your policy.

Create a New Project

  1. Make sure Team Explorer Everywhere is installed and its plug-ins are included in your target platform (see the Sample Walkthrough section for instructions on configuring the target platform).
  2. Create a new plug-in project. Click File > New > Other.... In the dialog that appears choose Plug-in Project and click Next.
  3. On the Plug-in Project wizard page:
  4. Click Next, then fill in the plug-in properties:
  5. Click Finish to complete the wizard.

Define Dependencies

Open the new project's plugin.xml file if it did not open automatically. Choose the Dependencies tab in the plug-in editor.

Extension Points

The check-in policy framework loads policy implementations (like the sample) through the com.microsoft.tfs.checkinpolicies.checkinPolicy extension point. All check-in policy plug-ins must contribute an extension at this point, and this is done in the plugin.xml file in the plug-in's project. You can view the sample project's plugin.xml source code to see how it contributes to this extension point by declaring a policy type ID and a class that implements the ID.

Note: For details on check-in policy types, including suggestions for choosing a policy type ID, see the Javadoc on the com.microsoft.tfs.core.checkinpolicies.PolicyType class.