Skip to content

manifest.md

Latest commit

 

History

History
634 lines (470 loc) · 22.4 KB

manifest.md

File metadata and controls

634 lines (470 loc) · 22.4 KB
ms.subservice azure-devops-ecosystem
title Extension Manifest Reference| Extensions for Azure DevOps
description How to create a manifest for your extension to Azure DevOps
ms.assetid e3150221-3cdf-47e1-b7e9-24211498cc29
ms.topic reference
monikerRange <= azure-devops
ms.author chcomley
author chcomley
ms.date 03/21/2025

Extension manifest reference

[!INCLUDE version-lt-eq-azure-devops]

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.

[!INCLUDE extension-docs-new-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:

[!code-json]

For information about inputs, see ...

Required attributes

[!INCLUDE ]

Examples of required attributes

[!code-json]

Optional attributes

Runtime attributes

[!INCLUDE ]

[!code-json]

Discovery attributes

[!INCLUDE ]

Mark an extension public

By default, all extensions in the Azure DevOps Marketplace are private. They are hidden from public view, and are only visible to the publisher and specific 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. 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." Make the "ID" 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

[!code-json]

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 Questions and Answers (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 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

[!INCLUDE ]

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), 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 and 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:

  1. Microsoft.VisualStudio.Services.Cloud
  2. 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:

  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. 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 require that the specified extension is already installed and enabled in the organization or 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. Make each contribution ID 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. Make each contribution type ID 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 get 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 Customer Support at the Developer Community.

Example manifest

The following extension contributes an action to the completed builds context menu and a hub to the Build hub group:

[!code-json]