Professional Documents
Culture Documents
Develop Extensions
Overview
What are extensions?
Quickstarts
Develop a web extension
Samples
Sample extensions
Concepts
Extensibility points
Contribution model
How-to Guides
Develop
Add a hub
Add a menu action
Add a build or release task
Add a dashboard widget
Add a new service endpoint
Add a service hook
Create a PR status server
Use Azure Functions to create custom branch policies
Add a chart
Store data and settings
Add Work hub extensions
Add backlog tabs
Add backlog panels
Extend the work item form
Add a custom control to the work item form
Configure work item form extensions in TFS
Add query result tabs
Call a REST API
Extensions for public projects
New navigation (preview)
Use a platform UI control
Configure
Use grid
Use menubar
Use treeview
Use combo
Use modal dialog
Use splitter
Use wait control
Use pivot filter
Package and publish
Package and publish extensions
Package and publish integrations
Make your listing public
Publish via command line
Respond to Marketplace reviews
Test and debug
Debug a web extension
Menu group IDs
Reporting
Extension reporting
Extension statistics PowerBI content pack
Reference
Manifest reference
Build/Release task reference
Endpoint authentication schemes
Content hosting
Modal dialog
Host page navigation
Basic styles for widgets
Auth and security
Deploy web content to Azure
Client APIs
Core SDK
Client services
REST clients
BuildHttpClient2_1
BuildHttpClient2_2
CoreHttpClient2_1
CoreHttpClient2_2
TestHttpClient2_1
TestHttpClient2_2
GitHttpClient2_1
GitHttpClient2_2
TfvcHttpClient2_1
TfvcHttpClient2_2
WorkHttpClient2_1
WorkHttpClient2_2
WorkItemTrackingHttpClient2_1
WorkItemTrackingHttpClient2_2
UI controls
Combo
Grid
TreeView
MenuBar
Modal Dialog
Splitter
WaitControl
How to get help
Resources
Visual Studio Marketplace
Manage Extensions
Build Visual Studio extensions
Develop Extensions
5/14/2018 • 2 minutes to read • Edit Online
Extensions are simple add-ons that can be used to customize and extend your DevOps experience with Visual
Studio Team Services (VSTS ). They are written with standard technologies - HTML, JavaScript, CSS - and can be
developed using your preferred dev tools.
5-minute Quickstarts
Check out the quick starts to get you started:
Write your first extension
Videos
Develop Visual Studio Team Services extension with continuous delivery pipeline:
Concepts
Extension points
Contribution model
Samples
Sample extensions
How-to Guides
Develop
Add a build task
Extend the work item form for work item tracking
Add a dashboard widget
Call a REST API
Package and publish
Package and publish extensions
Package and publish integrations
Reference
Manifest reference
Build task reference
Endpoint authentication schemes
Content hosting
Modal dialog
Host page navigation
Basic styles for widgets
Auth and security
Deploy web content to Azure
UI controls
Combo
Grid
TreeView
MenuBar
Modal Dialog
Splitter
WaitControl
What are extensions?
7/3/2018 • 2 minutes to read • Edit Online
NOTE
This section covers developing custom extensions and service-hooks, to find information on installing extensions from the
Marketplace, or buying Visual Studio Subscriptions, visit the Marketplace documentation.
Extensions are simple add-ons that can be used to customize and extend your DevOps experience with VSTS. They
are written with standard technologies - HTML, JavaScript, CSS - and can be developed using your preferred dev
tools. They utilize our RESTful API Library in order to easily interact with VSTS and applications/services. The
Visual Studio Marketplace is where extensions are published, where they can be kept privately for you and your
team or shared with the millions of developers currently using VSTS.
Helpful links
Visual Studio Marketplace
Extension Publisher Page
Visual Studio Partner Program
Next Steps
Quickstarts
Write your first extension (Add a hub)
Reference
Extension manifest reference
Develop a web extension for VSTS
7/3/2018 • 5 minutes to read • Edit Online
Extensions enhance Visual Studio Team Services (VSTS ) and Team Foundation Server (TFS ) by contributing
enhancements like new web experiences, dashboard widgets, build tasks, and more. Extensions are developed
using standard technologies like HTML, JavaScript, and CSS, are packaged and published to the Visual Studio
Marketplace, and can then be installed into a VSTS account.
This tutorial will guide you through creating your first web extension.
You will:
Install the required tools
Ready a local directory for your extension
Create an extension manifest file and hub contribution
Package and publish your extension to the Marketplace
Test your extension in a VSTS account
Prerequisites
To develop and test your extension you will need:
1. A VSTS account where you have permission to install extensions to (i.e. you are the owner).
If you don't have a personal VSTS account, you can create an account for free.
2. Install Node.js
3. Install the extension packaging tool (TFX) by running npm install -g tfx-cli from a command prompt
md my-first-extension
npm init -y
3. Install the Microsoft VSS Web Extension SDK package and save it to your NPM package manifest:
npm install vss-web-extension-sdk --save
This SDK includes a JavaScript library that provides APIs required for communicating with the page
your extension will be embedded in.
4. Create an extension manifest file named vss-extension.json at the root of your extension directory with
the following content:
{
"manifestVersion": 1,
"id": "my-first-extension",
"publisher": "",
"version": "1.0.0",
"name": "My First Extension",
"description": "A sample Visual Studio Services extension",
"public": false,
"categories": ["Code"],
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"contributions": [
{
"id": "my-hub",
"type": "ms.vss-web.hub",
"targets": [
"ms.vss-code-web.code-hub-group"
],
"properties": {
"name": "My Hub",
"uri": "my-hub.html"
}
}
],
"files": [
{
"path": "my-hub.html",
"addressable": true
},
{
"path": "node_modules/vss-web-extension-sdk/lib",
"addressable": true,
"packagePath": "lib"
}
]
}
NOTE
The public property controls whether the extension is visible to everyone on the Visual Studio Marketplace.
During development you should keep your extensions private.
5. Create a file named my-hub.html at the root of your extension directory with the following content:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script src="lib/VSS.SDK.min.js"></script>
<style>
body {
background-color: rgb(0, 67, 117);
color: white;
margin: 10px;
font-family: "Segoe UI VSS (Regular)","-apple-system",BlinkMacSystemFont,"Segoe UI",sans-
serif;
}
</style>
<script type="text/javascript">
VSS.init();
VSS.ready(function() {
document.getElementById("name").innerText = VSS.getWebContext().user.name;
});
</script>
</head>
<body>
<h1>Hello, <span id="name"></span></h1>
</body>
</html>
This will be the content for the view (also known as a hub) contributed into the VSTS web experience.
6. At this point your extension directory should look like this:
|-- my-hub.html
|-- node_modules
|-- @types
|-- vss-web-extension-sdk
|-- package.json
|-- vss-extension.json
You're now ready to package your extension and publish (upload) it to the Marketplace. Keep this browser window
open as you'll need to return here after you have packaged your extension.
Package your extension
1. Open your extension manifest file ( vss-extension.json ) and set the value of the publisher field to the ID
of your publisher. For example:
{
...
"id": "my-first-extension",
"publisher": "AnnetteNielsen",
...
}
2. From a command prompt, run the TFX tool's packaging command from your extension directory:
3. Once this completes you will see a message indicating your extension has been successfully packaged:
5. After a few seconds your extension will appear in the list of published extensions. Don't worry, the
extension is only visible to you.
2. Click Get it free to start the installation process. The account you shared the extension with should be
selected:
3. Click Install.
Congratulations! Your extension is now installed into an account and is ready to be tested.
If there are no projects in your account, you will be prompted to create one.
3. Navigate to the Code area and then to the hub contributed by your extension (My Hub):
Next steps
See more tutorials
Explore the samples
VSTS extension samples
4/27/2018 • 2 minutes to read • Edit Online
You can get started developing your extension by working from an sample. The Microsoft samples listed below
show the capabilities of the extension framework and how to contribute to various areas. Each sample illustrates
one or more contributions. We've limited the number of contributions for each sample to increase understanding
of the extension framework.
Color Scale Work Item Form GitHub Work Item Form Control Add color coding to the
Custom Control values in a dropdown.
File Owner GitHub Context menu action (source Allows users to see who
explorer) owns a file from the Source
Explorer
Folder Management GitHub Context menu action (code Create a folder in your
explorer tree) source repositories from the
code explorer tree. No need
to clone the repository or
install extra tools
Print Cards GitHub Toolbar action (Kanban Print cards from your
board) Kanban board for use on a
physical board
Offline Test Execution GitHub Test plan tab Allows the tester to perform
the test steps even if
disconnected from Visual
Studio Team Services (VSTS).
It can be done using the
exported Excel Spreadsheet.
Release Management Tasks GitHub Release Management tasks Utility tasks for Release
Management: Tokenizer,
Powershell++, Shell++, Zip
& Unzip, Powershell to
rollback
Sample Data GitHub Dashboard Widget Lets you create and remove
sample data in your project.
SAMPLE SOURCE CONTRIBUTIONS DESCRIPTION
State Model Visualization GitHub Toolbar action (work item), Visualize the state model for
Hub a selected work item type.
Tags MRU GitHub Context menu action (work Keeps a list of the most
item), Notification (work recently used work item tags
item) and allows adding them with
a single click.
Team Project Health GitHub Dashboard Widget Enable users to visualise the
overall health of builds,
delivering a visual cue similar
to the Codify Build Light.
User Voice UI GitHub Group (work item form), Shows rich data of the linked
Hub, Extension data User Voice suggestions on
the work item form. It covers
the following techniques:
calling external APIs, add
tags to work item, add links
to work item, resize of
container.
Work Item Details GitHub Context menu action (work View details of work item(s)
item), Dashboard Widget on your dashboard
Extensions extend and enhance the Visual Studio Team Services (VSTS ) user experience by contributing new
capabilities. This guide highlights the most common extensibility points that your extension can target.
NOTE
To learn more about the VSTS extensibility model, see contribution model for an overview.
Example
This example shows how to contribute a hub to the Code hub group:
{
...
"contributions": [
{
"id": "my-custom-hub",
"type": "ms.vss-web.hub",
"targets": [
"ms.vss-code-web.code-hub-group"
],
"properties": {
"name": "Code Hub",
"order": 30,
"uri": "/views/code/custom.html"
}
}
]
}
ms.vss-web.hub is the type of this contribution. This type is defined in the vss-web extension published under
the ms publisher. This type declares optional/required properties required by contributions of this type (name,
order, etc).
ms.vss-code-web.code-hub-group is the full ID of the hub group contribution this hub is targetting. This
contribution is declared in the vss-code-web extension published under the ms publisher
my-custom-hub is the short ID of this contribution; {publisherId}.{extensionId}.my-custom-hub is the full ID
Build
NAME TARGET ID PREVIEW
NAME TARGET ID PREVIEW
Release
NAME TARGET ID PREVIEW
Code
NAME TARGET ID PREVIEW
Test
NAME TARGET ID PREVIEW
Work
NAME TARGET ID PREVIEW
Dashboards
An extension can contribute a new type of widget that can be added by users to a dashboard. Learn how to
contribute a dashboard widget.
Service hooks
A "consumer" is the service that events are sent to in Service Hooks. An extension can contribute consumer
services that can be configured by a user (or programmatically) to send events to that service See contribute a
service hooks consumer.
Contribution model
4/27/2018 • 2 minutes to read • Edit Online
Extensions add new capabilities into the system by providing contributions and by defining ways for other
extensions to plug in to them. A contribution type defines something that can be added to the system. A
contribution is a specific instance of a contribution type. For example, hub is a contribution type defined by a core,
Microsoft-provided extension. The Explorer hub under the Build hub group is a specific contribution of type hub .
Contribution types
A contribution type defines a contract that all contributions to the system of that type must adhere to. hub ,
action , and build-task are all examples of contribution types. Types define the properties set by instances of
that type. Each property definition indicates the type of the property (string, boolean, etc.), whether the property is
required, and optionally specifies a default value if not specified by a contribution. A contribution type can also
extend from another contribution type.
Example
Here is an example of a contribution type declaration in an extension manifest:
{
...
"contributionTypes": [
{
"id": "hub",
"name": "Web Access Hub",
"description": "A hub that will appear in the hubs menu at the top of web pages.",
"properties": {
"name": {
"description": "The text to display for the hub",
"type": "string",
"required": true
},
"uri": {
"description": "URI of the contents of the hub page",
"type": "string",
"required": true
},
"order": {
"description": "An optional ordering value which can indicate in which position to place
the hub within the hub group",
"type": "integer"
}
...
}
}
]
}
Contributions
A contribution is an instance of a contribution type. For example, the Queries hub under the Work hub group is
a contribution of type hub and the Publish Test Results build task is a contribution of type build-task .
All contributions must specify a type and specify values for any properties required by that contribution type.
Example
Here is an example of a hub contribution declaration in an extension manifest:
{
"contributions": [
{
"id": "build-explorer-hub",
"type": "ms.vss-web.hub",
"targets": [
".build-hub-group"
],
"properties": {
"name": "Explorer",
"uri": "/_build",
"order": 22
}
}
]
}
Targeting contributions
A contribution can target one or more other contributions. This creates a relationship between the contribution
and each of its target(s) that enables the system to discover contributions for the target at runtime. For example, a
hub contribution ( Explorer ) might target a specific hub-group contribution ( Build ).
{
"id": "build-explorer-hub",
"type": "ms.vss-web.hub",
"targets": [
".build-hub-group"
]
}
When the hub group is being rendered, the system can query for all hub contributions that target the hub group in
order to know which hubs to render.
Identifying contributions and types
Every contribution and contribution type must have a unique ID (within the extension it is declared in).
A full contribution identifier includes the publisher ID, extension ID, and contribution/type ID, separated by a dot
(.). For example: "ms.vss-web.hub" is the full identifier for the contribution with ID of hub in the vss-web
extension published by the ms (Microsoft) publisher.
Relative contribution references may be used within an extension manifest for a contribution's reference to
another contribution or contribution type within that same extension. In this case, the publisher and extension IDs
are NOT included, and the ID is simply a dot (.) followed by the contribution id. For example, ".hub" may be used
within the "vss-web" extension mentioned above as a shortcut for "ms.vss-web.hub".
Add a hub
4/27/2018 • 2 minutes to read • Edit Online
We'll create a new hub that displays in the Work hub group, after the Backlogs and Queries hubs.
Structure of an extension
|--- README.md
|--- sdk
|--- node_modules
|--- scripts
|--- VSS.SDK.js
|--- images
|--- icon.png
|--- scripts // not used in this tutorial
|--- hello-world.html // html page to be used for your hub
|--- vss-extension.json // extension's manifest
To learn more about the SDK, visit the Client SDK GitHub Page.
NOTE
The publisher here will need to be changed to your publisher name. To create a publisher now, visit Package/Publish/Install.
Icons
The icons stanza specifies the path to your extension's icon in your manifest.
You will need to add a square image titled logo.png as shown in the extension manifest.
Contributions
The contributions stanza adds your contribution - the Hello hub - to your extension manifest.
For each contribution in your extension, the manifest defines
the type of contribution, hub,
the contribution target, the work hub group, (check out all of the targetable hub groups)
and the properties that are specific to each type of contribution. For a hub, we have
PROPERTY DESCRIPTION
Scopes
Include the scopes that your extension requires. In this case, we need vso.work to access work items.
Files
The files stanza states the files that you want to include in your package - your HTML page, your scripts, the SDK
script and your logo. Set addressable to true unless you include other files that don't need to be URL -
addressable.
NOTE
For more information about the extension manifest file, such as its properties and what they do, check out the extension
manifest reference.
Next Steps
Now that you've written your extension, the next steps are to Package, Publish, and Install your extension. You can
also check out the documentation for Testing and Debugging your extension.
Package, publish, and install extensions
Testing and debugging extensions
Add a menu action
5/14/2018 • 2 minutes to read • Edit Online
In this example, we'll add an action to the query context menu in the work item queries hub.
...
"contributions": [
{
"id": "myAction",
"type": "ms.vss-web.action",
"description": "Run in Hello hub action",
"targets": [
"ms.vss-work-web.work-item-query-menu"
],
"properties": {
"text": "Run in Hello hub",
"title": "Run in Hello hub",
"icon": "images/icon.png",
"groupId": "actions",
"uri": "action.html"
}
}
]
...
Properties
PROPERTY DESCRIPTION
icon URL to an icon that will appear on the menu item. Relative
URLs are resolved using baseUri.
uri URI to a page that registers the menu action handler (see
below).
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Action Sample</title>
</head>
<body>
<div>
The end user doesn't see the content on this page.
It is only in the background to handle the contributed menu item being clicked.
</div>
</body>
</html>
Your JavaScript
The script below registers the handler object to handle the action, place it in the head section of the HTML page
above.
<script src="sdk/scripts/VSS.SDK.js"></script>
<script>
VSS.init();
// Associate the menuContributionHandler object with the "myAction" menu contribution from the manifest.
VSS.register("myAction", menuContributionHandler);
</script>
Next Steps
Now that you've written your extension, the next steps are to Package, Publish, and Install your extension. You can
also check out the documentation for Testing and Debugging your extension.
Package, publish, and install extensions
Testing and debugging extensions
Add a build or release task
6/25/2018 • 7 minutes to read • Edit Online
Custom build or release tasks can be contributed by extensions that can be discovered and installed by users into a
VSTS account. These tasks will appear next to Microsoft-provided tasks in the Add Step wizard:
To learn more about the new cross-platform build/release system, see Team Foundation Build & Release.
Note: This article covers agent tasks in agent-based extensions. For information on server tasks/server-based
extensions, checkout the Server Task GitHub Documentation.
Steps
There are four steps to creating a build or release task extension and putting it on the Marketplace:
Step 1: Create the task metadata file
Step 2: Create the extension maniest file
Step 3: Package your extension
Step 4: Publish your extension
Optional: Install and test your extension
Remove either Build or Release from the *Visibility attribute if you wish to exclude one.
task.json components
Here is a description of some of the components of the task.json file.
PROPERTY DESCRIPTION
instanceNameFormat This is how the task will be displayed within the build or
release step list - you can use variable values by using
$(variablename)
NOTE
For a more in-depth look into the task.json file, or to learn how to bundle multiple versions in your extension, check out the
build/release task reference
You can explore the vso-agent-tasks repository on GitHub for multiple examples (Grunt is a good one).
NOTE
The publisher here will need to be changed to your publisher name. If you would like to create a publisher now, you can
jump down to create your publisher for instructions on how to do so.
Contributions
PROPERTY DESCRIPTION
properties.name Name of the task. This must match the folder name of the
corresponding self-contained build or release task definition.
Files
PROPERTY DESCRIPTION
NOTE
For more information about the extension manifest file, such as its properties and what they do, check out the extension
manifest reference.
NOTE
An extension/integration's version must be incremented on every update.
When updating an existing extension, either update the version in the manifest or pass the --rev-version command line
switch. This will increment the patch version number of your extension and save the new version to your manifest.
After you have your packaged extension in a .vsix file, you're ready to publish your extension to the marketplace.
IMPORTANT
Publishers must be verified in order to share extensions publicly, to learn more visit Package/Publish/Install
Now that your extension is in the marketplace and shared, anyone who wants to use it will have to install it.
Helpful links
Extension Manifest Reference
Build/Release Task JSON Schema
Build/Release Task Examples
NOTE
Check out our Node task sample in GitHub for a tutorial that shows how to create, debug, and test a cross platform task
in Node using the TypeScript API.
Add a dashboard widget
6/26/2018 • 29 minutes to read • Edit Online
Widgets on a dashboard are implemented as contributions in the extension framework. A single extension can
have multiple contributions. In this guide we will show you how to create an extension with multiple widgets as
contributions.
This guide is divided into three parts, each building on the previous ones. The goal is to start with a simple widget
and end with a comprehensive one.
|--- README.md
|--- sdk
|--- node_modules
|--- scripts
|--- VSS.SDK.min.js
|--- img
|--- logo.png
|--- scripts
|--- hello-world.html // html page to be used for your widget
|--- vss-extension.json // extension's manifest
If you're in a hurry and want to get your hands on the code right away, you can download the complete
samples here. Once downloaded, go to the widgets folder, then follow Step 6 and Step 7 directly to publish
the sample extension which has the three sample widgets of varying complexities.
Get started with some basic styles for widgets that we provide out of the box for you and some guidance on
widget structure.
Part 1: Hello World
This part presents a widget that prints "Hello World" using JavaScript.
The core SDK script, VSS.SDK.min.js , enables web extensions to communicate to the host VSTS frame and to
perform operations like initializing, notifying extension is loaded or getting context about the current page. Get the
Client SDK VSS.SDK.min.js file and add it to your web app. Place it in the home/sdk/scripts folder.
Use the 'npm install' command to retrieve the SDK:
To learn more about the SDK, visit the Client SDK GitHub Page.
This is the glue that holds your layout together and includes references to CSS and JavaScript. You can name this
file anything, just be sure to update all references to hello-world with the name you use.
Your widget is HTML based and will be hosted in an iframe. Add the below HTML in hello-world.html . We add
the mandatory reference to VSS.SDK.min.js file and include an h2 element in the body which will be updated
with the string Hello World in the upcoming step.
<!DOCTYPE html>
<html>
<head>
<script src="sdk/scripts/VSS.SDK.min.js"></script>
</head>
<body>
<div class="widget">
<h2 class="title"></h2>
</div>
</body>
</html>
Even though we are using an HTML file, most of the HTML head elements other than script and link will be
ignored by the framework.
<script type="text/javascript">
VSS.init({
explicitNotifyLoaded: true,
usePlatformStyles: true
});
return WidgetHelpers.WidgetStatusHelper.Success();
}
}
});
VSS.notifyLoadSucceeded();
});
</script>
VSS.init initializes the handshake between the iframe hosting the widget and the host frame.. We pass
explicitNotifyLoaded: true so that the widget can explicitly notify the host when we are done loading. This
control allows us to notify load completion after ensuring that the dependent modules are loaded. We pass
usePlatformStyles: true so that the VSTS core styles for html elements (such as body, div etc) can be used by the
Widget. If the widget prefers to not use these styles, they can pass in usePlatformStyles: false .
VSS.require is used to load the required VSS script libraries. A call to this method automatically loads general
libraries like JQuery and JQueryUI. In our case we depend on the WidgetHelpers library which is used to
communicate widget status to the widget framework. Therefore, we pass the corresponding module name
TFS/Dashboards/WidgetHelpers and a callback to VSS.require . The callback is called once the module is loaded. This
callback will have the rest of the JavaScript code needed for the widget. At the end of the callback we call
VSS.notifyLoadSucceeded to notify load completion.
WidgetHelpers.IncludeWidgetStyles will include a stylesheet with some basic css to get you started. Make sure to
wrap your content inside a HTML element with class widget to make use of these styles.
VSS.register is used to map a function in javascript which uniquely identifies the widget among the different
contributions in your extension. The name should match the id that identifies your contribution as described in
Step 5. For widgets, the function that is passed to VSS.register should return an object that satisfies the IWidget
contract, i.e. the returned object should have a load property whose value is another function that will have the
core logic to render the widget. In our case, it is simply to update the text of the h2 element to "Hello World". It is
this function that is called when the widget framework instantiates your widget. We use the WidgetStatusHelper
from WidgetHelpers to return the WidgetStatus as success.
Warning: If this name used to register the widget doesn't match the ID for the contribution in the manifest, then the widget will
behave unexpectedly.
The vss-extension.json should always be at the root of the folder (in this guide, HelloWorld ). For all the other
files, you can place them in whatever structure you want inside the folder, just make sure to update the
references appropriately in the HTML files and in the vss-extension.json manifest.
Step 4: Your extension's logo: logo.png
Your logo is displayed in the Marketplace, and in the widget catalog once a user installs your extension.
You will need a 98px x 98px catalog icon. Choose an image, name it logo.png , and place it in the img folder.
To support TFS 2015 Update 3, you will need an additional image that is 330px x 160px. This is a preview image
shown in this catalog. Choose an image, name it preview.png , and place it in the img folder as before.
You can name these images however you want as long as the extension manifest in the next step is updated with
the names you use.
Step 5: Your extension's manifest: vss-extension.json
NOTE
The publisher here will need to be changed to your publisher name. To create a publisher now, visit Package/Publish/Install.
Icons
The icons stanza specifies the path to your extension's icon in your manifest.
Contributions
Each contribution entry defines certain properties.
The id to identify your contribution. This should be unique within an extension. This ID should match with the
name you used in Step 3 to register your widget.
The type of contribution. For all widgets, this should be ms.vss-dashboards-web.widget .
The array of targets to which the contribution is contributing. For all widgets, this should be
[ms.vss-dashboards-web.widget-catalog] .
The properties is an object that includes properties for the contribution type. For widgets, the below properties
are mandatory.
PROPERTY DESCRIPTION
catalogIconUrl Relative path of the catalog icon that you added in Step 4 to
display in the widget catalog. The image should be 98px x
98px. If you have used a different folder structure or a
different file name, then this is the place to specify the
appropriate relative path.
previewImageUrl Relative path of the preview image that you added in Step 4
to display in the widget catalog for TFS 2015 Update 3 only.
The image should be 330px x 160px. If you have used a
different folder structure or a different file name, then this is
the place to specify the appropriate relative path.
uri Relative path of the HTML file that you added in Step 1. If you
have used a different folder structure or a different file name,
then this is the place to specify the appropriate relative path.
Files
The files stanza states the files that you want to include in your package - your HTML page, your scripts, the SDK
script and your logo. Set addressable to true unless you include other files that don't need to be URL -
addressable.
NOTE
For more information about the extension manifest file, such as its properties and what they do, check out the extension
manifest reference.
npm i -g tfx-cli
NOTE
An extension/integration's version must be incremented on every update.
When updating an existing extension, either update the version in the manifest or pass the --rev-version command line
switch. This will increment the patch version number of your extension and save the new version to your manifest.
After you have your packaged extension in a .vsix file, you're ready to publish your extension to the marketplace.
Create publisher for the extension
All extensions, including those from Microsoft, are identified as being provided by a publisher. If you aren't already
a member of an existing publisher, you'll create one.
1. Sign in to the Visual Studio Marketplace Publishing Portal
2. If you are not already a member of an existing publisher, you'll be prompted to create a publisher. If you're not
prompted to create a publisher, scroll down to the bottom of the page and select Publish Extensions underneath
Related Sites.
Specify an identifier for your publisher, for example: mycompany-myteam
This will be used as the value for the publisher attribute in your extensions' manifest file.
Specify a display name for your publisher, for example: My Team
3. Review the Marketplace Publisher Agreement and click Create
Now your publisher is defined. In a future release, you'll be able to grant permissions to view and manage your
publisher's extensions. This will make it easy (and more secure) for teams and organizations to publish extensions
under a common publisher, but without the need to share a set of credentials across a set of users.
You need to update the vss-extension.json manifest file in the samples to replace the dummy publisher
ID fabrikam with your publisher ID.
Publish and share the extension
After creating a publisher, you can now upload your extension to the marketplace.
1. Find the Upload new extension button, navigate to your packaged .vsix file, and select upload.
You can also upload your extension via the command line by using the tfx extension publish command instead
of tfx extension create to package and publish your extension in one step. You can optionally use --share-with
to share your extension with one or more accounts after publishing. You'll need a personal access token, too.
Step 1: HTML
Copy the file hello-world.html from the previous example, and rename the copy to hello-world2.html . Your
folder will now look like below:
|--- README.md
|--- sdk
|--- node_modules
|--- scripts
|--- VSS.SDK.min.js
|--- img
|--- logo.png
|--- scripts
|--- hello-world.html // html page to be used for your widget
|--- hello-world2.html // renamed copy of hello-world.html
|--- vss-extension.json // extension's manifest
Add a new div element right below the h2 to hold the query information. Update the name of the widget from
HelloWorldWidget to HelloWorldWidget2 in the line where you call VSS.register . This will allow the framework to
uniquely identify the widget within the extension.
<!DOCTYPE html>
<html>
<head>
<script src="sdk/scripts/VSS.SDK.min.js"></script>
<script type="text/javascript">
VSS.init({
explicitNotifyLoaded: true,
usePlatformStyles: true
});
return WidgetHelpers.WidgetStatusHelper.Success();
}
}
});
VSS.notifyLoadSucceeded();
});
</script>
</head>
<body>
<div class="widget">
<h2 class="title"></h2>
<div id="query-info-container"></div>
</div>
</body>
</html>
{
...,
"scopes":[
"vso.work"
]
}
Warning: Adding or changing scopes after an extension is published is currently not supported. If you have already uploaded
your extension, you need remove it from the marketplace. Go to Visual Studio Marketplace Publishing Portal, right-click on your
extension and select "Remove".
VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"],
function (WidgetHelpers, TFS_Wit_WebApi) {
WidgetHelpers.IncludeWidgetStyles();
VSS.register("HelloWorldWidget2", function () {
var projectId = VSS.getWebContext().project.id;
return WidgetHelpers.WidgetStatusHelper.Success();
}, function (error) {
return WidgetHelpers.WidgetStatusHelper.Failure(error.message);
});
}
return {
load: function (widgetSettings) {
// Set your title
var $title = $('h2.title');
$title.text('Hello World');
return getQueryInfo(widgetSettings);
}
}
});
VSS.notifyLoadSucceeded();
});
Notice the use of the Failure method from WidgetStatusHelper . It allows you to indicate to the widget framework
that an error has occurred and take advantage to the standard error experience provided to all widgets.
If you do not have the Feedback query under the Shared Queries folder, then replace Shared Queries\Feedback
in the code with the path of a query that exists in your project.
VSS.require(["TFS/Dashboards/WidgetHelpers", "TFS/WorkItemTracking/RestClient"],
function (WidgetHelpers, TFS_Wit_WebApi) {
WidgetHelpers.IncludeWidgetStyles();
VSS.register("HelloWorldWidget2", function () {
var projectId = VSS.getWebContext().project.id;
return {
load: function (widgetSettings) {
// Set your title
var $title = $('h2.title');
$title.text('Hello World');
return getQueryInfo(widgetSettings);
}
}
});
VSS.notifyLoadSucceeded();
});
</script>
</head>
<body>
<div class="widget">
<h2 class="title"></h2>
<div id="query-info-container"></div>
</div>
</body>
</html>
{
...,
"contributions":[
...,
{
"id": "HelloWorldWidget2",
"type": "ms.vss-dashboards-web.widget",
"targets": [
"ms.vss-dashboards-web.widget-catalog"
],
"properties": {
"name": "Hello World Widget 2 (with API)",
"description": "My second widget",
"previewImageUrl": "img/preview2.png",
"uri": "hello-world2.html",
"supportedSizes": [
{
"rowSpan": 1,
"columnSpan": 2
}
],
"supportedScopes": ["project_team"]
}
}
],
"files": [
{
"path": "hello-world.html", "addressable": true
},
{
"path": "hello-world2.html", "addressable": true
},
{
"path": "sdk/scripts", "addressable": true
},
{
"path": "img", "addressable": true
}
],
"scopes":[
"vso.work"
]
}
Step 1: HTML
Implementations of Widgets and Widget Configurations are a lot alike. Both are implemented in the extension
framework as contributions. Both use the same SDK file, VSS.SDK.min.js . Both are based on HTML as well as
JavaScript and CSS.
Copy the file html-world2.html from the previous example and rename the copy to hello-world3.html . Add
another HTML file called configuration.html . Your folder will now look like the below:
|--- README.md
|--- sdk
|--- node_modules
|--- scripts
|--- VSS.SDK.min.js
|--- img
|--- logo.png
|--- scripts
|--- configuration.html
|--- hello-world.html // html page to be used for your widget
|--- hello-world2.html // renamed copy of hello-world.html
|--- hello-world3.html // renamed copy of hello-world2.html
|--- vss-extension.json // extension's manifest
Add the below HTML in configuration.html . We basically add the mandatory reference to the VSS.SDK.min.js file
and a select element for the dropdown to select a query from a preset list.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<script src="sdk/scripts/VSS.SDK.min.js"></script>
</head>
<body>
<div class="container">
<fieldset>
<label class="label">Query: </label>
<select id="query-path-dropdown" style="margin-top:10px">
<option value="" selected disabled hidden>Please select a query</option>
<option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
<option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
<option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>
</select>
</fieldset>
</div>
</body>
</html>
<script type="text/javascript">
VSS.init({
explicitNotifyLoaded: true,
usePlatformStyles: true
});
return {
load: function (widgetSettings, widgetConfigurationContext) {
var settings = JSON.parse(widgetSettings.customSettings.data);
if (settings && settings.queryPath) {
$queryDropdown.val(settings.queryPath);
}
return WidgetHelpers.WidgetStatusHelper.Success();
},
onSave: function() {
var customSettings = {
data: JSON.stringify({
queryPath: $queryDropdown.val()
})
};
return WidgetHelpers.WidgetConfigurationSave.Valid(customSettings);
}
}
});
VSS.notifyLoadSucceeded();
});
</script>
VSS.init , VSS.require and VSS.register play the same role as they played for the widget as described in Part 1.
The only difference is that for widget configurations, the function that is passed to VSS.register should return an
object that satisfies the IWidgetConfiguration contract.
The load property of the IWidgetConfiguration contract should have a function as its value. This function will
have the set of steps to render the widget configuration. In our case it is simply to update the selected value of the
dropdown element with existing settings if any. It is this function that is called when the framework instantiates
your widget configuration
The onSave property of the IWidgetConfiguration contract should have a function as its value. This is the function
that is called by the framework when user clicks the "Save" button in the configuration pane. If the user input is
ready to save, then serialize it to a string, form the custom settings object and use
WidgetConfigurationSave.Valid() to save the user input..
In this guide we use JSON to serialize the user input into a string. You can choose any other way to serialize the
user input to string. It will be accessible to the widget via the customSettings property of the WidgetSettings
object. The widget will then have to deserialize this which is covered in Step 4.
Step 3: JavaScript - Enable Live Preview
To enable live preview update when the user selects a query from the dropdown, we attach a change event handler
to the button. This handler will notify the framework that the configuration has changed. It will also pass the
customSettings to be used for updating the preview. To notify the framework, the notify method on the
widgetConfigurationContext needs to be called. It takes two parameters, the name of the event, which in this case is
WidgetHelpers.WidgetEvent.ConfigurationChange , and an EventArgs object for the event, created from the
customSettings with the help of WidgetEvent.Args helper method.
$queryDropdown.on("change", function () {
var customSettings = {
data: JSON.stringify({
queryPath: $queryDropdown.val()
})
};
var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange;
var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings);
widgetConfigurationContext.notify(eventName, eventArgs);
});
You need to notify the framework of configuration change at least once so that the "Save" button can be
enabled.
return {
load: function (widgetSettings, widgetConfigurationContext) {
var settings = JSON.parse(widgetSettings.customSettings.data);
if (settings && settings.queryPath) {
$queryDropdown.val(settings.queryPath);
}
$queryDropdown.on("change", function () {
var customSettings = {data: JSON.stringify({queryPath:
$queryDropdown.val()})};
var eventName = WidgetHelpers.WidgetEvent.ConfigurationChange;
var eventArgs = WidgetHelpers.WidgetEvent.Args(customSettings);
widgetConfigurationContext.notify(eventName, eventArgs);
});
return WidgetHelpers.WidgetStatusHelper.Success();
},
onSave: function() {
var customSettings = {data: JSON.stringify({queryPath:
$queryDropdown.val()})};
return WidgetHelpers.WidgetConfigurationSave.Valid(customSettings);
}
}
});
VSS.notifyLoadSucceeded();
});
</script>
</head>
<body>
<div class="container">
<fieldset>
<label class="label">Query: </label>
<select id="query-path-dropdown" style="margin-top:10px">
<option value="" selected disabled hidden>Please select a query</option>
<option value="Shared Queries/Feedback">Shared Queries/Feedback</option>
<option value="Shared Queries/My Bugs">Shared Queries/My Bugs</option>
<option value="Shared Queries/My Tasks">Shared Queries/My Tasks</option>
</select>
</fieldset>
</div>
</body>
</html>
Open the file hello-world3.html and update the name of the widget from HelloWorldWidget2 to
HelloWorldWidget3 in the line where you call VSS.register . This will allow the framework to uniquely identify the
widget within the extension.
The function mapped to HelloWorldWidget3 via VSS.register currently returns an object that satisfies the IWidget
contract. Since our widget now needs configuration, this function needs to be updated to return an object that
satisfies the IConfigurableWidget contract. To do this, update the return statement to include a property called
reload as below. The value for this property will be a function that calls the getQueryInfo method one more time.
This reload method gets called by the framework everytime the user input changes to show the live preview. This
is also called when the configuration is saved.
return {
load: function (widgetSettings) {
// Set your title
var $title = $('h2.title');
$title.text('Hello World');
return getQueryInfo(widgetSettings);
},
reload: function (widgetSettings) {
return getQueryInfo(widgetSettings);
}
}
The hard-coded query path in getQueryInfo should be replaced with the configured query path which can be
extracted from the parameter widgetSettings that is passed to the method. Add the below in the very beginning
of the getQueryInfo method and replace the hard-coded querypath with settings.queryPath .
return WidgetHelpers.WidgetStatusHelper.Success();
}
At this point, your widget is ready to render with the configured settings.
You will notice that both the load and the reload properties have a similar function. This would be the case
for most simple widgets. For complex widgets, there would be certain operations that you would want to run
just once no matter how many times the configuration changes. Or there might be some heavy-weight
operations that need not run more than once. Such operations would be part of the function corresponding to
the load property and not the reload property.
Note that the contribution for widget configuration follows a slightly different model than the widget itself. A
contribution entry for widget configuration has:
The id to identify your contribution. This should be unique within an extension.
The type of contribution. For all widget configurations, this should be
ms.vss-dashboards-web.widget-configuration
The array of targets to which the contribution is contributing. For all widget configurations, this will have a
single entry: ms.vss-dashboards-web.widget-configuration .
The properties that contains a set of properties which includes name, description, and the URI of the HTML
file used for configuration.
To support configuration, the widget contribution needs to be changed as well. The array of targets for the widget
needs to be updated to include the ID for the configuration in the form < publisher >.< id for the extension >.<
id for the configuration contribution > which in this case will be
fabrikam.vsts-extensions-myExtensions.HelloWorldWidget.Configuration
Warning: If the contribution entry for your configurable widget does not target the configuration using the right publisher and
extension name as described above, then configure button will not show up for the widget.
At the end of this part, the manifest file should contains three widgets and one configuration. You can get the
complete manifest from the sample here.
Step 6: Package, Publish and Share
If you have not published your extension yet, then read this to package, publish and share your extension. If you
have already published the extension before this point, you can repackage the extension as described here and
directly update it to the marketplace.
Step 7: Add Widget From the Catalog
Now, go to your team dashboard at http://yourAccount.visualstudio.com/DefaultCollection/yourProject. If this
page is already open, refresh it. Hover on the Edit button in the bottom right, and click on the Add button. This
should open the widget catalog where you will find the widget you just installed. Choose your widget and click the
'Add' button to add it to your dashboard.
You would see a message asking you to configure the widget.
There are 2 ways to configure widgets. One is to hover on the widget, click on the ellipsis that appears on the top
right corner and then click Configure. The other is to click on the Edit button in the bottom right of the dashboard,
and then click the configure button that appears on the top right corner of the widget. Either will open the
configuration experience on the right side, and a preview of your widget in the center. Go ahead and choose a
query from the dropdown. The live preview will show the updated results. Click on "Save" and your widget will
display the updated results.
Step 8: Configure More (optional)
You can add as many HTML form elements as you need in the configuration.html for additional configuration.
There are two configurable features that are available out of the box: widget name and widget size.
By default, the name that you provide for your widget in the extension manifest is stored as the widget name for
every instance of your widget that ever gets added to a dashboard. You can allow users to configure this, so that
they can add any name they want to their instance of your widget. To allow such configuration, add
isNameConfigurable:true in the properties section for your widget in the extension manifest.
If you provide more than one entry for your widget in the supportedSizes array in the extension manifest, then
users can configure the widget's size as well.
The extension manifest for the third sample in this guide would look like the below if we enable the widget name
and size configuration:
{
...
"contributions": [
... ,
{
"id": "HelloWorldWidget3",
"type": "ms.vss-dashboards-web.widget",
"targets": [
"ms.vss-dashboards-web.widget-catalog", "fabrikam.vsts-extensions-
myExtensions.HelloWorldWidget.Configuration"
],
"properties": {
"name": "Hello World Widget 3 (with config)",
"description": "My third widget",
"previewImageUrl": "img/preview3.png",
"uri": "hello-world3.html",
"isNameConfigurable": true,
"supportedSizes": [
{
"rowSpan": 1,
"columnSpan": 2
},
{
"rowSpan": 2,
"columnSpan": 2
}
],
"supportedScopes": ["project_team"]
}
},
...
}
With the above change, repackage and update your extension. Refresh the dashboard that has this widget (Hello
World Widget 3 (with config)). Open the configuration mode for your widget, you should now be able to see the
option to change the widget name and size.
Go ahead and choose a different size from the drop down. You will see the live preview get resized. Save the
change and the widget on the dashboard will be resized as well.
Warning: If you remove an already supported size, then the widget will fail to load properly. We are working on a fix for a future
release.
You will notice that changing the name of the widget does not result in any visible change in the widget. This is
because our sample widgets do not display the widget name anywhere. Let us modify the sample code to display
the widget name instead of the hard-coded text "Hello World".
To do this, replace the hard-coded text "Hello World" with widgetSettings.name in the line where we set the text of
the h2 element. This will ensure that the widget name gets displayed every time the widget gets loaded on page
refresh. Since we want the live preview to be updated everytime the configuration changes, we should add the
same code in the reload part of our code as well. The final return statement in hello-world3.html will be as
follows:
return {
load: function (widgetSettings) {
// Set your title
var $title = $('h2.title');
$title.text(widgetSettings.name);
return getQueryInfo(widgetSettings);
},
reload: function (widgetSettings) {
// Set your title
var $title = $('h2.title');
$title.text(widgetSettings.name);
return getQueryInfo(widgetSettings);
}
}
Repackage and update your extension again. Refresh the dashboard that has this widget. Any changes to the
widget name in the configuration mode will update the widget title now.
Service Endpoints in VSTS
5/2/2018 • 5 minutes to read • Edit Online
Service endpoints are a way for VSTS to connect to external systems or services. They are a bundle of properties
securely stored by VSTS which includes but is not limited to:
Service Name
Description
Server URL
Certificates or Tokens
User names and passwords
Extensions are then able to leverage the service endpoint to acquire the stored details to perform the necessary
operations on that service. Follow this guide to create a new Service Point contribution and leverage it in your
extension.
Task overview
This article walks through developing a service endpoint by creating an example extension for VSTS that includes:
A custom service endpoint with data sources. This enables a build task or dashboard widget to call a REST
endpoint on the service/server defined by the endpoint.
A build task which defines 2 properties: The service endpoint & a picklist which has values populated from the
REST endpoint data source.
Note: Service endpoints created by users will be created at the project level, not the account level.
NOTE
This tutorial will refer to the home directory for your project as "home".
NOTE
You will need to update the publisher property.
NOTE
"BuildTaskFolder" is the path where we'll eventually place our build task definition
],
"authenticationSchemes": [
{
"type": "ms.vss-endpoint.endpoint-auth-scheme-token"
},
{
"type": "ms.vss-endpoint.endpoint-auth-scheme-basic",
"inputDescriptors": [
{
"id": "username",
"name": "Username",
"description": "Username",
"inputMode": "textbox",
"validation": {
"isRequired": false,
"dataType": "string"
}
},
{
"id": "password",
"name": "Password",
"description": "Password",
"inputMode": "passwordbox",
"isConfidential": true,
"validation": {
"isRequired": false,
"dataType": "string"
}
}
]
}
],
"helpMarkDown": "<a href=\"url-to-documentation\" target=\"_blank\"><b>Learn More</b></a>"
}
},
],
NOTE
Below is what your endpoint will look like after you've packaged and published your extension. See the Next Steps section
below for info on how to package and publish.
If you have successfully added the service contribution correctly, you will see the Fabrikam endpoint when trying to
add a new Service Endpoint to your VSTS account.
{
"id": "build-task",
"description": "Task with a dynamic property getting data from an endpoint REST data source",
"type": "ms.vss-distributed-task.task",
"targets": [ "ms.vss-distributed-task.tasks" ],
"properties": {
"name": "BuildTaskFolder"
}
}
Note that the datasource endpointUrl is usually computed from the url of the endpoint (or a fixed url), and some
additional values. For this tutorial this REST call will return nothing and is meant to be replaced by any REST calls
you wish to make to your service.
It's possible to use other parameters than the endpoint url for the REST URL, for instance some endpoint
properties. For instance, assuming that we had a property in the endpoint named subscriptionId, the REST URL
could use it with the following syntax: $(endpoint.subscription)
NOTE
Take a look at the build task reference to find the schema for the build task json file.
Create a task.json file in your BuildTaskFolder directory, if you have not created this folder yet, do so now.
{
"id": "6557a6d2-4caf-4247-99ea-5131286a8753",
"name": "build-task",
"friendlyName": "Build Task that uses the service endpoint",
"description": "Task with a dynamic property getting data from an endpoint REST data source",
"author": "francistotten",
"helpMarkDown": "Replace with markdown to show in help",
"category": "Build",
"visibility": [
"Build",
"Release"
],
"demands": [],
"version": {
"Major": "0",
"Minor": "1",
"Patch": "1"
},
"minimumAgentVersion": "1.95.0",
"instanceNameFormat": "Service Endpoint Build Task $(project)",
"inputs": [
{
"name": "FabrikamService",
"type": "connectedService:Fabrikam",
"label": "Fabrikam service/server end point",
"defaultValue": "",
"required": true,
"helpMarkDown": "Select the Fabrikam end point to use. If needed, click on 'manage', and add a new
Service Endpoint of type 'Fabrikam server connection'"
},
{
"name": "project",
"type": "pickList",
"label": "Fabrikam Project",
"required": true,
"helpMarkDown": "Select the name of the Fabrikam Project to analyze.",
"properties": {
"EditableOptions": "True"
}
}
],
"dataSourceBindings": [
{
"target": "project",
"endpointId": "$(FabrikamService)",
"dataSourceName": "Fabfrikam Projects"
}
],
"execution": {
"Node": {
"target": "sample.js",
"argumentFormat": ""
},
"PowerShell3": {
"target": "sample.ps1"
}
}
}
task.json components
The FabrikamService input object
This is the first field, of type connectedService:Fabrikam. connectedService expresses the fact that this is an
endpoint type, and Fabrikam is simply the name of the object.
The project input object
This is the second field. It's a picklist
This field is populated by a REST call.
The values from the field "project" are taken from the "Projects" REST data source of the custom endpoint.
This is expressed in the dataSourceBindings array
The target is the name of the build task field to be populated ("project")
The endpointId is the name of the build task field containing the custom endpoint type
The REST call is chosen by the dataSourceName
If you've added the Build Task successfully, you should now see the Build Task when adding tasks to a Build
Definition
Once you've added the Build Task to your definition, confirm that it can see the Fabrikam endpoint you created. The
projects dropdown in this tutorial will be blank since we are not using a real service. Once you replace Fabrikam
with your service, replace the Projects call with your own REST api call to leverage dynamic data inside your build
task
Authentication Documentation
The authentication scheme in a service endpoint determines the credentials that would be used to connect to the
external service. Check out the authentication schemes documentation for more information and to see the
following authentication schemes:
Basic authentication
Token based authentication
Certificate based authentication
No authentication
Next Steps
Now that you've written your extension, the next steps are to Package, Publish, and Install your extension. You can
also check out the documentation for Testing and Debugging your extension.
Package, publish, and install extensions
Testing and debugging extensions
Service hooks in VSTS
4/27/2018 • 3 minutes to read • Edit Online
Service hooks enable you to perform tasks on other services when events happen in your VSTS projects. For
example, create a card in Trello when a work item is created or send a push notification to your team's mobile
devices when a build fails. Service hooks can also be used in custom apps and services as a more efficient way to
drive activities when events happen in your projects.
Note: This tutorial will refer to the home directory for your project as "home".
Create the extension
Add an icon
Add a square image in the images folder that identifies your extension. It will displayed in the Marketplace, and
when someone installs your extension. You don't need to do this for your extension to work, but below is a sample
image you can use along with how it will look with the extension.
NOTE: Name the image logo.png , or remove the "icons" sections from the manifest file if you wish to skip this
step.
{
"manifestVersion": 1,
"id": "samples-service-hooks-consumer",
"version": "0.1.2",
"name": "Service Hooks Sample",
"description": "A simple extension that demonstrates how to contribute a consumer service into service
hooks.",
hooks.",
"publisher": "fabrikam",
"public": false,
"icons": {
"default": "images/logo.png"
},
"scopes": [],
"files": [
{
"path": "images",
"addressable": true
}
],
"content": {
"details": {
"path": "readme.md"
}
},
"categories": [
"Developer samples"
],
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"contributions": [
{
"id": "consumer",
"type": "ms.vss-servicehooks.consumer",
"targets": [
"ms.vss-servicehooks.consumers"
],
"properties": {
"id": "consumer",
"name": "Sample Consumer",
"description": "Sample consumer service",
"informationUrl": "https://aka.ms/vsoextensions",
"inputDescriptors": [
{
"id": "url",
"isRequired": true,
"name": "URL",
"description": "URL to post event payload to",
"inputMode": "textbox"
}
],
"actions": [
{
"id": "performAction",
"name": "Perform action",
"description": "Posts a standard event payload",
"supportedEventTypes": [
"git.push",
"git.pullrequest.created",
"git.pullrequest.updated"
],
"publishEvent": {
"url": "{{{url}}}",
"resourceDetailsToSend": "all",
"messagesToSend": "all",
"detailedMessagesToSend": "all"
}
}
]
}
}
]
}
Note: You will need to update the publisher property.
The icons stanza specifies the path to your extension's icon in your manifest.
The contributions stanza adds your contribution - the consumer service - to your extension manifest.
For each contribution in your extension, the manifest defines
the type of contribution - consumer service (ms.vss-servicehooks.consumer) in this case,
the contribution target - consumer services (ms.vss-servicehooks.consumers) in this case,
and the properties that are specific to each type of contribution. For a consumer service we have:
PROPERTY DESCRIPTION
actions Describes the actions to take and which events trigger them.
Prerequisites
A VSTS account with a Git repo. If you don't have a VSTS account, sign up to upload and share code in free
unlimited private Git repositories.
Install VS Code or other code editor of your choice. The instructions in this guide use VS Code but the steps in
other code editors are similar.
Install Node.js
To install Node.js, download the LTS release appropriate for your platform. The download contains an installer,
which you can run to install the Node.js runtime on your local machine. When installing Node.js, be sure to keep
the npm package manager portion of the install, which is selected by default.
mkdir pr-server
cd pr-server
2. Use the npm init command to create a new package.json file for the project.
npm init
Press Enter to accept the defaults for all of the options except the entry point. Change it to app.js
3. Install Express in the pr-server directory using the following command. This installs Express and saves it to
the dependencies list.
4. Create a simple Express app to build upon for the PR status server. The following steps are based on the
Express Hello world example. Open the project folder in VS Code by running the following command from
the pr-server folder.
code .
5. Create a new file (Ctrl + N) and paste in the following sample code.
app.listen(3000, function () {
console.log('Example app listening on port 3000!')
})
node app.js
node app.js
Ngrok will create a public URL that forwards to localhost:3000 . Note that URL as you will need it in the
next step. It will look something like this:
http://c3c1bffa.ngrok.io
4. From the navigation menu, hover over the gear and select Service Hooks.
If you already have other service hooks configured, select the green plus (+) to create a new service hook
subscription.
6. On the New Service Hooks Subscription dialog, select Web Hooks from the list of services, then select
Next.
7. Select Pull request created from the list of event triggers, then select Next.
8. In the Action page, enter the URL from ngrok in the URL box. Select Test to send a test event to your server.
In the ngrok console window, you'll see an incoming POST that returned a 200 OK , indicating your server
received the service hook event.
HTTP Requests
-------------
POST / 200 OK
In the Test Notification window, select the Response tab to see the details of the response from your server.
You should see a content length of 17 that matches the length of the string from your POST handler (i.e.
"Received the POST").
9. Close the Test Notification window, and select Finish to create the service hook.
app.use(bodyParser.json());
3. To simplify making REST API call to VSTS, install the vso-node-api package.
npm install vso-node-api
4. Update app.js to use the vso-node-api package, set up the details for a connection to your account, and get
an instance of the Git API.
5. Create an environment variable for your collection URL, replacing <your account> with the name of your
VSTS account.
6. Create a personal auth token (PAT) for your app to use, following these instructions: Authenticating with
personal access tokens. You should create a new PAT for every service that you use to access your account,
naming it appropriately.
7. Create an environment variable for your PAT.
8. Update the post() function to read the PR details from the service hook payload. You'll need these values
in order to post back status.
10. Instead of just blindly posting the succeeded status, inspect the PR title to see if the user has indicated if the
PR is a work in progress by adding WIP to the title. If so, change the status posted back to the PR.
if (title.includes("WIP")) {
prStatus.state = "pending";
prStatus.description = "Work in progress"
}
11. Finally, post the status using the createPullRequestStatus() method. It requires the status object, the repo
ID, and the pull request ID. Output the response to the node console so you can see the result of the post.
// Get the details about the PR from the service hook payload
var repoId = req.body.resource.repository.id;
var pullRequestId = req.body.resource.pullRequestId;
var title = req.body.resource.title;
node app.js
5. Add WIP in the title to test the functionality of the app. Select Create to create the PR.
6. Once the PR has been created, you will see the status section, with the Work in progress entry which links
to the URL specified in the payload.
7. Update the PR title and remove the WIP text and note that the status changes from Work in progress to
Ready for review.
Next Steps
In this article, you learned the basics of how to create a service that listens for PR events via service hooks and
can post status messages using the status API. For more information about the pull request status API see the
REST API documentation.
Configure a branch policy for an external service.
Use Azure Functions to create custom branch policies
6/29/2018 • 6 minutes to read • Edit Online
Prerequisites
A VSTS account with a Git repo. If you don't have a VSTS account, sign up to upload and share code in free
unlimited private Git repositories.
using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;
// Get the pull request object from the service hooks payload
dynamic jObject = JsonConvert.DeserializeObject(data.ToString());
log.Info("Service Hook Received for PR: " + pullRequestId + " " + pullRequestTitle);
return req.CreateResponse(HttpStatusCode.OK);
}
catch (Exception ex)
{
log.Info(ex.ToString());
return req.CreateResponse(HttpStatusCode.InternalServerError);
}
}
3. From the navigation menu, hover over the gear and select Service Hooks.
5. On the New Service Hooks Subscription dialog, select Web Hooks from the list of services, then select
Next.
6. Select Pull request created from the list of event triggers, then select Next.
7. In the Action page, enter the URL that you copied in step 1 in the URL box. Select Test to send a test event
to your server.
In the Azure function log window, you'll see an incoming POST that returned a 200 OK , indicating your
function received the service hook event.
HTTP Requests
-------------
POST / 200 OK
In the Test Notification window, select the Response tab to see the details of the response from your server.
You should see the response from your server.
8. Close the Test Notification window, and select Finish to create the service hook.
Go through steps 2-8 again but this time configure the Pull request updated event.
Create a pull request to verify your Azure function is receiving notifications.
IMPORTANT
This sample code stores the PAT in code to simplify the sample. It is recommended to store secrets in KeyVault and retrieve
them from there.
This sample inspects the PR title to see if the user has indicated if the PR is a work in progress by adding WIP to
the title. If so, the sample code changes the status posted back to the PR. Replace the code in your Azure function
with the following code to implement updating the status posted back to the PR.
#r "Newtonsoft.Json"
using System;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using Newtonsoft.Json;
private static string accountName = "[Account Name]"; // Account name
private static string projectName = "[Project Name]"; // Project name
private static string repositoryName = "[Repo Name]"; // Repository name
/*
This is here just to simplify the sample, it is recommended to store
secrets in KeyVault and retrieve them from there.
*/
private static string pat = "[PAT TOKEN]";
// Get the pull request object from the service hooks payload
dynamic jObject = JsonConvert.DeserializeObject(data.ToString());
log.Info("Service Hook Received for PR: " + pullRequestId + " " + pullRequestTitle);
PostStatusOnPullRequest(pullRequestId, ComputeStatus(pullRequestTitle));
return req.CreateResponse(HttpStatusCode.OK);
}
catch (Exception ex)
{
log.Info(ex.ToString());
return req.CreateResponse(HttpStatusCode.InternalServerError);
}
}
if (pullRequestTitle.ToLower().Contains("wip"))
{
state = "pending";
description = "Work in progress";
}
return JsonConvert.SerializeObject(
new
{
State = state,
Description = description,
TargetUrl = "http://visualstudio.microsoft.com",
Context = new
{
Name = "PullRequest-WIT-App",
Genre = "pr-azure-function-ci"
}
});
}
3. Be sure to commit the changes to a new branch so you can create a PR in the next step.
4. Select the Create a pull request link.
5. Add WIP in the title to test the functionality of the app. Select Create to create the PR.
6. Once the PR has been created, you will see the status section, with the Work in progress entry which links
to the URL specified in the payload.
7. Update the PR title and remove the WIP text and note that the status changes from Work in progress to
Ready for review.
Next Steps
In this article, you learned the basics of how to create a serverless Azure function that listens for PR events via
service hooks and can post status messages using the status API. For more information about the pull request
status API see the REST API documentation.
Configure a branch policy for an external service.
Add a chart
6/7/2018 • 4 minutes to read • Edit Online
This page demonstrates how you can add charts to your extensions. Charts can be added to any VSTS extension.
Currently, adding charts via extensions is only available for VSTS.
These charts are easy to create, resizable, intertactive and consistent with the VSTS look and feel. The following
chart types are supported:
1. Line
2. Bar
3. Column
4. Area
5. Stacked bar
6. Stacked column
7. Stacked area
8. Pie
9. Pivot table
10. Histogram
If you're in a hurry and want to get your hands on the code right away, you can download the complete
samples. Once downloaded, go to the charts folder, then follow the packaging and publishing instructions to
publish the sample extension. The extension contains sample chart widgets.
<!DOCTYPE html>
<html>
<head>
<script src="sdk/scripts/VSS.SDK.js"></script>
<script src="scripts/pie-chart.js"></script>
</head>
<body>
<div class="widget">
<h2 class="title">Chart Widget</h2>
<div id="Chart-Container"></div>
</div>
</body>
</html>
Use the npm install command to retrieve the SDK: npm install vss-web-extension-sdk . To learn more about
the SDK, visit the Client SDK GitHub Page.
Ensure that the VSS.SDK.js file is inside the sdk/scripts folder so that the path is home/sdk/scripts/VSS.SDK.js .
Images
Add the following images to an img folder in your project directory so that the path is home/img/logo.png and
home/img/CatalogIcon.png :
1. Extension logo
2. Catalog icon
Extension manifest file
In the home folder of your project, create your [extension manifest file](../develop/manifest.md. Create a
vss-extension.json file with the following contents:
{
"manifestVersion": 1,
"id": "samples-charts",
"version": "1.0.0",
"name": "Interactive Charts in VSTS",
"description": "Samples of interactive charts from the Chart SDK.",
"publisher": "Fabrikam",
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"icons": {
"default": "img/logo.png"
},
"demands": ["contribution/ms.vss-dashboards-web.widget-sdk-version-2", "contribution/ms.vss-web.charts-
service"],
"contributions": [
{
"id": "chart",
"type": "ms.vss-dashboards-web.widget",
"targets": [
"ms.vss-dashboards-web.widget-catalog"
],
"properties": {
"name": "Sample Chart",
"description": "A simple chart widget with no configuration and hard-coded data.",
"catalogIconUrl": "img/CatalogIcon.png",
"uri": "chart.html",
"supportedSizes": [
{
"rowSpan": 2,
"columnSpan": 2
}
],
"supportedScopes": [
"project_team"
]
}
}
],
"files": [
{
"path": "chart.html",
"addressable": true
},
{
"path": "sdk/scripts/VSS.SDK.js",
"addressable": true
},
{
"path": "img",
"addressable": true
},
{
"path": "scripts",
"addressable": true
}
],
"scopes": [
]
}
Before uploading this extension, you'll need to update the publisher to yours.
Put the following code snippets into a chart.js file in a scripts folder, so that the path is home/scripts/chart.js .
Then follow the packaging and publishing instructions to publish your extension.
Charts
Pie chart
This sample renders a pie chart. The data and labelValues have been hardcoded here, and would need to be
changed to the data you want to visualize.
VSS.init({
explicitNotifyLoaded: true,
usePlatformStyles: true
});
VSS.require([
"TFS/Dashboards/WidgetHelpers",
"Charts/Services"
],
function (WidgetHelpers, Services) {
WidgetHelpers.IncludeWidgetStyles();
VSS.register("PieChart", function () {
return {
load:function() {
return Services.ChartsService.getService().then(function(chartService){
var $container = $('#Chart-Container');
var chartOptions = {
"hostOptions": {
"height": "290",
"width": "300"
},
"chartType": "pie",
"series": [{
"data": [11, 4, 3, 1]
}],
"xAxis": {
"labelValues": ["Design", "On Deck", "Completed", "Development"]
},
"specializedOptions": {
"showLabels": "true",
"size": 200
}
};
chartService.createChart($container, chartOptions);
return WidgetHelpers.WidgetStatusHelper.Success();
});
}
}
});
VSS.notifyLoadSucceeded();
});
Here, the chart's size is defined in hostOptions . The series property is an array and contains a single object with
data in it. The xAxis object contains labelValues which correspond to the data . For pie charts, we also have
some special options that are defined by the specializedOptions property. Here, we're explicitly enabling data
labels for the pie chart. We also need to set the size of the pie chart by specifying its outer diameter.
Rendering the chart requires a container to render it in, the chart options, and a call to the Chart Service to get
initialize the chart and render it.
Stacked area chart
This sample renders a stacked area chart.This chart type is ideal for comparing a relationship of parts to a whole
and highlighting general trends across categories. It is commonly used to compare trends over time. This sample
also specifies a custom color for one of the series being rendered.
VSS.init({
explicitNotifyLoaded: true,
usePlatformStyles: true
});
VSS.require([
"TFS/Dashboards/WidgetHelpers",
"Charts/Services"
],
function (WidgetHelpers, Services) {
WidgetHelpers.IncludeWidgetStyles();
VSS.register("StackedAreaChart", function () {
return {
load:function() {
return Services.ChartsService.getService().then(function(chartService){
var $container = $('#Chart-Container');
var chartOptions = {
"hostOptions": {
"height": "290",
"width": "300"
},
"chartType": "stackedArea",
"series": [
{
"name": "Completed",
"data": [1,3,4,3,6,1,9,0,8,11]
},
{
"name": "Development",
"data": [1,1,0,3,0,2,8,9,2,8]
},
{
"name": "Design",
"data": [0,0,0,6,1,1,9,9,1,9],
"color": "#207752"
},
{
"name": "On Deck",
"data": [1,2,4,5,4,2,1,7,0,6]
}
],
"xAxis": {
"labelFormatMode": "dateTime_DayInMonth",
"labelValues": [
"1/1/2016",
"1/2/2016",
"1/3/2016",
"1/4/2016",
"1/5/2016",
"1/6/2016",
"1/7/2016",
"1/8/2016",
"1/9/2016",
"1/10/2016"
]
}
}
chartService.createChart($container, chartOptions);
return WidgetHelpers.WidgetStatusHelper.Success();
});
}
}
});
VSS.notifyLoadSucceeded();
});
Pivot table
This sample renders a Pivot Table. This chart type helps arrange and summarize complex data in a tabular form.
VSS.init({
explicitNotifyLoaded: true,
usePlatformStyles: true
});
VSS.require([
"TFS/Dashboards/WidgetHelpers",
"Charts/Services"
],
function (WidgetHelpers, Services) {
WidgetHelpers.IncludeWidgetStyles();
VSS.register("PivotTable", function () {
return {
load:function() {
return Services.ChartsService.getService().then(function(chartService){
var $container = $('#Chart-Container');
var chartOptions = {
"hostOptions": {
"height": "290",
"width": "300"
},
"chartType": "table",
"xAxis": {
"labelValues": ["Design","In Progress","Resolved","Total"]
},
"yAxis": {
"labelValues": ["P1","P2","P3","Total"]
},
"series": [
{
"name": "Design",
"data": [
[0,0,1],
[0,1,2],
[0,2,3]
]
},
{
"name": "In Progress",
"data": [
[1,0,4],
[1,1,5],
[1,2,6]
]
},
{
"name": "Resolved",
"data": [
[2,0,7],
[2,1,8],
[2,2,9]
]
},
{
"name": "Total",
"data": [
[3,0,12],
[3,1,15],
[3,2,18],
[0,3,6],
[1,3,15],
[2,3,24],
[3,3,10]
],
"color": "rgba(255,255,255,0)"
"color": "rgba(255,255,255,0)"
}
]
}
chartService.createChart($container, chartOptions);
return WidgetHelpers.WidgetStatusHelper.Success();
});
}
}
});
VSS.notifyLoadSucceeded();
});
Data storage
4/27/2018 • 8 minutes to read • Edit Online
VSTS extensions have the ability to store user preferences and complex data structures directly on Microsoft-
provided infrastructure. This ensures your user's data is secure and backed up just like other account and project
data. It also means for simple data storage needs, you (as the extension provider) are not required to setup or
manage (or pay for) third-party data storage services.
There are two ways to interact with the data storage service: REST APIs or a Microsoft-provided client service
available as part of the VSS SDK. It is highly recommended that extension developers use the provided client
service APIs, which provide a convenient wrapper over the REST APIs.
What you can store
The service is designed to let you store and manage two different types of data:
1. Settings: simple key-value settings (like user preferences)
2. Documents: collections of similar complex objects (documents)
A collection is as an indexed container for documents. A document is a JSON blob that belongs to a collection.
Other than a few reserved property names, the schema of these documents is controlled and managed by you.
How you can scope data
Settings and document collections can be scoped to either the:
1. Project Collection: shared by all users of the project collection to which the extension is installed
2. User: a single user of a project collection to which the extension is installed
Setting storage
The two primary functions for interacting with settings are getValue() and setValue():
getValue() takes a string key (and other options such as scope) and returns an IPromise. The resolution of this
promise will contain a value for the provided key.
setValue() take a string key and a value (and other options such as scope) and returns an IPromise. The
resolution this promise will contain the new value of the setting.
Here is an example of how to set a value:
If scopeType is not specified, the settings are stored at the project collection level and they are accessible to all
users in that project collection using the extension. Here is an example of how to set a setting value at the project
collection level:
This call will attempt to retrieve a document with the ID "MyDocumentId", from the collection "MyCollection".
Since no scope is provided, the collection that the service will use is scoped to the default of the entire instance of
this extension. If this collection does not exist or a document with that ID does not exist, then a 404 will be returned,
which should be handled by the extension. The document that is returned is a JSON object containing all of its own
properties, in addition to the special ID and __etag properties used by the data storage service.
Create a document
To create a new document, perform a call such as the following:
dataService.createDocument("MyCollection", newDoc).then(function(doc) {
// Even if no ID was passed to createDocument, one will be generated
console.log("Doc id: " + doc.id);
});
});
If the collection with the name and scope provided, does not yet exist, it will be created dynamically before the
document itself is created.
If the document provided contains an id property, that value will be used as the unique ID for the document. If
that field does not exist, a GUID will be generated by the service and included on the document that is returned
when the promise is resolved.
If another document in the collection already exists with the same ID as the one provided on the document, the
operation will fail. If the desired behavior is create a new document if the ID does not exist, but modify the existing
document if it does, then the setDocument() method should be used.
Set a document (update or create )
setDocument() performs the equivalent of an "upsert" operation - modifying an existing document if there is an ID
on the document provided that exists in the collection. If the ID does not exist, or no ID was provided, then a new
document will be added to the collection.
dataService.setDocument("MyCollection", myDoc).then(function(doc) {
console.log("Doc id: " + doc.id);
});
});
Update a document
updateDocument requires that the document which is being modified already exists in the collection. If no ID is
provided or the ID provided on the document does not exist in the collection, then an exception is thrown.
Here is an example of how update is used:
// Get data service
VSS.getService(VSS.ServiceIds.ExtensionData).then(function(dataService) {
var collection = "MyCollection";
var docId = "1234-4567-8910";
// Get document first
dataService.getDocument(collection, docId, { scopeType: "User" }).then(function(doc) {
// Update the document
doc.name = "John Doe";
dataService.updateDocument(collection, doc, { scopeType: "User" }).then(function(d) {
// Check the new version
console.log("Doc version: " + d.__etag);
});
});
});
Delete a document
This function will delete the document with the provided ID from the provided collection. If the collection does not
exist or the document does not exist, a 404 will be returned.
Here is an example usage:
This call will return all documents within a scoped collection. If the collection does not exist, a 404 will be returned.
Advanced
How settings are stored
This call wraps the setDocument client method, passing it several pieces of information. As previously mentioned,
settings are stored as documents internally, so a simple document is created on the fly, where the ID of the
document, is the key that was provided in the setValue() method. There are two additional properties on the
document. One is 'value', which contains value passed to the method. The other is 'revision', which is set to -1. The
revision property will be discussed in more detail in the "Working with Documents" section, but in the context of
settings, by passing revision: -1 in the document, we are indicating that we do not care about the versioning of this
setting document.
Because settings are stored as documents, we need to provide a collection name, indicating where to store the
document. To keep things simple, when working with the setValue()/getValue() methods, the collection name will
always be the special name '$settings'. The call above would issue a PUT Request at the following endpoint:
GET
_apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName}/Data/Scopes/User/Me/Collections/%
24settings/Documents
{
"id": "myKey",
"__etag": -1,
"value": "myValue"
}
REST APIs
Assuming this snippet is executed after the value has already been set, you should see an alert message containing
the text "The value is myValue". The getValue method is again a wrapper around the REST APIs, issuing a GET
request to the following endpoint:
GET
_apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName}/Data/Scopes/User/Me/Collections/%
24settings/Documents/myKey
etags
The __etag field is how the Data Storage Service handles document concurrency. Before an update to a document
is stored by the service, a check is performed to verify that the __etag of the document currently stored is equal to
the __etag of the document passed as part of the updated. If this check succeeds, the __etag is incremented, and
the new document is returned to the caller. If this check fails, it means that the document that was attempted to be
updated was out of date, and an exception will be thrown. It is up to the extension writer to gracefully handle this
exception, by either getting the latest __etag of the document merging the changes, and re-attempting the update,
or bubbling up a message to the user.
There may be certain types of documents where this level of concurrency is not needed, and a last-in-wins model is
what is actually desired. For these cases, when editing the document, pass -1 as the __etag value, to indicate this
type of functionality. The settings service described above uses this model for saving settings and preferences.
Add tabs on backlog pages
6/7/2018 • 2 minutes to read • Edit Online
If you have a web page that can be hosted in an iframe, it can be hosted in VSTS as a tab on the backlog pages. In
this example, we'll add a simple Hello World tab on the Product Backlog and the Iteration Backlog.
...
"contributions": [
{
"id": "Fabrikam.HelloWorld.Backlog.Tabs",
"type": "ms.vss-web.tab",
"description": "Adds a 'Hello' tab to the Product and Iteration backlog tabs.",
"targets": [
"ms.vss-work-web.product-backlog-tabs",
"ms.vss-work-web.iteration-backlog-tabs",
],
"properties": {
"name": "Hello",
"uri": "hello-world.html",
"registeredObjectId": "backlogTabObject"
}
}
],
"scopes": [
"vso.work"
],
"files": [
{
"path": "hello-world.html", "addressable": true
},
{
"path": "scripts", "addressable": true
},
{
"path": "sdk/scripts", "addressable": true
},
{
"path": "images/logo.png", "addressable": true
}
]
...
Contributions
The contributions stanza contains information about your tasks.
For each contribution in your extension, the manifest defines
the type of contribution (tab in this case),
the contribution target (the product or iteration backlog tabs in this case),
and the properties that are specific to each type of contribution. For a tab, we have
PROPERTY DESCRIPTION
registeredObjectId Id of the object registered for the tab. Include code like the
example below in the html file indicated in the "uri" property
of the contribution shown above.
Scopes
It includes the scopes that your extension requires. In this case, we need vso.work to access work items.
Files
Include all of the files your extension will access.
For your files, set addressable to true unless you include other files that don't need to be URL -addressable.
Example registeredObjectId
VSS.register("backlogTabObject", {
pageTitle: function(state) {
return "Hello Tab";
},
updateContext: function(tabContext) {
},
isInvisible: function(state) {
return false;
},
isDisabled: function(state) {
return false;
}
});
Learn about all of the places where you can add a hub in the contributions reference.
Next Steps:
Now that you've written your extension, the next steps are to Package, Publish, and Install it. You can also check out
the documentation for Testing and Debugging your extension.
In this example, we'll add a simple Hello World extension as a panel on the Portfolio backlog, Product backlog, and
Iteration backlog.
The custom panel opens in the same space that the mapping panel opens if it were selected.
There are three types of backlogs that can be targets for panel extensions: Portfolio backlogs, Product backlogs,
and Iteration backlogs. For the Agile template, this breakdown is as below. This is representitive of Scrum and
CMMI as well. For custom templates, please consult your process to see which backlogs are requirement or
portfolio category.
See the VSTS Extension Samples on GitHub for the full source of an example extension.
...
"contributions": [
{
"id": "Fabrikam.HelloWorld.Backlogs.Panel",
"type": "ms.vss-work-web.backlog-panel",
"description": "Adds a 'Hello' panel to Product and Iteration backlog pages.",
"targets": [
"ms.vss-work-web.requirement-backlog-toolpane",
"ms.vss-work-web.portfolio-backlog-toolpane",
"ms.vss-work-web.iteration-backlog-toolpane"
],
"properties": {
"title": "Hello Panel Pane",
"name": "Hello Panel",
"uri": "index.html",
"registeredObjectId": "backlogPanelObject"
}
}
],
"scopes": [
"vso.work"
]
...
Contribution
For each contribution in your extension, the manifest defines
the type of contribution (backlog pannel in this case),
the contribution target (the requirements, portfolio, and iteration backlogs in this case),
and the properties that are specific to each type of contribution. For panels, we have
PROPERTY DESCRIPTION
Learn about all of the places where you can add an extension in the contributions reference.
Scopes
Include thescopes that your extension requires. In this case, we need vso.work to access work items.
...
IContributedPanel {
workItemSelectionChanged: (selectedWorkItems) => void;
}
...
Next Steps
PAC KAG E, P U BL IS H, AN D TES T AN D
IN S TAL L DEBU G
Extend the work item form
6/7/2018 • 7 minutes to read • Edit Online
You can now customize how the work item form is presented to users via contributions made through an
extension:
Add a group to the main page
Add a page (tab)
Add an action to the context menu
Add a custom control
Listen for events on the form
Configure contributions in work item form
If you are just getting started and haven't created an extension, refer to the Create your first extension with Visual
Studio.
See the UI example in the VSTS Extension Samples on GitHub for the full source.
Add a group
To add a group to the main page, add a contribution to your extension manifest. The type of this contribution
should be ms.vss-work-web.work-item-form-group and it should target the ms.vss-work-web.work-item-form
contribution.
"contributions": [
{
"id": "sample-work-item-form-group",
"type": "ms.vss-work-web.work-item-form-group",
"description": "Custom work item form group",
"targets": [
"ms.vss-work-web.work-item-form"
],
"properties": {
"name": "My Group",
"uri": "workItemGroup.html",
"height": 600
}
}
]
Properties
PROPERTY DESCRIPTION
uri URI to a page that hosts the html that shows on the work
item form and its scripts
JavaScript sample
This sample shows how to register an object that is called when various events happen on the work item form that
may impact your contributed group.
VSS.require(["TFS/WorkItemTracking/Services"], function (_WorkItemServices) {
// Get the WorkItemFormService. This service allows you to get/set fields/links on the 'active' work
item (the work item
// that currently is displayed in the UI).
function getWorkItemFormService()
{
return _WorkItemServices.WorkItemFormService.getService();
}
getWorkItemFormService().then(function(service) {
// Get the current values for a few of the common fields
service.getFieldValues(["System.Id", "System.Title", "System.State",
"System.CreatedDate"]).then(
function (value) {
$(".events").append($("<div/>").text("onLoaded - " + JSON.stringify(value)));
});
});
},
// Called when the work item is reset to its unmodified state (undo)
onReset: function (args) {
$(".events").append($("<div/>").text("onReset - " + JSON.stringify(args)));
},
// Called when the work item has been refreshed from the server
onRefreshed: function (args) {
$(".events").append($("<div/>").text("onRefreshed - " + JSON.stringify(args)));
}
}
});
});
Events
EVENT EVENT DESCRIPTION ARGUMENT ARGUMENT DESCRIPTION
onLoaded Fired after when the data is id The ID of the work item.
loaded in the work item
form when the user opens a
work item, or when the user
navigates to another work
item in the triage view.
onReset Fired after the user undoes id The ID of the work item.
the changes to the work
item.
onUnloaded Fired before the user closes id The ID of the work item.
the dialog, or before the
user moves to another work
item in the triage view.
Add a page
A new page is rendered as a tab on the work item form. New pages appear next to the Details tab.
To add a page to the work item form, add a contribution to your extension manifest. The type of this contribution
should be ms.vss-work-web.work-item-form-page and it should target the ms.vss-work-web.work-item-form
contribution.
"contributions": [
{
"id": "sample-work-item-form-page",
"type": "ms.vss-work-web.work-item-form-page",
"description": "Custom work item form page",
"targets": [
"ms.vss-work-web.work-item-form"
],
"properties": {
"name": "My Page",
"uri": "workItemPage.html"
}
}
]
Properties
PROPERTY DESCRIPTION
uri URI to a page that hosts the html that shows on the work
item form and its scripts.
JavaScript sample
See the JavaScript sample in the form group section. The name of the registered object should match the id of
the contribution.
Events
EVENT EVENT DESCRIPTION ARGUMENT ARGUMENT DESCRIPTION
onLoaded Fired after when the data is id The ID of the work item.
loaded in the work item
form when the user opens a
work item, or when the user
navigates to another work
item in the triage view.
onReset Fired after the user undoes id The ID of the work item.
the changes to the work
item.
onUnloaded Fired before the user closes id The ID of the work item.
the dialog, or before the
user moves to another work
item in the triage view.
To add an item to the work item toolbar, add this contribution to your extension manifest. The item will appear in
the ... dropdown in the top right of the work item form.
"contributions": [
{
"id": "sample-work-item-menu",
"type": "ms.vss-web.action",
"description": "Sample toolbar item which updates the title of a work item",
"targets": [
"ms.vss-work-web.work-item-context-menu"
],
"properties": {
"text": "Try me!",
"title": "Updates the title of the work item from the extension",
"toolbarText": "Try me!",
"icon": "images/show-properties.png",
"uri": "menu-workItemToolbarButton.html"
}
}
]
Properties
PROPERTY DESCRIPTION
toolbarText Text that will appear when the item is being hovered over.
icon URL to an icon that will appear on the menu item. Relative
URLs are resolved using baseUri.
"contributions": [
{
"id": "sample-work-item-form-observer",
"type": "ms.vss-work-web.work-item-notifications",
"description": "Gets events about the current work item form for the 'Try Me!' toolbar button",
"targets": [
"ms.vss-work-web.work-item-form"
],
"properties": {
"uri": "myformobserver.html"
}
}
]
Properties
PROPERTY DESCRIPTION
Events
EVENT EVENT DESCRIPTION ARGUMENT ARGUMENT DESCRIPTION
onLoaded Fired after when the data is id The ID of the work item.
loaded in the work item
form when the user opens a
work item, or when the user
navigates to another work
item in the triage view.
onReset Fired after the user undoes id The ID of the work item.
the changes to the work
item.
onUnloaded Fired before the user closes id The ID of the work item.
the dialog, or before the
user moves to another work
item in the triage view.
HTML/JavaScript sample
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Work item extension page sample</title>
</head>
<body>
<script src="sdk/scripts/VSS.SDK.js"></script>
<script>
VSS.init({
usePlatformScripts: true
});
VSS.ready(function () {
// Register a listener for the work item page contribution.
VSS.register(VSS.getContribution().id, function () {
return {
// Called when the active work item is modified
onFieldChanged: function(args) {
},
},
},
},
// Called when the work item is reset to its unmodified state (undo)
onReset: function (args) {
},
// Called when the work item has been refreshed from the server
onRefreshed: function (args) {
}
}
});
});
</script>
</body>
</html>
Add a custom control to the work item form
4/27/2018 • 3 minutes to read • Edit Online
Custom controls allow you to change how users view and interact with a field on the work item form. The
screenshot below shows a sample custom work item control for the Priority field. The following article walks you
through how this sample custom control was built. At the end of the article you will understand how to build your
own custom control.
"contributions": [
{
"id": "sample-work-item-form-control",
"type": "ms.vss-work-web.work-item-form-control",
"description": "Custom work item form control",
"targets": [
"ms.vss-work-web.work-item-form"
],
"properties": {
"name": "My Control",
"uri": "workItemControl.html",
"height": 600
}
}
]
The work item form adds an iframe to host the custom control.
Properties
PROPERTY DESCRIPTION
uri URI to a page that hosts the html that is loaded by the iframe.
If you want to dynamically resize the iframe, you can use the resize method available in the client SDK.
A custom control on the work item form is another type of contribution like group & page contribution. The main
difference between a control contribution and group and page contribution is that a control contribution can take a
set of user inputs while group and page contributions can not.
"inputs": [
{
"id": "FieldName",
"description": "The field associated with the control.",
"type": "WorkItemField",
"properties": {
"workItemFieldTypes": ["String"]
},
"validation": {
"dataType": "String",
"isRequired": true
}
},
{
"id": "Colors",
"description": "The colors that match the values in the control.",
"validation": {
"dataType": "String",
"isRequired": false
}
}
]
These properties define a user input that the contribution can use:
id - A unique id for the input.
description - A few sentences describing the input.
type (optional) - The type of input. Only supported on VSTS and TFS 15 RC2 and later.
Valid values:
WorkItemField - Indicates that the input is a Work Item field. This means that the value provided
by the user for this input should be a valid work item field's reference name.
properties (optional) - Custom properties for the input. Only supported on VSTS and TFS 15 RTM.
Valid keys:
workItemFieldTypes - Defines an array of field types that this input supports. Valid values are -
String
Integer
Double
HTML
PlainText
Boolean
Guid
DateTime
TreePath
validation - A set of properties that defines which values are considered valid for the input.
Valid keys:
dataType - Defines the data type of the input value. Valid values for this property are -
String
Number
Boolean
Field - Only supported in TFS 15 RC1 and RC2 and not in VSTS.
isRequired - A boolean value which indicates if the input is required to have a value or not
JavaScript sample
A control extension works like a group or page extension with one difference that it can take certain user inputs. To
read the user input values, use VSS.getConfiguration().witInputs . This sample shows how to register an object
that is called when various events happen on the work item form that may impact your contributed control. It also
shows how to read input values provided by user for this control.
VSS.register(VSS.getContribution().id, provider);
4/27/2018 • 2 minutes to read • Edit Online
Note: work item form customization via xml is supported only on TFS, not VSTS
Step 3: This creates a file in the directory that you specified. Inside this file, navigate to the section called
"WebLayout". Inside the Weblayout Section a comment blob will be present that specifies what extensions
targeting work item form are installed in your collection. For each extension, all its form contributions will be listed
with their ids and inputs (if it's a Control contribution). In the example below, the comment shows that the "color-
control-dev" extension has been installed on the collection which has one control contribution that takes 2 inputs -
Extension:
Name: color-control-dev
Id: example.color-control-dev
Control contribution:
Id: example.color-control-dev.color-control-contribution
Description:
Inputs:
Id: FieldName
Description: The field associated with the control.
Type: Field
IsRequired: true
Id: Colors
Descriptions: The colors that match the values in the control.
Type: String
IsRequired: false
Extension:
Name: color-control-dev
Id: example.color-control-dev
...
Step 5: Add an extension tag below the "Work Item Extensions" section as shown below to make your extension
available to the work item form. To place a contribution inside the form, its extension must be specified in the
Extensions section.
Note: For more information on work item extensions use the following topic:
http://go.microsoft.com/fwlink/?LinkId=816513
-->
<Extensions>
<Extension Id="example.color-control-dev" />
</Extensions>
Step 6: Specifying the extensions in the xml automaticaly places both the page and group contributions defined
in the extensions inside the form. You can move the contributions following the examples below:
Add page contribution
<Page Id="Details">
<PageContribution Id="<page contribution id>" />
...
<Page Id="Details">
...
<Section>
...
<GroupContribution Id="<group contribution id>" />
...
Note that a page contribution and a group contribution can not take any other layout elements inside them.
If you have a web page that can be hosted in an iframe, it can be hosted in VSTS as a tab on the query result pages.
In this example, we'll add a simple Hello World tab on query results.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Hello World</title>
<script src="sdk/scripts/VSS.SDK.js"></script>
</head>
<body>
<script type="text/javascript">VSS.init();</script>
<h1>Hello World</h1>
<script type="text/javascript">VSS.notifyLoadSucceeded();</script>
</body>
</html>
"contributions": [
{
"id": "Fabrikam.HelloTab.Query.Tabs",
"type": "ms.vss-web.tab",
"description": "Adds a 'Hello' tab to the query results",
"targets": [
"ms.vss-work-web.query-tabs"
],
"properties": {
"uri": "hello-query-tab.html",
"title": "Hello",
"name": "Hello"
}
}
],
"scopes": [
"vso.work"
],
"files": [
{
"path": "hello-query-tab.html", "addressable": true
},
{
"path": "scripts", "addressable": true
},
{
"path": "sdk/scripts", "addressable": true
},
{
"path": "images/logo.png", "addressable": true
}
]
...
Contributions
The contributions stanza contains information about your tasks.
For each contribution in your extension, the manifest defines
the type of contribution (tab in this case),
the contribution target (the query tabs in this case),
and the properties that are specific to each type of contribution. For a tab, we have
PROPERTY DESCRIPTION
Scopes
It includes the scopes that your extension requires. In this case, we need vso.work to access work items.
Files
Include all of the files your extension will access.
For your files, set addressable to true unless you include other files that don't need to be URL -addressable.
Example
VSS.register(VSS.getContribution(), {
pageTitle: function(state) {
return "Hello";
},
updateContext: function(tabContext) {
},
isInvisible: function(state) {
return false;
},
isDisabled: function(state) {
return false;
}
});
Learn about all of the places where you can add a hub in the contributions reference.
Next Steps:
Now that you've written your extension, the next steps are to Package, Publish, and Install it. You can also check out
the documentation for Testing and Debugging your extension.
To call a REST API from your extension, get the client service first, and then use that to call the API.
Client services
You can find the full list of available REST clients and their references here.
Call an API
1. Get the REST client. In this case, we're getting the work item tracking client.
2. Call the API, getWorkItems , using the client service, witClient , with a callback that handles results.
NOTE
VSTS public project support is currently in Limited Preview. Contact vsts-public@microsoft.com if you are interested in
developing extensions that support public projects. To learn more about public projects, see VSTS Public Projects Limited
Preview.
A non-member user is either anonymous (not authenticated to VSTS ) or public (are authenticated to VSTS,
but do not belong to the account).
Non-member users generally see the same views as authenticated users, with non-public functionality such as
settings and actions (such as queue build) either hidden or disabled.
Contribution visibility
By default, contributions are only visible to account members. To give non-member users visibility to a
contribution, set the restrictedTo attribute on that contribution. The value is a string array that lists which types of
users should have visibility to the contribution. The possible values are:
member an authenticated user that is a member of the account
public an authenticated user that is not a member of the account
anonymous an un-authenticated user
You can also set the default visibility for all contributions in your extension by setting the restrictedTo attribute at
the root your extension manifest. You can then override this default on individual contributions.
Example: make every contribution, except for one, visible to all users
{
"id:": "my-extension",
"name": "My Extension",
"version": "1.0.0",
...
"restrictedTo": [
"anonymous",
"public",
"member"
],
"contributions": [
{
"id": "my-member-only-widget",
"type": "ms.vss-dashboards-web.widget",
"restrictedTo": [
"member"
],
"properties": {
...
}
},
{
"id": "my-hub",
"type": "ms.vss-web.hub",
"targets": [
"ms.vss-code-web.code-hub-group"
],
"properties": {
...
}
},
{
"id": "my-second-hub",
"type": "ms.vss-web.hub",
"targets": [
"ms.vss-work-web.work-hub-group"
],
"properties": {
...
}
}
]
}
Limitations
If you want to make some or all aspects of your contribution available to public users, be aware of the following
limitations.
VSS SDK methods
The core SDK script, VSS.SDK.js, allows web extensions to communicate with the parent frame to perform
operations like initializing communication and getting context information about the current user. The following
VSS SDK methods are not supported for non-member users:
VSS.getAccessToken()
VSS.getAppToken()
VSS.getService(VSS.ServiceIds.ExtensionData).then(function(dataService) {
dataService.getValue("someKey").then(function(value) {
// do something with the value
}, function(error) {
if (error.name === "AccessCheckException") {
alert(error.message);
}
});
});
REST APIs
A limited set of VSTS REST APIs are available to non-member users. This includes most account-level APIs and
project-level APIs for features unavailable to non-member users in general. You should take this into consideration
when deciding whether or not to make your extension available to non-member users.
It is also recommended that you use version 5.0 and later APIs, as certain APIs are only available to non-member
users starting with version 5.0.
Identity references
A majority of VSTS REST APIs use a common "contract" to represent a user or group. To protect member
information, like email addresses, when a REST API is invoked by an anonymous or public user, certain fields, like
uniqueName are omitted.
client.hasPermissionsBatch({
evaluations: [
{
"securityNamespaceId": "33344D9C-FC72-4d6f-ABA5-FA317101A7E9",
"token": securityToken,
"permissions": 128 /* queue builds */
}
]
}
).then(function(response) {
console.log("Can user queue builds in this project? " + response.evaluations[0].value);
});
});
Dashboard widget considerations
Just like other types of contributions, the visibility of dashboard widget contributions is controlled with the
restrictedTo contribution property. For example to make a widget visible to both non-member and member
users:
{
"contributions": [
{
"id": "HelloWorldWidget",
"type": "ms.vss-dashboards-web.widget",
"targets": [
"ms.vss-dashboards-web.widget-catalog"
],
"restrictedTo": [
"member",
"public",
"anonymous"
],
"properties": {
...
}
}
]
}
Widget settings
In addition to controlling visibility of the widget to non-member users, the dashboard framework provides an
optional, open-form storage mechanism for widget settings. Two mechanisms are available for indicate whether a
widget's settings are available for use by non-member users in public projects.
A widget with configurable settings that is visible to non-member users must follow one of the following patterns.
Not doing so will block the widget from surfacing to these users.
Pattern 1: widget declares its instances only store project-specific settings
Set the widget contribution's canStoreCrossProjectSettings property to false , indicating the widget settings are
project-specific.
{
"id:": "HelloWorldWidget",
"type": "ms.vss-dashboards-web.widget",
...
"properties": {
"canStoreCrossProjectSettings": false
}
}
{
"hasCrossProjectSettings": false,
"hypotheticalWidgetOption": true,
"backlogLevel": "Stories"
}
Build and release considerations
If your extension contributes a build or release task, no change is required to make use of that task from a
definition in a public project.
Our new vertical navigation preview brings with it changes that impact some extensions. This includes support for
extension icons along with changes to team context.
Team context
In traditional horizontal navigation, a user could navigate into a project or team by selecting it from a picker located
in the top left of the page header. This picker presented a list of recent teams and a way to browse for all teams. In
the new vertical navigation, a user can only navigate into a project (and not into a team). This change was made to
simplify the overall experience, but it introduces a challenge for web extensions that rely on users being able to
switch teams using the traditional team picker in the page header.
VSS.getWebContext() is a client-side API provided by the VSS SDK that provides information about the current
account, project, and team the user is operating in:
{
"account": {
"name": "Fabrikam",
"id": "50e49b94-4bb6-40e7-8c85-a6d756d8a4d8"
},
"project": {
"name": "Fabrikam Dev",
"id": "049b1af2-fc87-4e50-95e4-151357f04b7f"
},
"team": {
"name": "Ops Team",
"id": "9b3a6b80-fe95-4c8c-8aa1-1e5d535d7af1"
}
}
We do not recommend relaying on VSS.getWebContext().team and follow below guidance based on category your
extension falls under.
Hub extensions that are team aware
If your extension needs to provide users a way to select a team, you can use the Teams REST API to get a list of
teams for the current project. Here is an example of how to call this API from your extension:
VSS.require(["VSS/Service", "TFS/Core/RestClient"],
function(VSS_Service, Tfs_Core_WebApi) {
var client = VSS_Service.getCollectionClient(Tfs_Core_WebApi.CoreHttpClient4);
client.getTeams(VSS.getWebContext().project.id).then(
function(teams) {
console.log(teams);
}
);
});
For an example of an extension that provides a team picker control, see Team Calendar.
Pivots/Panels/Actions extensions that are in team aware hubs like Backlogs and Dashboard
Your extension can check the configuration object passed to your contribution. This object has different properties
depending on the contribution type and where the contribution is hosted. Example shows reading team from the
configuration and falling back to reading team from webContext to support both new vertical navigation and older
horizontal navigation in on-premise releases.
function getCurrentTeam() {
let webContext = VSS.getWebContext();
let configuration = VSS.getConfiguration();
if ("team" in configuration) {
return configuration.team;
} else if ("team" in webContext) {
return webContext.team;
} else {
return null; // should only happen if not in a project context
}
}
Hub icon
You can optionally set an asset (like a .png or .jpg) as the icon for your hub. This icon appears next to the hub in the
vertical navigation bar. It must be packaged with your extension.
For example:
{
"id": "my-extension",
"publisherId": "my-publisher",
...
"contributions": [
{
"id": "example-hub",
"type": "ms.vss-web.hub",
"targets": [
"ms.vss-code-web.code-hub-group"
],
"properties": {
"name": "My Hub",
"iconAsset": "my-publisher.my-extension/images/fabrikam-logo.png",
"_sharedData": {
"assets": [
"my-publisher.my-extension/images/fabrikam-logo.png"
]
}
}
}
],
"files": [
{
"path": "images/fabrikam-logo.png",
"addressable": true
}
]
}
Configure UI Controls
4/27/2018 • 2 minutes to read • Edit Online
This example shows the steps before you can add a control to the hub that we created in Add a hub.
1. Get the Client SDK and add it to your project.
sdk/scripts/VSS.SDK.js
<head>
<title>Sample app</title>
<script src="sdk/scripts/VSS.SDK.js"></script>
</head>
1. Add a div element in the body of the page to contain the grid.
<div id="grid-container"></div>
2. In the script element, before calling VSS.notifyLoadSucceeded() , initialize the VSS SDK.
// We are using some VSTS APIs, so we will need the module loader to load them in
usePlatformScripts: true,
usePlatformStyles: true
});
3. Create a grid and load it with data. (Replace your current call to VSS.notifyLoadSucceeded() with the
following snippet)
// Load VSTS controls
VSS.require(["VSS/Controls", "VSS/Controls/Grids"],
function (Controls, Grids) {
// Initialize the grid control with two colums, "key" and "value"
var dataSource = [];
dataSource.push({key: "key", value: "value"});
Controls.create(Grids.Grid, $("#grid-container"), {
height: "1000px", // Explicit height is required for a Grid control
columns: [
// text is the column header text.
// index is the key into the source object to find the data for this column
// width is the width of the column, in pixels
{ text: "Property key", index: "key", width: 150 },
{ text: "Property value", index: "value", width: 600 }
],
// This data source is rendered into the Grid columns defined above
source: dataSource
});
VSS.notifyLoadSucceeded();
});
return result;
} (),
columns: [
{ text: "Column 1", index: 0, width: 50 },
{ text: "Column 2", index: 1, width: 200, canSortBy: false },
{ text: "Column 3", index: 2, width: 450 }]
};
var source = [
{ name: "Germany", population: 8e7 },
{ name: "Turkey", population: 75e6 },
{ name: "Russia", population: 15e7 },
{ name: "Spain", population: 45e6 }
];
}, 5000);
Context menu
This sample shows the usage of contextMenu for each row in the grid. The item associated with the context menu
is obtained using args.get_commandArgument().item in menuItemClick function.
import Controls = require("VSS/Controls");
import Grids = require("VSS/Controls/Grids");
import Menus = require("VSS/Controls/Menus");
function menuItemClick(args) {
// Get the item associated with the context menu
var person = args.get_commandArgument().item;
switch (args.get_commandName()) {
case "open":
alert(JSON.stringify(person));
break;
case "delete":
confirm("Are you sure you want to delete " + person[0] + "?");
break;
}
}
Hierarchy
By default first column is indented. Setting indent: true for a particular column will cause that column to have
indentation for hierarchy. See column options in the below sample. Settings collapsed: true will get a parent
item to be displayed collapsed. To update the data source, use gridSource.update(newItems); .
import Controls = require("VSS/Controls");
import Grids = require("VSS/Controls/Grids");
Conditional formatting
This sample shows the customization of the grid cells. "Total" column is a calculated column and styled differently
in getCellContents method.
function getColumns() {
return [
{
index: "region",
index: "region",
text: "Region",
width: 80
},
{
index: "rep",
text: "Representative",
width: 80
},
{
index: "orderDate",
text: "Order Date",
width: 100,
getCellContents: function (
rowInfo,
dataIndex,
expandedState,
level,
column,
indentIndex,
columnOrder) {
function getSortOder() {
return [{ index: "orderDate", order: "asc" }];
}
function getDataSource() {
return [
{ orderDate: new Date(2010, 0, 6), region: 'Quebec', rep: 'Jones', item: 'Pencil', unit: 95, cost: 1.99
},
{ orderDate: new Date(2010, 0, 23), region: 'Ontario', rep: 'Kivell', item: 'Binder', unit: 50, cost:
19.99 },
{ orderDate: new Date(2010, 1, 9), region: 'Ontario', rep: 'Jardine', item: 'Pencil', unit: 36, cost:
4.99 },
{ orderDate: new Date(2010, 1, 26), region: 'Ontario', rep: 'Gill', item: 'Pen', unit: 27, cost: 19.99
},
{ orderDate: new Date(2010, 2, 15), region: 'Alberta', rep: 'Sorvino', item: 'Pencil', unit: 56, cost:
2.99 },
{ orderDate: new Date(2010, 3, 1), region: 'Quebec', rep: 'Jones', item: 'Binder', unit: 60, cost: 4.99
},
{ orderDate: new Date(2010, 3, 18), region: 'Ontario', rep: 'Andrews', item: 'Pencil', unit: 75, cost:
1.99 },
{ orderDate: new Date(2010, 4, 5), region: 'Ontario', rep: 'Jardine', item: 'Pencil', unit: 90, cost:
4.99 },
{ orderDate: new Date(2010, 4, 22), region: 'Alberta', rep: 'Thompson', item: 'Pencil', unit: 32, cost:
1.99 },
{ orderDate: new Date(2010, 5, 8), region: 'Quebec', rep: 'Jones', item: 'Binder', unit: 60, cost: 8.99
},
{ orderDate: new Date(2010, 5, 25), region: 'Ontario', rep: 'Morgan', item: 'Pencil', unit: 90, cost:
4.99 },
{ orderDate: new Date(2010, 6, 12), region: 'Quebec', rep: 'Howard', item: 'Binder', unit: 29, cost:
1.99 },
{ orderDate: new Date(2010, 6, 29), region: 'Quebec', rep: 'Parent', item: 'Binder', unit: 81, cost:
19.99 }
];
}
.row-drag-helper {
background-color: orange;
padding: 5px;
cursor: move;
padding-left: 30px;
}
.lower-drop-guide {
border-bottom-color: orange;
}
.upper-drop-guide {
border-top-color: orange;
}
interface DropTargetInfo {
dataIndex: number;
below: boolean;
}
interface MoveCompleteDelegate {
(oldIndex: number, newIndex: number): void;
}
interface Offset {
left: number;
top: number;
}
class DragDropHandler {
private _gridCanvas: JQuery;
private _gridRowHeight: number;
private _cursorOffset: Offset;
private _dragStartInfo: DragStartInfo;
private _lastDropTarget: JQuery;
constructor(
public grid: Grids.Grid,
public dragdropScope: string,
public dragdropTextProvider: (element: any) => string,
public moveCompleteDelegate: MoveCompleteDelegate) {
this.grid.setupDragDrop(this._getDraggableOptions(), this._getDroppableOptions());
this._gridCanvas = this.grid.getElement().find(".grid-canvas");
this._gridRowHeight = this.grid._rowHeight || 1;
}
return {
cursorAt: this._cursorOffset,
axis: "",
appendTo: document.body,
scroll: false,
scrollables: [".grid-canvas"],
scrollablesAxis: "y",
scope: this.dragdropScope,
distance: 10,
helper: (evt: JQueryEventObject, ui: any) => {
var rowData = this.grid.getRowData(ui.draggingRowInfo.dataIndex);
return $("<div />")
.addClass("row-drag-helper")
.text(this.dragdropTextProvider(rowData));
},
start: (evt: JQueryEventObject, ui: any) => {
this._dragStartInfo = {
top: ui.offset.top,
left: ui.offset.left,
dataIndex: ui.draggingRowInfo.dataIndex,
canvasWidth: this._gridCanvas.width()
};
},
stop: (evt: JQueryEventObject, ui: any) => {
this._dragStartInfo = null;
this._resetLastDropTarget();
},
drag: (evt: JQueryEventObject, ui: any) => {
if (this._dragStartInfo) {
this._resetLastDropTarget();
var dropTargetInfo = this._getRowDataIndex(<Offset>ui.offset, this._dragStartInfo);
if (dropTargetInfo) {
this._lastDropTarget = <JQuery>this.grid.getRowInfo(dropTargetInfo.dataIndex).row;
this._lastDropTarget.addClass(dropTargetInfo.below ? "lower-drop-guide" : "upper-drop-guide");
}
}
}
};
}
// Update grid
grid.setDataSource(gridSource);
<div class="drop-target"></div>
.row-drag-helper {
background-color: orange;
padding: 5px;
cursor: move;
padding-left: 30px;
}
.drop-target {
position: absolute;
top:20px;
right: 20px;
border: 2px dashed blue;
width: 300px;
height: 200px;
overflow: auto;
}
.drop-target::before {
content: "drop here";
position:absolute;
right: 5px;
top: 0;
color: blue;
font-size: 14pt;
.drop-target.active {
background-color: lightgreen
}
import Controls = require("VSS/Controls");
import Grids = require("VSS/Controls/Grids");
draggable: {
cursorAt: { left: 12, top: 12 },
axis: "",
containment: "",
appendTo: document.body,
revert: "invalid",
refreshPositions: true,
scroll: false,
scope: scope,
distance: 10,
helper: (evt: JQueryEventObject, ui: any) => {
var rowData = grid.getRowData(ui.draggingRowInfo.dataIndex);
var $helper = $("<div />")
.addClass("row-drag-helper")
.text(`Moving item: ${JSON.stringify(rowData[1]) }`);
$helper.data("rowData", rowData);
return $helper;
}
}
};
$(".drop-target").droppable({
scope: scope,
over: function (e, ui) {
var $dropTarget = $(e.target);
$dropTarget.addClass("active");
},
out: function (e, ui) {
var $dropTarget = $(e.target);
$dropTarget.removeClass("active");
},
drop: function (e, ui) {
var $dropTarget = $(e.target);
$dropTarget.removeClass("active");
Basic menubar
This sample shows the basic usage of the toolbar. Notice how text is added to the separators which becomes a
group text for sub menus.
TypeScript
JavaScript
var menubarOptions = {
items: menuItems
};
var menuItems = [
{ id: "file", text: "File", icon: "icon-pause", childItems: [
{ separator: true, text: "NEW" }, // Separator as group text
{ id: "new-tab", text: "New tab", icon: "icon-info" },
{ id: "new-file", text: "New file", icon: "icon-commented-file" },
{ separator: true, text: "SAVE" }, , // Separator as group text
{ id: "save-file", text: "Save file", icon: "icon-save" },
{ id: "save-file-close", text: "Save file & close", icon: "icon-save-close" },
{ separator: true}, // Default separator
{ id: "save-all", text: "Save all", icon: "icon-save-all" },
{ separator: true, text: "MISC"}, // Separator as group text
{ id: "recent-files", text: "Recent files", icon: "icon-play", childItems: [
{ id: "file1", text: "file1.txt", icon: "icon-restricted" },
{ id: "file2", text: "file2.txt", icon: "icon-restricted" },
{ id: "file3", text: "file3.txt", icon: "icon-restricted" }
]},
{ id: "exit", text: "Exit" }
]},
{ separator: true }, // Default separator
{ id: "settings", text: "Settings...", icon: "icon-settings" },
{ id: "help", text: "Help", icon: "icon-help", tag: "test" }
];
var menubarOptions = {
items: menuItems
};
});
VSS.notifyLoadSucceeded();
var menubarOptions = {
items: menuItems,
executeAction: function (args) {
var command = args.get_commandName();
switch (command) {
case "new-tab":
alert("Opening new tab!");
break;
case "save-all":
alert("Saving all!");
break;
case "exit":
alert("Exit!");
break;
default:
alert("Unhandled action: " + command);
break;
}
}
};
var menuItems = [
{ id: "new-tab", text: "New tab", icon: "icon-info" },
{ separator: true },
{ id: "save-all", text: "Save all", icon: "icon-save-all" },
{ separator: true },
{ id: "exit", text: "Exit", noIcon: true }
];
var menubarOptions = {
items: menuItems,
executeAction: function (args) {
var command = args.get_commandName();
switch (command) {
case "new-tab":
alert("Opening new tab!");
break;
case "save-all":
alert("Saving all!");
break;
case "exit":
alert("Exit!");
break;
default:
alert("Unhandled action: " + command);
break;
}
}
};
});
VSS.notifyLoadSucceeded();
Toggle enabled/disabled
This sample shows how the menu items can be enabled/disabled.
TypeScript
JavaScript
import Controls = require("VSS/Controls");
import Menus = require("VSS/Controls/Menus");
$("#btnToggle").click(function (e) {
// Get the menu item first
var settingsItem = menubar.getItem("settings");
var menuItems = [
{ id: "new-tab", text: "New tab", icon: "icon-info" },
{ separator: true },
{ id: "save-all", text: "Save all", icon: "icon-save-all" },
{ separator: true },
{ id: "exit", text: "Exit", noIcon: true }
];
var menuItems = [
{ id: "settings", text: "Settings...", icon: "icon-settings" },
{ id: "help", text: "Help", icon: "icon-help", tag: "test" }
];
$("#btnToggle").click(function (e) {
// Get the menu item first
var settingsItem = menubar.getItem("settings");
VSS.notifyLoadSucceeded();
Toggle visible/hidden
This sample shows how the menu items can be made visible/hidden.
TypeScript
JavaScript
$("#btnToggle").click(function (e) {
// Get the menu item first
var helpItem = menubar.getItem("help");
var menuItems = [
{ id: "settings", text: "Settings...", icon: "icon-settings" },
{ id: "help", text: "Help", icon: "icon-help", tag: "test" }
];
$("#btnToggle").click(function (e) {
// Get the menu item first
var helpItem = menubar.getItem("help");
VSS.notifyLoadSucceeded();
Use the treeview control
4/27/2018 • 2 minutes to read • Edit Online
Basic treeview
This sample shows the basic usage of the TreeView control. The items of tree source need to be TreeView.TreeNode
.
import Controls = require("VSS/Controls");
import TreeView = require("VSS/Controls/TreeView");
var source = [
{ name: "Asia", icon: "icon icon-people", children: [
{ name: "Russia" },
{ name: "Afghanistan" },
{ name: "India" },
{ name: "China" }]
},
{ name: "Africa", icon: "icon icon-people", children: [
{ name: "Algeria" },
{ name: "Botswana" },
{ name: "Cameroon" }]
},
{ name: "Europe", icon: "icon icon-people", children: [
{ name: "Germany" },
{ name: "Slovenia" },
{ name: "Belgium" },
{ name: "Luxembourg" },
{ name: "Turkey" }
],
expanded: true
}
];
Add/remove nodes
Below code works based on Basic tree example above. This sample displays how to add nodes to TreeView as well
as removing nodes from it.
$("#btnAdd").click(function(e) {
// Find the node to add new children
var turkeyNode = treeview.rootNode.findNode("europe/turkey");
$("#btnRemove").click(function(e) {
// Find the node to be removed
var africaNode = treeview.rootNode.findNode("africa");
if(africaNode) {
// Remove the node if exists
treeview.removeNode(africaNode);
} else {
alert("Node not found");
}
});
Context menu
Below code works based on the source used in Basic tree example above. The sample shows the usage of
contextMenu for each node in the treeView. The item associated with the context menu is obtained using
args.get_commandArgument().item in menuItemClick function.
function menuItemClick(args) {
// Get the item associated with the context menu
var node = args.get_commandArgument().item;
switch (args.get_commandName()) {
case "open":
alert(node.path());
break;
case "delete":
confirm(`Are you sure you want to delete ${node.text}?`);
break;
}
}
function getContextMenuItems() {
return [
{
id: "open",
text: "Open Details"
},
{ separator: true },
{
id: "delete",
text: "Delete",
icon: "icon-delete"
}
];
}
This page shows different samples about the combo control. There are TypeScript and JavaScript examples.
For more details, see the Combo Control API reference.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
</head>
<body>
<script src="sdk/scripts/VSS.SDK.js"></script>
<script>
VSS.init({ usePlatformScripts: true });
VSS.ready(function() {
require(["scripts/main.js"], function () { });
});
</script>
<div class="sample-container"/>
</body>
</html>
Ensure that the VSS.SDK.js file is inside the sdk/scripts folder so that the path is home/sdk/scripts/VSS.SDK.js .
Put the following code snippets into a main.js file in a scripts folder, so that the path is home/scripts/main.js .
Combos
Plain list combo
This sample shows combo of type list . It also shows how change delegate is used to populate another combo. If
the second combo does not have any source, its mode is changed to text to hide the unnecessary drop icon.
TypeScript
JavaScript
import Controls = require("VSS/Controls");
import Combos = require("VSS/Controls/Combos");
// Make combo
$("<label />").text("Make:").appendTo(container);
Controls.create(Combos.Combo, container, makeOptions);
// Model combo
$("<label />").text("Model:").appendTo(container);
var modelCombo = Controls.create(Combos.Combo, container, modelOptions);
VSS.require(["VSS/Controls", "VSS/Controls/Combos"], function(Controls, Combos) {
var container = $(".sample-container");
var makeOptions = {
width: "400px",
source:
["Aston Martin", "Audi (3)", "Bentley", "BMW (2)", "Bugatti",
"Ferrari", "Ford", "Honda", "Hyundai", "Kia", "Lamborghini",
"Land Rover", "Lotus", "Maserati", "Mazda", "Mercedes",
"Mitsubishi", "Nissan", "Porsche", "Toyota", "Volkswagen", "Volvo"],
change: function () {
var selected = this.getText();
if (selected.indexOf("Audi") === 0) {
modelCombo.setSource(["A3", "A4", "Q7"]);
modelCombo.setMode("drop");
}
else if (selected.indexOf("BMW") === 0) {
modelCombo.setSource(["325", "X5"]);
modelCombo.setMode("drop");
}
else {
modelCombo.setMode("text");
}
modelCombo.setText("");
}
};
var modelOptions = {
width: "400px",
mode: "text"
};
Tree combo
This sample shows combo of type tree which displays its source hierarchically by supporting expand/collapse. It
also supports search by node.
TypeScript
JavaScript
import Controls = require("VSS/Controls");
import Combos = require("VSS/Controls/Combos");
import TreeView = require("VSS/Controls/TreeView");
var dateTimeOptions:Combos.IDateTimeComboOptions = {
value: "Tuesday, September 29, 1982 8:30:00 AM",
type: "date-time",
dateTimeFormat: "F",
width: 300,
change: function () {
commandArea.prepend($("<div />").text(dateTimeCombo.getValue().toString()));
}
};
var dateTimeOptions = {
value: "Tuesday, September 29, 1982 8:30:00 AM",
type: "date-time",
dateTimeFormat: "F",
width: 300,
change: function () {
commandArea.prepend($("<div />").text(dateTimeCombo.getValue().toString()));
}
};
Multivalue combo
This sample shows the usage of combo by type multi-value .
TypeScript
JavaScript
import Controls = require("VSS/Controls");
import Combos = require("VSS/Controls/Combos");
var multiValueOptions = {
type: "multi-value",
width: 500,
source: [
"English", "Chinese", "German", "Turkish", "Spanish",
"Japanese", "Korean", "Russian", "Portuguese", "French",
"Italian", "Arabic"],
change: function () {
// Displaying the selected value
commandArea.prepend($("<div />").text(this.getText()));
}
};
This page shows different samples about the modal dialog control.
Go to API Reference for more details.
When using this modal dialog, dialog overlay will cover only the area dedicated to the extension due to iframe limitations. If you
want the modal dialog cover whole window, see Using host dialog.
$("#show").click(()=> {
Dialogs.show(Dialogs.ModalDialog, {
title: "My Dialog",
contentText: "This is the simplistic modal dialog.",
buttons: null
});
});
.dialog-content input {
border: 1px solid #ddd;
width: 100%;
outline: none;
padding: 2px;
}
$("#show").click(() => {
// Display the dialog
var dialog = Dialogs.show(Dialogs.ModalDialog, <Dialogs.IModalDialogOptions>{
width: 300,
title: "Register",
content: $(".dialog-content").clone(),
okCallback: (result: any) => {
$("<li />").text(result).appendTo(".person-list");
}
});
Confirmation dialog
Below sample displays how to use modal dialgo as a confirmation dialog.
import Dialogs = require("VSS/Controls/Dialogs");
$("#delete").click(() => {
showConfirmationDialog(()=> {
// Do your delete job here
$("<p />").text(`${filename} deleted`).appendTo(".log");
});
});
Use the splitter control
4/27/2018 • 2 minutes to read • Edit Online
Splitter enhancement
Unlike other controls, it is more convenient to instantiate splitter control on an existing markup since splitter is a
container control. Otherwise, it would be difficult to fill left and right panes programmatically.
There is a technic called enhancement which converts an existing html to a control. It is basically similar to what
Controls.create does but instead of creating a new DOM element and associating it with the control,
enhancement uses an existing element in the DOM tree.
Below sample shows a typical usage of splitter control.
<button id="expand">Expand</button>
<button id="collapse">Collapse</button>
.my-splitter {
margin: 10px;
border: 5px solid gray;
width:600px;
height: 400px;
}
By including this HTML structure in your code, you will have a Splitter control with an integrated toggle button
and when collapsed a label on the collapsed pane.
Use the wait control
4/27/2018 • 2 minutes to read • Edit Online
Basic usage
This sample shows basic usage of a pivot filter. Please try to use html markup below since it picks up necessary
styles from hub-pivot and filters classes.
<div class="hub-pivot">
<div class="filters filter-container"></div>
</div>
<div class="log"></div>
Controls.create(Navigation.PivotFilter, container, {
behavior: "dropdown",
text: "My Filter",
items: [
{ id: "v-1", text: "Value 1", value: "v1" },
{ id: "v-2", text: "Value 2", value: "v2", selected: true },
{ id: "v-3", text: "Value 3", value: "v3" }
],
change: function(item) {
var $log = $(".log");
$log.html(`${$log.html()}<p>Filter changed to ${item.text} (${item.value})</p>`);
}
});
Package, publish, unpublish, and install VSTS
extensions
4/27/2018 • 5 minutes to read • Edit Online
After writing a Visual Studio Team Services (VSTS ) extension, the next step is to package it. After packaging,
extensions are published, or uploaded, to the Visual Studio Marketplace, where they can be installed by users
that the extensions are shared with. The Marketplace is a centralized, global repository for private and public
extensions, integrations, and other offers from Microsoft.
NOTE
For information on the discovery properties available in your extension's manifest file that will help users discover and
learn about your extension, visit the Extension Manifest Reference
Publishing Requirements
Below is a list of requirements that must be checked before publishing to the Marketplace.
Ensure the proper permissions are granted to use any images (icons, logos, screenshots, etc.).
Include a thorough overview.md file to describe your listing in the Marketplace.
Include an icon for your extension which is at least 128x128 pixels in size.
When referring to Microsoft products, use full names in place of abbreviations.
e.g. Visual Studio Team Services vs. VSTS.
Refrain from using brand names in your extension's name.
Create a publisher
Every item on the Visual Studio Marketplace, including extensions and integrations, belong to a publisher.
A publisher has a unique identifier and a name. The name is displayed on the cards of items from that publisher
on the Marketplace:
A publisher is owned by a user, typically the user that created it, and can also be shared with other users.
1. Sign in to the Visual Studio Marketplace Publishing Portal
2. If you are not already a member of an existing publisher, you'll be prompted to create a publisher. If you're
not prompted to create a publisher, scroll down to the bottom of the page and select Publish Extensions
underneath Related Sites.
Specify an idenitifer for your publisher, for example: mycompany-myteam
This will be used as the value for the publisher attribute in your extensions' manifest file.
Specify a display name for your publisher, for example: My Team
3. Review the Marketplace Publisher Agreement and click Create
Once the publisher has been created, you'll be directed to the manage items, which will have no items.
Package
Extensions are packaged as VSIX 2.0-compatible .vsix files. To upload your extension, you need to package it as
a VSIX 2.0-compatible .vsix file. Microsoft provides a cross-platform command line interface (CLI) to package
(and also publish) your extension.
Get the package tool (tfx-cli)
You can install or update the TFS Cross Platform Command Line Interface (tfx-cli) using npm , a component of
Node.js, from your command line.
npm i -g tfx-cli
NOTE
An extension/integration's version must be incremented on every update.
If you haven't incremented your extension/integration in the manifest, you should pass the --rev-version command
line switch. This will increment the patch version number of your extension and save the new version to your manifest.
Publish
Once your extension has been packaged, you can upload it to the Marketplace under a publisher. The
publisher identifer specified in your extension's manifest file must match the identifier of the publisher the
extension is uploaded under.
To upload an extension to the Marketplace:
1. Navigate to the Visual Studio Marketplace Publishing Portal
2. Find the Upload new extension button, navigate to your packaged .vsix file, and select upload.
3. After a quick validation, your extension will appear in the extensions list:
At this point, your extension is not visible to any accounts and cannot be installed until you share it.
Share
Before an extension can be installed into a VSTS account, it must be shared with that account. Sharing is a
requirement during development and testing of an extension, as it is the only way to run an extension.
To share an extension so it can be installed:
1. Click on the ellipses of an extension item to bring up the menu
2. Click the Share button
3. Specify the name of the VSTS account to make this extension visible to
For example, to make an extension visible to the fabrikam-fiber-inc.visualstudio.com account, specify
fabrikam-fiber-inc .
Install
To install an extension that has been shared:
1. From your VSTS account home page, select the Marketplace icon in the top right corner and choose
"Manage Extensions":
2. Find the extension under the Shared with this account category:
Update
To change an extension that has already been published, update it.
Unpublish
You can unpublish/delist free extensions, if you no longer want to offer them in the Marketplace or published
by mistake.
Here are some scenarios where you might want to remove your extension from the Marketplace:
You developed another extension and no longer want to offer the current one.
Your extension has a problem, so you want to remove your extension from the Marketplace until you have
resolved the problem.
You published your extension as public by mistake.
To unpublish, select the extension on your publisher page and choose Unpublish on the menu. Your extension
will be unpublished immediately from the Marketplace, and new users won't be able to install it. Ratings and
reviews for your extension will stay intact.
To offer your extension again in the Marketplace, choose Publish on the menu.
You can also choose to remove your extension completely from the Marketplace if your extension has zero (0)
installs. To do this, choose Remove on the menu. This action cannot be undone.
Unpublish/Remove requirements
Certain criteria must be met for an extension to be unpublished or removed:
ACTION REQUIREMENTS
Important: If you must remove your extension due to legal or security problems, contact the Marketplace
team. We will review the request and manually delete the extension.
Contact
Send questions about publishing items to the Visual Studio Marketplace to vsmarketplace@microsoft.com.
Package and Publish an integration to the Marketplace
4/27/2018 • 9 minutes to read • Edit Online
Do you have a tool, service, or product that integrates with VSTS or Team Foundation Server? If so, help users find it
by publishing it on the Visual Studio Marketplace. The Visual Studio Marketplace is a one-stop-shop for individuals
and teams to find tools that extend and enhance the experience.
Browse the marketplace to see examples of other integrations and extensions.
NOTE
If you're looking for packaging and publishing information for extensions, check out Package & Publish Extensions.
Publishing Requirements
Below is a list of requirements that must be checked before publishing to the Marketplace.
Ensure the proper permissions are granted to use any images (icons, logos, screenshots, etc.).
Include a thorough overview.md file to describe your listing in the Marketplace.
Include an icon for your extension which is at least 128x128 pixels in size.
When referring to Microsoft products, use full names in place of abbreviations.
e.g. Visual Studio Team Services vs. VSTS.
Refrain from using brand names in your extension's name.
Steps
Publishing to the Marketplace is an iterative process that starts with creating a manifest file that defines your
integration and key discovery characteristics (like screen shots, logos, and overview content). This information is
used to present your integration to users on the Marketplace, for example:
Jenkins for VSTS
Note: you will see the term extension used in documentations referenced below. Extensions are another type of
Marketplace item and share many similarities from a discovery standpoint as integrations.
Need help getting your integration on the Marketplace? Contact us. And, yes, this e-mail address is monitored by real people.
Create a publisher
Every item on the Visual Studio Marketplace, including extensions and integrations, belong to a publisher.
A publisher has a unique identifier and a name. The name is displayed on the cards of items from that publisher on
the Marketplace:
A publisher is owned by a user, typically the user that created it, and can also be shared with other users.
1. Sign in to the Visual Studio Marketplace Publishing Portal
2. If you are not already a member of an existing publisher, you'll be prompted to create a publisher. If you're not
prompted to create a publisher, scroll down to the bottom of the page and select Publish Extensions underneath
Related Sites.
Specify an idenitifer for your publisher, for example: mycompany-myteam
This will be used as the value for the publisher attribute in your extensions' manifest file.
Specify a display name for your publisher, for example: My Team
3. Review the Marketplace Publisher Agreement and click Create
Once the publisher has been created, you'll be directed to the manage items, which will have no items.
Create a folder to contain your item manifest and other assets
Before you package your integration as an extension, you'll need to create a home folder to contain some required
assets, within this folder:
1. Create a folder called images to contain:
Logo for your integration (128x128 pixels)
Screen shots (1366x768 pixels)
2. Create a file called overview.md
This is where you'll describe your integration.
To learn more about markdown, see GitHub Flavored Markdown
3. Create a file called vss-integration.json
This is your Marketplace listing's manifest file, it contains many properties to describe your extension in
your Marketplace listing. You can browse the extension manifest reference here
Extension Manifest
1. Fill your vss-integration.json file with the following JSON:
{
"manifestVersion": 1,
"id": "myservice",
"version": "1.0.0",
"name": "My Service",
"publisher": "mycompany",
"description": "Awesome tools to help you and your team do great things everyday.",
"targets": [
{
"id": "Microsoft.VisualStudio.Services.Integration"
}
],
"icons": {
"default": "images/service-logo.png"
},
"categories": [
"Plan and track"
],
"tags": [
"working",
"people person",
"search"
],
"screenshots": [
{
"path": "images/screen1.png"
},
{
"path": "images/screen2.png"
}
],
"content": {
"details": {
"path": "overview.md"
},
"license": {
"path": "fabrikam-license-terms.md"
}
},
"links": {
"getstarted": {
"uri": "https://www.mycompany.com/help/getstarted"
},
"learn": {
"uri": "https://www.mycompany.com/features"
},
"support": {
"uri": "https://www.mycompany.com/support"
}
},
"branding": {
"color": "rgb(34, 34, 34)",
"theme": "dark"
}
}
publisher The identifier of the publisher. This identifier must match the identifier
the extension is published under. See
Create and manage a publisher.
targets The products and services supported by This is an array of objects, where each
your integration or extension. See object has an id field indicating one of
installation targets for more details. the following:
Microsoft.VisualStudio.Services
(extensions that works with VSTS or TFS),
Microsoft.TeamFoundation.Server
(extension that works with TFS),
Microsoft.VisualStudio.Services.Integration
(integrations that works with VSTS or
TFS),
Microsoft.TeamFoundation.Server.Integration
(integrations that work with TFS)
These optional properties help users discover and learn about your extension:
icons Dictionary of icons representing the Valid keys: default (128x128 pixels) of
extension. type BMP, GIF, EXIF, JPG, PNG and TIFF).
Other keys such as large (512x512
pixels) may be supported in the future.
The value of each key is the path to the
icon file in the extension
categories Array of strings representing the Valid values: Code , Plan and track ,
categories your extension belongs to. At Build and release , Test ,
least one category must be provided Collaborate , and Integrate .
and there is no limit to how many
categories you may include.
PROPERTY DESCRIPTION NOTES
screenshots Array of images that could not be Screenshots are more valuable when
included in your **content*. featured in your content, and should be
used there to help make a quality
market details page for your extension.
Use screenshots for less important
images not featured in your content.
Each image should be 1366x768 pixels.
The path of each item is the path to
the file in the extension.
content Dictionary of content files that describe Every extension should include solid
your extension to users. content-it's how you'll show users what
your extension can do; make it rich,
consumable, and include screenshots
where necessary. Include an
overview.md file as your base content
piece. Each file is assumed to be in
GitHub Flavored Markdown format. The
path of each item is the path to the
markdown file in the extension. Valid
keys: details . Other keys will be
supported in the future.
links Dictionary of links that help users learn Valid keys: getstarted - first steps,
more about your extension, get support, how to setup or use. learn - deeper
and move. content to help users better understand
your extension or service. license -
end user license agreement.
privacypolicy - privacy policy for an
extension. support - get help and
support for an extension. The value of
each key is an object with a uri field,
which is the absolute URL of the link
repository Dictionary of properties describing the Valid Keys: type - Type of repository.
source code repository for the extension Example: git. uri - Absolute URL of the
repository.
badges Array of links to external metadata Valid keys: href - Link the user will
badges like TravisCI, Appveyor etc from navigate to when clicking the badge.
the approved badges sites uri - The absolute URL of the badge
image to be displayed. description -
Description of the badge, to be displayed
on hover.
branding Dictionary of brand-related properties. Valid keys: color - primary color of the
extension or publisher; can be a hex
(#ff00ff ), RGB (rgb(100,200,50)), or
supported HTML color names (blue).
theme - complements the color; use
dark for dark branding colors, or light
for lighter branding colors.
Details page
1 - description
2 - icon
3 - categories
4 - screenshots
5 - content (details)
6 - links
7 - branding
Make sure the "public" attribute is set to "false" (or not set at all) to avoid your extension or integration from becoming prematurely
visible to all users on the Marketplace.
npm i -g tfx-cli
NOTE
An extension/integration's version must be incremented on every update.
If you haven't incremented your extension/integration in the manifest, you should pass the --rev-version command line
switch. This will increment the patch version number of your extension and save the new version to your manifest.
At this point, your extension is not visible to any accounts and cannot be installed until you share it.
Share your integration
Before an integration can be installed into a VSTS account, it must be shared with that account. Sharing is a
requirement during development and testing of an integration, as it is the only way to run an integration.
To share an integration so it can be installed:
1. Click an integration from the list of displayed items
2. Click the Share button
3. Specify the name of the VSTS account to make this integration visible to.
For example, to make an integration visible to the fabrikam-fiber-inc.visualstudio.com account, specify
fabrikam-fiber-inc .
Update an item
To change an extension that has already been published, update it.
The Visual Studio Marketplace is a single place users can go to find and purchase extensions, tools, products, and
services that extend Visual Studio, VSTS, Visual Studio Code, or Team Foundation Server.
This page covers the required steps to make your integration or extension listing publicly available in the
Marketplace.
Learn more about developing an extension for VSTS
Learn more about packaging and publishing an extension to the Marketplace
Learn more about packaging and publishing an integration to the Marketplace
As you are developing your extension or the content for your Marketplace page (for either an extension or
integration), your extension can and should remain private.
Qualifications
To have a public listing on the Marketplace, your integration or extension must meet the following qualifications:
1. Works with or extends one of the following Microsoft products or services:
Visual Studio, or
VSTS (formerly Visual Studio Online), or
Visual Studio Code, or
Visual Studio Team Foundation Server (2012, 2013, or 2015)
2. You (or your company) owns, develops, and is licensed to distribute and advertise the integration or extension.
3. The extension or integration is actively maintained.
Microsoft might also request a demo and to review the content planned for your Marketplace entry. For more
details, refer to the Visual Studio Marketplace Publisher Agreement, which you agreed to when creating your
publisher.
Process
The process to have a public VSTS listing for an integration or extension is the same. The publisher needs to be
verified in order to do so. Only verified publishers can have public VSTS items in the Marketplace.
Developing for Visual Studio, Visual Studio for Mac or Visual Studio Code? If so, you do not need to
request verification. Verification is only required for VSTS integrations or extensions.
Once you are ready to publish a public VSTS listing to the Marketplace, follow these steps:
1. Visit http://marketplace.visualstudio.com/manage/publishers and login with the account using which you will
publish and manage VSTS listings in Marketplace.
2. Select the publisher and through the Details tab apply for publisher verification. You will find the appropriate
section towards the bottom of the tab.
3. Expect Microsoft to approve or respond within 3 business days to your verification request.
Once your publisher is verified, you need to set the public flag to true in your manifest for your extension to be
available publicly.
Important: Once your publisher is verified, you will not be able to change its display name without contacting
Microsoft.
Contact
Send questions about publishing items to the Visual Studio Marketplace to vsmarketplace@microsoft.com.
Publish from the command line
4/27/2018 • 2 minutes to read • Edit Online
You can use the TFS Cross Platform Command Line Interface (tfx-cli) to publish your extension to the Visual
Studio Marketplace.
See the overview of publish, install, and share for additional details.
4. Add a description for your token, then select an expiration timeframe for your token.
5. In the Accounts list, select All accessible accounts. This is required because the Visual Studio
Marketplace publishing APIs work outside the context of an account.
6. Select the Marketplace (publish) scope. This will limit the token to only being able to publish extensions to
the Visual Studio Marketplace.
7. Finish creating your token.
8. Copy your generated personal access token. Make sure to keep it secret.
Create a publisher
If you haven't already created a publisher, you can do so using the command line tool.
To create a publisher using the TFS Cross Platform Command Line Interface, simply run the following command,
replacing each argument with the necessary value.
Note: The Publisher name must match the publisher property in your extension manifest.
Example
C:\tfs-cli>tfx extension publisher create
Copyright Microsoft Corporation
> Publisher name: Fabrikam
> Display name: Fabrikam, Inc.
> Description: Fabrikam's main publisher
You may receive the following error when publishing if your extension has already been published:
Failed Request: Internal Server Error(500) - Version number must increase each time an extension is published.
Extension: fabrikam.my-extension Current version: 0.1.9 Updated version: 0.1.9
You can add the --rev-version command line option to automatically increment the patch version of your
extension. Note that this will also save the new version to your manifest.
Example
As a publisher, you can respond to reviews that customers leave for your extensions in the Visual Studio
Marketplace. If you have owner, creator, or contributor permissions as the publisher, you can find and click Reply
next to a review.
You can leave only one response. Please avoid using reviews as a support forum. If you need more details, please
provide a support alias for the reviewer to contact. You can then resolve their problems externally and then update
your reply with a resolution.
Modern web browsers, like Microsoft Edge and Google Chrome, include tools for debugging the JavaScript that
runs on a web page. Usually these are referred to as the "F12 Tools", "Inspector", or "Developer Tools". Since your
extension is loaded onto a VSTS page in an iframe, you can use these browser tools to debug the JavaScript
portion of your extension. The standard shortcut to launch the browser developer tools is F12.
If your extension's iframe is placed in the foreground, you can use the regular element selector tool (IE: ,
Chrome: ) to inspect within the DOM of your extension.
Tip: You may need to set a breakpoint in a script block that is executed when your extension is first loaded, such
as during initialization. If that is the case, ensure your extension is loaded, set the breakpoint, then refresh the
page. Once the page is refreshed, cause your extension to get loaded again. The breakpoint will be persisted and
execution should pause when it is encountered during initialization.
Many VSTS context menus have named groups of actions. This helps ensure related actions are grouped together
when the context menu is presented to the user. When you contribute an action to a menu, you can optionally
specify a groupId property, which will place the action within that group.
To discover the possible group identifiers for a context menu:
1. Navigate to the page with the context menu
2. Open your browser's JavaScript console (typically by pressing F12)
3. Paste in this snippet (you may have to press enter to execute it)
VSS.UI.Controls.Menus.Menu.prototype.getGroupedItems=function(){if(!$.isArray(this._itemsSource))return
this._itemsSource;var r=[],e={__ungrouped__:[]};if(this._itemsSource.forEach(function(r){r.groupId&&!r.separator?
e[r.groupId]?e[r.groupId].push(r):e[r.groupId]=
[r]:e.__ungrouped__.push(r)}),e.__ungrouped__.length===this._itemsSource.length)return this._itemsSource;var
u=null;for(e.__ungrouped__=e.__ungrouped__.reduce(function(r,e,t,o){return e.separator&&
(u&&u.separator||0===r.length||t===o.length-1)||r.push(e),u=e,r},[]),$.each(e,function(e,u)
{return'__ungrouped__'===e?!0:(r.push({id:'group_'+e,text:'Group: '+e,title:'Group:
'+e}),Array.prototype.push.apply(r,u),void
r.push({separator:!0}))}),Array.prototype.push.apply(r,e.__ungrouped__),0===e.__ungrouped__.length&&r.splice(r.length-
1,1);r.length>0&&r[r.length-1].separator;)r.splice(r.length-1,1);return r};
4. Right-click to show the context menu, which will now show the group identifiers
5. Set the groupId property of your action contribution, for example:
{ "id": "my-edit-action", "type": "ms.vss-web.action", "targets": [ "ms.vss-code-web.source-grid-item-menu"
], "properties": { "title": "My custom edit action", "groupId": "editing", "uri": "action.html" } }
Now that your extension is available in the Visual Studio Marketplace, you can use the Reports feature to track and
analyze how the extension is performing and take required actions. To visit the extension hub, browse to your
publisher page and select the extension or click Reports link on the extension details page.
Acquisition
You can view acquisition related data in this tab for the selected period.
Aggregated acquisition in the selected period with respect to overall acquisition
Aggregated acquisition split by extension downloads, VSTS and TFS connected install for free extension
Aggregated acquisition split by trials, VSTS and TFS connected buy for paid extension
Daily trend of extension page views with acquisition for VSTS and TFS connected server
Conversion percentage from page views to acquisition
For paid extension, all transactional details for buy and trials is available with date, account name, trial end date,
and quantity. You can use the Contact action to reach out to your users for transactional communication. See the
Contact section provided later in this topic for more details.
Uninstall
You can view how many VSTS accounts have uninstalled your extension, daily trend of uninstall, detailed feedback
shared during uninstall, and top uninstall reasons. You can use search for text and dates to analyze and draw more
insights from the detailed feedback.
For paid extensions, you can use the Contact action to reach out to your users for transactional communication.
Contact section provided later in this topic for more details.
Sales transaction
This tab is only available for paid extensions and gives the details of sales w.r.t. quantity and accounts to help
understand how the extension is performing. Selection of the users button gives the aggregated details of sales
and churn i.e. number of new, upgrade, downgrade and cancelled user licenses respectively with the trend.
Selection of the accounts button gives similar aggregated details of sales and churn with respect to account and its
trend.
All transactional details for trials, new purchase, upgrade, downgrade and cancellations is available in details
section. You can use search for text and dates to analyze and draw more insights. This data can also be pivoted by
account to understand the lifecycle of an account or sorted to understand the top account w.r.t. user licensees /
resources purchased. Contact feature is also available.
Q&A
This tab will give you snapshot of all questions by your extension users with the non-responded queries on the top.
You can take actions of replying or editing a previous response and better manage engagement with your
extension users.
Export to Excel
All data elements available in the reports page are also available for download in XLS format to aid creating your
own custom reports.
Contact
For paid extension, you can use the Contact action to reach out to your users for transactional communication. this
functionality is available only for publishers with contributor + access on the extension.
Marketplace will broker the first communication with the user as our privacy policy doesn't allow direct sharing of
customer email addresses. Only users who have opt-ed in for communication will be sent the email. Last contacted
date for an account is as also updated after sending a communication.
Important Please follow the below guidance on transactional and promotional communication. A publisher found
to do promotional communication or spamming users will be blacklisted and won't be able to use the Contact
feature for any of his/her extensions.
Transactional Communication: Transactional emails convey critical information necessary for the continued use
of the extension or service. Examples include critical security notices, transaction confirmations, product recall
notices, specific feedback request and service discontinuation notices. Promotional Emails: Promotional emails
are used to market your extension, product, service, website, or event. Examples include invitations to events or
web casts, information about new marketing or partner programs and offers to prospect to obtain value-added
content. Almost all newsletters fall into the promotional bucket as they generally contain at least some promotional
content.
Refer the Marketplace Publisher Agreement for more guidance on communication with customers.
Terminology
Page views is total number of extension detail page views. Repeated views are counted.
VSTS install is the total number of VSTS accounts the extension is installed. Repeated installs on the same
account are counted.
TFS install is the total number of TFS connected accounts the extension is installed. Repeated installs on the
same account are counted. TFS disconnected server data isn't available.
Extension Statistics Power BI Content pack
4/27/2018 • 2 minutes to read • Edit Online
You can gain insight and analyze the progress of your extension by using Extension Statistics Power BI Content
pack. All data elements available in the extension hub are also available in Power BI content pack. The content pack
contains a complete analytic data model (tables, relationships and measures), a set of default reports, and a default
dashboard. Reports and dashboards are fully customizable but the data model is not.
5. Search for Marketplace and select the Visual Studio Marketplace Extension Statistics and click Get it now.
6. Enter the Marketplace publisher id for the publisher you want data for and click Next.
Important: Ensure you are logged in power BI using the same credentials you use on the Marketplace and
you have access to the Publisher Id.
7. The next step specifies the authentication method. Only oAuth2 is supported. Click Sign In to continue.
Important: You won't be able to connect if your account administrator disabled third party application
access via OAuth. When enabled, it appears as follows on the Administration > Control panel > Settings
page:
Contact your account administrator to determine if it needs to be enabled.
8. Successful authorization displays the following authorization dialog which allows Power BI to retrieve data
from your account. Scroll down to the bottom and click Accept.
9. Once Power BI is authorized, data will begin to load and you'll be presented with a loading screen until the
data is complete. Depending on how much data there is, it may take a few minutes to complete the data
load. All extension data associated with this publisher will be downloaded.
Every extension has a JSON manifest file which defines basic info about the extension and how it wants to extend
and enhance the experience.
Start by creating a file named vss-extension.json at the root of your extension folder. This file contains required
attributes, like the extension's ID and its installation targets (where it can run). It also defines the contributions
being made by your extension.
Here is an example of what a typical manifest will look like:
{
"manifestVersion": 1,
"id": "tools",
"version": "0.1.0",
"name": "Fabrikam Tools",
"publisher": "fabrikam",
"description": "Awesome tools to help you and your team do great things everyday.",
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"icons": {
"default": "images/fabrikam-logo.png"
},
"scopes": [
"vso.work",
"vso.code_write",
"vso.build_execute"
],
"categories": [
"Plan and track"
],
"branding": {
"color": "rgb(34, 34, 34)",
"theme": "dark"
},
"content": {
"details": {
"path": "readme.md"
},
"license": {
"path": "eula.md"
}
},
"links": {
"getstarted": {
"uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
},
"support": {
"uri": "https://www.fabrikam-fiber-inc.com/support"
}
},
"repository": {
"type": "git",
"uri": "https://github.com/fabrikam-fiber-inc/myextension"
},
"contributions": [
{
"id": "showCommits",
"type": "ms.vss-web.action",
"description": "Adds a menu action from builds grid to show associated items.",
"targets": [
"ms.vss-build-web.completed-build-menu"
],
"properties": {
"title": "View associated items",
"uri": "launch.html"
}
}
],
"files": [
{
"path": "launch.html",
"addressable": true
},
{
"path": "node_modules/vss-web-extension-sdk/lib",
"addressable": true,
"packagePath": "lib"
}
]
}
Required attributes
These properties are required:
publisher The identifier of the publisher. This identifier must match the identifier
the extension is published under. See
Create and manage a publisher.
PROPERTY DESCRIPTION NOTES
targets The products and services supported This is an array of objects, where each
by your integration or extension. See object has an id field indicating one
installation targets for more details. of the following:
Microsoft.VisualStudio.Services
(extensions that works with VSTS or
TFS),
Microsoft.TeamFoundation.Server
(extension that works with TFS),
Microsoft.VisualStudio.Services.Integration
(integrations that works with VSTS or
TFS),
Microsoft.TeamFoundation.Server.Integration
(integrations that work with TFS)
{
"manifestVersion": 1,
"id": "tools",
"version": "0.1.0",
"name": "Fabrikam Tools",
"publisher": "fabrikam",
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
]
}
Optional attributes
Runtime attributes
PROPERTY DESCRIPTION NOTES
{
"scopes": [
"vso.work",
"vso.code_write",
"vso.build_execute"
],
"demands": [
"api-version/3.0"
],
"contributions": [
{
"id": "showCommits",
"type": "ms.vss-web.action",
"description": "Adds a menu action from builds grid to show associated items.",
"targets": [
"ms.vss-build-web.completed-build-menu"
],
"properties": {
"title": "View associated items",
"uri": "launch.html"
}
}
]
}
Discovery attributes
These optional properties help users discover and learn about your extension:
icons Dictionary of icons representing the Valid keys: default (128x128 pixels)
extension. of type BMP, GIF, EXIF, JPG, PNG and
TIFF). Other keys such as large
(512x512 pixels) may be supported in
the future. The value of each key is the
path to the icon file in the extension
categories Array of strings representing the Valid values: Code , Plan and track ,
categories your extension belongs to. Build and release , Test ,
At least one category must be Collaborate , and Integrate .
provided and there is no limit to how
many categories you may include.
screenshots Array of images that could not be Screenshots are more valuable when
included in your **content*. featured in your content, and should
be used there to help make a quality
market details page for your extension.
Use screenshots for less important
images not featured in your content.
Each image should be 1366x768 pixels.
The path of each item is the path to
the file in the extension.
content Dictionary of content files that Every extension should include solid
describe your extension to users. content-it's how you'll show users what
your extension can do; make it rich,
consumable, and include screenshots
where necessary. Include an
overview.md file as your base content
piece. Each file is assumed to be in
GitHub Flavored Markdown format. The
path of each item is the path to the
markdown file in the extension. Valid
keys: details . Other keys will be
supported in the future.
links Dictionary of links that help users Valid keys: getstarted - first steps,
learn more about your extension, get how to setup or use. learn - deeper
support, and move. content to help users better understand
your extension or service. license -
end user license agreement.
privacypolicy - privacy policy for an
extension. support - get help and
support for an extension. The value of
each key is an object with a uri field,
which is the absolute URL of the link
repository Dictionary of properties describing the Valid Keys: type - Type of repository.
source code repository for the Example: git. uri - Absolute URL of
extension the repository.
badges Array of links to external metadata Valid keys: href - Link the user will
badges like TravisCI, Appveyor etc from navigate to when clicking the badge.
the approved badges sites uri - The absolute URL of the badge
image to be displayed. description -
Description of the badge, to be
displayed on hover.
Public flag
By default, all extensions on the Visual Studio Marketplace are private (only visible to the publisher and accounts
the publisher has shared the extension with). If your publisher has been verified, you can make your extension
public by setting the Public flag in your extension manifest:
{
"galleryFlags": [
"Public"
]
}
Or simply:
{
"public": true
}
{
"galleryFlags": [
"Preview"
]
}
Paid flag
If you want to sell your extension on the Marketplace, you can mark it as paid :
{
"galleryFlags": [
"Paid"
]
}
Currently, this is in limited Beta. All paid extensions are mandated to define privacy and end user licence
agreement. Additional configuration steps are required to sell extension in Marketplace.
Paid Preview flag
If you intend to sell your extension on the Marketplace in the future, you have to mark it as paid preview :
{
"galleryFlags": [
"Paid",
"Preview"
]
}
{
"description": "Awesome tools to help you and your team do great things everyday.",
"icons": {
"default": "images/fabrikam-logo.png"
},
"categories": [
"Plan and track"
"Plan and track"
],
"tags": [
"working",
"people person",
"search"
],
"content": {
"details": {
"path": "overview.md"
},
"license": {
"path": "license-terms.md"
}
},
"links": {
"home": {
"uri": "https://www.fabrikam-fiber-inc.com"
},
"getstarted": {
"uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
},
"learn": {
"uri": "https://www.fabrikam-fiber-inc.com/features"
},
"support": {
"uri": "https://www.fabrikam-fiber-inc.com/support"
},
"repository": {
"uri": "https://github.com/fabrikam-fiber-inc/tools"
},
"issues": {
"uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
}
},
"repository": {
"type": "git",
"uri": "https://github.com/fabrikam-fiber-inc/tools"
},
"badges": [
{
"href": "https://travis.ci/fabrikam-fiber-inc/myextension",
"uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
"description": "TravisCI build for the project"
},
{
"href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
"uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
"description": "AppVeyor build for the project"
}
],
"branding": {
"color": "rgb(34, 34, 34)",
"theme": "dark"
},
"screenshots": [
{
"path": "screenshots/screen1.png"
},
{
"path": "screenshots/screen2.png"
}
]
}
{
"CustomerQnASupport": {
"enableqna":"true",
"url": "http://uservoice.visualstudio.com"
}
}
Properties
Properties for the CustomerQnASupport section:
enableqna - boolean field, set to true for marketplace or custom Q&A; false for disabling Q&A
url - string, URL for custom Q&A
Examples showing usage of Q&A support
Example 10: Extension using custom Q&A
{
"CustomerQnASupport": {
"enableqna":"true",
"url": "http://uservoice.visualstudio.com"
}
}
Example 11: Extension with GitHub repository but using Marketplace Q&A instead of GitHub issues
{
"CustomerQnASupport": {
"enableqna":"true"
}
}
{
"CustomerQnASupport": {
"enableqna":"false"
}
}
Scopes
Your extension can specify one or more scopes. Scopes control what resources can be accessed by your extension
and what operations your extension is allowed to perform on those resources. The scopes you specify in your
extension manifest are the scopes set on access tokens issued to your extension (see Auth and security for more
information).
If no scopes are specified, extensions are only provided access to user profile and extension data.
Supported scopes
SCOPE NAME DESCRIPTION INCLUDED BY
vso.chat_write Team rooms (read and write) Grants the ability to access vso.chat_manage
rooms and view, post, and
update messages. Also
grants the ability to receive
notifications about new
messages via service hooks.
vso.chat_manage Team rooms (read, write, and Grants the ability to access
manage) rooms and view, post, and
update messages. Also
grants the ability to manage
rooms and users and to
receive notifications about
new messages via service
hooks.
vso.code_write Code (read and write) Grants the ability to read, vso.code_manage
update, and delete source
code, access metadata about
commits, changesets,
branches, and other version
control artifacts. Also grants
the ability to create and
manage pull requests and
code reviews and to receive
notifications about version
control events via service
hooks.
vso.packaging_write Packaging (read and write) Grants the ability to create vso.packaging_manage
and read feeds and
packages.
vso.project Project and team (read) Grants the ability to read vso.project_write
projects and teams. vso.project_manage
SCOPE NAME DESCRIPTION INCLUDED BY
vso.project_write Project and team (read and Grants the ability to read vso.project_manage
write) and update projects and
teams.
vso.release_execute Release (read, write and Grants the ability to read vso.release_manage
execute) and update release artifacts,
including releases, release
definitions and release
envrionment, and the ability
to queue a new release.
vso.symbols_write Symbols (read and write) Grants the ability to read vso.symbols_manage
and write symbols.
vso.work_write Work items (read and write) Grants the ability to read,
create, and update work
items and queries, update
board metadata, read area
and iterations paths other
work item tracking related
metadata, execute queries,
and to receive notifications
about work item events via
service hooks.
An administrator can then review and authorize the new set of scopes:
Installation targets
As the name implies, installation targets define the products and services your extension can be installed into.
Microsoft.VisualStudio.Services is the most common installation target and indicates that the extension can be
installed into VSTS and Team Foundation Server 2015 Update 2 and later (the version when extension were
introduced in Team Foundation Server).
The installation targets for an extension or integration are specified via the targets field in the manifest.
Supported identifiers for extensions:
Microsoft.VisualStudio.Services.Cloud : installs into VSTS
Microsoft.TeamFoundation.Server : installs into Team Foundation Server
Microsoft.VisualStudio.Services : installs into both. Shortcut for Microsoft.VisualStudio.Services.Cloud and
Microsoft.TeamFoundation.Server version [14.2,)
Supported identifiers for integrations (tools or services that integrate with VSTS or Team Foundation Server):
Microsoft.VisualStudio.Services.Cloud.Integration : integrates with VSTS
Microsoft.TeamFoundation.Server.Integration : integrates with Team Foundation Server
Microsoft.VisualStudio.Services.Integration : integrates with both. Shortcut for
Microsoft.VisualStudio.Services.Cloud.Integration and Microsoft.TeamFoundation.Server.Integration
Examples
Example 1: Extension that works with VSTS and Team Foundation Server
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
]
}
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services.Cloud"
}
]
}
Installation targets can also be used in the manifest of integrations (i.e. products, apps, or tools that work with, but
do not install into, VSTS or Team Foundation Server. For example:
Example 3: Integration that works with VSTS and Team Foundation Server
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services.Integration"
}
]
}
{
"targets": [
{
"id": "Microsoft.TeamFoundation.Server.Integration"
}
]
}
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services.Cloud"
},
{
"id": "Microsoft.TeamFoundation.Server",
"version": "[15.0,)"
}
]
}
Example 6: Integration that works with Team Foundation Server 2015 and later
{
"targets": [
{
"id": "Microsoft.TeamFoundation.Server.Integration",
"version": "[14.0,)"
}
]
}
Example 7: Integration that works with Team Foundation Server 2013 and 2015
{
"targets": [
{
"id": "Microsoft.TeamFoundation.Server.Integration",
"version": "[12.0,15.0)"
}
]
}
Shortcuts
Microsoft.VisualStudio.Services is a shortcut for VSTS and Team Foundation Server 2015 Update 2 and later. So
this:
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
]
}
is equivalent to:
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services.Cloud"
},
{
"id": "Microsoft.TeamFoundation.Server",
"version": "[14.2,)"
}
]
}
{
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"demands": [
"api-version/3.0"
]
}
Demands
Demands let you specify capabilities and other features required by your extension. These demands can then be
used to limit where your extension can be published or installed.
In the future, demands will be used by the Visual Studio Marketplace to list the products and environments your
extension is generally compatible with. This will help customers understand whether your extension will work with
their version of Team Foundation Server (for example).
Demands are specified in the extension manifest. For example:
{
"demands": [
"api-version/3.0",
"contribution/ms.vss-dashboards-web.widget-catalog"
]
}
In this example, the extension demands version 3.0 of the APIs, which means it can only be installed to VSTS or
Team Foundation Server 2017 RTM and later. It also requires the ms.vss-dashboards-web extension (and its
widget-catalog contribution) to be installed (and enabled) in the collection before your extension can be installed.
Supported demands
TYPE DESCRIPTION CHECKED AT PUBLISH? CHECKED AT INSTALL?
Notes
environment/cloud and environment/onprem should only be used when your extension has topology-related
requirements that require running in that particular environment.
extension , contribution , and contributionType demands are evaluated at install time, and requires that the
specified extension is already installed and enabled in the account/collection.
Files
The files section is where you reference any files you wish to include in your extension. You can add both folders
and individual files:
{
"files": [
{
"path": "hello-world.html", "addressable": true
},
{
"path": "scripts", "addressable": true
},
{
"path": "images/logo.png", "addressable": true, "packagePath": "/"
}
]
}
Properties
Properties for the Files section:
path - Path of resource, root directory is where your manifest file is located
addressable - Set to true if you want your file to be URL -addressable
packagePath - Places your resource from disk to the specified value when packaged
Contributions
Each contribution entry has the following properties:
id - A reference ID (string) for the contribution. Each contribution's ID must be unique within an extension. See
referencing contributions and types below.
type - The ID of the contributionType of this contribution.
description - (Optional) A string describing what the contribution is providing.
targets - An array of contribution IDs that the contribution is targeting (contributing to). See Targeting
contributions.
properties - (Optional) An object that includes properties for the contribution as defined in the contribution
type.
See the contribution model overview topic for an overview about contributions.
Contribution types
Each contribution entry has the following properties:
id - A reference ID (string) for the contribution type. Each contribution type's ID must be unique within an
extension. See referencing contributions and types below.
name - The friendly name of the contribution type.
description - (Optional) A string describing in more detail what the contribution type is for.
properties - (Optional) A dictionary that maps property names to property descriptions. These properties
describe the required and optional properties that can be used by contributions of this type.
Property descriptions have the following properties:
description - (Optional) A string describing what the property is used for.
required - (Optional) A boolean value which if true indicates that the property is required for all contributions
of this type.
type - The type of value that the property can have. This may be: string, uri, guid, boolean, integer, double,
dateTime, array, or object.
See the contribution model overview topic for an overview about contributions.
Referencing contributions and types
Contributions and contribution types are referenced by their identifiers. Contributions reference types through the
type property, and reference other contributions through the targets property.
A full contribution reference includes the publisher identifier, extension identifier, and contribution/type identifier,
separated by a dot (.). For example: ms.vss-web.hub is the full identifier for the contribution with identifier of "hub"
in the "vss-web" extension published by the "ms" (Microsoft) publisher.
Relative contribution references may be used within an extension manifest for a contribution's reference to
another contribution or contribution type within that same extension. In this case, the publisher and extension
identifiers are NOT included, and the identifier is simply a dot (.) followed by the contribution identifier. For
example, ".hub" may be used within the "vss-web" extension mentioned above as a shortcut for "ms.vss-web.hub".
Targeting contributions
Some contributions act as containers that can be targeted by other contributions. A Hub Group and a Menu are
examples of this. Hub contributions can target Hub Groups. When a page is rendered, the web UI will show all
Hub contributions that target the selected hub group. Hub groups themselves target a hub group collection which
defines a set of hub groups that show up in a given navigational area (e.g. project-level admin pages).
Menus can be targeted by contributions of different types: action, hyperlink-action, and action-provider. Actions
and hyperlink-actions provide single menu item entries. An action-provider can provide multiple dynamic menu
items. For a given menu, items are aggregated across all contributions (of any of these types) that target that
specific menu contribution.
Example manifest
This extension contributions an action to the completed builds context menu and a hub to the Build hub group:
{
"manifestVersion": 1,
"id": "tools",
"version": "0.1.0",
"name": "Fabrikam Tools",
"publisher": "fabrikam",
"description": "Awesome tools to help you and your team do great things everyday.",
"targets": [
{
"id": "Microsoft.VisualStudio.Services"
}
],
"demands": [
"api-version/3.0"
],
"icons": {
"default": "images/fabrikam-logo.png"
},
"scopes": [
"vso.work",
"vso.code_write"
],
"categories": [
"Plan and track"
],
"tags": [
"working",
"people person",
"search"
],
"branding": {
"color": "rgb(34, 34, 34)",
"theme": "dark"
},
"screenshots": [
{
"path": "screenshots/screen1.png"
},
{
"path": "screenshots/screen2.png"
}
],
"content": {
"details": {
"path": "overview.md"
},
"license": {
"path": "eula.md"
}
},
"links": {
"home": {
"uri": "https://www.fabrikam-fiber-inc.com"
},
"getstarted": {
"uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
},
"learn": {
"uri": "https://www.fabrikam-fiber-inc.com/features"
},
"support": {
"uri": "https://www.fabrikam-fiber-inc.com/support"
},
"repository": {
"uri": "https://github.com/fabrikam-fiber-inc/tools"
},
"issues": {
"uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
}
},
"repository": {
"type": "git",
"uri": "https://github.com/fabrikam-fiber-inc/myextension"
},
"badges": [
{
"href": "https://travis.ci/fabrikam-fiber-inc/myextension",
"uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
"description": "TravisCI build for the project"
},
{
"href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
"uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
"description": "AppVeyor build for the project"
}
],
"contributions": [
{
"id": "showCommits",
"type": "ms.vss-web.action",
"description": "Adds a menu action from builds grid to show associated items.",
"targets": [
"ms.vss-build-web.completed-build-menu"
],
"properties": {
"title": "View associated items",
"uri": "launch.html"
}
}
]
}
Reference for creating custom build/release tasks
within extensions
4/30/2018 • 2 minutes to read • Edit Online
NOTE
The code will look for the task.json file inside the task folder. If one is not found, it will look just one level deeper. An error
will be thrown if one is not found in either level.
Service endpoint authentication schemes
4/27/2018 • 2 minutes to read • Edit Online
For VSTS and Team Foundation Server to be able to connect to the external service, in addition to using the
credentials, there is also need to know how to set the credentials in the HTTP request header when calling the
external endpoint. VSTS supports a closed set of authentication schemes that can be utilized by a custom service
endpoint type. This set is closed so that VSTS would be able to interpret the authentication scheme used in any
custom endpoint & support connecting to the external service.
Following are the authentication schemes that are part of the closed set:
Basic authentication
This scheme takes 2 inputs - Username & Password (confidential)
Default authentication header used is: "Basic {{ #base64 endpoint.username ":" endpoint.password }}"
{
"id": "endpoint-auth-scheme-basic",
"description": "Basic Authentication based endpoint authentication scheme",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": [
"ms.vss-endpoint.endpoint-auth-schemes"
],
"properties": {
"name": "UsernamePassword",
"displayName": "i18n:Basic Authentication",
"headers": [
{
"name": "Authorization",
"value": "Basic {{ #base64 endpoint.username \":\" endpoint.password }}"
}
],
"inputDescriptors": [
{
"id": "username",
"name": "i18n:Username",
"description": "i18n:Username for connecting to the endpoint",
"inputMode": "textbox",
"isConfidential": false,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 300
}
},
{
"id": "password",
"name": "i18n:Password",
"description": "i18n:Password for connecting to the endpoint",
"inputMode": "passwordbox",
"isConfidential": true,
"validation": {
"isRequired": true,
"dataType": "string",
"maxLength": 300
}
}
]
}
}
No authentication
This scheme is used when an endpoint type does not require to take any input. For e.g. external services that
support anonymous access to its resources.
{
"id": "endpoint-auth-scheme-none",
"description": "i18n:Creates an endpoint authentication scheme with no authentication.",
"type": "ms.vss-endpoint.service-endpoint-auth-scheme",
"targets": [
"ms.vss-endpoint.endpoint-auth-schemes"
],
"properties": {
"name": "None",
"displayName": "i18n:No Authentication"
}
}
Static content hosting
4/27/2018 • 2 minutes to read • Edit Online
You have the option of hosting static content for your extension (like HTML, CSS, and JavaScript files) on your own
service, a third-party hosting service (like Azure or Heroku), or on VSTS directly.
IMPORTANT
If your extension needs to create a custom table in the TFS database, do not create it using the 'dbo' schema. Instead,
custom tables should be created in a seperate schema. For example, 'YourExtensionName'.
Host on VSTS
In this model, static content is packaged with your extension's .vsix file and is served from a public endpoint at
https://publisher.gallery.vsassets.io .
Having VSTS host your extension's static content is useful when you are simply enhancing or decorating data from
VSTS. It does not require you (the extension publisher) to setup, manage, or pay for hosting services for your
extension
Steps
1. In your extension manifest file, specify the files you want to include via the files property:
json { "files": [ { "path": "scripts", "addressable": true }, { "path": "images/extra/icon1.png",
"addressable": true } ] }
2. Remove the baseUri property (if set) from your extension manifest.
3. Package your extension (steps)
4. Publish (or re-publish) your extension (steps)
Important: Make sure to increment the version of your extension when you make changes to static content files included in your
.vsix.
Keep in mind:
The value specified by the path attribute can be a folder or individual file. If a folder, the entire folder (and any
sub-folders) are included.
The addressable attribute is important and is what tells Visual Studio Online to make the file(s) URL
addressable.
All addressable asset requests are case sensitive. If the request for an asset has a different case than the actual
uploaded asset, it will result in a HTTP 404 (Not found) error.
Not specifying a baseUri (or setting an empty value) tells Visual Studio Online at runtime to calculate the base
URI as if your static content is hosted by VSTS.
VSTS will load the contents of this hub when it is rendered at https://myservice.net/extension/hello-world.html .
Modal dialog
4/27/2018 • 3 minutes to read • Edit Online
The HostDialogService enables you to present a modal dialog to the user and prevent interaction with all parts of
web access until the dialog is dismissed.
In contrast to the standard dialog control, a modal dialog presented via the HostDialogService prevents interaction by the user
on the entire page, not just within the extension.
Dialog contents
To start, declare a contribution of type ms.vss-web.control in your extension manifest. This contribution represents
the content displayed within the dialog.
{
"id": "registration-form",
"type": "ms.vss-web.control",
"description": "The content to be displayed in the dialog",
"targets": [],
"properties": {
"uri": "registration-form.html"
}
}
The uri property references a page that will be rendered within the content area of the dialog:
<!DOCTYPE html>
<html>
<head>
<script src="sdk/scripts/VSS.SDK.js"></script>
</head>
<body>
<h2 id="header">Register now</h2>
<p>
<label>Name:</label>
<input id="inpName" />
</p>
<p>
<label>Data of birth:</label>
<input id="inpDob" />
</p>
<p>
<label>Email address:</label>
<input id="inpEmail" />
</p>
<script>
VSS.init();
var registrationForm = (function() {
var callbacks = [];
function inputChanged() {
// Execute registered callbacks
for(var i = 0; i < callbacks.length; i++) {
callbacks[i](isValid());
}
}
function isValid() {
// Check whether form is valid or not
// Check whether form is valid or not
return !!(name.value) && !!(dateOfBirth.value) && !!(email.value);
}
function getFormData() {
// Get form values
return {
name: name.value,
dateOfBirth: dateOfBirth.value,
email: email.value
};
}
name.addEventListener("change", inputChanged);
dateOfBirth.addEventListener("change", inputChanged);
email.addEventListener("change", inputChanged);
return {
isFormValid: function() {
return isValid();
},
getFormData: function() {
return getFormData();
},
attachFormChanged: function(cb) {
callbacks.push(cb);
}
};
})();
VSS.getService(VSS.ServiceIds.Dialog).then(function(dialogService) {
var extensionCtx = VSS.getExtensionContext();
// Build absolute contribution ID for dialogContent
var contributionId = extensionCtx.publisherId + "." + extensionCtx.extensionId + ".registration-form";
// Show dialog
var dialogOptions = {
title: "My Dialog",
width: 800,
height: 600
};
dialogService.openDialog(contributionId, dialogOptions);
});
VSS.getService(VSS.ServiceIds.Dialog).then(function(dialogService) {
var registrationForm;
var extensionCtx = VSS.getExtensionContext();
var contributionId = extensionCtx.publisherId + "." + extensionCtx.extensionId + ".registration-form";
var dialogOptions = {
title: "Registration Form",
width: 800,
height: 600,
getDialogResult: function() {
// Get the result from registrationForm object
return registrationForm ? registrationForm.getFormData() : null;
},
okCallback: function (result) {
// Log the result to the console
console.log(JSON.stringify(result));
}
};
dialogService.openDialog(contributionId, dialogOptions).then(function(dialog) {
// Get registrationForm instance which is registered in registrationFormContent.html
dialog.getContributionInstance("registration-form").then(function (registrationFormInstance) {
// Keep a reference of registration form instance (to be used above in dialog options)
registrationForm = registrationFormInstance;
dialogService.openDialog(contributionId, dialogOptions).then(function(dialog) {
// Set true/false to enable/disable ok button
dialog.updateOkButton(true);
});
When the dialog is opened, following options need to be specified to pass myId :
var dialogOptions = {
title: "My Dialog Title",
width: 800,
height: 600,
urlReplacementObject: { myId: new Date().getTime() }
};
var dialogOptions = {
title: "My Dialog Title",
width: 800,
height: 600,
okText: "Yes",
cancelText: "No"
};
To not show any buttons on the dialog, you can set the buttons attribute to null :
var dialogOptions = {
title: "My Dialog Title",
width: 800,
height: 600,
buttons: null
};
Host page navigation
4/27/2018 • 2 minutes to read • Edit Online
The HostNavigationService provides APIs for interacting with the parent host frame, including refreshing it and
accessing the hash of the URL:
We recommend you use the basic styles provided via the Widget SDK. Using these styles will help you quickly and
easily create a widget that's consistent with the rest of the widgets on the dashboard. To use these styles, add the
below line inside the VSS.require block in the javascript code for your widget.
WidgetHelpers.IncludeWidgetStyles();
This will pull a stylesheet by the name sdk-widget.css and include it in the iframe for your widget. It includes styles
for font-family, font-size, margin and paddings for your widget. It also includes styles for headings (h1, h2, h3 etc.),
links, and more.
Similarly, to use common styles in the widget configuration, include the line below inside the VSS.require block in
the javascript code for your widget configuration.
WidgetHelpers.IncludeWidgetConfigurationStyles();
This will pull a stylesheet by the name sdk-widget-configuration.css and include it in the iframe for your widget
configuration. It includes styles for font-family, font-size and styles for common form elements like input, textarea,
and select.
NOTE
For these styles to apply to your widget, you need to add a "widget" class on the HTML element that contains your widget.
All styles from the sdk-widgets.css are scoped to this class. Similarly, add a "widget-configuration" class on the HTML element
that contains your widget configuration. All styles from the sdk-widget-configuration.css are scoped to this class.
Download the samples to get started or use the code snippets provided below.
Widget body, title and description
By adding the class "widget" on the HTML element that contains your widget, you automatically get padding, font,
and color for widget contents.
You should always have a title for your widget. This helps the user identify your widget and its functionality at a
glance. Use <h2> with class "title". This also helps people using screen readers to quickly identify the different
widgets on the dashboard.
Design principle: Widgets should have a title. Use the <h2> tag with the "title" class.
Sometimes you might want to provide a small description about your widget or how to use it. In such cases, use
the class "description" on the HTML element you wish to use for widget description.
Design principle: Use the "description" class for the widget description. Descriptions should make sense even
when read out of the widget context.
<div class="widget">
<h2 class="title">Widget title</h2>
<div class="description">The widget description is used to describe the widget. It makes sense even
when read outside of the widget context.</div>
<p>Place widget content here.</p>
</div>
Design principle: Use the "subtitle" class to provide more information about the widget. It may not make
sense out of the widget context.
Use the below structure and classes "title", "inner-title" and "subtitle" to get the right font, color and margins for a
title and subtitle combination. The title will get a greater font-size than the subtitle. The subtitle will have a subdued
color relative to the title or rest of the widget.
<div class="widget">
<h2 class="title">
<div class="inner-title">Widget title</div>
<div class="subtitle">Widget subtitle</div>
</h2>
<div class="content">
Place widget content here.
</div>
</div>
You can use any html element for the title and subtitle combination. Here are some tips:
When you need the subtitle to appear in the same line as the title, use an inline element like <span>
When you need the subtitle to appear in the next line from the title, use a block element like <div>
Design principle: Use links with an icon and subtext to make the purpose of the link obvious to the user.
Ensure that the icon symbolizes the link's target.
To get the same look and feel, use the below HTML structure and classes.
<div class="widget">
<h2 class="title">Widget title</h2>
<div class="content">
<p>Place your content here.</p>
<a class="link-with-icon-text" href="http://bing.com" target="_blank">
<span class="icon-container" style="background-color: #68217A"></span>
<div class="title">
Primary link text
<div class="subtitle">Link subtext</div>
</div>
</a>
</div>
</div>
<div class="widget">
<h2 class="title">Counter widget</h2>
<div class="big-count">223</div>
<div>Additional text</div>
</div>
Design principle: Use the "clickable" class and the <a> tag to make the entire widget clickable. This is ideal
when your widget is a summary of data available on another page.
Simple text box div with class "single-line-text-input". Use a label element to add text next
to the text box. Use the input
element to create a text box. Use the
placeholder attribute to provide
placeholder text.
Checkbox fieldset with class "checkbox" Use a label element to add text next
to each checkbox. Use a legend
element to caption the group of
checkboxes. Use the for attribute on
each label element to help screen
readers understand the form element.
Radio button fieldset with class "radio" Use a label element to add text next
to each radio button. Use a legend
element to caption the group of radio
buttons. Use the for attribute on
each label element to help screen
readers understand the form element.
Dropdown div with class "dropdown" Use a label element to add text next
to the dropdown. If you want a
dropdown occupying half the width,
add class "half" to the wrapping div
element. If you want to use the
standard arrow icon from the sdk
instead of the one provided by the
browser, wrap the select element
with another div with class "wrapper".
Multi-line text box div with class "multi-line-text-input". Use label element to label the
textarea element used as multi-line
text box.
The example below uses each of the form elements listed in the table.
<div class="widget-configuration">
<div class="multi-line-text-input">
<label>Comments</label>
<textarea></textarea>
</div>
</div>
</div>
<span class="validation-error">
<span class="icon-error-exclamation"></span>
<span class="validation-error-text"></span>
</span>
The above will have the visibility hidden by default. Whenever you want to display an error message, find the
corresponding "validation-error-text", add text to it and set visibility:visible on its parent.
Example: There is a simple text box where the user needs to type in a string. You need to show an error message if
the text box is empty.
The html for this would be:
<div class="widget-configuration">
<div class="single-line-text-input">
<label>Your name</label>
<input type="text">Type Here</input>
<span class="validation-error">
<span class="icon-error-exclamation"></span>
<span class="validation-error-text"></span>
</span>
</div>
</div>
$singleLineInput.on("input", function(){
if ($singleLineInput.val() == ""){
$errorSingleLineInput.text("Please enter your name.");
$errorSingleLineInput.parent().css("visibility", "visible");
return;
}
$errorSingleLineInput.parent().css("visibility", "hidden");
});
Auth and security
5/18/2018 • 3 minutes to read • Edit Online
VSS.require(["VSS/Authentication/Services"],
function (VSS_Auth_Service) {
VSS.getAccessToken().then(function(token){
// Format the auth header
var authHeader = VSS_Auth_Service.authTokenManager.getAuthorizationHeader(token);
VSS.getAppToken().then(function(token){
// Add token to your request
});
using System.Collections.Generic;
using System.ServiceModel.Security.Tokens;
using Microsoft.IdentityModel.Tokens;
namespace TokenSample
{
class Program
{
static void Main(string[] args)
{
string secret = ""; // Load your extension's secret
string issuedToken = ""; // Token you are validating
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.IdentityModel.Tokens;
namespace TokenSample.Core.API
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
string _secret = "ey9asfasdmax..<the secret key downloaded from the VSTS publisher page>.9faf7eh";
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddJwtBearer((o) =>
{
o.TokenValidationParameters = new TokenValidationParameters()
{
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(_secret)),
ValidateIssuer = false,
ValidateAudience = false,
ValidateActor = false,
RequireSignedTokens = true,
RequireExpirationTime = true,
ValidateLifetime = true
};
});
}
[Route("api/[controller]"),
Authorize()]
public class SampleLogicController : Controller
{
// ...
}
Deploy web content to Azure
4/27/2018 • 2 minutes to read • Edit Online
If your extension does not require any back-end logic, consider hosting your static content direcly on VSTS. See content hosting.
After you've created an extension, you can publish it to Azure so that it's available in the cloud.
1. If you don't have an Azure subscription, create one. You can use the free trial.
2. Create a web app in Microsoft Azure to host your extension.
4. Publish to Azure.
5. Pick the web app that you set up to host your extension.
If your web site doesn't show up, use the Manage subscriptions dialog to connect your Visual Studio
account to your Microsoft Azure subscription.
6. Publish your extension.
7. Change your extension manifest to use your Microsoft Azure web app instead of localhost.
"baseUri": "https://fabrikam-vso-extensions.azurewebsites.net/",
init()
Initiates the handshake with the host window.
Syntax
void VSS.init(options)
Parameters
options : IExtensionInitializationOptions. Initialization options for the extension.
require()
Ensures that the AMD loader from the host is configured and fetches a script (AMD ) module (and its
dependencies) . If no callback is supplied, this will still perform an asynchronous fetch of the module (unlike AMD
require which returns synchronously). This method has no return value.
Usage:
VSS.require(["VSS/Controls", "VSS/Controls/Grids"], function(Controls, Grids) { ... });
Syntax
void VSS.require(modules, callback)
Parameters
modules : string[] or string. A single module path (string) or array of paths (string[])
callback : Function. Optional. Method called once the modules have been loaded.
ready()
Register a callback that gets called once the initial setup/handshake has completed. If the initial setup is already
completed, the callback is invoked at the end of the current call stack.
Syntax
void VSS.ready(callback)
Parameters
callback : (): void.
notifyLoadSucceeded()
Notifies the host that the extension successfully loaded (stop showing the loading indicator)
Syntax
void VSS.notifyLoadSucceeded()
notifyLoadFailed()
Notifies the host that the extension failed to load
Syntax
void VSS.notifyLoadFailed(e)
Parameters
e : any.
getWebContext()
Get the web context from the parent host
Syntax
WebContext VSS.getWebContext()
Returns
WebContext
getConfiguration()
Get the configuration data passed in the initial handshake from the parent frame
Syntax
any VSS.getConfiguration()
Returns
any
getExtensionContext()
Get the context about the extension that owns the content that is being hosted
Syntax
IExtensionContext VSS.getExtensionContext()
Returns
IExtensionContext
getContribution()
Gets the information about the contribution that first caused this extension to load.
Syntax
Contribution VSS.getContribution()
Returns
Contribution
getService<T>()
Get a contributed service from the parent host.
Syntax
Parameters
contributionId : string.
context : Object. Optional.
Returns
IPromise<T>
getServiceContribution()
Get the contribution with the given contribution id. The returned contribution has a method to get a registered
object within that contribution.
Syntax
IPromise<IServiceContribution> VSS.getServiceContribution(contributionId)
Parameters
contributionId : string. ID of the contribution to get
Returns
IPromise<IServiceContribution>
getServiceContributions()
Get contributions that target a given contribution id. The returned contributions have a method to get a registered
object within that contribution.
Syntax
IPromise<IServiceContribution[]> VSS.getServiceContributions(targetContributionId)
Parameters
targetContributionId : string. Contributions that target the contribution with this ID will be returned
Returns
IPromise<IServiceContribution[]>
register()
Register an object (instance or factory method) that this extension exposes to the host frame.
Syntax
Parameters
instanceId : string. unique ID of the registered object
instance : Object or <unknown_object_signature_kind>. Either: (1 ) an object instance, or (2 ) a function that
takes optional context data and returns an object instance.
getRegisteredObject()
Get an instance of an object registered with the given id
Syntax
Parameters
instanceId : string. unique ID of the registered object
contextData : Object. Optional. Optional context data to pass to the contructor of an object factory method
Returns
Object
getAccessToken()
Fetch an access token which will allow calls to be made to other VSTS services
Syntax
IPromise<ISessionToken> VSS.getAccessToken()
Returns
IPromise<ISessionToken>
getAppToken()
Fetch an token which can be used to identify the current user
Syntax
IPromise<ISessionToken> VSS.getAppToken()
Returns
IPromise<ISessionToken>
resize()
Requests the parent window to resize the container for this extension based on the current extension size.
Syntax
void VSS.resize()
Client Services
5/3/2018 • 2 minutes to read • Edit Online
A client service provides client-side (web) capability. An instance of a client service can be acquired via the
VSS.getService method:
VSS.getService(serviceId).then(function(svc) {
// interact with the service via svc
});
Available services
Dialog
ExtensionData
Navigation
REST Clients
5/3/2018 • 2 minutes to read • Edit Online
BuildHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/Build/RestClient
Initialization sample
Methods
addBuildTag()
addBuildTags()
createArtifact()
createDefinition()
createQueue()
deleteBuild()
deleteBuildTag()
deleteDefinition()
deleteQueue()
deleteTemplate()
getAgentPoolQueue()
getArtifact()
getArtifactContentZip()
getArtifacts()
getBadge()
getBuild()
getBuildBadge()
getBuildBadgeData()
getBuildChanges()
getBuildController()
getBuildControllers()
getBuildDeployments()
getBuildLog()
getBuildLogs()
getBuildLogsZip()
getBuildOptionDefinitions()
getBuilds()
getBuildSettings()
getBuildTags()
getBuildTimeline()
getBuildWorkItemsRefs()
getBuildWorkItemsRefsFromCommits()
getChangesBetweenBuilds()
getDefinition()
getDefinitionRevisions()
getDefinitions()
getQueues()
getResourceUsage()
getTags()
getTemplate()
getTemplates()
getWorkItemsBetweenBuilds()
queueBuild()
saveTemplate()
updateBuild()
updateBuildSettings()
updateDefinition()
addBuildTag()
Adds a tag to a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
tag : string.
Returns
IPromise<string[]>
addBuildTags()
Adds tag to a build
Syntax
Parameters
tags : string[].
project : string.
buildId : number.
Returns
IPromise<string[]>
createArtifact()
Associates an artifact with a build
Syntax
Parameters
artifact : Contracts.BuildArtifact.
buildId : number.
project : string. Optional.
Returns
IPromise<Contracts.BuildArtifact>
createDefinition()
Creates a new definition
Syntax
Parameters
definition : Contracts.BuildDefinition.
project : string. Optional.
definitionToCloneId : number. Optional.
definitionToCloneRevision : number. Optional.
Returns
IPromise<Contracts.BuildDefinition>
createQueue()
Creates a build queue
Syntax
IPromise<Contracts.AgentPoolQueue> createQueue(queue)
Parameters
queue : Contracts.AgentPoolQueue.
Returns
IPromise<Contracts.AgentPoolQueue>
deleteBuild()
Deletes a build
Syntax
Parameters
buildId : number.
project : string. Optional.
Returns
IPromise<void>
deleteBuildTag()
Deletes a tag from a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
tag : string.
Returns
IPromise<string[]>
deleteDefinition()
Deletes a definition and all associated builds
Syntax
Parameters
definitionId : number.
project : string. Optional.
Returns
IPromise<void>
deleteQueue()
Deletes a build queue
Syntax
IPromise<void> deleteQueue(id)
Parameters
id : number.
Returns
IPromise<void>
deleteTemplate()
Deletes a definition template
Syntax
Parameters
project : string. Project ID or project name
templateId : string.
Returns
IPromise<void>
getAgentPoolQueue()
Gets a queue
Syntax
IPromise<Contracts.AgentPoolQueue> getAgentPoolQueue(controllerId)
Parameters
controllerId : number.
Returns
IPromise<Contracts.AgentPoolQueue>
getArtifact()
Gets a specific artifact for a build
Syntax
Parameters
buildId : number.
artifactName : string.
project : string. Optional.
Returns
IPromise<Contracts.BuildArtifact>
getArtifactContentZip()
Gets a specific artifact for a build
Syntax
Parameters
buildId : number.
artifactName : string.
project : string. Optional.
Returns
IPromise<ArrayBuffer>
getArtifacts()
Gets all artifacts for a build
Syntax
Parameters
buildId : number.
project : string. Optional.
Returns
IPromise<Contracts.BuildArtifact[]>
getBadge()
Syntax
Parameters
project : string.
definitionId : number.
branchName : string. Optional.
Returns
IPromise<string>
getBuild()
Gets a build
Syntax
Parameters
buildId : number.
project : string. Optional.
propertyFilters : string. Optional.
Returns
IPromise<Contracts.Build>
getBuildBadge()
Syntax
Parameters
project : string. Project ID or project name
repoType : string.
repoId : string. Optional.
branchName : string. Optional.
Returns
IPromise<Contracts.BuildBadge>
getBuildBadgeData()
Syntax
Parameters
project : string. Project ID or project name
repoType : string.
repoId : string. Optional.
branchName : string. Optional.
Returns
IPromise<string>
getBuildChanges()
Gets the changes associated with a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
continuationToken : string. Optional.
top : number. Optional.
Returns
IPromise<Contracts.Change[]>
getBuildController()
Gets a controller
Syntax
IPromise<Contracts.BuildController> getBuildController(controllerId)
Parameters
controllerId : number.
Returns
IPromise<Contracts.BuildController>
getBuildControllers()
Gets controller, optionally filtered by name
Syntax
IPromise<Contracts.BuildController[]> getBuildControllers(name)
Parameters
name : string. Optional.
Returns
IPromise<Contracts.BuildController[]>
getBuildDeployments()
Gets the deployment information associated with a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<Contracts.Deployment[]>
getBuildLog()
Gets a log
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
logId : number.
startLine : number. Optional.
endLine : number. Optional.
Returns
IPromise<ArrayBuffer>
getBuildLogs()
Gets logs for a build
Syntax
IPromise<Contracts.BuildLog[]> getBuildLogs(project, buildId)
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<Contracts.BuildLog[]>
getBuildLogsZip()
Gets logs for a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<ArrayBuffer>
getBuildOptionDefinitions()
Syntax
IPromise<Contracts.BuildOptionDefinition[]> getBuildOptionDefinitions(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<Contracts.BuildOptionDefinition[]>
getBuilds()
Gets builds
Syntax
Parameters
project : string. Optional. Project ID or project name
definitions : number []. Optional. A comma-delimited list of definition ids
queues : number []. Optional. A comma-delimited list of queue ids
buildNumber : string. Optional.
minFinishTime : Date. Optional.
maxFinishTime : Date. Optional.
requestedFor : string. Optional.
reasonFilter : Contracts.BuildReason. Optional.
statusFilter : Contracts.BuildStatus. Optional.
resultFilter : Contracts.BuildResult. Optional.
tagFilters : string[]. Optional.
properties : string[]. Optional.
type : Contracts.DefinitionType. Optional.
top : number. Optional.
continuationToken : string. Optional.
maxBuildsPerDefinition : number. Optional.
deletedFilter : Contracts.QueryDeletedOption. Optional.
queryOrder : Contracts.BuildQueryOrder. Optional.
branchName : string. Optional.
Returns
IPromise<Contracts.Build[]>
getBuildSettings()
Syntax
IPromise<Contracts.BuildSettings> getBuildSettings()
Parameters
Returns
IPromise<Contracts.BuildSettings>
getBuildTags()
Gets the tags for a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<string[]>
getBuildTimeline()
Gets details for a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
timelineId : string. Optional.
changeId : number. Optional.
Returns
IPromise<Contracts.Timeline>
getBuildWorkItemsRefs()
Gets the work item IDs associated with a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
top : number. Optional.
Returns
IPromise<VSS_Common_Contracts.ResourceRef[]>
getBuildWorkItemsRefsFromCommits()
Gets the work item IDs associated with build commits
Syntax
Parameters
commitIds : string[].
project : string.
buildId : number.
top : number. Optional.
Returns
IPromise<VSS_Common_Contracts.ResourceRef[]>
getChangesBetweenBuilds()
Syntax
Parameters
project : string. Project ID or project name
fromBuildId : number. Optional.
toBuildId : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.Change[]>
getDefinition()
Gets a definition, optionally at a specific revision
Syntax
Parameters
definitionId : number.
project : string. Optional.
revision : number. Optional.
propertyFilters : string[]. Optional.
Returns
IPromise<Contracts.DefinitionReference>
getDefinitionRevisions()
Gets revisions of a definition
Syntax
Returns
IPromise<Contracts.BuildDefinitionRevision[]>
getDefinitions()
Gets definitions, optionally filtered by name
Syntax
Parameters
project : string. Optional. Project ID or project name
name : string. Optional.
type : Contracts.DefinitionType. Optional.
repositoryId : string. Optional.
repositoryType : string. Optional.
queryOrder : Contracts.DefinitionQueryOrder. Optional.
top : number. Optional.
Returns
IPromise<Contracts.DefinitionReference[]>
getQueues()
Gets queues, optionally filtered by name
Syntax
IPromise<Contracts.AgentPoolQueue[]> getQueues(name)
Parameters
name : string. Optional.
Returns
IPromise<Contracts.AgentPoolQueue[]>
getResourceUsage()
Syntax
IPromise<Contracts.BuildResourceUsage> getResourceUsage()
Parameters
Returns
IPromise<Contracts.BuildResourceUsage>
getTags()
Syntax
IPromise<string[]> getTags(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<string[]>
getTemplate()
Gets definition template filtered by id
Syntax
Parameters
project : string. Project ID or project name
templateId : string.
Returns
IPromise<Contracts.BuildDefinitionTemplate>
getTemplates()
Syntax
IPromise<Contracts.BuildDefinitionTemplate[]> getTemplates(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.BuildDefinitionTemplate[]>
getWorkItemsBetweenBuilds()
Syntax
Parameters
project : string. Project ID or project name
fromBuildId : number.
toBuildId : number.
top : number. Optional.
Returns
IPromise<VSS_Common_Contracts.ResourceRef[]>
queueBuild()
Queues a build
Syntax
Parameters
build : Contracts.Build.
project : string. Optional.
ignoreWarnings : boolean. Optional.
Returns
IPromise<Contracts.Build>
saveTemplate()
Saves a definition template
Syntax
Parameters
template : Contracts.BuildDefinitionTemplate.
project : string.
templateId : string.
Returns
IPromise<Contracts.BuildDefinitionTemplate>
updateBuild()
Updates a build
Syntax
Parameters
build : Contracts.Build.
buildId : number.
project : string. Optional.
Returns
IPromise<Contracts.Build>
updateBuildSettings()
Updates the build settings
Syntax
IPromise<Contracts.BuildSettings> updateBuildSettings(settings)
Parameters
settings : Contracts.BuildSettings.
Returns
IPromise<Contracts.BuildSettings>
updateDefinition()
Updates an existing definition
Syntax
Parameters
definition : Contracts.BuildDefinition.
definitionId : number.
project : string. Optional.
secretsSourceDefinitionId : number. Optional.
secretsSourceDefinitionRevision : number. Optional.
Returns
IPromise<Contracts.BuildDefinition>
5/3/2018 • 6 minutes to read • Edit Online
BuildHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/Build/RestClient
Initialization sample
Methods
addBuildTag()
addBuildTags()
createArtifact()
createDefinition()
createQueue()
deleteBuild()
deleteBuildTag()
deleteDefinition()
deleteQueue()
deleteTemplate()
getAgentPoolQueue()
getArtifact()
getArtifactContentZip()
getArtifacts()
getBadge()
getBuild()
getBuildBadge()
getBuildBadgeData()
getBuildChanges()
getBuildController()
getBuildControllers()
getBuildDeployments()
getBuildLog()
getBuildLogs()
getBuildLogsZip()
getBuildOptionDefinitions()
getBuilds()
getBuildSettings()
getBuildTags()
getBuildTimeline()
getBuildWorkItemsRefs()
getBuildWorkItemsRefsFromCommits()
getChangesBetweenBuilds()
getDefinition()
getDefinitionRevisions()
getDefinitions()
getQueues()
getResourceUsage()
getTags()
getTemplate()
getTemplates()
getWorkItemsBetweenBuilds()
queueBuild()
saveTemplate()
updateBuild()
updateBuildSettings()
updateDefinition()
addBuildTag()
Adds a tag to a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
tag : string.
Returns
IPromise<string[]>
addBuildTags()
Adds tag to a build
Syntax
Parameters
tags : string[].
project : string.
buildId : number.
Returns
IPromise<string[]>
createArtifact()
Associates an artifact with a build
Syntax
Parameters
artifact : Contracts.BuildArtifact.
buildId : number.
project : string. Optional.
Returns
IPromise<Contracts.BuildArtifact>
createDefinition()
Creates a new definition
Syntax
Parameters
definition : Contracts.BuildDefinition.
project : string. Optional.
definitionToCloneId : number. Optional.
definitionToCloneRevision : number. Optional.
Returns
IPromise<Contracts.BuildDefinition>
createQueue()
Creates a build queue
Syntax
IPromise<Contracts.AgentPoolQueue> createQueue(queue)
Parameters
queue : Contracts.AgentPoolQueue.
Returns
IPromise<Contracts.AgentPoolQueue>
deleteBuild()
Deletes a build
Syntax
Parameters
buildId : number.
project : string. Optional.
Returns
IPromise<void>
deleteBuildTag()
Deletes a tag from a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
tag : string.
Returns
IPromise<string[]>
deleteDefinition()
Deletes a definition and all associated builds
Syntax
Parameters
definitionId : number.
project : string. Optional.
Returns
IPromise<void>
deleteQueue()
Deletes a build queue
Syntax
IPromise<void> deleteQueue(id)
Parameters
id : number.
Returns
IPromise<void>
deleteTemplate()
Deletes a definition template
Syntax
Parameters
project : string. Project ID or project name
templateId : string.
Returns
IPromise<void>
getAgentPoolQueue()
Gets a queue
Syntax
IPromise<Contracts.AgentPoolQueue> getAgentPoolQueue(controllerId)
Parameters
controllerId : number.
Returns
IPromise<Contracts.AgentPoolQueue>
getArtifact()
Gets a specific artifact for a build
Syntax
Parameters
buildId : number.
artifactName : string.
project : string. Optional.
Returns
IPromise<Contracts.BuildArtifact>
getArtifactContentZip()
Gets a specific artifact for a build
Syntax
Parameters
buildId : number.
artifactName : string.
project : string. Optional.
Returns
IPromise<ArrayBuffer>
getArtifacts()
Gets all artifacts for a build
Syntax
Parameters
buildId : number.
project : string. Optional.
Returns
IPromise<Contracts.BuildArtifact[]>
getBadge()
Syntax
Parameters
project : string.
definitionId : number.
branchName : string. Optional.
Returns
IPromise<string>
getBuild()
Gets a build
Syntax
Parameters
buildId : number.
project : string. Optional.
propertyFilters : string. Optional.
Returns
IPromise<Contracts.Build>
getBuildBadge()
Syntax
Parameters
project : string. Project ID or project name
repoType : string.
repoId : string. Optional.
branchName : string. Optional.
Returns
IPromise<Contracts.BuildBadge>
getBuildBadgeData()
Syntax
Parameters
project : string. Project ID or project name
repoType : string.
repoId : string. Optional.
branchName : string. Optional.
Returns
IPromise<string>
getBuildChanges()
Gets the changes associated with a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
continuationToken : string. Optional.
top : number. Optional.
Returns
IPromise<Contracts.Change[]>
getBuildController()
Gets a controller
Syntax
IPromise<Contracts.BuildController> getBuildController(controllerId)
Parameters
controllerId : number.
Returns
IPromise<Contracts.BuildController>
getBuildControllers()
Gets controller, optionally filtered by name
Syntax
IPromise<Contracts.BuildController[]> getBuildControllers(name)
Parameters
name : string. Optional.
Returns
IPromise<Contracts.BuildController[]>
getBuildDeployments()
Gets the deployment information associated with a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<Contracts.Deployment[]>
getBuildLog()
Gets a log
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
logId : number.
startLine : number. Optional.
endLine : number. Optional.
Returns
IPromise<ArrayBuffer>
getBuildLogs()
Gets logs for a build
Syntax
IPromise<Contracts.BuildLog[]> getBuildLogs(project, buildId)
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<Contracts.BuildLog[]>
getBuildLogsZip()
Gets logs for a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<ArrayBuffer>
getBuildOptionDefinitions()
Syntax
IPromise<Contracts.BuildOptionDefinition[]> getBuildOptionDefinitions(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<Contracts.BuildOptionDefinition[]>
getBuilds()
Gets builds
Syntax
Parameters
project : string. Optional. Project ID or project name
definitions : number []. Optional. A comma-delimited list of definition IDs
queues : number []. Optional. A comma-delimited list of queue IDs
buildNumber : string. Optional.
minFinishTime : Date. Optional.
maxFinishTime : Date. Optional.
requestedFor : string. Optional.
reasonFilter : Contracts.BuildReason. Optional.
statusFilter : Contracts.BuildStatus. Optional.
resultFilter : Contracts.BuildResult. Optional.
tagFilters : string[]. Optional.
properties : string[]. Optional.
type : Contracts.DefinitionType. Optional.
top : number. Optional.
continuationToken : string. Optional.
maxBuildsPerDefinition : number. Optional.
deletedFilter : Contracts.QueryDeletedOption. Optional.
queryOrder : Contracts.BuildQueryOrder. Optional.
branchName : string. Optional.
Returns
IPromise<Contracts.Build[]>
getBuildSettings()
Syntax
IPromise<Contracts.BuildSettings> getBuildSettings()
Parameters
Returns
IPromise<Contracts.BuildSettings>
getBuildTags()
Gets the tags for a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
Returns
IPromise<string[]>
getBuildTimeline()
Gets details for a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
timelineId : string. Optional.
changeId : number. Optional.
Returns
IPromise<Contracts.Timeline>
getBuildWorkItemsRefs()
Gets the work item IDs associated with a build
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
top : number. Optional.
Returns
IPromise<VSS_Common_Contracts.ResourceRef[]>
getBuildWorkItemsRefsFromCommits()
Gets the work item IDs associated with build commits
Syntax
Parameters
commitIds : string[].
project : string.
buildId : number.
top : number. Optional.
Returns
IPromise<VSS_Common_Contracts.ResourceRef[]>
getChangesBetweenBuilds()
Gets the changes associated between given builds
Syntax
Parameters
project : string. Project ID or project name
fromBuildId : number. Optional.
toBuildId : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.Change[]>
getDefinition()
Gets a definition, optionally at a specific revision
Syntax
Parameters
definitionId : number.
project : string. Optional.
revision : number. Optional.
propertyFilters : string[]. Optional.
Returns
IPromise<Contracts.DefinitionReference>
getDefinitionRevisions()
Gets revisions of a definition
Syntax
IPromise<Contracts.BuildDefinitionRevision[]> getDefinitionRevisions(project, definitionId)
Parameters
project : string. Project ID or project name
definitionId : number.
Returns
IPromise<Contracts.BuildDefinitionRevision[]>
getDefinitions()
Gets definitions, optionally filtered by name
Syntax
Parameters
project : string. Optional. Project ID or project name
name : string. Optional.
type : Contracts.DefinitionType. Optional.
repositoryId : string. Optional.
repositoryType : string. Optional.
queryOrder : Contracts.DefinitionQueryOrder. Optional.
top : number. Optional.
Returns
IPromise<Contracts.DefinitionReference[]>
getQueues()
Gets queues, optionally filtered by name
Syntax
IPromise<Contracts.AgentPoolQueue[]> getQueues(name)
Parameters
name : string. Optional.
Returns
IPromise<Contracts.AgentPoolQueue[]>
getResourceUsage()
Syntax
IPromise<Contracts.BuildResourceUsage> getResourceUsage()
Parameters
Returns
IPromise<Contracts.BuildResourceUsage>
getTags()
Syntax
IPromise<string[]> getTags(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<string[]>
getTemplate()
Gets definition template filtered by id
Syntax
Parameters
project : string. Project ID or project name
templateId : string.
Returns
IPromise<Contracts.BuildDefinitionTemplate>
getTemplates()
Syntax
IPromise<Contracts.BuildDefinitionTemplate[]> getTemplates(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.BuildDefinitionTemplate[]>
getWorkItemsBetweenBuilds()
Gets all the work item IDs inbetween fromBuildId to toBuildId
Syntax
Parameters
project : string. Project ID or project name
fromBuildId : number.
toBuildId : number.
top : number. Optional.
Returns
IPromise<VSS_Common_Contracts.ResourceRef[]>
queueBuild()
Queues a build
Syntax
Parameters
build : Contracts.Build.
project : string. Optional.
ignoreWarnings : boolean. Optional.
Returns
IPromise<Contracts.Build>
saveTemplate()
Saves a definition template
Syntax
Parameters
template : Contracts.BuildDefinitionTemplate.
project : string.
templateId : string.
Returns
IPromise<Contracts.BuildDefinitionTemplate>
updateBuild()
Updates a build
Syntax
Parameters
build : Contracts.Build.
buildId : number.
project : string. Optional.
Returns
IPromise<Contracts.Build>
updateBuildSettings()
Updates the build settings
Syntax
IPromise<Contracts.BuildSettings> updateBuildSettings(settings)
Parameters
settings : Contracts.BuildSettings.
Returns
IPromise<Contracts.BuildSettings>
updateDefinition()
Updates an existing definition
Syntax
Parameters
definition : Contracts.BuildDefinition.
definitionId : number.
project : string. Optional.
secretsSourceDefinitionId : number. Optional.
secretsSourceDefinitionRevision : number. Optional.
Returns
IPromise<Contracts.BuildDefinition>
5/3/2018 • 2 minutes to read • Edit Online
CoreHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/Core/RestClient
Initialization sample
Methods
createTeam()
deleteTeam()
getProcessById()
getProcesses()
getProject()
getProjectCollection()
getProjectCollections()
getProjects()
getTeam()
getTeamMembers()
getTeams()
queueCreateProject()
queueDeleteProject()
updateProject()
updateTeam()
createTeam()
Creates a team
Syntax
Parameters
team : Contracts.WebApiTeam. The team data used to create the team.
projectId : string. The name or ID ( GUID ) of the team project in which to create the team.
Returns
IPromise<Contracts.WebApiTeam>
deleteTeam()
Deletes a team
Syntax
Parameters
projectId : string. The name or ID (GUID ) of the team project containing the team to delete.
teamId : string. The name of ID of the team to delete.
Returns
IPromise<void>
getProcessById()
Retrieve process by id
Syntax
IPromise<Contracts.Process> getProcessById(processId)
Parameters
processId : string.
Returns
IPromise<Contracts.Process>
getProcesses()
Syntax
IPromise<Contracts.Process[]> getProcesses()
Parameters
Returns
IPromise<Contracts.Process[]>
getProject()
Get project with the specified ID or name, optionally including capabilities.
Syntax
Parameters
projectId : string.
includeCapabilities : boolean. Optional.
includeHistory : boolean. Optional.
Returns
IPromise<Contracts.TeamProject>
getProjectCollection()
Get project collection with the specified ID or name.
Syntax
IPromise<Contracts.TeamProjectCollection> getProjectCollection(collectionId)
Parameters
collectionId : string.
Returns
IPromise<Contracts.TeamProjectCollection>
getProjectCollections()
Get project collection references for this application.
Syntax
Parameters
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.TeamProjectCollectionReference[]>
getProjects()
Get project references with the specified state
Syntax
IPromise<Contracts.TeamProjectReference[]> getProjects(stateFilter, top, skip)
Parameters
stateFilter: any. Optional. Filter on team projects in a specific team project state (default: WellFormed).
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.TeamProjectReference[]>
getTeam()
Gets a team
Syntax
Parameters
projectId : string.
teamId : string.
Returns
IPromise<Contracts.WebApiTeam>
getTeamMembers()
Syntax
Parameters
projectId : string.
teamId : string.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<VSS_Common_Contracts.IdentityRef[]>
getTeams()
Syntax
Returns
IPromise<Contracts.WebApiTeam[]>
queueCreateProject()
Queue a project creation.
Syntax
IPromise<VSS_Operations_Contracts.OperationReference> queueCreateProject(projectToCreate)
Parameters
projectToCreate : Contracts.TeamProject. The project to create.
Returns
IPromise<VSS_Operations_Contracts.OperationReference>
queueDeleteProject()
Queue a project deletion.
Syntax
IPromise<VSS_Operations_Contracts.OperationReference> queueDeleteProject(projectId)
Parameters
projectId : string. The project ID of the project to delete.
Returns
IPromise<VSS_Operations_Contracts.OperationReference>
updateProject()
Update an existing project's name, abbreviation, or description.
Syntax
Parameters
projectUpdate : Contracts.TeamProject. The updates for the project.
projectId : string. The project ID of the project to update.
Returns
IPromise<VSS_Operations_Contracts.OperationReference>
updateTeam()
Updates a team's name and/or description
Syntax
Parameters
teamData : Contracts.WebApiTeam.
projectId : string.
teamId : string.
Returns
IPromise<Contracts.WebApiTeam>
5/3/2018 • 2 minutes to read • Edit Online
CoreHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/Core/RestClient
Initialization sample
Methods
createTeam()
deleteTeam()
getProcessById()
getProcesses()
getProject()
getProjectCollection()
getProjectCollections()
getProjects()
getTeam()
getTeamMembers()
getTeams()
queueCreateProject()
queueDeleteProject()
updateProject()
updateTeam()
createTeam()
Creates a team
Syntax
Parameters
team : Contracts.WebApiTeam. The team data used to create the team.
projectId : string. The name or ID ( GUID ) of the team project in which to create the team.
Returns
IPromise<Contracts.WebApiTeam>
deleteTeam()
Deletes a team
Syntax
Parameters
projectId : string. The name or ID (GUID ) of the team project containing the team to delete.
teamId : string. The name of ID of the team to delete.
Returns
IPromise<void>
getProcessById()
Retrieve process by id
Syntax
IPromise<Contracts.Process> getProcessById(processId)
Parameters
processId : string.
Returns
IPromise<Contracts.Process>
getProcesses()
Syntax
IPromise<Contracts.Process[]> getProcesses()
Parameters
Returns
IPromise<Contracts.Process[]>
getProject()
Get project with the specified ID or name, optionally including capabilities.
Syntax
Parameters
projectId : string.
includeCapabilities : boolean. Optional.
includeHistory : boolean. Optional.
Returns
IPromise<Contracts.TeamProject>
getProjectCollection()
Get project collection with the specified ID or name.
Syntax
IPromise<Contracts.TeamProjectCollection> getProjectCollection(collectionId)
Parameters
collectionId : string.
Returns
IPromise<Contracts.TeamProjectCollection>
getProjectCollections()
Get project collection references for this application.
Syntax
Parameters
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.TeamProjectCollectionReference[]>
getProjects()
Get project references with the specified state
Syntax
IPromise<Contracts.TeamProjectReference[]> getProjects(stateFilter, top, skip)
Parameters
stateFilter: any. Optional. Filter on team projects in a specific team project state (default: WellFormed).
top : number. Optional. Default is 100.
skip : number. Optional.
Returns
IPromise<Contracts.TeamProjectReference[]>
getTeam()
Gets a team
Syntax
Parameters
projectId : string.
teamId : string.
Returns
IPromise<Contracts.WebApiTeam>
getTeamMembers()
Syntax
Parameters
projectId : string.
teamId : string.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<VSS_Common_Contracts.IdentityRef[]>
getTeams()
Syntax
Returns
IPromise<Contracts.WebApiTeam[]>
queueCreateProject()
Queue a project creation.
Syntax
IPromise<VSS_Operations_Contracts.OperationReference> queueCreateProject(projectToCreate)
Parameters
projectToCreate : Contracts.TeamProject. The project to create.
Returns
IPromise<VSS_Operations_Contracts.OperationReference>
queueDeleteProject()
Queue a project deletion.
Syntax
IPromise<VSS_Operations_Contracts.OperationReference> queueDeleteProject(projectId)
Parameters
projectId : string. The project ID of the project to delete.
Returns
IPromise<VSS_Operations_Contracts.OperationReference>
updateProject()
Update an existing project's name, abbreviation, or description.
Syntax
Parameters
projectUpdate : Contracts.TeamProject. The updates for the project.
projectId : string. The project ID of the project to update.
Returns
IPromise<VSS_Operations_Contracts.OperationReference>
updateTeam()
Updates a team's name and/or description
Syntax
Parameters
teamData : Contracts.WebApiTeam.
projectId : string.
teamId : string.
Returns
IPromise<Contracts.WebApiTeam>
5/3/2018 • 9 minutes to read • Edit Online
TestHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/TestManagement/RestClient
Initialization sample
Methods
addCustomFields()
addTestCasesToSuite()
addTestResultsToTestRun()
bulkUpdateTestResults()
cloneTestPlan()
cloneTestSuite()
createResultRetentionSettings()
createTestConfiguration()
createTestPlan()
createTestResultAttachment()
createTestRun()
createTestRunAttachment()
createTestSettings()
createTestSuite()
createTestVariable()
deleteResultRetentionSettings()
deleteTestConfiguration()
deleteTestRun()
deleteTestSettings()
deleteTestSuite()
deleteTestVariable()
getActionResults()
getBugsLinkedToTestResult()
getBuildCodeCoverage()
getCodeCoverageSummary()
getPlanById()
getPlanCloneInformation()
getPlans()
getPoint()
getPoints()
getResultParameters()
getResultRetentionSettings()
getSuiteCloneInformation()
getSuitesByTestCaseId()
getTestCaseById()
getTestCaseResultById()
getTestCaseResults()
getTestCases()
getTestConfigurationById()
getTestConfigurations()
getTestIteration()
getTestIterations()
getTestResultAttachmentContent()
getTestResultAttachmentZip()
getTestResultById()
getTestResults()
getTestResultsByIds()
getTestResultsByQuery()
getTestRunAttachmentContent()
getTestRunAttachmentZip()
getTestRunById()
getTestRunCodeCoverage()
getTestRunLogs()
getTestRuns()
getTestRunsByQuery()
getTestRunStatistics()
getTestSettingsById()
getTestSuiteById()
getTestSuitesForPlan()
getTestVariable()
getTestVariables()
queryCustomFields()
queryFailureDetailsForBuild()
queryFailureDetailsForTestRun()
queryReportForBuild()
queryResultTrendForBuild()
queryTestResultRecentBugs()
queryTestResultTrendReport()
removeTestCasesFromSuiteUrl()
updateCodeCoverageSummary()
updateResultRetentionSettings()
updateTestConfiguration()
updateTestPlan()
updateTestPoints()
updateTestResults()
updateTestRun()
updateTestSuite()
updateTestVariable()
addCustomFields()
Syntax
Parameters
newFields : Contracts.CustomTestFieldDefinition[].
project : string.
Returns
IPromise<Contracts.CustomTestFieldDefinition[]>
addTestCasesToSuite()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
testCaseIds : string.
Returns
IPromise<Contracts.SuiteTestCase[]>
addTestResultsToTestRun()
Syntax
Parameters
resultCreateModels : Contracts.TestResultCreateModel[].
project : string.
runId : number.
Returns
IPromise<Contracts.TestCaseResult[]>
bulkUpdateTestResults()
Syntax
Parameters
resultUpdateModel : Contracts.TestCaseResultUpdateModel.
project : string.
runId : number.
resultIds : number [].
Returns
IPromise<Contracts.TestCaseResult[]>
cloneTestPlan()
Syntax
Parameters
cloneRequestBody : Contracts.TestPlanCloneRequest.
project : string.
sourcePlanId : number.
Returns
IPromise<Contracts.CloneOperationInformation>
cloneTestSuite()
Syntax
Parameters
cloneRequestBody : Contracts.TestSuiteCloneRequest.
project : string.
sourceSuiteId : number.
planId : number.
Returns
IPromise<Contracts.CloneOperationInformation>
createResultRetentionSettings()
Syntax
IPromise<Contracts.ResultRetentionSettings> createResultRetentionSettings(retentionSettings,
project)
Parameters
retentionSettings : Contracts.ResultRetentionSettings.
project : string.
Returns
IPromise<Contracts.ResultRetentionSettings>
createTestConfiguration()
Syntax
Parameters
testConfiguration : Contracts.TestConfiguration.
project : string.
Returns
IPromise<Contracts.TestConfiguration>
createTestPlan()
Syntax
Parameters
testPlan : Contracts.PlanUpdateModel.
project : string.
Returns
IPromise<Contracts.TestPlan>
createTestResultAttachment()
Syntax
IPromise<Contracts.TestAttachmentReference> createTestResultAttachment(attachmentRequestModel,
project, runId, testCaseResultId)
Parameters
attachmentRequestModel : Contracts.TestAttachmentRequestModel.
project : string.
runId : number.
testCaseResultId : number.
Returns
IPromise<Contracts.TestAttachmentReference>
createTestRun()
Syntax
Parameters
testRun : Contracts.RunCreateModel.
project : string.
Returns
IPromise<Contracts.TestRun>
createTestRunAttachment()
Syntax
IPromise<Contracts.TestAttachmentReference> createTestRunAttachment(attachmentRequestModel,
project, runId)
Parameters
attachmentRequestModel : Contracts.TestAttachmentRequestModel.
project : string.
runId : number.
Returns
IPromise<Contracts.TestAttachmentReference>
createTestSettings()
Syntax
IPromise<number> createTestSettings(testSettings, project)
Parameters
testSettings : Contracts.TestSettings.
project : string.
Returns
IPromise<number>
createTestSuite()
Syntax
Parameters
testSuite : Contracts.SuiteCreateModel.
project : string.
planId : number.
suiteId : number.
Returns
IPromise<Contracts.TestSuite[]>
createTestVariable()
Syntax
Parameters
testVariable : Contracts.TestVariable.
project : string.
Returns
IPromise<Contracts.TestVariable>
deleteResultRetentionSettings()
Syntax
IPromise<void> deleteResultRetentionSettings(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<void>
deleteTestConfiguration()
Syntax
Parameters
project : string. Project ID or project name
testConfigurationId : number.
Returns
IPromise<void>
deleteTestRun()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<void>
deleteTestSettings()
Syntax
Parameters
project : string. Project ID or project name
testSettingsId : number.
Returns
IPromise<void>
deleteTestSuite()
Syntax
IPromise<void> deleteTestSuite(project, planId, suiteId)
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
Returns
IPromise<void>
deleteTestVariable()
Syntax
Parameters
project : string. Project ID or project name
testVariableId : number.
Returns
IPromise<void>
getActionResults()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
iterationId : number.
actionPath : string. Optional.
Returns
IPromise<Contracts.TestActionResultModel[]>
getBugsLinkedToTestResult()
Syntax
IPromise<Contracts.WorkItemReference[]> getBugsLinkedToTestResult(project, runId,
testCaseResultId)
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
Returns
IPromise<Contracts.WorkItemReference[]>
getBuildCodeCoverage()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
flags : number.
Returns
IPromise<Contracts.BuildCoverage[]>
getCodeCoverageSummary()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
deltaBuildId : number. Optional.
Returns
IPromise<Contracts.CodeCoverageSummary>
getPlanById()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
Returns
IPromise<Contracts.TestPlan>
getPlanCloneInformation()
Syntax
Parameters
project : string. Project ID or project name
operationId : number.
includeDetails : boolean. Optional.
Returns
IPromise<Contracts.CloneOperationInformation>
getPlans()
Syntax
Parameters
project : string. Project ID or project name
owner : string. Optional.
skip : number. Optional.
top : number. Optional.
includePlanDetails : boolean. Optional.
filterActivePlans : boolean. Optional.
Returns
IPromise<Contracts.TestPlan[]>
getPoint()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
pointIds : number.
witFields : string. Optional.
Returns
IPromise<Contracts.TestPoint>
getPoints()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
witFields : string. Optional.
configurationId : string. Optional.
testCaseId : string. Optional.
testPointIds : string. Optional.
includePointDetails : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestPoint[]>
getResultParameters()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
iterationId : number.
paramName : string. Optional.
Returns
IPromise<Contracts.TestResultParameterModel[]>
getResultRetentionSettings()
Syntax
IPromise<Contracts.ResultRetentionSettings> getResultRetentionSettings(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.ResultRetentionSettings>
getSuiteCloneInformation()
Syntax
Parameters
project : string. Project ID or project name
operationId : number.
includeDetails : boolean. Optional.
Returns
IPromise<Contracts.CloneOperationInformation>
getSuitesByTestCaseId()
Syntax
IPromise<Contracts.TestSuite[]> getSuitesByTestCaseId(testCaseId)
Parameters
testCaseId : number.
Returns
IPromise<Contracts.TestSuite[]>
getTestCaseById()
Syntax
IPromise<Contracts.SuiteTestCase> getTestCaseById(project, planId, suiteId, testCaseIds)
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
testCaseIds : number.
Returns
IPromise<Contracts.SuiteTestCase>
getTestCaseResultById()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
includeIterationDetails : boolean.
includeAssociatedBugs : boolean. Optional.
Returns
IPromise<Contracts.TestCaseResult>
getTestCaseResults()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
includeIterationDetails : boolean.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestCases()
Syntax
IPromise<Contracts.SuiteTestCase[]> getTestCases(project, planId, suiteId)
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
Returns
IPromise<Contracts.SuiteTestCase[]>
getTestConfigurationById()
Syntax
Parameters
project : string. Project ID or project name
testConfigurationId : number.
Returns
IPromise<Contracts.TestConfiguration>
getTestConfigurations()
Syntax
Parameters
project : string. Project ID or project name
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestConfiguration[]>
getTestIteration()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
iterationId : number.
includeActionResults : boolean. Optional.
Returns
IPromise<Contracts.TestIterationDetailsModel>
getTestIterations()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
includeActionResults : boolean. Optional.
Returns
IPromise<Contracts.TestIterationDetailsModel[]>
getTestResultAttachmentContent()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestResultAttachmentZip()
Syntax
IPromise<ArrayBuffer> getTestResultAttachmentZip(project, runId, testCaseResultId, attachmentId)
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestResultById()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
detailsToInclude : Contracts.ResultDetails. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestResults()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
detailsToInclude : Contracts.ResultDetails. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestResultsByIds()
Syntax
Parameters
ids : Contracts.TestCaseResultIdentifier [].
project : string.
fields : string[].
Returns
IPromise<Contracts.TestCaseResult[]>
getTestResultsByQuery()
Syntax
Parameters
query : Contracts.QueryModel.
project : string.
includeResultDetails : boolean. Optional.
includeIterationDetails : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestRunAttachmentContent()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestRunAttachmentZip()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestRunById()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<Contracts.TestRun>
getTestRunCodeCoverage()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
flags : number.
Returns
IPromise<Contracts.TestRunCoverage[]>
getTestRunLogs()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<Contracts.TestMessageLogDetails[]>
getTestRuns()
Syntax
Parameters
project : string. Project ID or project name
buildUri : string. Optional.
owner : string. Optional.
tmiRunId : string. Optional.
planId : number. Optional.
includeRunDetails : boolean. Optional.
automated : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestRun[]>
getTestRunsByQuery()
Syntax
Parameters
query : Contracts.QueryModel.
project : string.
includeRunDetails : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestRun[]>
getTestRunStatistics()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<Contracts.TestRunStatistic>
getTestSettingsById()
Syntax
Parameters
project : string. Project ID or project name
testSettingsId : number.
Returns
IPromise<Contracts.TestSettings>
getTestSuiteById()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
includeChildSuites : boolean. Optional.
Returns
IPromise<Contracts.TestSuite>
getTestSuitesForPlan()
Syntax
Returns
IPromise<Contracts.TestSuite[]>
getTestVariable()
Syntax
Parameters
project : string. Project ID or project name
testVariableId : number.
Returns
IPromise<Contracts.TestVariable>
getTestVariables()
Syntax
Parameters
project : string. Project ID or project name
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestVariable[]>
queryCustomFields()
Syntax
Parameters
project : string. Project ID or project name
scopeFilter : Contracts.CustomTestFieldScope.
Returns
IPromise<Contracts.CustomTestFieldDefinition[]>
queryFailureDetailsForBuild()
Syntax
Parameters
build : Contracts.BuildReference.
project : string.
sourceWorkflow : string.
buildToCompare : Contracts.BuildReference.
Returns
IPromise<Contracts.TestFailuresAnalysis>
queryFailureDetailsForTestRun()
Syntax
Parameters
project : string. Project ID or project name
testRunId : number.
Returns
IPromise<Contracts.TestFailuresAnalysis>
queryReportForBuild()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
sourceWorkflow : string.
includeFailureDetails : boolean.
buildToCompare : Contracts.BuildReference.
Returns
IPromise<Contracts.TestReport>
queryResultTrendForBuild()
Syntax
Parameters
filter : Contracts.TestResultTrendFilter.
project : string.
buildCount : number. Optional.
Returns
IPromise<Contracts.AggregatedResultsForBuild[]>
queryTestResultRecentBugs()
Syntax
Parameters
project : string. Project ID or project name
testRunId : number.
testResultId : number.
recentDays : number. Optional.
Returns
IPromise<Contracts.WorkItemReference[]>
queryTestResultTrendReport()
Syntax
Parameters
project : string. Project ID or project name
testRunId : number.
testResultId : number.
historyDays : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
removeTestCasesFromSuiteUrl()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
testCaseIds : string.
Returns
IPromise<void>
updateCodeCoverageSummary()
Syntax
Parameters
coverageData : Contracts.CodeCoverageData.
project : string.
buildId : number.
Returns
IPromise<void>
updateResultRetentionSettings()
Syntax
IPromise<Contracts.ResultRetentionSettings> updateResultRetentionSettings(retentionSettings,
project)
Parameters
retentionSettings : Contracts.ResultRetentionSettings.
project : string.
Returns
IPromise<Contracts.ResultRetentionSettings>
updateTestConfiguration()
Syntax
Parameters
testConfiguration : Contracts.TestConfiguration.
project : string.
testConfigurationId : number.
Returns
IPromise<Contracts.TestConfiguration>
updateTestPlan()
Syntax
Parameters
planUpdateModel : Contracts.PlanUpdateModel.
project : string.
planId : number.
Returns
IPromise<Contracts.TestPlan>
updateTestPoints()
Syntax
Parameters
pointUpdateModel : Contracts.PointUpdateModel.
project : string.
planId : number.
suiteId : number.
pointIds : string.
Returns
IPromise<Contracts.TestPoint[]>
updateTestResults()
Syntax
Parameters
resultUpdateModels : Contracts.TestCaseResultUpdateModel[].
project : string.
runId : number.
Returns
IPromise<Contracts.TestCaseResult[]>
updateTestRun()
Syntax
Parameters
runUpdateModel : Contracts.RunUpdateModel.
project : string.
runId : number.
Returns
IPromise<Contracts.TestRun>
updateTestSuite()
Syntax
Parameters
suiteUpdateModel : Contracts.SuiteUpdateModel.
project : string.
planId : number.
suiteId : number.
Returns
IPromise<Contracts.TestSuite>
updateTestVariable()
Syntax
Parameters
testVariable : Contracts.TestVariable.
project : string.
testVariableId : number.
Returns
IPromise<Contracts.TestVariable>
5/3/2018 • 10 minutes to read • Edit Online
TestHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/TestManagement/RestClient
Initialization sample
Methods
addCustomFields()
addTestCasesToSuite()
addTestResultsToTestRun()
bulkUpdateTestResults()
cloneTestPlan()
cloneTestSuite()
createResultRetentionSettings()
createTestConfiguration()
createTestPlan()
createTestResultAttachment()
createTestRun()
createTestRunAttachment()
createTestSettings()
createTestSuite()
createTestSession()
createTestVariable()
deleteResultRetentionSettings()
deleteTestConfiguration()
deleteTestRun()
deleteTestSettings()
deleteTestSuite()
deleteTestVariable()
getActionResults()
getBugsLinkedToTestResult()
getBuildCodeCoverage()
getCodeCoverageSummary()
getPlanById()
getPlanCloneInformation()
getPlans()
getPoint()
getPoints()
getResultParameters()
getResultRetentionSettings()
getSuiteCloneInformation()
getSuiteEntries()
getSuitesByTestCaseId()
getTestCaseById()
getTestCaseResultById()
getTestCaseResults()
getTestCases()
getTestConfigurationById()
getTestConfigurations()
getTestIteration()
getTestIterations()
getTestResultAttachmentContent()
getTestResultAttachmentZip()
getTestResultById()
getTestResultDetailsForBuild()
getTestResults()
getTestResultsByIds()
getTestResultsByQuery()
getTestRunAttachmentContent()
getTestRunAttachmentZip()
getTestRunById()
getTestRunCodeCoverage()
getTestRunLogs()
getTestRuns()
getTestRunsByQuery()
getTestRunStatistics()
getTestSettingsById()
getTestSuiteById()
getTestSuitesForPlan()
getTestVariable()
getTestSessions()
getTestVariables()
queryCustomFields()
queryFailureDetailsForBuild()
queryFailureDetailsForTestRun()
queryReportForBuild()
queryResultTrendForBuild()
queryTestResultRecentBugs()
queryTestResultTrendReport()
removeTestCasesFromSuiteUrl()
reorderSuiteEntries()
updateCodeCoverageSummary()
updateResultRetentionSettings()
updateTestConfiguration()
updateTestPlan()
updateTestPoints()
updateTestResults()
updateTestRun()
updateTestSuite()
updateTestSession()
updateTestVariable()
addCustomFields()
Syntax
Parameters
newFields : Contracts.CustomTestFieldDefinition[].
project : string.
Returns
IPromise<Contracts.CustomTestFieldDefinition[]>
addTestCasesToSuite()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
testCaseIds : string.
Returns
IPromise<Contracts.SuiteTestCase[]>
addTestResultsToTestRun()
Syntax
Returns
IPromise<Contracts.TestCaseResult[]>
bulkUpdateTestResults()
Syntax
Parameters
resultUpdateModel : Contracts.TestCaseResultUpdateModel.
project : string.
runId : number.
resultIds : number [].
Returns
IPromise<Contracts.TestCaseResult[]>
cloneTestPlan()
Syntax
Parameters
cloneRequestBody : Contracts.TestPlanCloneRequest.
project : string.
sourcePlanId : number.
Returns
IPromise<Contracts.CloneOperationInformation>
cloneTestSuite()
Syntax
Returns
IPromise<Contracts.CloneOperationInformation>
createResultRetentionSettings()
Syntax
IPromise<Contracts.ResultRetentionSettings> createResultRetentionSettings(retentionSettings,
project)
Parameters
retentionSettings : Contracts.ResultRetentionSettings.
project : string.
Returns
IPromise<Contracts.ResultRetentionSettings>
createTestConfiguration()
Syntax
Parameters
testConfiguration : Contracts.TestConfiguration.
project : string.
Returns
IPromise<Contracts.TestConfiguration>
createTestPlan()
Syntax
Parameters
testPlan : Contracts.PlanUpdateModel.
project : string.
Returns
IPromise<Contracts.TestPlan>
createTestResultAttachment()
Syntax
IPromise<Contracts.TestAttachmentReference> createTestResultAttachment(attachmentRequestModel,
project, runId, testCaseResultId)
Parameters
attachmentRequestModel : Contracts.TestAttachmentRequestModel.
project : string.
runId : number.
testCaseResultId : number.
Returns
IPromise<Contracts.TestAttachmentReference>
createTestRun()
Syntax
Parameters
testRun : Contracts.RunCreateModel.
project : string.
Returns
IPromise<Contracts.TestRun>
createTestRunAttachment()
Syntax
IPromise<Contracts.TestAttachmentReference> createTestRunAttachment(attachmentRequestModel,
project, runId)
Parameters
attachmentRequestModel : Contracts.TestAttachmentRequestModel.
project : string.
runId : number.
Returns
IPromise<Contracts.TestAttachmentReference>
createTestSettings()
Syntax
Parameters
testSettings : Contracts.TestSettings.
project : string.
Returns
IPromise<number>
createTestSuite()
Syntax
Parameters
testSuite : Contracts.SuiteCreateModel.
project : string.
planId : number.
suiteId : number.
Returns
IPromise<Contracts.TestSuite[]>
createTestSession()
Syntax
Parameters
testSession : Contracts.TestSession.
teamContext : Contracts.TeamContext.
Returns
IPromise<Contracts.TestSession>
createTestVariable()
Syntax
Returns
IPromise<Contracts.TestVariable>
deleteResultRetentionSettings()
Syntax
IPromise<void> deleteResultRetentionSettings(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<void>
deleteTestConfiguration()
Syntax
Parameters
project : string. Project ID or project name
testConfigurationId : number.
Returns
IPromise<void>
deleteTestRun()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<void>
deleteTestSettings()
Syntax
Parameters
project : string. Project ID or project name
testSettingsId : number.
Returns
IPromise<void>
deleteTestSuite()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
Returns
IPromise<void>
deleteTestVariable()
Syntax
Parameters
project : string. Project ID or project name
testVariableId : number.
Returns
IPromise<void>
getActionResults()
Syntax
Returns
IPromise<Contracts.TestActionResultModel[]>
getBugsLinkedToTestResult()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
Returns
IPromise<Contracts.WorkItemReference[]>
getBuildCodeCoverage()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
flags : number.
Returns
IPromise<Contracts.BuildCoverage[]>
getCodeCoverageSummary()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
deltaBuildId : number. Optional.
Returns
IPromise<Contracts.CodeCoverageSummary>
getPlanById()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
Returns
IPromise<Contracts.TestPlan>
getPlanCloneInformation()
Syntax
Parameters
project : string. Project ID or project name
operationId : number.
includeDetails : boolean. Optional.
Returns
IPromise<Contracts.CloneOperationInformation>
getPlans()
Syntax
Parameters
project : string. Project ID or project name
owner : string. Optional.
skip : number. Optional.
top : number. Optional.
includePlanDetails : boolean. Optional.
filterActivePlans : boolean. Optional.
Returns
IPromise<Contracts.TestPlan[]>
getPoint()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
pointIds : number.
witFields : string. Optional.
Returns
IPromise<Contracts.TestPoint>
getPoints()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
witFields : string. Optional.
configurationId : string. Optional.
testCaseId : string. Optional.
testPointIds : string. Optional.
includePointDetails : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestPoint[]>
getResultParameters()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
iterationId : number.
paramName : string. Optional.
Returns
IPromise<Contracts.TestResultParameterModel[]>
getResultRetentionSettings()
Syntax
IPromise<Contracts.ResultRetentionSettings> getResultRetentionSettings(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.ResultRetentionSettings>
getSuiteCloneInformation()
Syntax
Parameters
project : string. Project ID or project name
operationId : number.
includeDetails : boolean. Optional.
Returns
IPromise<Contracts.CloneOperationInformation>
getSuiteEntries()
Syntax
Parameters
project : string. Project ID or project name
suiteId : number.
Returns
IPromise<Contracts.SuiteEntry[]>
getSuitesByTestCaseId()
Syntax
IPromise<Contracts.TestSuite[]> getSuitesByTestCaseId(testCaseId)
Parameters
testCaseId : number.
Returns
IPromise<Contracts.TestSuite[]>
getTestCaseById()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
testCaseIds : number.
Returns
IPromise<Contracts.SuiteTestCase>
getTestCaseResultById()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
includeIterationDetails : boolean.
includeAssociatedBugs : boolean. Optional.
Returns
IPromise<Contracts.TestCaseResult>
getTestCaseResults()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
includeIterationDetails : boolean.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestCases()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
Returns
IPromise<Contracts.SuiteTestCase[]>
getTestConfigurationById()
Syntax
Parameters
project : string. Project ID or project name
testConfigurationId : number.
Returns
IPromise<Contracts.TestConfiguration>
getTestConfigurations()
Syntax
Parameters
project : string. Project ID or project name
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestConfiguration[]>
getTestIteration()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
iterationId : number.
includeActionResults : boolean. Optional.
Returns
IPromise<Contracts.TestIterationDetailsModel>
getTestIterations()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
includeActionResults : boolean. Optional.
Returns
IPromise<Contracts.TestIterationDetailsModel[]>
getTestResultAttachmentContent()
Returns a test result attachment
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestResultAttachmentZip()
Returns a test result attachment
Syntax
Parameters
project : string. Project ID or project name
runId : number.
testCaseResultId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestResultById()
Syntax
Returns
IPromise<Contracts.TestCaseResult[]>
getTestResultDetailsForBuild()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
sourceWorkflow : string.
groupBy : string. Optional.
filter : string. Optional.
Returns
IPromise<Contracts.AggregatedResultsWithDetails>
getTestResults()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
detailsToInclude : Contracts.ResultDetails. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestResultsByIds()
Syntax
IPromise<Contracts.TestCaseResult[]> getTestResultsByIds(ids, project, fields)
Parameters
ids : Contracts.TestCaseResultIdentifier [].
project : string.
fields : string[].
Returns
IPromise<Contracts.TestCaseResult[]>
getTestResultsByQuery()
Syntax
Parameters
query : Contracts.QueryModel.
project : string.
includeResultDetails : boolean. Optional.
includeIterationDetails : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
getTestRunAttachmentContent()
Returns a test run attachment
Syntax
Parameters
project : string. Project ID or project name
runId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestRunAttachmentZip()
Returns a test run attachment
Syntax
Parameters
project : string. Project ID or project name
runId : number.
attachmentId : number.
Returns
IPromise<ArrayBuffer>
getTestRunById()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<Contracts.TestRun>
getTestRunCodeCoverage()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
flags : number.
Returns
IPromise<Contracts.TestRunCoverage[]>
getTestRunLogs()
Syntax
Returns
IPromise<Contracts.TestMessageLogDetails[]>
getTestRuns()
Syntax
Parameters
project : string. Project ID or project name
buildUri : string. Optional.
owner : string. Optional.
tmiRunId : string. Optional.
planId : number. Optional.
includeRunDetails : boolean. Optional.
automated : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestRun[]>
getTestRunsByQuery()
Syntax
Parameters
query : Contracts.QueryModel.
project : string.
includeRunDetails : boolean. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestRun[]>
getTestRunStatistics()
Syntax
Parameters
project : string. Project ID or project name
runId : number.
Returns
IPromise<Contracts.TestRunStatistic>
getTestSettingsById()
Syntax
Parameters
project : string. Project ID or project name
testSettingsId : number.
Returns
IPromise<Contracts.TestSettings>
getTestSuiteById()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
includeChildSuites : boolean. Optional.
Returns
IPromise<Contracts.TestSuite>
getTestSuitesForPlan()
Syntax
Returns
IPromise<Contracts.TestSuite[]>
getTestSessions()
Syntax
Parameters
teamContext : string. Project ID or project name
period : number. Optional.
allSessions : boolean. Optional.
includeAllProperties : boolean. Optional.
source : Contracts.TestSessionSource[]. Optional.
includeOnlyCompletedSessions : boolean. Optional.
Returns
IPromise<Contracts.TestSession[]>
getTestVariable()
Syntax
Parameters
project : string. Project ID or project name
testVariableId : number.
Returns
IPromise<Contracts.TestVariable>
getTestVariables()
Syntax
IPromise<Contracts.TestVariable[]> getTestVariables(project, skip, top)
Parameters
project : string. Project ID or project name
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestVariable[]>
queryCustomFields()
Syntax
Parameters
project : string. Project ID or project name
scopeFilter : Contracts.CustomTestFieldScope.
Returns
IPromise<Contracts.CustomTestFieldDefinition[]>
queryFailureDetailsForBuild()
Syntax
Parameters
build : Contracts.BuildReference.
project : string.
sourceWorkflow : string.
buildToCompare : Contracts.BuildReference.
Returns
IPromise<Contracts.TestFailuresAnalysis>
queryFailureDetailsForTestRun()
Syntax
Parameters
project : string. Project ID or project name
testRunId : number.
Returns
IPromise<Contracts.TestFailuresAnalysis>
queryReportForBuild()
Syntax
Parameters
project : string. Project ID or project name
buildId : number.
sourceWorkflow : string.
includeFailureDetails : boolean.
buildToCompare : Contracts.BuildReference.
Returns
IPromise<Contracts.TestReport>
queryResultTrendForBuild()
Syntax
Parameters
filter : Contracts.TestResultTrendFilter.
project : string.
buildCount : number. Optional.
Returns
IPromise<Contracts.AggregatedResultsForBuild[]>
queryTestResultRecentBugs()
Syntax
Parameters
project : string. Project ID or project name
testRunId : number.
testResultId : number.
recentDays : number. Optional.
Returns
IPromise<Contracts.WorkItemReference[]>
queryTestResultTrendReport()
Syntax
Parameters
project : string. Project ID or project name
testRunId : number.
testResultId : number.
historyDays : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.TestCaseResult[]>
removeTestCasesFromSuiteUrl()
Syntax
Parameters
project : string. Project ID or project name
planId : number.
suiteId : number.
testCaseIds : string.
Returns
IPromise<void>
reorderSuiteEntries()
Syntax
Returns
IPromise<Contracts.SuiteEntry[]>
updateCodeCoverageSummary()
http://(tfsserver):8080/tfs/DefaultCollection/_apis/test/CodeCoverage?buildId=10 Request: Json of code coverage
summary
Syntax
Parameters
coverageData : Contracts.CodeCoverageData.
project : string.
buildId : number.
Returns
IPromise<void>
updateResultRetentionSettings()
Syntax
IPromise<Contracts.ResultRetentionSettings> updateResultRetentionSettings(retentionSettings,
project)
Parameters
retentionSettings : Contracts.ResultRetentionSettings.
project : string.
Returns
IPromise<Contracts.ResultRetentionSettings>
updateTestConfiguration()
Syntax
Parameters
testConfiguration : Contracts.TestConfiguration.
project : string.
testConfigurationId : number.
Returns
IPromise<Contracts.TestConfiguration>
updateTestPlan()
Syntax
Parameters
planUpdateModel : Contracts.PlanUpdateModel.
project : string.
planId : number.
Returns
IPromise<Contracts.TestPlan>
updateTestPoints()
Syntax
Parameters
pointUpdateModel : Contracts.PointUpdateModel.
project : string.
planId : number.
suiteId : number.
pointIds : string.
Returns
IPromise<Contracts.TestPoint[]>
updateTestResults()
Syntax
Parameters
resultUpdateModels : Contracts.TestCaseResultUpdateModel[].
project : string.
runId : number.
Returns
IPromise<Contracts.TestCaseResult[]>
updateTestRun()
Syntax
Parameters
runUpdateModel : Contracts.RunUpdateModel.
project : string.
runId : number.
Returns
IPromise<Contracts.TestRun>
updateTestSuite()
Syntax
Parameters
suiteUpdateModel : Contracts.SuiteUpdateModel.
project : string.
planId : number.
suiteId : number.
Returns
IPromise<Contracts.TestSuite>
updateTestSession()
Syntax
Parameters
testSession : Contracts.TestSession.
teamContext : Contracts.TeamContext.
Returns
IPromise<Contracts.TestSession>
updateTestVariable()
Syntax
Parameters
testVariable : Contracts.TestVariable.
project : string.
testVariableId : number.
Returns
IPromise<Contracts.TestVariable>
5/3/2018 • 10 minutes to read • Edit Online
GitHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/VersionControl/GitRestClient
Initialization sample
Methods
createCommitStatus()
createPullRequest()
createPullRequestReviewer()
createPullRequestReviewers()
createPush()
createRepository()
deletePullRequestReviewer()
deleteRepository()
getBlob()
getBlobContent()
getBlobsZip()
getBlobZip()
getBranch()
getBranches()
getChanges()
getCommit()
getCommits()
getCommitsBatch()
getItem()
getItemContent()
getItems()
getItemsBatch()
getItemText()
getItemZip()
getPullRequest()
getPullRequestCommits()
getPullRequestReviewer()
getPullRequestReviewers()
getPullRequests()
getPullRequestsByProject()
getPullRequestWorkItems()
getPush()
getPushCommits()
getPushes()
getRefs()
getRepositories()
getRepository()
getStatuses()
getTree()
getTreeZip()
updatePullRequest()
updateRefs()
updateRepository()
createCommitStatus()
Syntax
Parameters
gitCommitStatusToCreate : Contracts.GitStatus.
commitId : string.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitStatus>
createPullRequest()
Create a git pull request
Syntax
Parameters
gitPullRequestToCreate : Contracts.GitPullRequest.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitPullRequest>
createPullRequestReviewer()
Adds a reviewer to a git pull request
Syntax
Parameters
reviewer : Contracts.IdentityRefWithVote.
repositoryId : string.
pullRequestId : number.
reviewerId : string.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote>
createPullRequestReviewers()
Adds reviewers to a git pull request
Syntax
Parameters
reviewers : VSS_Common_Contracts.IdentityRef[].
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote[]>
createPush()
Push changes to the repository.
Syntax
Returns
IPromise<Contracts.GitPush>
createRepository()
Create a git repository
Syntax
Parameters
gitRepositoryToCreate : Contracts.GitRepository.
project : string. Optional.
Returns
IPromise<Contracts.GitRepository>
deletePullRequestReviewer()
Adds reviewers to a git pull request
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
reviewerId : string.
project : string. Optional.
Returns
IPromise<void>
deleteRepository()
Delete a git repository
Syntax
Returns
IPromise<void>
getBlob()
Gets a single blob.
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
download : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<Contracts.GitBlobRef>
getBlobContent()
Gets a single blob.
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
download : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getBlobsZip()
Gets one or more blobs in a zip file download.
Syntax
Parameters
blobIds : string[].
repositoryId : string.
project : string. Optional.
filename : string. Optional.
Returns
IPromise<ArrayBuffer>
getBlobZip()
Gets a single blob.
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
download : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getBranch()
Retrieve statistics about a single branch.
Syntax
Parameters
repositoryId : string. Friendly name or guid of repository
name : string. Name of the branch
project : string. Optional. Project ID or project name
baseVersionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitBranchStats>
getBranches()
Retrieve statistics about all branches within a repository.
Syntax
Parameters
repositoryId : string. Friendly name or guid of repository
project : string. Optional. Project ID or project name
baseVersionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitBranchStats[]>
getChanges()
Retrieve changes for a particular commit.
Syntax
Parameters
commitId : string. The ID of the commit.
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
top : number. Optional. The maximum number of changes to return.
skip : number. Optional. The number of changes to skip.
Returns
IPromise<Contracts.GitCommitChanges>
getCommit()
Retrieve a particular commit.
Syntax
Parameters
commitId : string. The ID of the commit.
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
changeCount : number. Optional. The number of changes to include in the result.
Returns
IPromise<Contracts.GitCommit>
getCommits()
Retrieve git commits for a project
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
searchCriteria : Contracts.GitQueryCommitsCriteria.
project : string. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getCommitsBatch()
Retrieve git commits for a project
Syntax
Parameters
searchCriteria : Contracts.GitQueryCommitsCriteria. Search options
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getItem()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitItem>
getItemContent()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getItems()
Get Item Metadata and/or Content for a collection of items. The download parameter is to indicate whether the
content should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content
which is always returned as a download.
Syntax
Parameters
repositoryId : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
includeLinks : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitItem[]>
getItemsBatch()
Post for retrieving a creating a batch out of a set of items in a repo / project given a list of paths or a long path
Syntax
Parameters
requestData : Contracts.GitItemRequestData.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitItem[][]>
getItemText()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
IPromise<string> getItemText(repositoryId, path, project, scopePath, recursionLevel,
includeContentMetadata, latestProcessedChange, download, versionDescriptor)
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<string>
getItemZip()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getPullRequest()
Retrieve a pull request
Syntax
IPromise<Contracts.GitPullRequest> getPullRequest(repositoryId, pullRequestId, project,
maxCommentLength, skip, top, includeCommits, includeWorkItemRefs)
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
maxCommentLength : number. Optional.
skip : number. Optional.
top : number. Optional.
includeCommits : boolean. Optional.
includeWorkItemRefs : boolean. Optional.
Returns
IPromise<Contracts.GitPullRequest>
getPullRequestCommits()
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getPullRequestReviewer()
Retrieve a reviewer from a pull request
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
reviewerId : string.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote>
getPullRequestReviewers()
Retrieve a pull request reviewers
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote[]>
getPullRequests()
Query for pull requests
Syntax
Parameters
repositoryId : string.
searchCriteria : Contracts.GitPullRequestSearchCriteria.
project : string. Optional.
maxCommentLength : number. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitPullRequest[]>
getPullRequestsByProject()
Syntax
Parameters
project : string. Project ID or project name
searchCriteria : Contracts.GitPullRequestSearchCriteria.
maxCommentLength : number. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitPullRequest[]>
getPullRequestWorkItems()
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
commitsTop : number. Optional.
commitsSkip : number. Optional.
Returns
IPromise<Contracts.AssociatedWorkItem[]>
getPush()
Retrieve a particular push.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
pushId : number. The ID of the push.
project : string. Optional. Project ID or project name
includeCommits : number. Optional. The number of commits to include in the result.
includeRefUpdates : boolean. Optional.
Returns
IPromise<Contracts.GitPush>
getPushCommits()
Retrieve a list of commits associated with a particular push.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
pushId : number. The ID of the push.
project : string. Optional. Project ID or project name
top : number. Optional. The maximum number of commits to return ("get the top x commits").
skip : number. Optional. The number of commits to skip.
includeLinks : boolean. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getPushes()
Retrieves pushes associated with the specified repository.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
skip : number. Optional.
top : number. Optional.
searchCriteria : Contracts.GitPushSearchCriteria. Optional.
Returns
IPromise<Contracts.GitPush[]>
getRefs()
Queries the provided repository for its refs and returns them.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
filter : string. Optional. [optional] A filter to apply to the refs.
includeLinks : boolean. Optional. [optional] Specifies if referenceLinks should be included in the result. default is
false.
includeStatuses : boolean. Optional. [optional] Includes the first 1000 statuses of the commits the refs are
pointing at as well. default is false.
Returns
IPromise<Contracts.GitRef[]>
getRepositories()
Retrieve git repositories.
Syntax
Parameters
project : string. Optional. Project ID or project name
includeLinks : boolean. Optional.
Returns
IPromise<Contracts.GitRepository[]>
getRepository()
Syntax
Parameters
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitRepository>
getStatuses()
Syntax
Parameters
commitId : string.
repositoryId : string.
project : string. Optional.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.GitStatus[]>
getTree()
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
projectId : string. Optional.
recursive : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<Contracts.GitTreeRef>
getTreeZip()
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
projectId : string. Optional.
recursive : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
updatePullRequest()
Updates a pull request
Syntax
Parameters
gitPullRequestToUpdate : Contracts.GitPullRequest.
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.GitPullRequest>
updateRefs()
Creates or updates refs with the given information
Syntax
Parameters
refUpdates : Contracts.GitRefUpdate[]. List of ref updates to attempt to perform
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
projectId : string. Optional. The ID of the project.
Returns
IPromise<Contracts.GitRefUpdateResult[]>
updateRepository()
Updates the Git repository with the single populated change in the specified repository information.
Syntax
Parameters
newRepositoryInfo : Contracts.GitRepository.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitRepository>
5/3/2018 • 10 minutes to read • Edit Online
GitHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/VersionControl/GitRestClient
Initialization sample
Methods
createCommitStatus()
createPullRequest()
createPullRequestReviewer()
createPullRequestReviewers()
createPush()
createRepository()
deletePullRequestReviewer()
deleteRepository()
getBlob()
getBlobContent()
getBlobsZip()
getBlobZip()
getBranch()
getBranches()
getChanges()
getCommit()
getCommits()
getCommitsBatch()
getItem()
getItemContent()
getItems()
getItemsBatch()
getItemText()
getItemZip()
getPullRequest()
getPullRequestCommits()
getPullRequestReviewer()
getPullRequestReviewers()
getPullRequests()
getPullRequestsByProject()
getPullRequestWorkItems()
getPush()
getPushCommits()
getPushes()
getRefs()
getRepositories()
getRepository()
getStatuses()
getSuggestions()
getTree()
getTreeZip()
updatePullRequest()
updateRefs()
updateRepository()
createCommitStatus()
Syntax
Parameters
gitCommitStatusToCreate : Contracts.GitStatus.
commitId : string.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitStatus>
createPullRequest()
Create a git pull request
Syntax
Parameters
gitPullRequestToCreate : Contracts.GitPullRequest.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitPullRequest>
createPullRequestReviewer()
Adds a reviewer to a git pull request
Syntax
Parameters
reviewer : Contracts.IdentityRefWithVote.
repositoryId : string.
pullRequestId : number.
reviewerId : string.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote>
createPullRequestReviewers()
Adds reviewers to a git pull request
Syntax
Parameters
reviewers : VSS_Common_Contracts.IdentityRef[].
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote[]>
createPush()
Push changes to the repository.
Syntax
IPromise<Contracts.GitPush> createPush(push, repositoryId, project)
Parameters
push : Contracts.GitPush.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitPush>
createRepository()
Create a git repository
Syntax
Parameters
gitRepositoryToCreate : Contracts.GitRepository.
project : string. Optional.
Returns
IPromise<Contracts.GitRepository>
deletePullRequestReviewer()
Adds reviewers to a git pull request
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
reviewerId : string.
project : string. Optional.
Returns
IPromise<void>
deleteRepository()
Delete a git repository
Syntax
IPromise<void> deleteRepository(repositoryId, project)
Parameters
repositoryId : string.
project : string. Optional.
Returns
IPromise<void>
getBlob()
Gets a single blob.
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
download : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<Contracts.GitBlobRef>
getBlobContent()
Gets a single blob.
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
download : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getBlobsZip()
Gets one or more blobs in a zip file download.
Syntax
Parameters
blobIds : string[].
repositoryId : string.
project : string. Optional.
filename : string. Optional.
Returns
IPromise<ArrayBuffer>
getBlobZip()
Gets a single blob.
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
download : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getBranch()
Retrieve statistics about a single branch.
Syntax
Parameters
repositoryId : string. Friendly name or guid of repository
name : string. Name of the branch
project : string. Optional. Project ID or project name
baseVersionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitBranchStats>
getBranches()
Retrieve statistics about all branches within a repository.
Syntax
Parameters
repositoryId : string. Friendly name or guid of repository
project : string. Optional. Project ID or project name
baseVersionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitBranchStats[]>
getChanges()
Retrieve changes for a particular commit.
Syntax
Parameters
commitId : string. The ID of the commit.
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
top : number. Optional. The maximum number of changes to return.
skip : number. Optional. The number of changes to skip.
Returns
IPromise<Contracts.GitCommitChanges>
getCommit()
Retrieve a particular commit.
Syntax
Parameters
commitId : string. The ID of the commit.
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
changeCount : number. Optional. The number of changes to include in the result.
Returns
IPromise<Contracts.GitCommit>
getCommits()
Retrieve git commits for a project
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
searchCriteria : Contracts.GitQueryCommitsCriteria.
project : string. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getCommitsBatch()
Retrieve git commits for a project
Syntax
Parameters
searchCriteria : Contracts.GitQueryCommitsCriteria. Search options
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getItem()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitItem>
getItemContent()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getItems()
Get Item Metadata and/or Content for a collection of items. The download parameter is to indicate whether the
content should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content
which is always returned as a download.
Syntax
Parameters
repositoryId : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
includeLinks : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<Contracts.GitItem[]>
getItemsBatch()
Post for retrieving a creating a batch out of a set of items in a repo / project given a list of paths or a long path
Syntax
Parameters
requestData : Contracts.GitItemRequestData.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitItem[][]>
getItemText()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
IPromise<string> getItemText(repositoryId, path, project, scopePath, recursionLevel,
includeContentMetadata, latestProcessedChange, download, versionDescriptor)
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<string>
getItemZip()
Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content
should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is
always returned as a download.
Syntax
Parameters
repositoryId : string.
path : string.
project : string. Optional.
scopePath : string. Optional.
recursionLevel : Contracts.VersionControlRecursionType. Optional.
includeContentMetadata : boolean. Optional.
latestProcessedChange : boolean. Optional.
download : boolean. Optional.
versionDescriptor : Contracts.GitVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getPullRequest()
Retrieve a pull request
Syntax
IPromise<Contracts.GitPullRequest> getPullRequest(repositoryId, pullRequestId, project,
maxCommentLength, skip, top, includeCommits, includeWorkItemRefs)
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
maxCommentLength : number. Optional.
skip : number. Optional.
top : number. Optional.
includeCommits : boolean. Optional.
includeWorkItemRefs : boolean. Optional.
Returns
IPromise<Contracts.GitPullRequest>
getPullRequestCommits()
Retrieve pull request's commits
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getPullRequestReviewer()
Retrieve a reviewer from a pull request
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
reviewerId : string.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote>
getPullRequestReviewers()
Retrieve a pull request reviewers
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.IdentityRefWithVote[]>
getPullRequests()
Query for pull requests
Syntax
Parameters
repositoryId : string.
searchCriteria : Contracts.GitPullRequestSearchCriteria.
project : string. Optional.
maxCommentLength : number. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<Contracts.GitPullRequest[]>
getPullRequestsByProject()
Query pull requests by project
Syntax
Returns
IPromise<Contracts.GitPullRequest[]>
getPullRequestWorkItems()
Retrieve a pull request work items
Syntax
Parameters
repositoryId : string.
pullRequestId : number.
project : string. Optional.
commitsTop : number. Optional.
commitsSkip : number. Optional.
Returns
IPromise<Contracts.AssociatedWorkItem[]>
getPush()
Retrieve a particular push.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
pushId : number. The ID of the push.
project : string. Optional. Project ID or project name
includeCommits : number. Optional. The number of commits to include in the result.
includeRefUpdates : boolean. Optional.
Returns
IPromise<Contracts.GitPush>
getPushCommits()
Retrieve a list of commits associated with a particular push.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
pushId : number. The ID of the push.
project : string. Optional. Project ID or project name
top : number. Optional. The maximum number of commits to return ("get the top x commits").
skip : number. Optional. The number of commits to skip.
includeLinks : boolean. Optional.
Returns
IPromise<Contracts.GitCommitRef[]>
getPushes()
Retrieves pushes associated with the specified repository.
Syntax
Parameters
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
skip : number. Optional.
top : number. Optional.
searchCriteria : Contracts.GitPushSearchCriteria. Optional.
Returns
IPromise<Contracts.GitPush[]>
getRefs()
Queries the provided repository for its refs and returns them.
Syntax
getRepositories()
Retrieve git repositories.
Syntax
Parameters
project : string. Optional. Project ID or project name
includeLinks : boolean. Optional.
Returns
IPromise<Contracts.GitRepository[]>
getRepository()
Syntax
Parameters
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitRepository>
getStatuses()
Syntax
Returns
IPromise<Contracts.GitStatus[]>
getSuggestions()
Retrieve a set of suggestions (including a pull request suggestion).
Syntax
Parameters
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitSuggestion[]>
getTree()
Syntax
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
projectId : string. Optional.
recursive : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<Contracts.GitTreeRef>
getTreeZip()
Syntax
IPromise<ArrayBuffer> getTreeZip(repositoryId, sha1, project, projectId, recursive, fileName)
Parameters
repositoryId : string.
sha1 : string.
project : string. Optional.
projectId : string. Optional.
recursive : boolean. Optional.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
updatePullRequest()
Updates a pull request
Syntax
Parameters
gitPullRequestToUpdate : Contracts.GitPullRequest.
repositoryId : string.
pullRequestId : number.
project : string. Optional.
Returns
IPromise<Contracts.GitPullRequest>
updateRefs()
Creates or updates refs with the given information
Syntax
Parameters
refUpdates : Contracts.GitRefUpdate[]. List of ref updates to attempt to perform
repositoryId : string. The ID or friendly name of the repository. To use the friendly name, projectId must also be
specified.
project : string. Optional. Project ID or project name
projectId : string. Optional. The ID of the project.
Returns
IPromise<Contracts.GitRefUpdateResult[]>
updateRepository()
Updates the Git repository with the single populated change in the specified repository information.
Syntax
Parameters
newRepositoryInfo : Contracts.GitRepository.
repositoryId : string.
project : string. Optional.
Returns
IPromise<Contracts.GitRepository>
5/3/2018 • 5 minutes to read • Edit Online
TfvcHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/VersionControl/TfvcRestClient
Initialization sample
Methods
createChangeset()
getBatchedChangesets()
getBranch()
getBranches()
getBranchRefs()
getChangeset()
getChangesetChanges()
getChangesets()
getChangesetWorkItems()
getItem()
getItemContent()
getItems()
getItemsBatch()
getItemsBatchZip()
getItemText()
getItemZip()
getLabel()
getLabelItems()
getLabels()
getProjectInfo()
getProjectInfos()
getShelveset()
getShelvesetChanges()
getShelvesets()
getShelvesetWorkItems()
createChangeset()
Syntax
Parameters
changeset : TFS_VersionControl_Contracts.TfvcChangeset.
project : string. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef>
getBatchedChangesets()
Syntax
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef[]>
getBatchedChangesets(changesetsRequestData)
Parameters
changesetsRequestData : TFS_VersionControl_Contracts.TfvcChangesetsRequestData.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef[]>
getBranch()
Get a single branch hierarchy at the given path with parents or children (if specified)
Syntax
Parameters
path : string.
project : string. Optional.
includeParent : boolean. Optional.
includeChildren : boolean. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcBranch>
getBranches()
Get a collection of branch roots -- first-level children, branches with no parents
Syntax
Parameters
project : string. Optional. Project ID or project name
includeParent : boolean. Optional.
includeChildren : boolean. Optional.
includeDeleted : boolean. Optional.
includeLinks : boolean. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcBranch[]>
getBranchRefs()
Get branch hierarchies below the specified scopePath
Syntax
Parameters
scopePath : string.
project : string. Optional.
includeDeleted : boolean. Optional.
includeLinks : boolean. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcBranchRef[]>
getChangeset()
Retrieve a Tfvc Changeset
Syntax
Parameters
id : number.
project : string. Optional.
maxChangeCount : number. Optional.
includeDetails : boolean. Optional.
includeWorkItems : boolean. Optional.
maxCommentLength : number. Optional.
includeSourceRename : boolean. Optional.
skip : number. Optional.
top : number. Optional.
orderby : string. Optional.
searchCriteria : TFS_VersionControl_Contracts.TfvcChangesetSearchCriteria. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangeset>
getChangesetChanges()
Retrieve Tfvc changes for a given changeset
Syntax
Parameters
id : number. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChange[]>
getChangesets()
Retrieve Tfvc changesets
Syntax
Parameters
project : string. Optional. Project ID or project name
maxChangeCount : number. Optional.
includeDetails : boolean. Optional.
includeWorkItems : boolean. Optional.
maxCommentLength : number. Optional.
includeSourceRename : boolean. Optional.
skip : number. Optional.
top : number. Optional.
orderby : string. Optional.
searchCriteria : TFS_VersionControl_Contracts.TfvcChangesetSearchCriteria. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef[]>
getChangesetWorkItems()
Syntax
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]> getChangesetWorkItems(id)
Parameters
id : number. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]>
getItem()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem>
getItemContent()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
IPromise<ArrayBuffer> getItemContent(path, project, fileName, download, scopePath,
recursionLevel, versionDescriptor)
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getItems()
Get a list of Tfvc items
Syntax
Parameters
project : string. Optional. Project ID or project name
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
includeLinks : boolean. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem[]>
getItemsBatch()
Post for retrieving a set of items given a list of paths or a long path. Allows for specifying the recursionLevel and
version descriptors for each path.
Syntax
Parameters
itemRequestData : TFS_VersionControl_Contracts.TfvcItemRequestData.
project : string. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem[][]>
getItemsBatchZip()
Post for retrieving a set of items given a list of paths or a long path. Allows for specifying the recursionLevel and
version descriptors for each path.
Syntax
Parameters
itemRequestData : TFS_VersionControl_Contracts.TfvcItemRequestData.
project : string. Optional.
Returns
IPromise<ArrayBuffer>
getItemText()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<string>
getItemZip()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getLabel()
Get a single deep label.
Syntax
Parameters
labelId : string. Unique identifier of label
requestData : TFS_VersionControl_Contracts.TfvcLabelRequestData. maxItemCount
project : string. Optional. Project ID or project name
Returns
IPromise<TFS_VersionControl_Contracts.TfvcLabel>
getLabelItems()
Get items under a label.
Syntax
Parameters
labelId : string. Unique identifier of label
top : number. Optional. Max number of items to return
skip : number. Optional. Number of items to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem[]>
getLabels()
Get a collection of shallow label references.
Syntax
Parameters
requestData : TFS_VersionControl_Contracts.TfvcLabelRequestData. labelScope, name, owner, and
itemLabelFilter
project : string. Optional. Project ID or project name
top : number. Optional. Max number of labels to return
skip : number. Optional. Number of labels to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcLabelRef[]>
getProjectInfo()
[Obsolete - Use the Projects API instead] Retrieve the version control information for a given Team Project
Syntax
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo> getProjectInfo(projectId,
project)
Parameters
projectId : string. The ID (or name) of the team project
project : string. Optional. Project ID or project name
Returns
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo>
getProjectInfos()
[Obsolete - Use the Projects API instead]
Syntax
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo[]> getProjectInfos(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo[]>
getShelveset()
Get a single deep shelveset.
Syntax
Parameters
shelvesetId: string. Shelveset's unique ID
requestData : TFS_VersionControl_Contracts.TfvcShelvesetRequestData. includeDetails, includeWorkItems,
maxChangeCount, and maxCommentLength
Returns
IPromise<TFS_VersionControl_Contracts.TfvcShelveset>
getShelvesetChanges()
Get changes included in a shelveset.
Syntax
Parameters
shelvesetId: string. Shelveset's unique ID
top : number. Optional. Max number of changes to return
skip : number. Optional. Number of changes to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChange[]>
getShelvesets()
Return a collection of shallow shelveset references.
Syntax
Parameters
: TFS_VersionControl_Contracts.TfvcShelvesetRequestData. name, owner, and
requestData
maxCommentLength
top : number. Optional. Max number of shelvesets to return
skip : number. Optional. Number of shelvesets to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcShelvesetRef[]>
getShelvesetWorkItems()
Get work items associated with a shelveset.
Syntax
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]> getShelvesetWorkItems(shelvesetId)
Parameters
shelvesetId : string. Shelveset's unique ID
Returns
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]>
5/3/2018 • 5 minutes to read • Edit Online
TfvcHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/VersionControl/TfvcRestClient
Initialization sample
Methods
createChangeset()
getBatchedChangesets()
getBranch()
getBranches()
getBranchRefs()
getChangeset()
getChangesetChanges()
getChangesets()
getChangesetWorkItems()
getItem()
getItemContent()
getItems()
getItemsBatch()
getItemsBatchZip()
getItemText()
getItemZip()
getLabel()
getLabelItems()
getLabels()
getProjectInfo()
getProjectInfos()
getShelveset()
getShelvesetChanges()
getShelvesets()
getShelvesetWorkItems()
createChangeset()
Syntax
Parameters
changeset : TFS_VersionControl_Contracts.TfvcChangeset.
project : string. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef>
getBatchedChangesets()
Syntax
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef[]>
getBatchedChangesets(changesetsRequestData)
Parameters
changesetsRequestData : TFS_VersionControl_Contracts.TfvcChangesetsRequestData.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef[]>
getBranch()
Get a single branch hierarchy at the given path with parents or children (if specified)
Syntax
Parameters
path : string.
project : string. Optional.
includeParent : boolean. Optional.
includeChildren : boolean. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcBranch>
getBranches()
Get a collection of branch roots -- first-level children, branches with no parents
Syntax
Parameters
project : string. Optional. Project ID or project name
includeParent : boolean. Optional.
includeChildren : boolean. Optional.
includeDeleted : boolean. Optional.
includeLinks : boolean. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcBranch[]>
getBranchRefs()
Get branch hierarchies below the specified scopePath
Syntax
Parameters
scopePath : string.
project : string. Optional.
includeDeleted : boolean. Optional.
includeLinks : boolean. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcBranchRef[]>
getChangeset()
Retrieve a Tfvc Changeset
Syntax
Parameters
id : number.
project : string. Optional.
maxChangeCount : number. Optional.
includeDetails : boolean. Optional.
includeWorkItems : boolean. Optional.
maxCommentLength : number. Optional.
includeSourceRename : boolean. Optional.
skip : number. Optional.
top : number. Optional.
orderby : string. Optional.
searchCriteria : TFS_VersionControl_Contracts.TfvcChangesetSearchCriteria. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangeset>
getChangesetChanges()
Retrieve Tfvc changes for a given changeset
Syntax
Parameters
id : number. Optional.
skip : number. Optional.
top : number. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChange[]>
getChangesets()
Retrieve Tfvc changesets
Syntax
Parameters
project : string. Optional. Project ID or project name
maxChangeCount : number. Optional.
includeDetails : boolean. Optional.
includeWorkItems : boolean. Optional.
maxCommentLength : number. Optional.
includeSourceRename : boolean. Optional.
skip : number. Optional.
top : number. Optional.
orderby : string. Optional.
searchCriteria : TFS_VersionControl_Contracts.TfvcChangesetSearchCriteria. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChangesetRef[]>
getChangesetWorkItems()
Syntax
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]> getChangesetWorkItems(id)
Parameters
id : number. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]>
getItem()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem>
getItemContent()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
IPromise<ArrayBuffer> getItemContent(path, project, fileName, download, scopePath,
recursionLevel, versionDescriptor)
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getItems()
Get a list of Tfvc items
Syntax
Parameters
project : string. Optional. Project ID or project name
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
includeLinks : boolean. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem[]>
getItemsBatch()
Post for retrieving a set of items given a list of paths or a long path. Allows for specifying the recursionLevel and
version descriptors for each path.
Syntax
Parameters
itemRequestData : TFS_VersionControl_Contracts.TfvcItemRequestData.
project : string. Optional.
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem[][]>
getItemsBatchZip()
Post for retrieving a set of items given a list of paths or a long path. Allows for specifying the recursionLevel and
version descriptors for each path.
Syntax
Parameters
itemRequestData : TFS_VersionControl_Contracts.TfvcItemRequestData.
project : string. Optional.
Returns
IPromise<ArrayBuffer>
getItemText()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<string>
getItemZip()
Get Item Metadata and/or Content. The download parameter is to indicate whether the content should be available
as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as
a download.
Syntax
Parameters
path : string.
project : string. Optional.
fileName : string. Optional.
download : boolean. Optional.
scopePath : string. Optional.
recursionLevel : TFS_VersionControl_Contracts.VersionControlRecursionType. Optional.
versionDescriptor : TFS_VersionControl_Contracts.TfvcVersionDescriptor. Optional.
Returns
IPromise<ArrayBuffer>
getLabel()
Get a single deep label.
Syntax
Parameters
labelId : string. Unique identifier of label
requestData : TFS_VersionControl_Contracts.TfvcLabelRequestData. maxItemCount
project : string. Optional. Project ID or project name
Returns
IPromise<TFS_VersionControl_Contracts.TfvcLabel>
getLabelItems()
Get items under a label.
Syntax
Parameters
labelId : string. Unique identifier of label
top : number. Optional. Max number of items to return
skip : number. Optional. Number of items to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcItem[]>
getLabels()
Get a collection of shallow label references.
Syntax
Parameters
requestData : TFS_VersionControl_Contracts.TfvcLabelRequestData. labelScope, name, owner, and
itemLabelFilter
project : string. Optional. Project ID or project name
top : number. Optional. Max number of labels to return
skip : number. Optional. Number of labels to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcLabelRef[]>
getProjectInfo()
[Obsolete - Use the Projects API instead] Retrieve the version control information for a given Team Project
Syntax
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo> getProjectInfo(projectId,
project)
Parameters
projectId : string. The ID (or name) of the team project
project : string. Optional. Project ID or project name
Returns
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo>
getProjectInfos()
[Obsolete - Use the Projects API instead]
Syntax
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo[]> getProjectInfos(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<TFS_VersionControl_Contracts.VersionControlProjectInfo[]>
getShelveset()
Get a single deep shelveset.
Syntax
Parameters
shelvesetId: string. Shelveset's unique ID
requestData : TFS_VersionControl_Contracts.TfvcShelvesetRequestData. includeDetails, includeWorkItems,
maxChangeCount, and maxCommentLength
Returns
IPromise<TFS_VersionControl_Contracts.TfvcShelveset>
getShelvesetChanges()
Get changes included in a shelveset.
Syntax
Parameters
shelvesetId: string. Shelveset's unique ID
top : number. Optional. Max number of changes to return
skip : number. Optional. Number of changes to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcChange[]>
getShelvesets()
Return a collection of shallow shelveset references.
Syntax
Parameters
: TFS_VersionControl_Contracts.TfvcShelvesetRequestData. name, owner, and
requestData
maxCommentLength
top : number. Optional. Max number of shelvesets to return
skip : number. Optional. Number of shelvesets to skip
Returns
IPromise<TFS_VersionControl_Contracts.TfvcShelvesetRef[]>
getShelvesetWorkItems()
Get work items associated with a shelveset.
Syntax
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]> getShelvesetWorkItems(shelvesetId)
Parameters
shelvesetId : string. Shelveset's unique ID
Returns
IPromise<TFS_VersionControl_Contracts.AssociatedWorkItem[]>
5/3/2018 • 3 minutes to read • Edit Online
WorkHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/Work/RestClient
Initialization sample
Methods
deleteTeamIteration()
getBoard()
getBoardCardRuleSettings()
getBoardCardSettings()
getBoardChart()
getBoardCharts()
getBoardColumns()
getBoardRows()
getBoards()
getCapacities()
getCapacity()
getColumnSuggestedValues()
getRowSuggestedValues()
getTeamDaysOff()
getTeamFieldValues()
getTeamIteration()
getTeamIterations()
getTeamSettings()
postTeamIteration()
replaceCapacities()
setBoardOptions()
updateBoardCardRuleSettings()
updateBoardCardSettings()
updateBoardChart()
updateBoardColumns()
updateBoardRows()
updateCapacity()
updateTeamDaysOff()
updateTeamFieldValues()
updateTeamSettings()
deleteTeamIteration()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
id : string.
Returns
IPromise<void>
getBoard()
Get board
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
id : string. identifier for board, either category plural name ( Eg:"Stories") or guid
Returns
IPromise<Contracts.Board>
getBoardCardRuleSettings()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardCardRuleSettings>
getBoardCardSettings()
Get board card settings for the board ID or board by name
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardCardSettings>
getBoardChart()
Get a board chart
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string. Identifier for board, either category plural name ( Eg:"Stories") or Guid
name : string. The chart name
Returns
IPromise<Contracts.BoardChart>
getBoardCharts()
Get board charts
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string. Identifier for board, either category plural name ( Eg:"Stories") or Guid
Returns
IPromise<Contracts.BoardChartReference[]>
getBoardColumns()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardColumn[]>
getBoardRows()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardRow []>
getBoards()
Syntax
IPromise<Contracts.BoardReference[]> getBoards(teamContext)
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
Returns
IPromise<Contracts.BoardReference[]>
getCapacities()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
iterationId : string.
Returns
IPromise<Contracts.TeamMemberCapacity[]>
getCapacity()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
iterationId : string.
teamMemberId : string.
Returns
IPromise<Contracts.TeamMemberCapacity>
getColumnSuggestedValues()
Syntax
IPromise<Contracts.BoardSuggestedValue[]> getColumnSuggestedValues(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<Contracts.BoardSuggestedValue[]>
getRowSuggestedValues()
Syntax
IPromise<Contracts.BoardSuggestedValue[]> getRowSuggestedValues(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<Contracts.BoardSuggestedValue[]>
getTeamDaysOff()
Syntax
Returns
IPromise<Contracts.TeamSettingsDaysOff>
getTeamFieldValues()
Syntax
IPromise<Contracts.TeamFieldValues> getTeamFieldValues(teamContext)
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
Returns
IPromise<Contracts.TeamFieldValues>
getTeamIteration()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
id : string.
Returns
IPromise<Contracts.TeamSettingsIteration>
getTeamIterations()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
timeframe : string. Optional.
Returns
IPromise<Contracts.TeamSettingsIteration[]>
getTeamSettings()
Syntax
IPromise<Contracts.TeamSetting> getTeamSettings(teamContext)
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
Returns
IPromise<Contracts.TeamSetting>
postTeamIteration()
Syntax
Parameters
iteration : Contracts.TeamSettingsIteration.
teamContext : TFS_Core_Contracts.TeamContext.
Returns
IPromise<Contracts.TeamSettingsIteration>
replaceCapacities()
Syntax
Parameters
capacities : Contracts.TeamMemberCapacity[].
teamContext : TFS_Core_Contracts.TeamContext.
iterationId : string.
Returns
IPromise<Contracts.TeamMemberCapacity[]>
setBoardOptions()
Update board options
Syntax
Returns
IPromise<{[key: string]: string}>
updateBoardCardRuleSettings()
Syntax
IPromise<Contracts.BoardCardRuleSettings> updateBoardCardRuleSettings(boardCardRuleSettings,
teamContext, board)
Parameters
boardCardRuleSettings: Contracts.BoardCardRuleSettings.
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardCardRuleSettings>
updateBoardCardSettings()
Update board card settings for the board ID or board by name
Syntax
IPromise<Contracts.BoardCardSettings> updateBoardCardSettings(boardCardSettingsToSave,
teamContext, board)
Parameters
boardCardSettingsToSave: Contracts.BoardCardSettings.
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardCardSettings>
updateBoardChart()
Update a board chart
Syntax
Returns
IPromise<Contracts.BoardChart>
updateBoardColumns()
Syntax
Parameters
boardColumns : Contracts.BoardColumn[].
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardColumn[]>
updateBoardRows()
Syntax
Parameters
boardRows : Contracts.BoardRow [].
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardRow []>
updateCapacity()
Syntax
Parameters
patch : Contracts.CapacityPatch.
teamContext : TFS_Core_Contracts.TeamContext.
iterationId : string.
teamMemberId : string.
Returns
IPromise<Contracts.TeamMemberCapacity>
updateTeamDaysOff()
Syntax
Parameters
daysOffPatch : Contracts.TeamSettingsDaysOffPatch.
teamContext : TFS_Core_Contracts.TeamContext.
iterationId : string.
Returns
IPromise<Contracts.TeamSettingsDaysOff>
updateTeamFieldValues()
Syntax
Parameters
patch : Contracts.TeamFieldValuesPatch.
teamContext : TFS_Core_Contracts.TeamContext.
Returns
IPromise<Contracts.TeamFieldValues>
updateTeamSettings()
Syntax
Parameters
teamSettingsPatch : Contracts.TeamSettingsPatch.
teamContext : TFS_Core_Contracts.TeamContext.
Returns
IPromise<Contracts.TeamSetting>
5/3/2018 • 3 minutes to read • Edit Online
WorkHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/Work/RestClient
Initialization sample
Methods
deleteTeamIteration()
getBoard()
getBoardCardRuleSettings()
getBoardCardSettings()
getBoardChart()
getBoardCharts()
getBoardColumns()
getBoardRows()
getBoards()
getCapacities()
getCapacity()
getColumnSuggestedValues()
getRowSuggestedValues()
getTeamDaysOff()
getTeamFieldValues()
getTeamIteration()
getTeamIterations()
getTeamSettings()
postTeamIteration()
replaceCapacities()
setBoardOptions()
updateBoardCardRuleSettings()
updateBoardCardSettings()
updateBoardChart()
updateBoardColumns()
updateBoardRows()
updateCapacity()
updateTeamDaysOff()
updateTeamFieldValues()
updateTeamSettings()
deleteTeamIteration()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
id : string.
Returns
IPromise<void>
getBoard()
Get board
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
id : string. identifier for board, either category plural name ( Eg:"Stories") or guid
Returns
IPromise<Contracts.Board>
getBoardCardRuleSettings()
Get board card Rule settings for the board ID or board by name
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardCardRuleSettings>
getBoardCardSettings()
Get board card settings for the board ID or board by name
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardCardSettings>
getBoardChart()
Get a board chart
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string. Identifier for board, either category plural name ( Eg:"Stories") or Guid
name : string. The chart name
Returns
IPromise<Contracts.BoardChart>
getBoardCharts()
Get board charts
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string. Identifier for board, either category plural name ( Eg:"Stories") or Guid
Returns
IPromise<Contracts.BoardChartReference[]>
getBoardColumns()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardColumn[]>
getBoardRows()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
board : string.
Returns
IPromise<Contracts.BoardRow []>
getBoards()
Syntax
IPromise<Contracts.BoardReference[]> getBoards(teamContext)
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
Returns
IPromise<Contracts.BoardReference[]>
getCapacities()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
iterationId : string.
Returns
IPromise<Contracts.TeamMemberCapacity[]>
getCapacity()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
iterationId : string.
teamMemberId : string.
Returns
IPromise<Contracts.TeamMemberCapacity>
getColumnSuggestedValues()
Syntax
IPromise<Contracts.BoardSuggestedValue[]> getColumnSuggestedValues(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<Contracts.BoardSuggestedValue[]>
getRowSuggestedValues()
Syntax
IPromise<Contracts.BoardSuggestedValue[]> getRowSuggestedValues(project)
Parameters
project : string. Optional. Project ID or project name
Returns
IPromise<Contracts.BoardSuggestedValue[]>
getTeamDaysOff()
Syntax
Returns
IPromise<Contracts.TeamSettingsDaysOff>
getTeamFieldValues()
Syntax
IPromise<Contracts.TeamFieldValues> getTeamFieldValues(teamContext)
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
Returns
IPromise<Contracts.TeamFieldValues>
getTeamIteration()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
id : string.
Returns
IPromise<Contracts.TeamSettingsIteration>
getTeamIterations()
Syntax
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
timeframe : string. Optional.
Returns
IPromise<Contracts.TeamSettingsIteration[]>
getTeamSettings()
Syntax
IPromise<Contracts.TeamSetting> getTeamSettings(teamContext)
Parameters
teamContext : TFS_Core_Contracts.TeamContext. The team context for the operation
Returns
IPromise<Contracts.TeamSetting>
postTeamIteration()
Syntax
Parameters
iteration : Contracts.TeamSettingsIteration.
teamContext : TFS_Core_Contracts.TeamContext.
Returns
IPromise<Contracts.TeamSettingsIteration>
replaceCapacities()
Syntax
Parameters
capacities : Contracts.TeamMemberCapacity[].
teamContext : TFS_Core_Contracts.TeamContext.
iterationId : string.
Returns
IPromise<Contracts.TeamMemberCapacity[]>
setBoardOptions()
Update board options
Syntax
Returns
IPromise<{[key: string]: string}>
updateBoardCardRuleSettings()
Update board card Rule settings for the board ID or board by name
Syntax
IPromise<Contracts.BoardCardRuleSettings> updateBoardCardRuleSettings(boardCardRuleSettings,
teamContext, board)
Parameters
boardCardRuleSettings: Contracts.BoardCardRuleSettings.
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardCardRuleSettings>
updateBoardCardSettings()
Update board card settings for the board ID or board by name
Syntax
IPromise<Contracts.BoardCardSettings> updateBoardCardSettings(boardCardSettingsToSave,
teamContext, board)
Parameters
boardCardSettingsToSave: Contracts.BoardCardSettings.
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardCardSettings>
updateBoardChart()
Update a board chart
Syntax
IPromise<Contracts.BoardChart> updateBoardChart(chart, teamContext, board, name)
Parameters
chart : Contracts.BoardChart.
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
name : string.
Returns
IPromise<Contracts.BoardChart>
updateBoardColumns()
Syntax
Parameters
boardColumns : Contracts.BoardColumn[].
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardColumn[]>
updateBoardRows()
Syntax
Parameters
boardRows : Contracts.BoardRow [].
teamContext : TFS_Core_Contracts.TeamContext.
board : string.
Returns
IPromise<Contracts.BoardRow []>
updateCapacity()
Syntax
Returns
IPromise<Contracts.TeamMemberCapacity>
updateTeamDaysOff()
Syntax
Parameters
daysOffPatch : Contracts.TeamSettingsDaysOffPatch.
teamContext : TFS_Core_Contracts.TeamContext.
iterationId : string.
Returns
IPromise<Contracts.TeamSettingsDaysOff>
updateTeamFieldValues()
Syntax
Parameters
patch : Contracts.TeamFieldValuesPatch.
teamContext : TFS_Core_Contracts.TeamContext.
Returns
IPromise<Contracts.TeamFieldValues>
updateTeamSettings()
Syntax
Parameters
teamSettingsPatch : Contracts.TeamSettingsPatch.
teamContext : TFS_Core_Contracts.TeamContext.
Returns
IPromise<Contracts.TeamSetting>
5/3/2018 • 7 minutes to read • Edit Online
WorkItemTrackingHttpClient2_1
This API is in private preview and subject to change.
Module path: TFS/WorkItemTracking/RestClient
Initialization sample
Methods
createAttachment()
createOrUpdateClassificationNode()
createQuery()
createWorkItem()
deleteClassificationNode()
deleteQuery()
deleteWorkItem()
destroyWorkItem()
evaluateRulesOnField()
exportWorkItemTypeDefinition()
getAttachmentContent()
getAttachmentZip()
getClassificationNode()
getDeletedWorkItem()
getDeletedWorkItems()
getDependentFields()
getField()
getFields()
getHistory()
getHistoryById()
getQueries()
getQuery()
getRelationType()
getRelationTypes()
getReportingLinks()
getRevision()
getRevisions()
getRootNodes()
getUpdate()
getUpdates()
getWorkItem()
getWorkItems()
getWorkItemTemplate()
getWorkItemType()
getWorkItemTypeCategories()
getWorkItemTypeCategory()
getWorkItemTypes()
queryById()
queryByWiql()
readReportingRevisionsGet()
readReportingRevisionsPost()
restoreWorkItem()
updateClassificationNode()
updateQuery()
updateWorkItem()
updateWorkItemTemplate()
updateWorkItemTypeDefinition()
createAttachment()
Creates an attachment.
Syntax
Parameters
content : string. Content to upload
fileName : string. Optional.
uploadType : string. Optional.
Returns
IPromise<Contracts.AttachmentReference>
createOrUpdateClassificationNode()
Syntax
IPromise<Contracts.WorkItemClassificationNode> createOrUpdateClassificationNode(postedNode,
project, structureGroup, path)
Parameters
postedNode : Contracts.WorkItemClassificationNode.
project : string.
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode>
createQuery()
Creates a query, or moves a query.
Syntax
Parameters
postedQuery : Contracts.QueryHierarchyItem. The query to create.
project : string. Project ID or project name
query : string. The parent path for the query to create.
Returns
IPromise<Contracts.QueryHierarchyItem>
createWorkItem()
Syntax
Parameters
document : VSS_Common_Contracts.JsonPatchDocument.
project : string.
type : string.
validateOnly : boolean. Optional.
bypassRules : boolean. Optional.
Returns
IPromise<Contracts.WorkItem>
deleteClassificationNode()
Syntax
Parameters
project : string. Project ID or project name
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
reclassifyId : number. Optional.
Returns
IPromise<void>
deleteQuery()
Syntax
Parameters
project : string. Project ID or project name
query : string.
Returns
IPromise<void>
deleteWorkItem()
Syntax
Parameters
id : number.
destroy : boolean. Optional.
Returns
IPromise<Contracts.WorkItemDelete>
destroyWorkItem()
Syntax
Parameters
id : number.
project : string. Optional.
Returns
IPromise<void>
evaluateRulesOnField()
Validates the fields values.
Syntax
IPromise<void> evaluateRulesOnField(ruleEngineInput)
Parameters
ruleEngineInput : Contracts.FieldsToEvaluate.
Returns
IPromise<void>
exportWorkItemTypeDefinition()
Export work item type
Syntax
Parameters
project : string. Optional. Project ID or project name
type : string. Optional.
exportGlobalLists : boolean. Optional.
Returns
IPromise<Contracts.WorkItemTypeTemplate>
getAttachmentContent()
Returns an attachment
Syntax
Parameters
id : string.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getAttachmentZip()
Returns an attachment
Syntax
Parameters
id : string.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getClassificationNode()
Syntax
Parameters
project : string. Project ID or project name
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
depth : number. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode>
getDeletedWorkItem()
Syntax
Parameters
id : number.
project : string. Optional.
Returns
IPromise<Contracts.WorkItemDelete>
getDeletedWorkItems()
Syntax
IPromise<Contracts.WorkItemDeleteReference[]> getDeletedWorkItems(project, ids)
Parameters
project : string. Optional. Project ID or project name
ids : number []. Optional.
Returns
IPromise<Contracts.WorkItemDeleteReference[]>
getDependentFields()
Returns the dependent fields for the corresponding workitem type and fieldname
Syntax
Parameters
project : string. Project ID or project name
type : string.
field : string.
Returns
IPromise<Contracts.FieldDependentRule>
getField()
Syntax
IPromise<Contracts.WorkItemField> getField(field)
Parameters
field : string.
Returns
IPromise<Contracts.WorkItemField>
getFields()
Syntax
IPromise<Contracts.WorkItemField[]> getFields()
Parameters
Returns
IPromise<Contracts.WorkItemField[]>
getHistory()
Returns history of all revision for a given work item ID
Syntax
Parameters
id : number.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.WorkItemHistory[]>
getHistoryById()
Returns the history value of particular revision
Syntax
Parameters
id : number.
revisionNumber : number.
Returns
IPromise<Contracts.WorkItemHistory>
getQueries()
Retrieves all queries the user has access to in the current project
Syntax
Parameters
project : string. Project ID or project name
expand : Contracts.QueryExpand. Optional.
depth : number. Optional.
includeDeleted : boolean. Optional.
Returns
IPromise<Contracts.QueryHierarchyItem[]>
getQuery()
Retrieves a single query by project and either ID or path
Syntax
Parameters
project : string. Project ID or project name
query : string.
expand : Contracts.QueryExpand. Optional.
depth : number. Optional.
includeDeleted : boolean. Optional.
Returns
IPromise<Contracts.QueryHierarchyItem>
getRelationType()
Gets the work item relation types.
Syntax
IPromise<Contracts.WorkItemRelationType> getRelationType(relation)
Parameters
relation : string.
Returns
IPromise<Contracts.WorkItemRelationType>
getRelationTypes()
Syntax
IPromise<Contracts.WorkItemRelationType[]> getRelationTypes()
Parameters
Returns
IPromise<Contracts.WorkItemRelationType[]>
getReportingLinks()
Get a batch of work item links
Syntax
IPromise<Contracts.ReportingWorkItemLinksBatch> getReportingLinks(project, types, watermark,
startDateTime)
Parameters
project : string. Optional. Project ID or project name
types : string[]. Optional. A list of types to filter the results to specific work item types. Omit this parameter to
get work item links of all work item types.
watermark : number. Optional. Specifies the watermark to start the batch from. Omit this parameter to get the
first batch of links.
startDateTime : Date. Optional. Date/time to use as a starting point for link changes. Only link changes that
occurred after that date/time will be returned. Cannot be used in conjunction with 'watermark' parameter.
Returns
IPromise<Contracts.ReportingWorkItemLinksBatch>
getRevision()
Returns a fully hydrated work item for the requested revision
Syntax
Parameters
id : number.
revisionNumber : number.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem>
getRevisions()
Returns the list of fully hydrated work item revisions, paged.
Syntax
Parameters
id : number.
top : number. Optional.
skip : number. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem[]>
getRootNodes()
Syntax
Parameters
project : string. Project ID or project name
depth : number. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode[]>
getUpdate()
Returns a single update for a work item
Syntax
Parameters
id : number.
updateNumber : number.
Returns
IPromise<Contracts.WorkItemUpdate>
getUpdates()
Returns a the deltas between work item revisions
Syntax
Parameters
id : number.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.WorkItemUpdate[]>
getWorkItem()
Returns a single work item
Syntax
Parameters
id : number.
fields : string[]. Optional.
asOf : Date. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem>
getWorkItems()
Returns a list of work items
Syntax
Parameters
ids : number [].
fields : string[]. Optional.
asOf : Date. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem[]>
getWorkItemTemplate()
Returns a single work item from a template
Syntax
Parameters
project : string. Project ID or project name
type : string.
fields : string. Optional.
asOf : Date. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem>
getWorkItemType()
Returns a the deltas between work item revisions
Syntax
Parameters
project : string. Project ID or project name
type : string.
Returns
IPromise<Contracts.WorkItemType>
getWorkItemTypeCategories()
Syntax
IPromise<Contracts.WorkItemTypeCategory[]> getWorkItemTypeCategories(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.WorkItemTypeCategory[]>
getWorkItemTypeCategory()
Returns a the deltas between work item revisions
Syntax
Parameters
project : string. Project ID or project name
category : string.
Returns
IPromise<Contracts.WorkItemTypeCategory>
getWorkItemTypes()
Syntax
IPromise<Contracts.WorkItemType[]> getWorkItemTypes(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.WorkItemType[]>
queryById()
Gets the results of the query by id.
Syntax
Parameters
id : string. The query id.
project : string. Optional. Project ID or project name
team : string. Optional. Team ID or team name
Returns
IPromise<Contracts.WorkItemQueryResult>
queryByWiql()
Gets the results of the query.
Syntax
Parameters
wiql : Contracts.Wiql. The query containing the wiql.
project : string. Optional. Project ID or project name
team : string. Optional. Team ID or team name
Returns
IPromise<Contracts.WorkItemQueryResult>
readReportingRevisionsGet()
Get a batch of work item revisions
Syntax
Parameters
project : string. Optional. Project ID or project name
fields : string[]. Optional. A list of fields to return in work item revisions. Omit this parameter to get all
reportable fields.
types : string[]. Optional. A list of types to filter the results to specific work item types. Omit this parameter to
get work item revisions of all work item types.
watermark : number. Optional. Specifies the watermark to start the batch from. Omit this parameter to get the
first batch of revisions.
startDateTime : Date. Optional. Date/time to use as a starting point for revisions, all revisions will occur after this
date/time. Cannot be used in conjunction with 'watermark' parameter.
includeIdentityRef : boolean. Optional. Return an identity reference instead of a string value for identity fields.
includeDeleted : boolean. Optional. Specify if the deleted item should be returned.
Returns
IPromise<Contracts.ReportingWorkItemRevisionsBatch>
readReportingRevisionsPost()
Get a batch of work item revisions
Syntax
Parameters
filter : Contracts.ReportingWorkItemRevisionsFilter. An object that contains request settings: field filter, type
filter, identity format
project : string. Optional. Project ID or project name
watermark : number. Optional. Specifies the watermark to start the batch from. Omit this parameter to get the
first batch of revisions.
startDateTime : Date. Optional. Date/time to use as a starting point for revisions, all revisions will occur after this
date/time. Cannot be used in conjunction with 'watermark' parameter.
Returns
IPromise<Contracts.ReportingWorkItemRevisionsBatch>
restoreWorkItem()
Syntax
Parameters
payload : Contracts.WorkItemDeleteUpdate.
id : number.
project : string. Optional.
Returns
IPromise<Contracts.WorkItemDelete>
updateClassificationNode()
Syntax
Parameters
postedNode : Contracts.WorkItemClassificationNode.
project : string.
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode>
updateQuery()
Syntax
Parameters
queryUpdate : Contracts.QueryHierarchyItem.
project : string.
query : string.
undeleteDescendants : boolean. Optional.
Returns
IPromise<Contracts.QueryHierarchyItem>
updateWorkItem()
Syntax
Parameters
document : VSS_Common_Contracts.JsonPatchDocument.
id : number.
validateOnly : boolean. Optional.
bypassRules : boolean. Optional.
Returns
IPromise<Contracts.WorkItem>
updateWorkItemTemplate()
Syntax
Parameters
document : VSS_Common_Contracts.JsonPatchDocument.
project : string.
type : string.
validateOnly : boolean. Optional.
bypassRules : boolean. Optional.
Returns
IPromise<Contracts.WorkItem>
updateWorkItemTypeDefinition()
Add/updates a work item type
Syntax
Parameters
updateModel : Contracts.WorkItemTypeTemplateUpdateModel.
project : string. Optional.
Returns
IPromise<Contracts.ProvisioningResult>
5/3/2018 • 7 minutes to read • Edit Online
WorkItemTrackingHttpClient2_2
This API is in private preview and subject to change.
Module path: TFS/WorkItemTracking/RestClient
Initialization sample
Methods
createAttachment()
createOrUpdateClassificationNode()
createQuery()
createWorkItem()
deleteClassificationNode()
deleteQuery()
deleteWorkItem()
destroyWorkItem()
evaluateRulesOnField()
exportWorkItemTypeDefinition()
getAttachmentContent()
getAttachmentZip()
getClassificationNode()
getDeletedWorkItem()
getDeletedWorkItems()
getDependentFields()
getField()
getFields()
getHistory()
getHistoryById()
getQueries()
getQuery()
getRelationType()
getRelationTypes()
getReportingLinks()
getRevision()
getRevisions()
getRootNodes()
getUpdate()
getUpdates()
getWorkItem()
getWorkItems()
getWorkItemTemplate()
getWorkItemType()
getWorkItemTypeCategories()
getWorkItemTypeCategory()
getWorkItemTypes()
queryById()
queryByWiql()
readReportingRevisionsGet()
readReportingRevisionsPost()
restoreWorkItem()
updateClassificationNode()
updateQuery()
updateWorkItem()
updateWorkItemTemplate()
updateWorkItemTypeDefinition()
createAttachment()
Creates an attachment.
Syntax
Parameters
content : string. Content to upload
fileName : string. Optional.
uploadType : string. Optional.
Returns
IPromise<Contracts.AttachmentReference>
createOrUpdateClassificationNode()
Syntax
IPromise<Contracts.WorkItemClassificationNode> createOrUpdateClassificationNode(postedNode,
project, structureGroup, path)
Parameters
postedNode : Contracts.WorkItemClassificationNode.
project : string.
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode>
createQuery()
Creates a query, or moves a query.
Syntax
Parameters
postedQuery : Contracts.QueryHierarchyItem. The query to create.
project : string. Project ID or project name
query : string. The parent path for the query to create.
Returns
IPromise<Contracts.QueryHierarchyItem>
createWorkItem()
Syntax
Parameters
document : VSS_Common_Contracts.JsonPatchDocument.
project : string.
type : string.
validateOnly : boolean. Optional.
bypassRules : boolean. Optional.
Returns
IPromise<Contracts.WorkItem>
deleteClassificationNode()
Syntax
Parameters
project : string. Project ID or project name
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
reclassifyId : number. Optional.
Returns
IPromise<void>
deleteQuery()
Syntax
Parameters
project : string. Project ID or project name
query : string.
Returns
IPromise<void>
deleteWorkItem()
Syntax
Parameters
id : number.
destroy : boolean. Optional.
Returns
IPromise<Contracts.WorkItemDelete>
destroyWorkItem()
Syntax
Parameters
id : number.
project : string. Optional.
Returns
IPromise<void>
evaluateRulesOnField()
Validates the fields values.
Syntax
IPromise<void> evaluateRulesOnField(ruleEngineInput)
Parameters
ruleEngineInput : Contracts.FieldsToEvaluate.
Returns
IPromise<void>
exportWorkItemTypeDefinition()
Export work item type
Syntax
Parameters
project : string. Optional. Project ID or project name
type : string. Optional.
exportGlobalLists : boolean. Optional.
Returns
IPromise<Contracts.WorkItemTypeTemplate>
getAttachmentContent()
Returns an attachment
Syntax
Parameters
id : string.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getAttachmentZip()
Returns an attachment
Syntax
Parameters
id : string.
fileName : string. Optional.
Returns
IPromise<ArrayBuffer>
getClassificationNode()
Syntax
Parameters
project : string. Project ID or project name
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
depth : number. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode>
getDeletedWorkItem()
Syntax
Parameters
id : number.
project : string. Optional.
Returns
IPromise<Contracts.WorkItemDelete>
getDeletedWorkItems()
Syntax
IPromise<Contracts.WorkItemDeleteReference[]> getDeletedWorkItems(project, ids)
Parameters
project : string. Optional. Project ID or project name
ids : number []. Optional.
Returns
IPromise<Contracts.WorkItemDeleteReference[]>
getDependentFields()
Returns the dependent fields for the corresponding workitem type and fieldname
Syntax
Parameters
project : string. Project ID or project name
type : string.
field : string.
Returns
IPromise<Contracts.FieldDependentRule>
getField()
Syntax
IPromise<Contracts.WorkItemField> getField(field)
Parameters
field : string.
Returns
IPromise<Contracts.WorkItemField>
getFields()
Syntax
IPromise<Contracts.WorkItemField[]> getFields()
Parameters
Returns
IPromise<Contracts.WorkItemField[]>
getHistory()
Returns history of all revision for a given work item ID
Syntax
Parameters
id : number.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.WorkItemHistory[]>
getHistoryById()
Returns the history value of particular revision
Syntax
Parameters
id : number.
revisionNumber : number.
Returns
IPromise<Contracts.WorkItemHistory>
getQueries()
Retrieves all queries the user has access to in the current project
Syntax
Parameters
project : string. Project ID or project name
expand : Contracts.QueryExpand. Optional.
depth : number. Optional.
includeDeleted : boolean. Optional.
Returns
IPromise<Contracts.QueryHierarchyItem[]>
getQuery()
Retrieves a single query by project and either ID or path
Syntax
Parameters
project : string. Project ID or project name
query : string.
expand : Contracts.QueryExpand. Optional.
depth : number. Optional.
includeDeleted : boolean. Optional.
Returns
IPromise<Contracts.QueryHierarchyItem>
getRelationType()
Gets the work item relation types.
Syntax
IPromise<Contracts.WorkItemRelationType> getRelationType(relation)
Parameters
relation : string.
Returns
IPromise<Contracts.WorkItemRelationType>
getRelationTypes()
Syntax
IPromise<Contracts.WorkItemRelationType[]> getRelationTypes()
Parameters
Returns
IPromise<Contracts.WorkItemRelationType[]>
getReportingLinks()
Get a batch of work item links
Syntax
IPromise<Contracts.ReportingWorkItemLinksBatch> getReportingLinks(project, types, watermark,
startDateTime)
Parameters
project : string. Optional. Project ID or project name
types : string[]. Optional. A list of types to filter the results to specific work item types. Omit this parameter to
get work item links of all work item types.
watermark : number. Optional. Specifies the watermark to start the batch from. Omit this parameter to get the
first batch of links.
startDateTime : Date. Optional. Date/time to use as a starting point for link changes. Only link changes that
occurred after that date/time will be returned. Cannot be used in conjunction with 'watermark' parameter.
Returns
IPromise<Contracts.ReportingWorkItemLinksBatch>
getRevision()
Returns a fully hydrated work item for the requested revision
Syntax
Parameters
id : number.
revisionNumber : number.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem>
getRevisions()
Returns the list of fully hydrated work item revisions, paged.
Syntax
Parameters
id : number.
top : number. Optional.
skip : number. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem[]>
getRootNodes()
Syntax
Parameters
project : string. Project ID or project name
depth : number. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode[]>
getUpdate()
Returns a single update for a work item
Syntax
Parameters
id : number.
updateNumber : number.
Returns
IPromise<Contracts.WorkItemUpdate>
getUpdates()
Returns a the deltas between work item revisions
Syntax
Parameters
id : number.
top : number. Optional.
skip : number. Optional.
Returns
IPromise<Contracts.WorkItemUpdate[]>
getWorkItem()
Returns a single work item
Syntax
Parameters
id : number.
fields : string[]. Optional.
asOf : Date. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem>
getWorkItems()
Returns a list of work items
Syntax
Parameters
ids : number [].
fields : string[]. Optional.
asOf : Date. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem[]>
getWorkItemTemplate()
Returns a single work item from a template
Syntax
Parameters
project : string. Project ID or project name
type : string.
fields : string. Optional.
asOf : Date. Optional.
expand : Contracts.WorkItemExpand. Optional.
Returns
IPromise<Contracts.WorkItem>
getWorkItemType()
Returns a the deltas between work item revisions
Syntax
Parameters
project : string. Project ID or project name
type : string.
Returns
IPromise<Contracts.WorkItemType>
getWorkItemTypeCategories()
Syntax
IPromise<Contracts.WorkItemTypeCategory[]> getWorkItemTypeCategories(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.WorkItemTypeCategory[]>
getWorkItemTypeCategory()
Returns a the deltas between work item revisions
Syntax
Parameters
project : string. Project ID or project name
category : string.
Returns
IPromise<Contracts.WorkItemTypeCategory>
getWorkItemTypes()
Syntax
IPromise<Contracts.WorkItemType[]> getWorkItemTypes(project)
Parameters
project : string. Project ID or project name
Returns
IPromise<Contracts.WorkItemType[]>
queryById()
Gets the results of the query by id.
Syntax
Parameters
id : string. The query id.
project : string. Optional. Project ID or project name
team : string. Optional. Team ID or team name
Returns
IPromise<Contracts.WorkItemQueryResult>
queryByWiql()
Gets the results of the query.
Syntax
Parameters
wiql : Contracts.Wiql. The query containing the wiql.
project : string. Optional. Project ID or project name
team : string. Optional. Team ID or team name
Returns
IPromise<Contracts.WorkItemQueryResult>
readReportingRevisionsGet()
Get a batch of work item revisions
Syntax
Parameters
project : string. Optional. Project ID or project name
fields : string[]. Optional. A list of fields to return in work item revisions. Omit this parameter to get all
reportable fields.
types : string[]. Optional. A list of types to filter the results to specific work item types. Omit this parameter to
get work item revisions of all work item types.
watermark : number. Optional. Specifies the watermark to start the batch from. Omit this parameter to get the
first batch of revisions.
startDateTime : Date. Optional. Date/time to use as a starting point for revisions, all revisions will occur after this
date/time. Cannot be used in conjunction with 'watermark' parameter.
includeIdentityRef : boolean. Optional. Return an identity reference instead of a string value for identity fields.
includeDeleted : boolean. Optional. Specify if the deleted item should be returned.
Returns
IPromise<Contracts.ReportingWorkItemRevisionsBatch>
readReportingRevisionsPost()
Get a batch of work item revisions
Syntax
Parameters
filter : Contracts.ReportingWorkItemRevisionsFilter. An object that contains request settings: field filter, type
filter, identity format
project : string. Optional. Project ID or project name
watermark : number. Optional. Specifies the watermark to start the batch from. Omit this parameter to get the
first batch of revisions.
startDateTime : Date. Optional. Date/time to use as a starting point for revisions, all revisions will occur after this
date/time. Cannot be used in conjunction with 'watermark' parameter.
Returns
IPromise<Contracts.ReportingWorkItemRevisionsBatch>
restoreWorkItem()
Syntax
Parameters
payload : Contracts.WorkItemDeleteUpdate.
id : number.
project : string. Optional.
Returns
IPromise<Contracts.WorkItemDelete>
updateClassificationNode()
Syntax
Parameters
postedNode : Contracts.WorkItemClassificationNode.
project : string.
structureGroup : Contracts.TreeStructureGroup.
path : string. Optional.
Returns
IPromise<Contracts.WorkItemClassificationNode>
updateQuery()
Syntax
Parameters
queryUpdate : Contracts.QueryHierarchyItem.
project : string.
query : string.
undeleteDescendants : boolean. Optional.
Returns
IPromise<Contracts.QueryHierarchyItem>
updateWorkItem()
Syntax
Parameters
document : VSS_Common_Contracts.JsonPatchDocument.
id : number.
validateOnly : boolean. Optional.
bypassRules : boolean. Optional.
Returns
IPromise<Contracts.WorkItem>
updateWorkItemTemplate()
Syntax
Parameters
document : VSS_Common_Contracts.JsonPatchDocument.
project : string.
type : string.
validateOnly : boolean. Optional.
bypassRules : boolean. Optional.
Returns
IPromise<Contracts.WorkItem>
updateWorkItemTypeDefinition()
Add/updates a work item type
Syntax
Parameters
updateModel : Contracts.WorkItemTypeTemplateUpdateModel.
project : string. Optional.
Returns
IPromise<Contracts.ProvisioningResult>
Combo control
5/3/2018 • 2 minutes to read • Edit Online
Create a combo
TypeScript
JavaScript
Create a grid
TypeScript
JavaScript
Q&A
Q: How is the performance with huge data?
A: Grid uses UI virtualization which performs great on tens of thousands of rows.
Q: Can I have variable height rows?
A: No at the moment. This is caused by UI virtualization where scrolling is managed by grid itself. However, we are
thinking to improve this scenario.
TreeView control
5/3/2018 • 2 minutes to read • Edit Online
Create a treeview
TypeScript
JavaScript
Create a menubar
TypeScript
JavaScript
See Use modal dialog for basic usage and advanced samples.
JavaScript
require(["VSS/Controls/Dialogs"], function(Dialogs) {
// Create the modal dialog
var dialog = Dialogs.show(Dialogs.ModalDialog, options);
});
Splitter control
5/3/2018 • 2 minutes to read • Edit Online
Create a splitter
TypeScript
JavaScript
See Use wait control for basic usage and advanced samples.
JavaScript
Our goal is to help you be successful developing for VSTS. For any of the following:
Technical / how -to questions
Bugs (or potential bugs)
Feature requests
Documentations problems or gaps
Have a question? Check out the Developer Community site.
Manage Extensions
4/27/2018 • 2 minutes to read • Edit Online
Extensions for Visual Studio Team Services (VSTS ) and Team Foundation Server (TFS ) can be installed through
the Visual Studio Marketplace.
5-minute Quickstarts
Install VSTS extensions
Get extensions for TFS
Assign paid extensions to users
How-to Guides
Manage extension related permissions
Request extensions
Approve extension requests
Respond to Marketplace extension reviews
Troubleshooting
Marketplace FAQs