Extension manifest reference

Article
01/06/2023

TFS 2018

Every extension has a JSON manifest file that defines basic information about the extension. The file also defines how it can extend and enhance the experience. This article shows you how to create a manifest for your extension to Azure DevOps.

Tip

Check out our newest documentation on extension development using the Azure DevOps Extension SDK.

Create 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.

See the following example of a typical manifest:

{
    "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": [
        "Azure Boards"
    ],
    "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.	Should be `1`.
ID	The extension's identifier.	Th ID 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`. You can also add a fourth number for the following format: `0.1.2.3`
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.
categories	Array of strings representing the categories your extension belongs to. At least one category must be provided and there's no limit to how many categories you may include.	Valid values: `Azure Repos`, `Azure Boards`, `Azure Pipelines`, `Azure Test Plans`, and `Azure Artifacts`. Notes: - Use version >=0.6.3 of the tfx-cli if you're publishing the extension programmatically. - If you're using Azure DevOps Extension Tasks extension to publish, ensure that its version is >= 1.2.8. You might have to approve the extension update because of recent scope changes. - The categories previously mentioned are natively present in Visual Studio Marketplace and Azure DevOps Server 2019 & above. For extensions targeting earlier versions of TFS: - If TFS customers acquire your extension via Visual Studio Marketplace (not local gallery) in connected context, then use the categories that are previously stated. - If you are going to share the extension directly (that is, not via the Visual Studio Marketplace) with a customer using TFS <=2018 then use the following categories instead: Code, Plan and track, Build and release, Test, Collaborate, and Integrate. If you need to share both via Visual Studio Marketplace and directly with a TFS <= 2018 customer then you would need to have 2 extension packages.
targets	The products and services supported by your integration or extension. For more information, see installation targets.	An array of objects, where each object has an `id` field indicating one of the following: - `Microsoft.VisualStudio.Services` (extensions that works with Azure DevOps or TFS), - `Microsoft.TeamFoundation.Server` (extension that works with TFS), - `Microsoft.VisualStudio.Services.Integration` (integrations that works with Azure DevOps or TFS), - `Microsoft.TeamFoundation.Server.Integration` (integrations that work with TFS)

Examples of required attributes

{
    "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	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. For more information, see the full list of scopes.
demands	An array of demands (strings) listing the capabilities required by your extension.	For example, `api-version/3.0` indicates that your extension uses version 3.0 APIs, and so can't run in older products that don't support this version. For more information, see the full list of demands.
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

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

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
tags	Array of string tags to help users find your extension.	Examples: `agile`, `project management`, `task timer`, and so on.
screenshots	Array of images that couldn't 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. This is 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 may 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, and so on, from the approved badges sites	Valid keys: `href` - Link the user navigates to when selecting 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.

Mark an extension public

By default, all extensions in the Azure DevOps Marketplace are private. They're only visible to the publisher and accounts shared to by the publisher. If your publisher is verified, you can make your extension public by setting the Public flag in your extension manifest:

{
    "galleryFlags": [
        "Public"
    ]
}

Or:

{
    "public": true
}

For more information, see Package/Publish/Install.

Mark an extension to be in preview

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

{
    "galleryFlags": [
        "Preview"
    ]
}

Mark an extension as paid preview

If you intend to sell your extension on the Marketplace, mark it as paid preview. An extension marked free can't be changed to paid.

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

Mark an extension as paid

If you want to sell your extension on the Marketplace, you can mark it with the Paid flag and __BYOLENFORCED tag (starts with two underscores):

{
    "galleryFlags": [
        "Paid"        
    ],
     "tags": [        
        "__BYOLENFORCED"
    ]
}

Both the Paid flag and __BYOLENFORCED tag need to be present to mark an extension as paid in the Marketplace. Bring-Your-Own-License (BYOL) means the publisher of the extension provides the billing and licensing mechanism for the extension, as it isn't provided by Microsoft for Azure DevOps extensions. All paid extensions are required to define privacy policy, support policy, and an end-user license agreement. Also, publishers must provide content for the pricing tab in Marketplace as follows:

{
    "content": {
        "details": {
            "path": "overview.md"
        }, 
        "pricing": {
            "path": "pricing.md"
        }
    }
}

You also need to add a new section in your extension manifest to override paid licensing. In the future, we remove the paid licensing check and no longer require the override. For now, ensure your extension displays as expected. Each override consists of an “ID” and a “behavior.” The “ID” must match the ID of the contributions defined in the manifest.

"licensing": {

      "overrides": [

        { "id": "my-hub", "behavior": " AlwaysInclude" }
      ]
    }

If your paid BYOL extension offers a trial period (we recommend so), then you can specify the length of the trial in days:

{
    "galleryproperties": {
        "trialDays": "30"
    } 
}

Note

If you want to target Azure DevOps, but don't wish to surface a Download option for your extension, then add the __DoNotDownload tag (starts with two underscores) to the extension manifest. If you're moving an extension from the previously-offered billing & licensing from Microsoft to the BYOL model, then contact us for suitable steps.

Example of more 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 a custom Q&A URL. You can disable Q&A in the Marketplace using the CustomerQnASupport property in the manifest.

Default experience (No changes to manifest are required)

For extensions with a GitHub repository, Marketplace redirects users in the Q&A section to the associated GitHub issues.
For extensions without a 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": {
        "enablemarketplaceqna": true,
        "url": "http://uservoice.visualstudio.com"
    } 
}

Properties

Properties for the Customer Q & A Support section:

enablemarketplaceqna - 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: Extension using custom Q & A

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true",
        "url": "http://uservoice.visualstudio.com"
    } 
}

Example: Extension with GitHub repository but using Marketplace Q & A instead of GitHub issues

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true"
    } 
}

Example: Extension disabling Q & A section

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"false"
    } 
}

Scopes

In your extension, you can define one or more scopes. These scopes determine which resources your extension can access and the operations it's permitted to perform on those resources. The scopes you specify in your extension manifest are the scopes set on access tokens issued to your extension. For more information, see Auth and security.

If no scopes are specified, extensions are only provided access to user profile and extension data.

Supported scopes

Category	Scope	Name	Description
Agent Pools	`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`	Agent Pools (read, manage)	Grants the ability to manage pools, queues, and agents.
	`vso.environment_manage`	Environment (read, manage)	Grants the ability to manage pools, queues, agents, and environments.
Analytics	`vso.analytics`	Analytics (read)	Grants the ability to query analytics data.
Auditing	`vso.auditlog`	Audit Log (read)	Grants the ability to read the auditing log to users.
	`vso.auditstreams_manage`	Audit Streams (read)	Grants the ability to manage auditing streams to users.
Build	`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`	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.
Code	`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 search code and get notified about version control events via service hooks.
	`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`	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.code_full`	Code (full)	Grants full access to source code, 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. Also includes limited support for Client OM APIs.
	`vso.code_status`	Code (status)	Grants the ability to read and write commit and pull request status.
Connected Server	`vso.connected_server`	Connected Server	Grants the ability to access endpoints needed from an on-prem connected server.
Entitlements	`vso.entitlements`	Entitlements (Read)	Provides read only access to licensing entitlements endpoint to get account entitlements.
	`vso.memberentitlementmanagement`	MemberEntitlement Management (read)	Grants the ability to read users, their licenses as well as projects and extensions they can access.
	`vso.memberentitlementmanagement_write`	MemberEntitlement Management (write)	Grants the ability to manage users, their licenses as well as projects and extensions they can access.
Extensions	`vso.extension`	Extensions (read)	Grants the ability to read installed extensions.
	`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`	Extension data (read and write)	Grants the ability to read and write data (settings and documents) stored by installed extensions.
Graph & identity	`vso.graph`	Graph (read)	Grants the ability to read user, group, scope, and group membership information.
	`vso.graph_manage`	Graph (manage)	Grants the ability to read user, group, scope and group membership information, and to add users, groups, and manage group memberships.
	`vso.identity`	Identity (read)	Grants the ability to read identities and groups.
	`vso.identity_manage`	Identity (manage)	Grants the ability to read, write, and manage identities and groups.
Machine Group	`vso.machinegroup_manage`	Deployment group (read, manage)	Provides ability to manage deployment group and agent pools.
Marketplace	`vso.gallery`	Marketplace	Grants read access to public and private items and publishers.
	`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`	Marketplace (manage)	Grants read access and the ability to publish and manage items and publishers.
Notifications	`vso.notification`	Notifications (read)	Provides read access to subscriptions and event metadata, including filterable field values.
	`vso.notification_write`	Notifications (write)	Provides read and write access to subscriptions and read access to event metadata, including filterable field values.
	`vso.notification_manage`	Notifications (manage)	Provides read, write, and management access to subscriptions and read access to event metadata, including filterable field values.
	`vso.notification_diagnostics`	Notifications (diagnostics)	Provides access to notification-related diagnostic logs and provides the ability to enable diagnostics for individual subscriptions.
Packaging	`vso.packaging`	Packaging (read)	Grants the ability to read feeds and packages.
	`vso.packaging_write`	Packaging (read and write)	Grants the ability to create and read feeds and packages.
	`vso.packaging_manage`	Packaging (read, write, and manage)	Grants the ability to create, read, update, and delete feeds and packages.
Pipeline Resources	`vso.pipelineresources_use`	Pipeline Resources (use)	Grants the ability to approve a pipeline's request to use a protected resource: agent pool, environment, queue, repository, secure files, service connection, and variable group.
	`vso.pipelineresources_manage`	Pipeline Resources (use and manage)	Grants the ability to manage a protected resource or a pipeline's request to use a protected resource: agent pool, environment, queue, repository, secure files, service connection, and variable group.
Project and Team	`vso.project`	Project and team (read)	Grants the ability to read projects and teams.
	`vso.project_write`	Project and team (read and write)	Grants the ability to read and update projects and teams.
	`vso.project_manage`	Project and team (read, write and manage)	Grants the ability to create, read, update, and delete projects and teams.
Release	`vso.release`	Release (read)	Grants the ability to read release artifacts, including releases, release definitions and release environment.
	`vso.release_execute`	Release (read, write and execute)	Grants the ability to read and update release artifacts, including releases, release definitions and release environment, and the ability to queue a new release.
	`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 environment, and the ability to queue and approve a new release.
Secure Files	`vso.securefiles_read`	Secure Files (read)	Grants the ability to read secure files.
	`vso.securefiles_write`	Secure Files (read, create)	Grants the ability to read and create secure files.
	`vso.securefiles_manage`	Secure Files (read, create, and manage)	Grants the ability to read, create, and manage secure files.
Security	`vso.security_manage`	Security (manage)	Grants the ability to read, write, and manage security permissions.
Service Connections	`vso.serviceendpoint`	Service Endpoints (read)	Grants the ability to read service endpoints.
	`vso.serviceendpoint_query`	Service Endpoints (read and query)	Grants the ability to read and query service endpoints.
	`vso.serviceendpoint_manage`	Service Endpoints (read, query and manage)	Grants the ability to read, query, and manage service endpoints.
Settings	`vso.settings`	Settings (read)	Grants the ability to read settings.
	`vso.settings_write`	Settings (read and write)	Grants the ability to create and read settings.
Symbols	`vso.symbols`	Symbols (read)	Grants the ability to read symbols.
	`vso.symbols_write`	Symbols (read and write)	Grants the ability to read and write symbols.
	`vso.symbols_manage`	Symbols (read, write and manage)	Grants the ability to read, write, and manage symbols.
Task Groups	`vso.taskgroups_read`	Task Groups (read)	Grants the ability to read task groups.
	`vso.taskgroups_write`	Task Groups (read, create)	Grants the ability to read and create task groups.
	`vso.taskgroups_manage`	Task Groups (read, create and manage)	Grants the ability to read, create and manage taskgroups.
Team Dashboard	`vso.dashboards`	Team dashboards (read)	Grants the ability to read team dashboard information.
	`vso.dashboards_manage`	Team dashboards (manage)	Grants the ability to manage team dashboard information.
Test Management	`vso.test`	Test management (read)	Grants the ability to read test plans, cases, results and other test management related artifacts.
	`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.
Threads	`vso.threads_full`	PR threads	Grants the ability to read and write to pull request comment threads.
Tokens	`vso.tokens`	Delegated Authorization Tokens	Grants the ability to manage delegated authorization tokens to users.
	`vso.tokenadministration`	Token Administration	Grants the ability to manage (view and revoke) existing tokens to organization administrators.
User Profile	`vso.profile`	User profile (read)	Grants the ability to read your profile, accounts, collections, projects, teams, and other top-level organizational artifacts.
	`vso.profile_write`	User profile (write)	Grants the ability to write to your profile.
Variable Groups	`vso.variablegroups_read`	Variable Groups (read)	Grants the ability to read variable groups.
	`vso.variablegroups_write`	Variable Groups (read, create)	Grants the ability to read and create variable groups.
	`vso.variablegroups_manage`	Variable Groups (read, create and manage)	Grants the ability to read, create and manage variable groups.
Wiki	`vso.wiki`	Wiki (read)	Grants the ability to read wikis, wiki pages and wiki attachments. Also grants the ability to search wiki pages.
	`vso.wiki_write`	Wiki (read and write)	Grants the ability to read, create and updates wikis, wiki pages and wiki attachments.
Work Items	`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, search work items and to receive notifications about work item events via service hooks.
	`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.
	`vso.work_full`	Work items (full)	Grants full access to work items, queries, backlogs, plans, and work item tracking metadata. Also provides the ability to receive notifications about work item events via service hooks.
User Impersonation	`user_impersonation`	User Impersonation	Have full access to Visual Studio Team Services REST APIs. Request and/or consent this scope with caution as it is very powerful!

Changing scope of published extension

You can change the scope of a published extension. If you previously installed your extension (and authorized the previous set of scopes), you must authorize the new scopes before you can upgrade to the newest version.

The Action Required section of the Extension settings hub shows a user that, 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 where you can install your extension. Microsoft.VisualStudio.Services is the most common installation target and indicates that the extension can be installed into Azure DevOps.

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 Azure DevOps Services
Microsoft.TeamFoundation.Server: installs into Azure DevOps Server
Microsoft.VisualStudio.Services: installs into both. Shortcut for Microsoft.VisualStudio.Services.Cloud and Microsoft.TeamFoundation.Server version [14.2,)

Supported identifiers for integrations:

Microsoft.VisualStudio.Services.Cloud.Integration: integrates with Azure DevOps Services
Microsoft.TeamFoundation.Server.Integration: integrates with Azure DevOps Server
Microsoft.VisualStudio.Services.Integration: integrates with both. Shortcut for Microsoft.VisualStudio.Services.Cloud.Integration and Microsoft.TeamFoundation.Server.Integration

For more information, see Extensibility points.

Examples of installation targets

Example: Extension that works with Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

Example: Extension that works only with Azure DevOps Services

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        }
    ]
}

Installation targets can also be used in the manifest of integrations. For example, products, apps, or tools that work with, but don't install into Azure DevOps.

Example: Integration that works with Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ]
}

Example: Integration that only works with Azure DevOps Server

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

Installation target versions

Some installation target identifiers, like Microsoft.TeamFoundation.Server and Microsoft.TeamFoundation.Server.Integration, support an optional version range. This optional version range 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:
- [: minimum version inclusive
- ]: maximum version inclusive
- (: minimum version exclusive
- ): maximum version exclusive

Version numbers for Azure DevOps 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
2018	RTM and updates	16.0
2019	RTM and updates	17.0
2020	RTM and updates	18.0

Examples showing versions

Example: Extension that works with Azure DevOps

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[15.0,)"
        }
    ]
}

Shortcuts

Microsoft.VisualStudio.Services is a shortcut for Azure DevOps.

{
    "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 a correct 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-version/3.0 means the extension works with Azure DevOps.

Tip

For more information on REST APIs, see the REST API Reference.

Example: Extension that uses version 3.0 APIs

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

Resolves to the following installation targets:

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

Example: Integration that uses version 2.0 APIs

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

Resolves to the following installation targets:

Microsoft.VisualStudio.Services.Cloud.Integration
Microsoft.TeamFoundation.Server.Integration, version: [14.0,)

Demands

Demands let you specify capabilities and other features required by your extension. You can use these demands to limit where your extension can be published or installed.

Demands get used by the Visual Studio Marketplace to list the products and environments your extension is compatible with, which helps customers understand whether your extension works with their version of Azure DevOps, for example.

See the following example of how demands get specified in the extension manifest.

{
    "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 Azure DevOps. 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

Note

Use environment/cloud and environment/onprem only 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 organization/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 to resource on disk, which can be relative to your root directory.
addressable – (optional) Set to true if you want your file to be URL-addressable. Defaults to false.
packagePath – (optional) Path to the resource within the package. Defaults to the relative path on disk from your root directory.
contentType – (optional) MIME type of the file. Defaults to a best guess based on the file extension and OS settings.
assetType – (optional) Specify the value of the Type attribute of the asset entry in the VSIX manifest. Can also be an array of strings, in which case multiple asset entries get added for this file. Defaults to the packagePath.
lang – (optional) Language of this asset. Localized files are served based on the Accept-Language header. Leave blank to signify this file is in the default (or fallback) language. Localized versions of the same file should have the same assetType.

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

For more information, see the contribution model overview.

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.
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 contributions of this type can use.

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, which could be string, uri, guid, boolean, integer, double, dateTime, array, or object.

For more information, see the contribution model overview.

Referencing contributions and types

Use unique identifiers to reference contributions and contribution types. Reference types with the type property, and reference other contributions with 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 might 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 a dot (.) followed by the contribution identifier. For example, ".hub" might be used within the "vss-web" extension mentioned previously as a shortcut for "ms.vss-web.hub."

Targeting contributions

Some contributions act as containers targeted by other contributions.

Hub contributions can target Hub Groups. When a page is rendered, the web UI shows all Hub contributions that target the selected hub group. Hub groups target a hub group collection, which defines a set of hub groups that show up in a given navigational area, for example, project-level admin pages.
Different types of contributions can target menus: 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.

Adding a hub icon

For information on adding an icon to your hub, check out the hub icon guidance.

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/
vsmarketplacebadges.dev/
bithound.io/
deepscan.io/
githost.io/
gitlab.com/
opencollective.co/

Note

Replace "vsmarketplacebadge.apphb.com" with "vsmarketplacebadges.dev".

To show a badge from another service, contact vsmarketplace@microsoft.com.

Example manifest

The following extension contributes 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"
            }
        }
    ]
}

Share via

Extension manifest reference

Required attributes

Examples of required attributes

Optional attributes

Runtime attributes

Discovery attributes

Mark an extension public

Mark an extension to be in preview

Mark an extension as paid preview

Mark an extension as paid

Example of more properties

Details page example

Marketplace Q & A - CustomerQnASupport property

Properties

Examples showing usage of Q & A support

Example: Extension using custom Q & A

Example: Extension with GitHub repository but using Marketplace Q & A instead of GitHub issues

Example: Extension disabling Q & A section

Scopes

Supported scopes

Changing scope of published extension

Installation targets

Examples of installation targets

Example: Extension that works with Azure DevOps

Example: Extension that works only with Azure DevOps Services

Example: Integration that works with Azure DevOps

Example: Integration that only works with Azure DevOps Server

Installation target versions

Examples showing versions

Example: Extension that works with Azure DevOps

Shortcuts

Using installation targets and demands

Example: Extension that uses version 3.0 APIs

Example: Integration that uses version 2.0 APIs

Demands

Supported demands

Files

Properties

Contributions

Contribution types

Referencing contributions and types

Targeting contributions

Adding a hub icon

Supported badge services

Example manifest

Additional resources