azure-devops-extension-sdk

Azure DevOps Web Extension SDK

Overview

Client SDK and TypeScript declare files for developing Azure DevOps extensions.

The core SDK script, DevOps.SDK.js, enables web extensions to communicate to the host frame and to perform operations like initialization, notifying the host that the extension is loaded or getting context about the current page.

Get the SDK

1. Download and install Node.js
2. Run npm install azure-devops-extension-sdk from the root of your extension project

This will place DevOps.SDK.js and DevOps.SDK.debug.js in node_modules/azure-devops-extension-sdk/lib/

Include the SDK script on your page

If you are developing a web extension, you will need to reference the SDK script from your HTML pages. For example:

<script src="lib/DevOps.SDK.js"></script>

To ensure the SDK script is packaged with your extension, update your extension manifest (typically vss-extension.json) and add a new entry to files:

{       
	"files": [{
		"path": "node_modules/azure-devops-extension-sdk/lib",
		"addressable": true,
		"packagePath": "lib"
	}]
}

Note: setting packagePath is optional, but results in a simpler path for referencing the SDK script from your HTML pages. Not setting a part name would have required you to reference the full path in your <script> tag (src="node_modules/azure-devops-extension-sdk/lib/DevOps.SDK.js")

Use the SDK

From your web extension's HTML page, include and initialize the DevOps SDK like this:

<script>

  // Initialize the SDK
  DevOps.init({
    applyTheme: true, // Supply if your extension is showing UI for it to reflect the user's DevOps theme
    loaded: true // Supply if your extension content is ready to be shown. Otherwise call DevOps.notifyLoadSucceeded() when loaded.
  });

  // Register callback to get called when initial handshake with the host has completed
  DevOps.ready(function() {
    // Start using the DevOps SDK
  });

</script>

Full API reference of DevOps.SDK.js can be found at Core Client SDK page.

Types

Type definitions are provided for:

• The DevOps SDK itself (see typings/DevOps.SDK.d.ts)
• Extension services

Consuming the types

From a TypeScript 2.5 or later project:

• Set "moduleResolution": "node" in your tsconfig.json project file

See TypeScript Module Resolution for more details.

Alternatively, you can explicitly reference the types at the top of your TypeScript file(s):

    /// <reference types="azure-devops-extension-sdk" />

Organizing your web extension project

If you are developing a web extension for Azure DevOps using TypeScript, we recommend the following organization:

Project structure

 |-- src
     |-- app.ts
     |-- some-module
         |-- a.ts
         |-- b.ts
 |-- static
     |-- css
         |-- main.css
     |-- images
         |-- logo.png
     |-- app.html
 |-- vss-extension.json
 |-- package.json
 |-- tsconfig.json

1. Place TypeScript source files in src
2. Place static content (CSS, images, HTML, etc) in static
   • This simplifes the process of packaging all necessary static content in your

TypeScript project file (tsconfig.json)

Defines the options for compiling your TypeScript files.

{
    "compilerOptions": {
        "module": "amd",
        "moduleResolution": "node",
        "target": "es5",
        "rootDir": "src/",
        "outDir": "dist/",
        "types": [
            "azure-devops-extension-sdk"
        ]	
    }
}

1. After compiling (tsc -p .), resulting .js files are placed in dist. For example, dist/app.js.

2. If your code directly uses types from other @types modules, you will want to include the module(s) in your package.json and add them to the types array. See @types.

Learn more about tsconfig.json

NPM package manifest (package.json)

Declares the libraries (like the azure-devops-extension-sdk) required to compile, package, and use your extension.

{
  /* other details like ID, version, etc are omitted */
  
  "scripts": {
    "build": "tsc -p .",
    "postbuild": "npm run package",
    "package": "tfx extension create",
    "gallery-publish": "tfx extension publish --rev-version",
    "clean": "rimraf ./dist && rimraf ./*.vsix"
  },
  "devDependencies": {
    "rimraf": "^2.5.4",
    "tfx-cli": "^0.3.45",
    "typescript": "^2.1.4"
  },
  "dependencies": {
    "azure-devops-extension-sdk": "^1.141.0"
  }
}

1. scripts provides a convenient way to define common operations that you want to perform on your project, like compiling and packaging.
   • For example, to build (compile) and package your extension, run: npm run build. This runs build and postbuild. If you make a change that doesn't require compiling, you can package by simply running npm run package.
   • To package and publish directly to the Marketplace on build, change the postbuild script to run the gallery-publish script (instead of package). You can then run npm run build -- --token xxxxxx (where xxxx is you personal access token for publishing to the Marketplace) to build, package, and publish your extension.

Learn more about package.json

Extension manifest (vss-extension.json)

{
    /* details omitted */
    "files": [
        {
            "path": "dist",
            "addressable": true
        },
        {
            "path": "static",
            "addressable": true
        },
        {
            "path": "node_modules/azure-devops-extension-sdk/lib",
            "addressable": true,
            "packagePath": "lib"
        }
    ],
    "contributions": [
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "properties": {
                "name": "Hub",
                "uri": "static/app.html"
            }
        }
    ]
}

1. The compiled JavaScript files (placed into dist by your tsconfig.json) will be packaged into the dist folder of the extension package.

2. The DevOps SDK scripts will be packaged into the lib folder of the extension package.

Learn more about the extension manifest.

HTML page

<head>
   <script src="../lib/Devops.SDK.js"></script>
   <!-- 
        Alternatively, if the packagePath attribute is not set for this file in your extension manifest (see above), do this:
         <script src="../node_modules/azure-devops-extension-sdk/lib/DevOps.SDK.js"></script>
   -->
</head>

<body>

 <script type="text/javascript">

  // Initialize the SDK
  DevOps.init({
    applyTheme: true, // Supply if your extension is showing UI for it to reflect the user's DevOps theme
    loaded: true // Supply if your extension content is ready to be shown. Otherwise call DevOps.notifyLoadSucceeded() when loaded.
  });

  // Register callback to get called when initial handshake with the host has completed
  DevOps.ready(function() {
    // Start using the DevOps SDK
  });

 </script>

</body>

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.