Custom Controls in Work Item Types

Work Item Tracking Custom Controls

Note: This is draft documentation for the Team Foundation Server SP1 Beta. The contents of this article should not be considered as final.  All feedback is welcome.

Introduction

The Work Item Tracking Custom Controls mechanism provides a standard way to enhance T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItems to include enhanced user-interface capabilities, extended event-based rules, and workflow capabilities. These custom controls can be bound to T:Microsoft.TeamFoundation.WorkItemTracking.Client.Fields within T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItems. These custom controls enable users to view and edit data.

Purpose of the Work Item Tracking Custom Controls

The Work Item Tracking Custom Controls are intended to enable the following capabilities:

·         Allow the use of new or existing Windows Form controls. This includes ActiveX controls wrapped as a Windows Form control.

·         Place controls on a T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItem Form using design layout constraints.

·         Allow a Control to be read and to write to a T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItem or T:Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItem T:Microsoft.TeamFoundation.WorkItemTracking.Client.Field.

·         Allow a Control to read and write from external data sources.

Restrictions of the Work Item Tracking Custom Controls

There are some restrictions for custom controls.

·         Multiple value fields are not directly supported. The use of a single field value as a holder of multiple values makes querying very difficult to do reliably.

·         Attachments do not have an update capability. The use of Custom Controls cannot overcome this limitation.

·         The existing controls are not public and therefore cannot be extended.

·         The binaries for each custom control must be installed on the client computer. There is no requirement for Admin rights to install custom control binaries.

·         There is no provisioning system for custom control binaries in Visual Studio. Visual Studio assumes the binaries are already installed on the client computer.

·         Custom controls that are missing or are not configured correctly must not cause the client to crash. They must also provide enough information to troubleshoot the problem.

Custom Control Implementations

Custom Controls have the following rules:

·         They must derive from the T:System.Windows.Forms.Control class

·         They must have a no-argument constructor

·         They must implement the T:Microsoft.TeamFoundation.WorkItemTracking.Controls.IWorkItemControl interface

As an option, they can implement the following interfaces:

T:Microsoft.TeamFoundation.WorkItemTracking.Controls.IWorkItemClipboard

T:Microsoft.TeamFoundation.WorkItemTracking.Controls.IWorkItemUserAction

T:Microsoft.TeamFoundation.WorkItemTracking.Controls.IWorkItemToolTip

See description/comment a Work Item Type definition

In the Work Item Type definition Layout, each Control element has a Type attribute. The schema previously identified the following valid control types:  

<xs:restriction base=”xs:string”>

    <xs:enumeration value=”FieldControl” />

    <xs:enumeration value=”DateTimeControl” />

    <xs:enumeration value=”HtmlFieldControl” />

    <xs:enumeration value=”LinksControl” />

    <xs:enumeration value=”AttachmentsControl” />

    <xs:enumeration value=”WorkItemClassificationControl” />

    <xs:enumeration value=”WorkItemLogControl” />

</xs:restriction>

This has been replaced with:

<xs:restriction base=”xs:string”>

    </xs:restriction>

This allows any name to be used. The built-in Types are still permitted. However, the use of a Type that does not match a built-in Type will infer the use of a Custom Control. This reference must not be to a specific DLL or Control. The reference is used as a name to look up an assembly manifest file on the client. For more information on assembly manifests see the topic, Assembly Manifests, on MSDN (http://go.microsoft.com/fwlink/?LinkId=74355).

Example

<Control Type=”WorkItemIdReference” FieldName=”MyFields.DuplicateId”  Label=”&amp;Duplicate Id:” LabelPosition=”Left” />

Work Item Custom Control (.wicc) Files

Use the value for the Control Type to identify the Work Item Custom Control (WICC) manifest file. The WICC file uses a naming convention of <Control Type>.wicc. It is located on the client computer in the following search path:

 

Term	Definition
Environment.SpecialFolder.LocalApplicationData	User-specific Path
Environment.SpecialFolder.CommonApplicationData folder	All Users

 

This manifest contains the following information:

·         Assembly

·         FullClassName

Here is an example:

<?xml version=”1.0″?>

<CustomControl xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>

  <Assembly>WitCustomControlSample.dll</Assembly>

  <FullClassName>WitCustomControlSample.WorkItemIdReference</FullClassName>

</CustomControl>

Use the Assembly element to locate and load the assembly. This value can be either the relative path of the location of the assembly file or the absolute path of the location of the assembly file.

Additional Notes

·         If you cannot find the control, or if some other error occurs, you will see a red, read-only error message. This message is substituted for the control itself.

·         Custom validation rules cannot be enforced in other client environments, such as Microsoft Excel and Microsoft Project. Use these rules carefully.

·         Validation rules cause the existing controls to change color when they are invalid. The colors are not customizable. Therefore, new controls should use standard colors to remain consistent.

·         The Work Item Object Model is updated on every change to a control. Custom control implementations must set the dirty flag correctly in the Object Model so that changes in the custom control will be saved.

See Also