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 http://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 http://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=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://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 http://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: http://www.codeplex.com/WitCustomControls 


 


Got questions?:


 


Please raise your questions in workitemtracking forum: http://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 http://www.microsoft.com/info/cpyright.htm %>

WitCustomControlSample.zip


Comments (38)

  1. With the new service pack, some interesting features have become available. Until recently we did not

  2. Aquilegia says:

    Excellent informative post.  This should make TFS Work Items truly extensible.  Cheers.

  3. Work Item TypeのForm定義(VSで作業項目を開いたときに見える画面の定義) では標準として以下のコントロールが使用できます。 ・FieldControl ・HTMLFieldControl

  4. We’ve been working on putting together docs on 4 SP1 features. The documentation team will be ultimately

  5. Aaron Hallberg on Team Build API: GetListOfBuilds. Brian Harry on Bug fixes in TFS SP1 and Some Days….

  6. Last week I posted about the availability of the Visual Studio 2005 SP1 beta. I mentioned that the ability

  7. Aquilegia says:

    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!

  8. Aquilegia says:

    I can’t get the source code to run as it stands, because there is no AfterUpdateDatasource event in the IWorkItemControl interface.   I’m going to take this out, but I’m wondering why it’s there?  Do I have the correct version of Microsoft.TeamFoundation.WorkItemTracking.Controls.dll (8.0.50727.147)?

    [NarenD] The dll you have is RTM version and SP1 beta setup should have updated the dll. May be it is setup issue? Can you try reinstall and box restart just to be sure?

  9. Aquilegia says:

    Naren,  have reinstalled and restarted box.  I can see that KB918525 is in my currently installed programs list, but I still have the version of the control as mentioned before.  I have a test control ready to go, but of course I cannot import it.  Any ideas?  I may have to try uninstalling the SP and downloading it again 🙁

    [Naren] Actually it is hard to discuss these issues as comments & replies, so could you post this in our forums http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=479&SiteID=1? I’ll forward that post to setup guys to see if there is possible bug. I saw a post where someone was successful using this feature, so am not sure if the setup issue is machine specific.

  10. Aquilegia says:

    Further to my previous comment – my Visual Studio About Box looks exactly like this:

    http://www.myvstsblog.com/Images/InstallingVS2005SP1andTFSSP1betas_13F41/image010.png

  11. Luis Fraile says:

    Hola, bueno ha pasado alg&uacute;n tiempo desde el &uacute;ltimo art&iacute;culo, pero no he tenido mucho

  12. MSDNArchive says:

    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:” />

  13. MSDNArchive says:

    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.

  14. Naren has given us a great blog post to get us started on How to use Custom Control in a Work Item Type….

  15. Naren's Blog says:

    I heard more than few times question on how to build combobox like dropdown custom control where clicking

  16. Visual Studio 2005 SP1 is out the door! Get your bits here . There are fixes and enhancements across

  17. 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;

  18. Jung says:

    Is there any way transferring parameters representing the values of other workitem fields.

  19. narend says:

    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

  20. Jeff Levinson says:

    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

  21. Jeff Levinson says:

    Oh, forget the above, it was my mistake 🙂

  22. Since Service Pack 1 [1] we have the ability to create our own controls to display field value within

  23. Naren's Blog says:

    Recently few asking me about how to implement custom validation rules in a work item form. Our rules

  24. Recently few asking me about how to implement custom validation rules in a work item form. Our rules

  25. ryan farahani says:

    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

  26. narend says:

    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.

  27. SRLTeam says:

    Multiple values fields have become a necessity in work items. I noticed a lot of people searching for

  28. SRLTeam says:

    Multiple values fields have become a necessity in work items. I noticed a lot of people searching for

  29. Arunkumar says:

    Nice article. Provides good guidance for TFS customization. Thank you very much.

  30. Oceana says:

    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 !!!!!!

  31. Sadiq says:

    How to view this control in Work Item Web Access?

  32. Naren Datha says:

    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

  33. Sadiq says:

    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.

  34. Well TFS is not my specialty, but some time ago I was asked to develop custom control for one of our

  35. karthik says:

    Hi Naren..

    I have downloaded the sample project you have given here in the blog..

    I am getting an execution while executing the project, ReflectionTypeLoadException was unhandled.. "Unable to load one or more of the requested types. Retrieve the LoaderExceptions property for more information".

    I have googled and found that a change in the assembly version to 5.5.5 would help, but still I am facing the exception.

    Can any body tell me how to resolve this?

  36. karthik says:

    *that was ‘exception’ not ‘execution’… typographical mistake..!!

  37. Madhusudan says:

    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.