Develop a web extension

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Use extensions to enhance Azure DevOps with new web experiences, dashboard widgets, build tasks, and more. You can develop extensions using standard technologies like HTML, JavaScript, and CSS. This tutorial guides you through creating a web extension for Azure DevOps.

Tip

Explore the extension samples and the newest documentation on extension development using the Azure DevOps Extension SDK.

Prerequisites

You must have the following permission and installations.

Create a directory and manifest

An extension is composed of a set of files that includes a required manifest file. You package it into a .vsix file and publish to the Visual Studio Marketplace.

  1. Create a directory to hold the files needed for your extension:

    mkdir my-first-extension
    
  2. From this directory, initialize a new npm package manifest:

    npm init -y
    

    This file describes the libraries required by your extension.

  3. Install the Microsoft VSS Web Extension SDK package and save it to your npm package manifest:

    npm install azure-devops-extension-sdk --save
    

    This SDK includes a JavaScript library that provides APIs required for communicating with the page your extension is embedded in.

  4. Create an extension manifest file named vss-extension.json at the root of your extension directory with the following content:

    {
        "manifestVersion": 1,
        "id": "my-first-extension",
        "publisher": "",
        "version": "1.0.0",
        "name": "My First Extension",
        "description": "A sample Visual Studio Services extension",
        "public": false,
        "categories": ["Azure Repos"],
        "targets": [
            {
                "id": "Microsoft.VisualStudio.Services"
            }
        ],
        "contributions": [
            {
                "id": "my-hub",
                "type": "ms.vss-web.hub",
                "targets": [
                    "ms.vss-code-web.code-hub-group"
                ],
                "properties": {
                    "name": "My Hub",
                    "uri": "my-hub.html"
                }
            }
        ],
        "files": [
            {
                "path": "my-hub.html",
                "addressable": true
            },
            {
                "path": "node_modules/azure-devops-extension-sdk",
                "addressable": true,
                "packagePath": "lib"
            }
        ]
    }
    

    Note

    The public property controls whether the extension is visible to everyone on the Visual Studio Marketplace. Keep your extensions private during development.

  5. Create a file named my-hub.html at the root of your extension directory with the following content, which is for the view (also known as a hub) contributed into the web experience.

    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
        <script>
            window.requirejs.config({
                enforceDefine: true,
                paths: {
                    'SDK': './lib/SDK.min'
                }
            });
            window.requirejs(['SDK'], function (SDK) {
                if (typeof SDK !== 'undefined') {
                    console.log("SDK is defined. Trying to initialize...");
                    SDK.init();
                    SDK.ready().then(() => {
                        console.log("SDK is ready");
                        document.getElementById("name").innerText = SDK.getUser().displayName;
                    });
                } else {
                    console.log('SDK is not defined');
                }
            });
        </script>
        <style>
            body {
                background-color: rgb(0, 67, 117);
                color: white;
                margin: 10px;    
                font-family: "Segoe UI VSS (Regular)","-apple-system",BlinkMacSystemFont,"Segoe UI",sans-serif;
            }
        </style>
    </head>
    <body>        
        <h1>Hello, <span id="name"></span></h1>
    </body>
    </html>
    
  6. Your extension directory should look like the following example.

    |-- my-hub.html
    |-- node_modules
        |-- @types
        |-- azure-devops-extension-sdk
    |-- package.json
    |-- vss-extension.json
    
Need help? Post questions to the Azure DevOps Services Developer Community.

Next steps