How to use Custom Controls in Work Item Form

  • [アーティクル]

What is custom control feature?

Now you can show your own controls in work item form. See for https://blogs.msdn.com/narend/archive/2006/09/27/773025.aspx introduction to this feature. This is part of SP1 beta . There is also a codeplex project to build & share generic controls.

Note: if you are trying to port VS2005 custom controls to Orcas see here.

 

Where to get documentation & Sample of this control?

Apparently the SP1 beta comes with minimal documentation and we are working to deliver detailed documentation. See https://blogs.msdn.com/vstsue/archive/2006/09/27/777554.aspx for additonal documentation. The purpose of this entry is to enable quick start on using this feature. I attached a sample in this post and this sample (revised) will also be available in official documentation soon, and that documentation will give more details on this feature. See here for shorter documentation on this and another tiny sample.

High level overview on how custom controls work:

When work item form is drawn, the control names are read from the work item type xml. A custom control can be added in that work item type xml under form section like below for sample control:

                <Control Type="WorkItemIdReference" FieldName="MyFields.DuplicateId" Label="&amp;Duplicate Id:" LabelPosition="Left" CustomAttribute1="Custom parameters here" CustomAttribute2="Custom parameters here"/>

If it is built-in control, then it is loaded from product assembly. Otherwise, a file with name <ControlName>.wicc is searched in local disc in order described below. If a file is found, it is expected to be in below example format:

<?xml version="1.0"?>

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

  <Assembly>WitCustomControlSample.dll</Assembly>

  <FullClassName>WitCustomControlSample.WorkItemIdReference</FullClassName>

</CustomControl>

The xml file basically says which assembly (optionally with its path) and which class name implements the custom control. The control needs to implement at least IWorkItemControl interface (explained below). Why use the file instead of registry or other options? It enables xcopy deployment and is similar to add-ins deployment. The assembly is then loaded and an object of the specified type is created with an empty constructor and loaded into the form. If searched file is not found, then a control is shown there with an error message for troubleshooting.

Now that the control is loaded, a reference to work item is passed to the control using IWorkItemControl.WorkItemDatasource property. The control is asked to display its data using IWorkItemControl.InvalidateDatasource method. The control is required to update any values directly in WorkItem object itself when user changes data.

Custom control Search Order:

Custom controls are searched in folder “Microsoft\Team Foundation\Work Item Tracking\Custom Controls” under Environment.SpecialFolder.CommonApplicationData folder first, then under Environment.SpecialFolder.LocalApplicationData. For Orcas, search is first made under "9.0" folder under above directory. This enables installing both VS2005 and Orcas version of controls in same machine. See here for more information on this.

Creating custom control:

Custom controls need to derive from Control. Typically custom controls are built from UserControl. To create a new user control project, go to Visual Studio, File/new project and choose “Windows Control Library” to create a user control.

The control needs to implement IWorkItemControl. This is defined in Microsoft.TeamFoundation.WorkItemTracking.Controls.dll assembly that can be found from VS installation folder, typically "<drive>:\Program Files\Microsoft Visual Studio 8\Common7\IDE\PrivateAssemblies". Add reference to that assembly and line "using Microsoft.TeamFoundation.WorkItemTracking.Controls;" in code. Below is definition of IWorkItemControl and comments on members in order of importance as I see it:

    public interface IWorkItemControl

    {

        bool ReadOnly { get; set; }

        string WorkItemFieldName { get; set; }

        object WorkItemDatasource { get; set; }

        StringDictionary Properties { get; set; }

        void Clear();

        void InvalidateDatasource();

        void FlushToDatasource();

        void SetSite(IServiceProvider serviceProvider);

        event EventHandler BeforeUpdateDatasource;

        event EventHandler AfterUpdateDatasource;

    }

WorkItemDatasource

This passes reference to source work item object. Cast this object to WorkItem type.

WorkItemFieldName

The field name if the control is associated with a field name in work item form xml. A custom control can be associated with 0 or 1 work item field.

InvalidateDatasource

Asks control to invalidate the contents and redraw. At this point, control can read from work item object and display/refresh data.

SetSite

Gives pointer to IServiceProvider if you intended to access Document service or VS Services. If services are not needed, do nothing in this method.

Clear

Control is asked to clear its contents

Properties

A property bag of all attributes specified in work item form xml for this control. Custom attributes are allowed and can be used to pass parameters specific for this control from work item type xml.

BeforeUpdateDatasource

AfterUpdateDatasource

Raise these events before and after updating WorkItem object with values. When value is changed by a control, work item form asks all controls (except current control) to refresh their display values (by calling InvalidateDatasource) in case if affects other controls

ReadOnly

Tells the control to display in readonly mode.

FlushToDatasource

 

Control is requested to flush any data to workitem object. This usually happens during save operation or when the form is left. In most cases data will be written to workitem immediately on change and hence this will not need implementation. Some customers want a way to do operations during save, and this is the closest thing we got. If you do need a way to react to before-save & after-save events, pls let us know in forums given below and we'll consider for future revision.
 

For additional functionality, below interfaces can be implemented optionally. I will talk about these interfaces may be in another post. It should be easy to figure out their usage by looking into their definition.

IWorkItemToolTip

IWorkItemUserAction

IWorkItemClipboard

See here for communicating with other controls

 

Custom operations before and after save events:

 

If you need to perform certain operations before the workitem is attempted to be saved (with an option to abort save operation), or after workitem save, use the addin interfaces and hook to Saving & Saved events. You need to build an addin to do it if this has to work for both new and existing items. If this is for existing items, then you can do without Addin: Basically get document service by using GetService call of IServiceProvider passed to you and use FindDocument with workitemid to get curent document and hook to workitemsaved event. Addin interfaces are documented at https://blogs.msdn.com/narend/archive/2006/07/07/AccessingWitFromAddin.aspx .  FlushToDatasource described above is closest to do some operations just before save operation or when leaving the form.

 

About the attached sample:

 

A sample is attached to this post (see end of post for attachments link). Check out the sample to see example implementation of IWorkItemControl members. The sample shows a control to accept a work item id and provides a button to navigate to that item. Steps to use the control is described here. The navigate part is example of using Work Item Tracking document service to manipulate WIT documents in VS. Now that you got work item object reference and the field name, implement the richness in your control as you desire. Build the control as dll and the custom control is ready.

Testing the custom control:

To test the control, create a .wicc file and see above for its format. You can copy the one in sample to start with and rename it to use your control’s name. Now edit the work item type xml. You might want to export an existing workitem’s xml using WitExport utility or use the one in the attached sample. Add a line like below in the xml.

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

Place the wicc file in folders as explained in search order above. Open the work item form and you should see the control in action. Not seeing the control? See troubleshooting section below for help in debugging.

Deploying custom control:

The control is developed and tested. Now the wicc file and assembly needs to be deployed in boxes for all users. Two ways to deploy it:

- xcopy deploy: Simply ask users to copy these two files to their local folders

- Create setup package: A simple setup package can be created using VS setup project. Steps below:

o In VS, right click on solution and add new project. Choose Other project type/setup and deployment in left pane of “Add Project” dialog, and choose “Setup project”

o Right click on setup project and add output from controls project.

o File system folders are shown by default. Add the folders, wicc files and assembly there. Build it for the setup msi. Share the msi for users to install.

Users also need to install SP1 to see controls. We know the deployment story is less than ideal and are investigating better deployment model.

Troubleshooting custom control issues:

- Issue: Control is deployed, but work item form shows an error box there: This means that work item form failed to find the control assembly or failed to load it. The error on the errorbox should point to .net error. If the wicc file or assembly is not found, I recommend using FileMon tool from here, and using fusion logg viewer to find out where workitemform was looking for files and why it failed to load.

 

      Another reason users have trouble is when xml elements in wicc file differ by case or spelling - they need to be exact for deserialization to work. Also, pls remember that the end users must have SP1 beta installed for them to view the deployed controls.

 

      See how Mickey Gousset got this to work & issues faced here. Still no luck? Post your question with error you get in work item tracking forum

- How to debug code in custom control itself? : The control is loaded in visual studio, and it can be debugged using another visual studio instance or CLR debugger. To make sure symbols get loaded for debugging, deploy pdb files alone with dll. Attach the VS install by “Debug/Attach to Process” menu. Make sure symbols for control are loaded by “Debug/windows/modules” menu.

Got Ideas for generic custom controls?:

Please share your ideas in codeplex opensource dev project: https://www.codeplex.com/WitCustomControls

Got questions? :

Please raise your questions in workitemtracking forum: https://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=479&SiteID=1

         

 

<%//This posting is provided "AS IS" with no warranties of any kind and confers no rights. Use of samples included in this posting is subject to the terms specified at https://www.microsoft.com/info/cpyright.htm %>

WitCustomControlSample.zip

Comments

  • Anonymous
    October 03, 2006
    With the new service pack, some interesting features have become available. Until recently we did not

  • Anonymous
    October 03, 2006
    Excellent informative post.  This should make TFS Work Items truly extensible.  Cheers.

  • Anonymous
    October 03, 2006
    Work Item TypeのForm定義（VSで作業項目を開いたときに見える画面の定義） では標準として以下のコントロールが使用できます。 ・FieldControl ・HTMLFieldControl

  • Anonymous
    October 04, 2006
    We've been working on putting together docs on 4 SP1 features. The documentation team will be ultimately

  • Anonymous
    October 04, 2006
    Aaron Hallberg on Team Build API: GetListOfBuilds. Brian Harry on Bug fixes in TFS SP1 and Some Days....

  • Anonymous
    October 04, 2006
    Last week I posted about the availability of the Visual Studio 2005 SP1 beta. I mentioned that the ability

  • Anonymous
    October 08, 2006
    Any chance of getting a VB sample up and running?  I want to do a quick Proof of Concept before promising anything to the users!

  • Anonymous
    October 09, 2006
    The comment has been removed

  • Anonymous
    October 10, 2006
    The comment has been removed

  • Anonymous
    October 10, 2006
    The comment has been removed

  • Anonymous
    October 15, 2006
    The comment has been removed

  • Anonymous
    October 18, 2006
    Naren, great post! I was wondering if you could provide a snippet for adding a built-in control (such as a DateTimePicker control)? [Naren] It is same like other controls you see in wit xml. Example is below. Can you post such questions in our forums instead because it is hard to answer questions raised in comments? <Control Type="FieldControl" FieldName="System.Title" Label="&amp;Title:" />

  • Anonymous
    October 18, 2006
    Regarding my previous comment... I'm wondering if the built-in control can be referenced directly from the WIT definition, or if I have to first wrap it in a custom control as you describe in this post? thx.

  • Anonymous
    October 20, 2006
    Naren has given us a great blog post to get us started on How to use Custom Control in a Work Item Type....

  • Anonymous
    October 24, 2006
    I heard more than few times question on how to build combobox like dropdown custom control where clicking

  • Anonymous
    December 14, 2006
    Visual Studio 2005 SP1 is out the door! Get your bits here . There are fixes and enhancements across

  • Anonymous
    January 11, 2007
    Když jsem se poprv&eacute; dočetl, že v SP1 na TFS bude možnost přid&aacute;vat vlastn&iacute; ovl&aacute;dac&iacute;

  • Anonymous
    May 14, 2007
    Is there any way transferring parameters representing the values of other workitem fields.

  • Anonymous
    May 17, 2007
    Jung, workitem object itelf is passed to custom control in WorkItemDataSource property, so any field can be accessed directly from workitem. For further questions on this, pls post your question in forums

  • Anonymous
    June 29, 2007
    Just as an FYI, the .wicc file is not <ControlName>.wicc it's <AssemblyName>.wicc where AssemblyName is the name of the assembly that contains the control. Also, I still haven't been able to get this to work, and I've posted to the forums asking for help. I just thought I would point this out. Jeff Levinson Team System MVP

  • Anonymous
    June 29, 2007
    Oh, forget the above, it was my mistake :)

  • Anonymous
    July 07, 2007
    Since Service Pack 1 [1] we have the ability to create our own controls to display field value within

  • Anonymous
    July 24, 2007
    Recently few asking me about how to implement custom validation rules in a work item form. Our rules

  • Anonymous
    July 24, 2007
    Recently few asking me about how to implement custom validation rules in a work item form. Our rules

  • Anonymous
    September 12, 2007
    We are going to develop a listbox custom control to support multi-select functionality. Before that, we want to make sure that there is no such control out there in the market and Microsoft has no plan of adding this control to the next version of TFS. Can anyone help us? Thanks in advance. Ryan

  • Anonymous
    September 12, 2007
    This is answer to Ryan's question above. Yes, we do not have plans to release a multiselect control (may be in a codeplex project). How soon do you need it? Please ask future questions/comments in forums or send email using link at top right.

  • Anonymous
    October 15, 2007
    Multiple values fields have become a necessity in work items. I noticed a lot of people searching for

  • Anonymous
    October 15, 2007
    Multiple values fields have become a necessity in work items. I noticed a lot of people searching for

  • Anonymous
    February 07, 2008
    Nice article. Provides good guidance for TFS customization. Thank you very much.

  • Anonymous
    March 18, 2008
    Hallo Naren, I Tried your custom WI, Its working fine. I have a question . How to access this controls value  ?  (like  wi.Fields["Microsoft.VSTS.Common.Discipline"].Value.ToString()  for accessing Discipline) I am using a TextBox in my custom control . I need to return the value in this textbox when I access the custom controls value. I tried many logic , but no improvement plzzzz help !!!!!!

  • Anonymous
    October 21, 2008
    How to view this control in Work Item Web Access?

  • Anonymous
    October 22, 2008
    Custom controls built for winforms cannot be used in ASP.net. Since the technology is different, same controls need to be built in ASP.net. The interfaces are similar. Doing a web search for asp.net custom controls for tfs should find the process

  • Anonymous
    October 27, 2008
    I am using Team System Web Access 2005. What I want is to render an EditableDropDown (which is provided by Microsoft) in the work item edit page. Can anybody tell me how I can do this. I don't know what methods should be called and what properties should be set. A sample code will be much appreciated.

  • Anonymous
    February 22, 2009
    Well TFS is not my specialty, but some time ago I was asked to develop custom control for one of our

  • Anonymous
    February 09, 2010
    The comment has been removed

  • Anonymous
    February 09, 2010
    The comment has been removed

  • Anonymous
    December 15, 2010
    I have always felt a need for trapping events especially before an update to the work item (in case of the Scrum 1.0 template for example) to know how much work an user enters in the Work completed field. This will give me an audit trail of the various updates users have made during the sprint and a custom report can thus be generated. My management want to use the scrum template with the added benefit of a tracking mechanism in place for reporting purposes. It would be great if one can do that.

  • Anonymous
    March 05, 2014
    I have written articles to get this working on visual studio as well as web refer to www.codeproject.com/.../Close-a-Work-Item-only-if-Child-Work-items-are-c-2 www.codeproject.com/.../Close-a-Work-Item-Only-if-Child-Work-Items-are-C