Extension manifest reference

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:

Property Description Notes
manifestVersion A number corresponding to the version of the manifest format. This should be 1.
id The extension's identifier. This is a string that must be unique among extensions from the same publisher. It must start with an alphabetic or numeric character and contain 'A' through 'Z', 'a' through 'z', '0' through '9', and '-' (hyphen). Example: sample-extension.
version A string specifying the version of an extension. Should be in the format major.minor.patch, for example 0.1.2 or 1.0.0.
name A short, human-readable name of the extension. Limited to 200 characters. Example: "Fabrikam Agile Board Extension".
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 your integration or extension. See installation targets for more details. This is an array of objects, where each object has an id field indicating one 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)
Property Description Notes
scopes An array of authorization scopes (strings) listing permissions required by your extension. For example, vso.work and vs.code_write indicates your extension needs read-only access to work items and read/write access to source code (and related resource). Scopes are presented to the user when installing your extension.
demands An array of demands (strings) listing the capabilities required by your extension. For example, api-version/3.0 indicates your extension uses version 3.0 APIs and therefore cannot run in older products that do not support this version.
baseUri (Optional) base URL for all relative URLs specified by the extension's contributions. For example: https://myapp.com/{{account.name}}/. This property should be left empty if your extension's contents are packaged with your extension.
contributions An array of contributions to the system.
contributionTypes An array of contribution types defined by the extension

Examples of required attributes

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}
{
    "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"
            }
        }
    ]
}

Additional attributes

These optional properties help users discover and learn about your extension:

Property Description Notes
description A few sentences describing the extensions. Limited to 200 characters. The description should be your extension's "elevator pitch" - a couple of lines to describe your extension in the marketplace and make people want to install it. See the example below
icons Dictionary of icons representing the extension. Valid keys: default (128x128 pixels) 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 categories your extension belongs to. Limited to 3. First is considered the default. Valid values: Build and release, Collaborate, Code, Developer samples, Plan and track, Integrate, and Test
tags Array of string tags to help users find your extension. Examples: agile, project management, task timer, etc.
screenshots Array of images that could not be included in your **content*. Screenshots are more valuable when 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 your extension to users. Every extension should include solid 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 more about your extension, get support, and move. Valid keys: getstarted - first steps, how to setup or use. learn - deeper 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 source code repository for the extension Valid Keys: type - Type of repository. Example: git. uri - Absolute URL of the repository.
badges Array of links to external metadata badges like TravisCI, Appveyor etc from the approved badges sites Valid keys: href - Link the user will navigate to when clicking the badge. 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.

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
}            

See Package/Publish/Install for additional details.

Preview flag

If your extension is ready for users on the Marketplace to try, but you are still working out a few bugs or adding function, you can mark it as preview:

{
    "galleryFlags": [
        "Preview"
    ]
}            

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.

If you intend to sell your extension on the Marketplace in the future, you have to mark it as paid preview:

{
    "galleryFlags": [
        "Paid",
        "Preview"
    ]
}            

Only extensions marked as paid preview can be converted to paid.

Note: If you do want to target TFS but do not wish to surface a Download option for your extension then add __DoNotDownload tag (starts with two underscores) to the extension manifest.

Example of additional properties

{
    "description": "Awesome tools to help you and your team do great things everyday.",
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "categories": [
        "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"
        }
    ]
}

Details page example

  • 1 - description
  • 2 - icon
  • 3 - categories
  • 4 - screenshots
  • 5 - content (details)
  • 6 - links
  • 7 - branding

card

Marketplace Q&A - CustomerQnASupport property

All extensions on the Visual Studio Marketplace have a Q&A section to allow one-on-one public conversations between extension users and publishers. Publishers can choose between Marketplace Q&A, GitHub issues, or custom Q&A URL for the Q&A section or disable Q&A in Marketplace using the CustomerQnASupport property in the manifest.

Default experience (No changes to manifest are required)

  • For extension with GitHub repository, Marketplace will redirect users in the Q&A section to the associated GitHub issues.
  • For extension without GitHub repository, Marketplace Q&A is enabled.

For a different experience than one of the default options use the CustomerQnASupport property in the manifest.

{
    "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"
    } 
}

Example 12: Extension disabling Q&A section

{
     "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.agentpools_manage Agent Pools (read, manage) Grants the ability to manage pools, queues, and agents
vso.agentpools Agent Pools (read) Grants the ability to view tasks, pools, queues, agents, and currently running or recently completed jobs for agents vso.agentpools_manage
vso.build Build (read) Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to receive notifications about build events via service hooks. vso.build_execute
vso.build_execute Build (read and execute) Grants the ability to access build artifacts, including build results, definitions, and requests, and the ability to queue a build, update build properties, and the ability to receive notifications about build events via service hooks.
vso.chat_write Team rooms (read and write) Grants the ability to access rooms and view, post, and update messages. Also grants the ability to receive notifications about new messages via service hooks. vso.chat_manage
vso.chat_manage Team rooms (read, write, and manage) Grants the ability to access 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 Code (read) Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to get notified about version control events via service hooks. vso.code_write
vso.code_manage
vso.code_write Code (read and write) Grants the ability to read, 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.code_manage
vso.code_status Code (status) Grants the ability to read and write commit and pull request status.
vso.code_manage Code (read, write, and manage) Grants the ability to read, update, and delete source code, access metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to create and manage code repositories, create and manage pull requests and code reviews, and to receive notifications about version control events via service hooks.
vso.dashboards_manage Team dashboards (manage) Grants the ability to manage team dashboard information
vso.dashboards Team dashboards (read) Grants the ability to read team dashboard information
vso.entitlements Entitlements (Read) Provides read only access to VSTS licensing entitlements endpoint to get account entitlements.
vso.extension Extensions (read) Grants the ability to read installed extensions. vso.extension_manage
vso.extension_manage Extensions (read and manage) Grants the ability to install, uninstall, and perform other administrative actions on installed extensions.
vso.extension.data Extension data (read) Grants the ability to read data (settings and documents) stored by installed extensions. vso.extension.data_write
vso.extension.data_write Extension data (read and write) Grants the ability to read and write data (settings and documents) stored by installed extensions.
vso.gallery Marketplace Grants read access to public and private items and publishers. vso.gallery_publish
vso.gallery_manage
vso.gallery_acquire
vso.gallery_acquire Marketplace (acquire) Grants read access and the ability to acquire items.
vso.gallery_publish Marketplace (publish) Grants read access and the ability to upload, update, and share items. vso.gallery_manage
vso.gallery_manage Marketplace (manage) Grants read access, the ability to publish and manage items and publishers.
vso.identity Identity (read) Grants the ability to read identities and groups.
vso.notification Notifications (read) Provides read access to subscriptions and event metadata, including filterable field values. vso.notification_write
vso.notification_manage
vso.notification_write Notifications (write) Provides read/write access to subscriptions and read access to event metadata, including filterable field values. vso.notification_manage
vso.notification_manage Notifications (manage) Provides read, write, and management access to subscriptions and read access to event metadata, including filterable field values.
vso.packaging Packaging (read) Grants the ability to read feeds and packages. vso.packaging_write
vso.packaging_manage
vso.packaging_write Packaging (read and write) Grants the ability to create and read feeds and packages. vso.packaging_manage
vso.packaging_manage Packaging (read, write, and manage) Grants the ability to create, read, update, and delete feeds and packages.
vso.profile User profile (read) Grants the ability to read your profile, accounts, collections, projects, teams, and other top-level organizational artifacts. vso.extension
vso.extension_manage
vso.extension.data
vso.extension.data_write
vso.gallery
vso.gallery_acquire
vso.gallery_publish
vso.gallery_manage
vso.notification
vso.notification_write
vso.notification_manage
vso.packaging
vso.packaging_write
vso.packaging_manage
vso.profile_write
vso.release
vso.release_execute
vso.release_manage
vso.test
vso.test_write
vso.profile_write User profile (write) Grants the ability to write to your profile.
vso.project Project and team (read) Grants the ability to read projects and teams. vso.project_write
vso.project_manage
vso.project_write Project and team (read and write) Grants the ability to read and update projects and teams. vso.project_manage
vso.project_manage Project and team (read, write, and manage) Grants the ability to create, read, update, and delete projects and teams.
vso.release Release (read) Grants the ability to read release artifacts, including releases, release definitions and release environment. vso.release_execute
vso.release_manage
vso.release_execute Release (read, write and execute) Grants the ability to read and update release artifacts, including releases, release definitions and release envrionment, and the ability to queue a new release. vso.release_manage
vso.release_manage Release (read, write, execute and manage) Grants the ability to read, update and delete release artifacts, including releases, release definitions and release envrionment, and the ability to queue and approve a new release.
vso.test Test management (read) Grants the ability to read test plans, cases, results and other test management related artifacts. vso.test_write
vso.test_write Test management (read and write) Grants the ability to read, create, and update test plans, cases, results and other test management related artifacts.
vso.work Work items (read) Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries and to receive notifications about work item events via service hooks. vso.work_write
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.

Changing a published extension's scopes

The scopes of an extension can be changed after publishing. Customers that previously installed your extension (and authorized the previous set of scopes) will remain on the previous version of the extension and will need to authorize the new scopes before being upgraded to the newest version.

The Action Required section of the Extension settings hub shows a user which, if any, installed extensions require authorization:

scope-change

An administrator can then review and authorize the new set of scopes:

scope-change-dialog

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 boht. 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"
        }
    ]
}

Example 2: Extension that works only with VSTS

{
    "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"
        }
    ]
}

Example 4: Integration that only works with Team Foundation Server

{
    "targets": [
        {
            "id": "Microsoft.TeamFoundation.Server.Integration"
        }
    ]
}

Installation target versions

Some installation target identifiers, like Microsoft.TeamFoundation.Server and Microsoft.TeamFoundation.Server.Integration, suppport an optional version range. This further clarifies the supported releases the extension or integration is supported on.

The version or version range is specified via the version field on the installation target object. This value can be either:

  • A specific version, for example: 15.0 (2017 RTM only)
  • A range of supported versions, for example: [14.0) (2015 RTM and later), [14.3,15.1] (2015 Update 3 through 2017 Update 1). Range values are refined using the following:
    • [: minimum version inclusive
    • ]: maximum version inclusive
    • (: minimum version exclusive
    • ): maximum version exclusive

Version numbers for Team Foundation Server:

Release Releases Version
2010 All releases 10.0
2012 All releases 11.0
2013 RTM and updates 12.0, 12.1, 12.2, 12.3, 12.4
2015 RTM and updates 14.0, 14.1, 14.2, 14.3
2017 RTM and updates 15.0, 15.1

Examples showing versions

Example 5: Extension that works with VSTS and Team Foundation Server 2017 and later

{
    "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,)"
        }
    ]
}

Using installation targets and demands

Installation targets and demands are used together to present users with an accurate view of the products/services your extension or integration is compatible with. For example, specifying an installation target of Microsoft.VisualStudio.Services with a demand of api-verison/3.0 means the extension works with VSTS and Team Foundation Server 2017 RTM and later:

Example 8: Extension that uses version 3.0 APIs

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ]
}

Resolves to the following installation targets:

  1. Microsoft.VisualStudio.Services.Cloud
  2. Microsoft.TeamFoundation.Server, version: [15.0,)

Example 9: Integration that uses version 2.0 APIs

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ],
    "demands": [
        "api-version/2.0"
    ]
}

Resolves to the following installation targets:

  1. Microsoft.VisualStudio.Services.Cloud.Integration
  2. Microsoft.TeamFoundation.Server.Integration, version: [14.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?
environment/cloud Requires running in a cloud environment Yes Yes
environment/onprem Requires running in an on-premises environment Yes Yes
api-version/{version} Requires a specific API version (minimum) No Yes
extension/{id} Requires a specific extension be installed/enabled No Yes
contribution/{id} Requires a specific contribution be available No Yes
contributionType/{id} Requires a specific contribution type be available No Yes

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.

Supported badge services

The Marketplace only supports badges from the following trusted services:

  • api.travis-ci.org/
  • badge.fury.io/
  • badges.frapsoft.com/
  • badges.gitter.im/
  • badges.greenkeeper.io/
  • cdn.travis-ci.org/
  • ci.appveyor.com/
  • codeclimate.com/
  • codecov.io/
  • coveralls.io/
  • david-dm.org/
  • gemnasium.com/
  • img.shields.io/
  • isitmaintained.com/
  • marketplace.visualstudio.com/
  • snyk.io/
  • travis-ci.com/
  • travis-ci.org/
  • vsmarketplacebadge.apphb.com/
  • bithound.io/

If you want to show a badge from another service, please contact vsmarketplace@microsoft.com.

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"
            }
        }
    ]
}