Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
azure-devops-extension-sdk
Advanced tools
azure-devops-extension-sdk - npm Package Compare versions
Comparing version 1.141.14 to 2.0.0
| { | ||
| "name": "azure-devops-extension-sdk", | ||
| "version": "1.141.14", | ||
| "description": "Azure DevOps web extension JavaScript library and types.", | ||
| "version": "2.0.0", | ||
| "description": "Azure DevOps web extension JavaScript library.", | ||
| "repository": { | ||
@@ -6,0 +6,0 @@ "type": "git", |
238
README.md
@@ -5,236 +5,42 @@ # Azure DevOps Web Extension SDK | ||
| Client SDK and TypeScript declare files for developing [Azure DevOps extensions](https://docs.microsoft.com/en-us/azure/devops/integrate). | ||
| Client SDK and TypeScript declare files for developing [Azure DevOps extensions](https://docs.microsoft.com/en-us/azure/devops/extend/overview). | ||
| 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. | ||
| The client SDK enables web extensions to communicate to the host frame. It can be used to: | ||
| ## Get the SDK | ||
| - Notify the host that the extension is loaded or has errors | ||
| - Get basic contextual information about the current page (current user, host and extension information) | ||
| - Get theme information | ||
| - Obtain an authorization token to use in REST calls back to Azure DevOps | ||
| - Get remote services offered by the host frame | ||
| 1. Download and install [Node.js]((https://nodejs.org/en/download/)) | ||
| 2. Run `npm install azure-devops-extension-sdk` from the root of your extension project | ||
| ## Get started with a new extension | ||
| This will place `DevOps.SDK.js` and `DevOps.SDK.debug.js` in `node_modules/azure-devops-extension-sdk/lib/` | ||
| See the [Develop a web extension for Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/extend/get-started/node?view=vsts) documentation for instructions on getting started with a new extension. You can also refer to the [azure-devops-extension-sample](https://github.com/Microsoft/azure-devops-extension-sample) repository as a working reference. | ||
| ### Include the SDK script on your page | ||
| ## Import the SDK within your extension project | ||
| If you are developing a web extension, you will need to reference the SDK script from your HTML pages. For example: | ||
| 1. Add `azure-devops-extension-sdk` to the list of dependencies in your package.json | ||
| 2. Add `import * as SDK from "azure-devops-extension-sdk"` to your TypeScript code | ||
| ```html | ||
| <script src="lib/DevOps.SDK.js"></script> | ||
| ``` | ||
| ## Initialize the SDK | ||
| 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`: | ||
| When you have rendered your extension content, call `SDK.init()`. Your extension content will not be displayed until you have notified the host frame that you are ready. There are two options for doing this: | ||
| ```json | ||
| { | ||
| "files": [{ | ||
| "path": "node_modules/azure-devops-extension-sdk/lib", | ||
| "addressable": true, | ||
| "packagePath": "lib" | ||
| }] | ||
| } | ||
| ``` | ||
| 1. Call `SDK.init()` with no `loaded` option | ||
| 2. Call `SDK.init({ loaded: false })` to start initializing the SDK. Then call `SDK.notifyLoadSucceeded()` once you have finished your initial rendering. This allows you to make other SDK calls while your content is still loading (and hidden behind a spinner). | ||
| 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"`) | ||
| Example: | ||
| ```typescript | ||
| import * as SDK from "azure-devops-extension-sdk"; | ||
| ## Use the SDK | ||
| SDK.init(); | ||
| ``` | ||
| From your web extension's HTML page, include and initialize the DevOps SDK like this: | ||
| ```html | ||
| <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> | ||
| ``` | ||
| ## API | ||
| Full API reference of DevOps.SDK.js can be found at [Core Client SDK](https://docs.microsoft.com/en-us/azure/devops/extend/reference/client/core-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](https://www.typescriptlang.org) 2.5 or later project: | ||
| * Set `"moduleResolution": "node"` in your `tsconfig.json` project file | ||
| See [TypeScript Module Resolution](https://www.typescriptlang.org/docs/handbook/module-resolution.html) for more details. | ||
| Alternatively, you can explicitly reference the types at the top of your TypeScript file(s): | ||
| ```ts | ||
| /// <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. | ||
| ```json | ||
| { | ||
| "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](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html). | ||
| Learn more about [tsconfig.json](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html) | ||
| ### NPM package manifest (`package.json`) | ||
| Declares the libraries (like the azure-devops-extension-sdk) required to compile, package, and use your extension. | ||
| ```js | ||
| { | ||
| /* 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](https://docs.npmjs.com/files/package.json) | ||
| ### Extension manifest (`vss-extension.json`) | ||
| ```js | ||
| { | ||
| /* 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](https://www.visualstudio.com/docs/integrate/extensions/develop/manifest). | ||
| ### HTML page | ||
| ```html | ||
| <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](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Worsened metrics
- Total package byte prevSize
- decreased by-7.97%
65958
- Number of lines in readme file
- decreased by-80.83%
46
No dependency changes