Azure DevOps Web Sample Extension
This repository generates an Azure DevOps extension containing a number of different contributions of various types.
Dependencies
The sample repository depends on a few Azure DevOps packages:
- azure-devops-extension-sdk: Required module for Azure DevOps extensions which allows communication between the host page and the extension iframe.
- azure-devops-extension-api: Contains REST client libraries for the various Azure DevOps feature areas.
- azure-devops-ui: UI library containing the React components used in the Azure DevOps web UI.
Some external dependencies:
React
- Is used to render the UI in the samples, and is a dependency ofazure-devops-ui
.TypeScript
- Samples are written in TypeScript and complied to JavaScriptSASS
- Extension samples are styled using SASS (which is compiled to CSS and delivered in webpack js bundles).webpack
- Is used to gather dependencies into a single javascript bundle for each sample.
Building the sample project
Just run:
npm run build
This produces a .vsix file which can be uploaded to the Visual Studio Marketplace
Using the extension
The preferred way to get started is to use the tfx init
command which will clone from this sample and prompt you for replacement information (like your publisher id). Just run:
npm install -g tfx-cli
tfx init
You can also clone the sample project and change the publisher
property in azure-devops-extension.json
to your own Marketplace publisher id. Refer to the online documentation for setting up your own publisher and publishing an extension.
Samples
Individual sample contributions are self-contained folders under ./src/Pages
. Within each sample you will find:
{SampleName}.json
- describes the contribution objects being added to Azure DevOps{SampleName}.html
- page which is rendered within an iframe on the appropriate Azure DevOps page or pages. It may be visible UI (such as a Hub) or a background iframe (such as a Menu action handler). This will include a sample reference for{SampleName}.js
, and for visible frames it will contain a single<div>
element with an id ofroot
.{SampleName}.ts(x)
- Root script that is run when the frame is loaded. A webpack entry is added for this file which will generate a singlejs
file with this content and all its dependencies.{SampleName}.scss
- optional sass file containing the styles (CSS) for the UI- Additional ts/tsx files - For samples that are too big for one file, the code will be broken up appropriately
Hub
This sample adds a hub named "Sample Hub" into the Pipelines
hub group. If you visit a project-level page, you will find Sample Hub under the Pipelines
navigation element in the vertical navigation menu on the left of the page.
The hub uses a Pivot component to draw 4 different tabs:
- An
Overview
tab contains some simple details about the current user and project - A
Navigation
tab contains a few actions that allow you to integrate with the page's URL and title - An
Extension Data
tab demonstrates reading and writing to the extension data service - A
Messages
tab shows how to display global messages
There are also actions at the top-right of the hub which demonstrate opening dialogs and panels, including custom content within them (used in the Panel
sample).
Pivot
This sample adds a "Sample Pivot" pivot (tab) to the Organization (Project Collection) home page, next to "Projects", "My work items", and "My pull requests".
This pivot makes a REST call for all the projects in the organization and it displays them in a grid view.
Menu
This sample adds a "Sample build definition menu item" to the Builds
hub in the dropdown actions menu in the top-right of the page. The menu handler gets the current build definition from the context that is passed to it, it makes a REST call, and shows the result in a message box.
Panel
This sample is leveraged within the Hub
sample. It is content that contains a toggle button along with OK/Cancel buttons. It can be used as custom panel or dialog content.
References
The full set of documentation for developing extensions can be found at https://docs.microsoft.com/en-us/azure/devops/extend.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.