NOTE: This extension has been deprecated. The code is still available but there will be no updates moving forward. Feel free to use the code as-is to build something on your own.
Learn how to build your own custom control for the work item form.
-
Clone the repository.
-
Open the Command Prompt and change to the directory where you cloned the project. For instance, if it is cloned in a folder called "extensions" and saved as "vsts-sample-wit-custom-control", you will navigate to the following command line.
> cd C:\extensions\vsts-sample-wit-custom-control -
Run
npm installto install required local dependencies. -
Run
npm build:dev -
Run
npm run package:dev. -
Run
npm run dev- to start webpack dev server -
Go to your personal Marketplace.
-
Click the Marketplace icon in the upper righthand corner.
-
Click "Browse local extensions" in the dropdown.
-
Scroll down and click on the "Manage Extensions" widget.
-
Click the button "Upload new extension".
-
Browse to the .vsix file generated when you packaged your extension.
-
Select the extension, and then click "Open". Click "Upload" when the button activates.
-
Hover over the extension when it appears in the list, and click "Install".
You have now installed the extension inside your collection. You are now able to put the control on the work item form.
A work item type is defined by XML, including the layout of the work item form. As part of the walkthrough, you will add the control to the layout. Read more information on WebLayout XML. In this example, we will add the control to the Agile "user story".
-
Open the
Developer Command Prompt. Export the XML file to your desktop with command shown below.witadmin exportwitd /collection:CollectionURL /p:Project /n:TypeName /f:FileName -
This creates a file in the directory that you specified. Inside this file, navigate to the section called "Work Item Extensions". This section shows the documentation of the control such as the inputs and ids. All this information was defined in the manifest, vss-extension.json.
<!--**********************************Work Item Extensions***************************
Extension: Name: color-form-control Id: ms-devlabs.color-form-control
Control contribution:
Id: ms-devlabs.color-form-control.color-control-contribution
Description: Add custom colors and labels for picklist fields.
Inputs:
Id: FieldName
Description: The field must have allowed values.
Type: WorkItemField
Field Type: String; Integer
Data Type: String
IsRequired: true
Id: Labels
Description:
Data Type: String
IsRequired: false
Id: Colors
Description:
Data Type: String
IsRequired: false
```
-
Add an extension tag below the "Work Item Extensions" section as shown below to make your control available to work item form.
<!--**********************************Work Item Extensions*************************** ... Note: For more information on work item extensions use the following topic: http://go.microsoft.com/fwlink/?LinkId=816513 --> <Extensions> <Extension Id="ms-devlabs.color-form-control" /> </Extensions>
-
Find your extension ID in the "Work Item Extensions" section:
<!--**********************************Work Item Extensions***************************
Extension: Name: color-form-control Id: ms-devlabs.color-form-control ... ```
-
This extension is a contribution, so you add it with a contribution tag in place of the tag. This example adds the "ControlContribution" to the "Planning" group.
<Page Id="Details"> ... <Section> ... <Group Id="Planning"> ... <ControlContribution Label="Priority" Id="ms-devlabs.color-form-control.color-control-contribution" <Inputs> <Input Id="FieldName" Value="Microsoft.VSTS.Common.Priority" /> </Inputs> </ControlContribution> <Control Label="Risk" Type="FieldControl" FieldName="Microsoft.VSTS.Common.Risk" />
-
Finally, import this .xml file, using witadmin.
witadmin importwitd /collection:CollectionURL /p:Project /f:FileName
If you make changes to your extension files, you need to compile the Typescript and create the .vsix file again (steps 4-7 in the "Package & Upload to the marketplace" section).
Instead of re-installing the extension, you can replace the extension with the new .vsix package. Right-click the extension in the "Manage Extensions" page and click "Update". You do not need to make changes to your XML file again.
Reading data from VSTS/TFS server is a common REST API task for a work item control. The VSS SDK provides a set of services for these REST APIs. To use the service, import it into the typescript file.
import * as VSSService from "VSS/Service";
import * as WitService from "TFS/WorkItemTracking/Services";
import * as ExtensionContracts from "TFS/WorkItemTracking/ExtensionContracts";
import * as Q from "q";To enable Intellisense in Visual Studio Code, include the type definition file index.d.ts. Once you've added this definition file, it shows all functions available in the VSS SDK.
/// <reference path="../typings/index.d.ts" />| API | Functions | Usage |
|---|---|---|
| VSSService | VSS.getConfiguration() | Returns the XML which defines the work item type. Used in the sample to read the inputs of the control to describe its behavior. |
| WitService | getService() | Returns an instance of the server to make calls. |
| getFieldValue() | Returns the field's current value. | |
| setFieldValue() | Returns the field's current value using your control. | |
| getAllowedFieldValues() | Returns the allowed values, or the items in a dropdown, of a field. |
Create an instance of the work item service to get information about the work item. Use one of the service's functions to get information about the field. This example asks for the allowed values of a field.
WitService.WorkItemFormService.getservice().then(
(service) => {
service.getAllowedFieldValues(this._fieldName), (allowedValues: string[]) => {
// do something
}
}
)To wait on the response of multiple calls, you can use Q. This example shows how to ask for the allowed values and the current value associated with a field using the Q.spread function. You can make two parallel requests, and the code will not be executed until both services have returned a response.
WitService.WorkItemFormService.getService().then(
(service) => {
Q.spread<any, any>(
[service.getAllowedFieldValues(this._fieldName), service.getFieldValue(this._fieldName)],
(allowedValues: string[], currentValue: (string | number)) => {
//do something
}
)
}
)/scripts - Typescript code for extension
/img - Image assets for extension and description
/typings - Typescript typings
index.html - Main entry point
vss-extension.json - Extension manifest
Five basic grunt tasks are defined:
build- Compiles TS files inscriptsfolderpackage-dev- Builds the development version of the vsix packagepackage-release- Builds the release version of the vsix packagepublish-dev- Publishes the development version of the extension to the marketplace usingtfx-clipublish-release- Publishes the release version of the extension to the marketplace usingtfx-cli
The included .vscode config allows you to open and build the project using VS Code.
The project is setup for unit testing using mocha, chai, and the karma test runner. A simple example unit test is included in scripts/logic/messageHelper.tests.ts. To run tests just execute:
grunt test
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![microsoft-github-policy-service[bot] avatar](https://avatars.githubusercontent.com/in/95686?v=4 "microsoft-github-policy-service[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent