Introduction

com.microsoft.tfs.sdk.samples.witcontrols is an Eclipse Java project that demonstrates the basics of TFS work item tracking custom control development for Team Explorer Everywhere. It should be imported into an Eclipse instance where Team Explorer Everywhere is installed. you can avoid the need to create a Java based custom work item control by setting the editor to be the embedded one which will use a web based custom work item control. However, if you want to enable custom work item controls for the SWT based editor then this sample shows you how.

Source code for for the following custom controls is included:

Sample Walkthrough

This section will help you configure Eclipse, import, build, debug, and deploy the sample plug-in project. Developing your own custom work item control 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

Prepare the work item type definition for uploading

  1. Open the TEECustomControlsBug.xml in this sample project in a text editor. This file is a work item type definition file for a TEECustomControlsBug work item, which is a standard MSF Agile Bug with modifications that demonstrate the controls included in this sample.
  2. Find the occurrences of the string C:\temp\choices.txt in this file. The FileSourceDropdown sample control reads choices from this file on each client where it is deployed. You can change this path to something else you prefer. For deployment to non-Windows clients, the sample control code will need to be modified to use a different path convention or some other configuration.
  3. Save any changes you made to TEECustomControlsBug.xml and close it.

Upload a work item type definition to TFS that uses the custom controls

Uploading the new type definition requires running the witadmin.exe program on a Windows computer where the Visual Studio 2012 (or newer) client software is installed (see \Program Files (x86)\Microsoft Visual Studio 2012\Common7\IDE\witadmin.exe).

  1. Run witadmin.exe, supplying your TFS server, collection, team project, and path as necessary:
    witadmin.exe importwitd /collection:http://server:8080/tfs/DefaultCollection /p:TeamProjectName /f:Path\To\TEECustomControlsBug.xml

The definition needs to be sent to the server ("imported") each time it changes. Refer to TFS documentation on work item customization for details.

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.witcontrols 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.

View and use the custom work item controls

In the Eclipse instance that is being debugged, open the Team Explorer view (Window > Show View > Other... > Team Foundation Server > Team Explorer). Click on the Work Items page in the team project you uploaded the work item type definition to and choose New Work Item > TEECustomControlsBug. A new work item appears that contains the custom controls in this sample.

You can set breakpoints in the sample code and trigger them while the debugged Eclipse runs by manipulating the work item form. Exit the debugged Eclipse when you are finished testing.

5. Deploy to Eclipse

Since custom work item controls for Team Explorer Everywhere Plug-in for Eclipse 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.