Work Item Custom Control Development in TF Web Access 2012 – Deployment

In the previous post, we talked about the development changes of a Work Item Custom Control in the new version of Team Foundation Web Access. In this post, we’ll dive into details of Work Item Custom Control deployment which is completely different than the previous version.

In TF Web Access 2010, you needed to place the assembly which contains the Work Item Custom Control implementation along with a manifest file in one of the search folders under Web Access installation folder. The manifest file (.wicc) was necessary for Web Access to resolve details about the custom control like assembly name the control lives in and the control type name.

New Web Access requires a zip package to be created which includes JavaScript files and a manifest file. The name of the manifest file must be manifest.xml and a typical content of it is as follows:

 <WebAccess version="11.0">
  <plugin name="Voting Button Custom Control" vendor="Acme" moreinfo="https://www.acme.com" version="2.0.0" >
    <modules>
      <module namespace="Acme.VoteButton" kind="TFS.WorkItem.CustomControl"/>  
    </modules>
  </plugin>
</WebAccess>

Plugin name, vendor, moreInfo and version attributes will appear in the extensions list of Web Access. It is possible to specify multiple modules inside a single extension package. Also please note that, the namespace attribute of the module should match the highlighted value below which exists in your JavaScript file and was explained in the previous post:

 TFS.module("Acme.VoteButton",
    [
        "TFS.WorkItemTracking.Controls",
        "TFS.WorkItemTracking",
        "TFS.Core"
    ],
    function () {
        // custom control implementation
    }
);

The kind attribute of a module specifies the type of the module. Specify TFS.WorkItem.CustomControl as the kind value which ensures Web Access will load your module whenever the custom control is needed.

As mentioned in the previous post, you have to have two versions of the .js file, debug and min. During the development and testing phase, you can use the debug version of the .js file by cloning and renaming it to min.js but it is suggested that, you minify your .js file when the custom control is ready for the production.

Now you have the .js files and the manifest file ready, you can create your package. The simplest way of doing this is to place these three files in a temporary folder, select them all, right click and send to compressed folder.

image

You are free to specify any name for your package as it will not be used by Web Access.

After you created your package, you need to upload the package to Web Access and this is going to be done inside Web Access. Please note that, the scope of an extension package is for the application (or account for hosted TFS) meaning that it will be available to all project collections and projects. Extensions are not supported for TFS Hosted Preview because there is no way to customize the work item types for now.

In order to navigate to extensions management page you can either navigate directly to https://tfsinstance:8080/tfs/_admin/_Extensions page or navigate to https://tfsinstance:8080/tfs and click the administration icon on the upper right corner first.

image

And then click to extensions link to go to extensions management page.

image

Inside the extensions management page, click the plus icon to install your package.

image

From the dialog, click the browse button and specify the package you previously created. Then click OK button to upload the package.

image

By default, newly installed extensions are disabled. You need to activate the extension package by clicking “Enable” button on the right. Then click “OK” to pass the confirmation.

image

Also note that, as we mentioned earlier, you can see the extension details you specified in the manifest file in this list.

After having the extension package installed, you need to change the definition of the work item type which you want to add the custom control to. You can use witadmin command line tool to export and import work item type definitions.

On a computer which has Visual Studio installed, open the developer command prompt from All Programs\Visual Studio\Visual Studio Tools. Then export the desired work item type definition using the following command:

witadmin exportwitd /n:Bug /f:c:\temp\bug.xml /collection:https://tfsinstance:8080/tfs/collectionname /p:projectname

Open the exported work item type definition from the file path you specified in the command and add the field definition to Fields section if necessary (you can use the existing fields).

 <FIELD name="VoteButton" refname="ACME.VoteButton" type="Integer">
  <HELPTEXT>Vote button</HELPTEXT>
</FIELD>

Then add the necessary entry to Form\Layout section for your custom control.

 <Control FieldName="ACME.VoteButton" Type="VoteButton" Label="Vote" LabelPosition="Left" />

Save the file and import the work item type definition using the following command to make your custom control appear in the work item form.

witadmin importwitd /f:c:\temp\bug.xml /collection:https://tfsinstance:8080/tfs/collectionname /p:projectname

You’re done. After connecting to web access and opening a work item which has the custom control, you can see it in the form.

image

While implementing the custom control, package creation and upload steps will probably occur several times and we know that it is not fun. However, we are planning to make improvements on this area to have a seamless development environment. At the same time, you can refer to this blog post about a Fiddler trick to be able to change your JavaScript file without ever needing to install your package again and again.

Let us know if you have any questions or feedback.