Edit

Share via

Contribution model

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022 | Azure DevOps Server 2020

Extensions add capabilities to Azure DevOps by declaring contribution types and contribution instances. A contribution type defines a contract (the properties and behavior) that contributions of that type must implement. A contribution is a concrete instance of a contribution type (for example, a hub or a build task).

Tip

If you're starting a new Azure DevOps extension, try these maintained sample collections first—they work with current product builds and cover modern scenarios (for example, adding tabs on pull request pages).

If a sample doesn't work in your organization, install it into a personal or test organization and compare the extension manifest's target IDs and API versions with the current docs. For reference and APIs, see:

For more information, see:

Contribution types

A contribution type defines the properties and rules that contributions of that type must follow. A contribution type can extend another contribution type, inheriting its properties.

Common contribution types include:

  • hub
  • action
  • build-task

Each property definition includes:

  • property type (for example, string or boolean)
  • whether the property is required
  • an optional default value

Example

A contribution type declaration in a manifest looks like this:

{
  "contributionTypes": [
    {
      "id": "hub",
      "name": "Web Access Hub",
      "description": "A hub that appears in the hubs menu at the top of web pages.",
      "properties": {
        "name": {
          "description": "The text to display for the hub",
          "type": "string",
          "required": true
        },
        "uri": {
          "description": "URI of the contents of the hub page",
          "type": "string",
          "required": true
        },
        "order": {
          "description": "Optional ordering value indicating the hub's position within the hub group",
          "type": "integer"
        }
      }
    }
  ]
}

Contributions

A contribution is an instance of a contribution type. For example, the Queries hub under the Work hub group is a contribution of type hub and the Publish Test Results build task is a contribution of type build-task.

All contributions must specify a type and specify values for any properties required by that contribution type.

Example

Here's an example of a hub contribution declaration in an extension manifest:

{
    "contributions": [
        {
            "id": "build-explorer-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                ".build-hub-group"
            ],
            "properties": {
                "name": "Explorer",
                "uri": "/_build",
                "order": 22
            }
        }
    ]
}

Target contributions

A contribution can target one or more other contributions, which creates a relationship between the contribution and each of its targets. The system can discover contributions for the target at runtime. For example, a hub contribution (Explorer) might target a specific hub-group contribution (Build).

{
    "id": "build-explorer-hub",
    "type": "ms.vss-web.hub",
    "targets": [
        ".build-hub-group"
    ]
}

When the hub group renders, the system can query for all hub contributions that target the hub group to know which hubs to render.

Identify contributions and types

Every contribution and contribution type must have a unique ID within the extension it's declared in.

A full contribution identifier includes the following items, which you separate with a dot . :

  • Publisher ID
  • Extension ID
  • Contribution/type ID

For example: ms.vss-web.hub is the full identifier for the following contribution:

  • Publisher ID: ms
  • Extension ID: vss-web
  • Contribution/type ID: hub

You can use relative contribution references within an extension manifest for a contribution's reference to another contribution or contribution type within that same extension. In this case, the publisher and extension IDs aren't included, and the ID is a dot . followed by the contribution ID. For example, .hub might be used within the vss-web extension mentioned previously as a shortcut for ms.vss-web.hub.