|
1 | | -# Azure DevOps Web Sample Extension |
| 1 | +[](https://dev.azure.com/gabrielbourgault/Kiosoft/_build/latest?definitionId=23&branchName=master) |
2 | 2 |
|
3 | | -[](https://dev.azure.com/ms/azure-devops-extension-sample/_build/latest?definitionId=14) |
| 3 | +# AzureDevOps.InnerSource :star2: - Extension |
4 | 4 |
|
5 | | -This repository generates an [Azure DevOps extension](https://docs.microsoft.com/en-us/azure/devops/extend/overview?view=vsts) containing a number of different contributions of various types. |
| 5 | +The extension was started from this ReactJS sample: https://github.com/microsoft/azure-devops-extension-sample |
6 | 6 |
|
7 | | -## Dependencies |
| 7 | +This sample is also interesting for hot reloading: https://github.com/microsoft/azure-devops-extension-hot-reload-and-debug |
8 | 8 |
|
9 | | -The sample repository depends on a few Azure DevOps packages: |
| 9 | +Icon list: https://learn.microsoft.com/en-us/windows/apps/design/style/segoe-ui-symbol-font & https://uifabricicons.azurewebsites.net/ |
10 | 10 |
|
11 | | -- [azure-devops-extension-sdk](https://github.com/Microsoft/azure-devops-extension-sdk): Required module for Azure DevOps extensions which allows communication between the host page and the extension iframe. |
12 | | -- [azure-devops-extension-api](https://github.com/Microsoft/azure-devops-extension-api): Contains REST client libraries for the various Azure DevOps feature areas. |
13 | | -- [azure-devops-ui](https://developer.microsoft.com/azure-devops): UI library containing the React components used in the Azure DevOps web UI. |
| 11 | +Extension manifest: https://learn.microsoft.com/en-us/azure/devops/extend/develop/manifest?view=azure-devops#scopes |
14 | 12 |
|
15 | | -Some external dependencies: |
| 13 | +Extensibility points (partial): https://learn.microsoft.com/en-us/azure/devops/extend/reference/targets/overview?view=azure-devops |
16 | 14 |
|
17 | | -- `React` - Is used to render the UI in the samples, and is a dependency of `azure-devops-ui`. |
18 | | -- `TypeScript` - Samples are written in TypeScript and compiled to JavaScript |
19 | | -- `SASS` - Extension samples are styled using SASS (which is compiled to CSS and delivered in webpack js bundles). |
20 | | -- `webpack` - Is used to gather dependencies into a single javascript bundle for each sample. |
21 | | - |
22 | | -## Building the sample project |
23 | | - |
24 | | -Just run: |
25 | | - |
26 | | - npm run build |
27 | | - |
28 | | -This produces a .vsix file which can be uploaded to the [Visual Studio Marketplace](https://marketplace.visualstudio.com/azuredevops) |
29 | | - |
30 | | -## Using the extension |
31 | | - |
32 | | -The preferred way to get started is to use the `tfx extension init` command which will clone from this sample and prompt you for replacement information (like your publisher id). Just run: |
33 | | - |
34 | | - npm install -g tfx-cli |
35 | | - tfx extension init |
36 | | - |
37 | | -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](https://docs.microsoft.com/en-us/azure/devops/extend/publish/overview?view=vsts) for setting up your own publisher and publishing an extension. |
38 | | - |
39 | | -# Samples |
40 | | - |
41 | | -Individual sample contributions are self-contained folders under `./src/Samples`. Within each sample you will find: |
42 | | - |
43 | | -1. `{SampleName}.json` - describes the contribution objects being added to Azure DevOps |
44 | | -2. `{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 of `root`. |
45 | | -3. `{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 single `js` file with this content and all its dependencies. |
46 | | -4. `{SampleName}.scss` - optional sass file containing the styles (CSS) for the UI |
47 | | -5. Additional ts/tsx files - For samples that are too big for one file, the code will be broken up appropriately |
48 | | - |
49 | | -## BreadcrumbService |
50 | | - |
51 | | -This sample adds a breadcrumb service which adds a "Sample Breadcrumb Item" global breadcrumb item to the sample hub. Visit the "Sample Hub" in the `Pipelines` hub group to see this item. |
52 | | - |
53 | | -## CodeEditorContribution |
54 | | - |
55 | | -This sample adds a language definition and a JSON schema for the code editor. |
56 | | - |
57 | | -To see the language definition in action, add a new file to git or TFVC called "sample.mylog", then copy the example log content from [the Monaco playground](https://microsoft.github.io/monaco-editor/playground.html#extending-language-services-custom-languages). |
58 | | - |
59 | | -To see the JSON schema in action, add a new file to git or TFVC called "myconfig.json", then begin editing it. |
60 | | - |
61 | | -## Feature |
62 | | - |
63 | | -This sample shows how to hook into the Preview Features panel (under the user profile menu). It adds a simple hub that is only shown when an "ABC" feature is turned on. The feature can be toggled per-user or per-organization. |
64 | | - |
65 | | -This also defines a second feature (ABC v2) which controls whether v1 or v2 of the ABC hub is used (when the ABC feature is turned on). When enabled, a "property-provider" contribution modifies the name and url of the hub contribution. Here we add a v2=true query parameter to our existing hub page, but you could also |
66 | | -specify a completely different html page here. This feature shows off a bit more advanced functionality provided by preview features. It can be toggled per-user, per-project, or per-organization (the "null" hostScopeValue). It is on by default (defaultState: true). And it has an override rule which causes the v2 feature to be OFF (and disabled in the preview features panel) whenever the ABC feature is off. |
67 | | - |
68 | | -## Hub |
69 | | - |
70 | | -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. |
71 | | - |
72 | | -The hub uses a Pivot component to draw 4 different tabs: |
73 | | - |
74 | | -1. An `Overview` tab contains some simple details about the current user and project |
75 | | -2. A `Navigation` tab contains a few actions that allow you to integrate with the page's URL and title |
76 | | -3. An `Extension Data` tab demonstrates reading and writing to the extension data service |
77 | | -4. A `Messages` tab shows how to display global messages |
78 | | - |
79 | | -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). |
80 | | - |
81 | | -## Menu |
82 | | - |
83 | | -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. |
84 | | - |
85 | | -## Panel |
86 | | - |
87 | | -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. |
88 | | - |
89 | | -## Pivot |
90 | | - |
91 | | -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". |
92 | | - |
93 | | -This pivot makes a REST call for all the projects in the organization and it displays them in a grid view. |
94 | | - |
95 | | -## Pill |
96 | | - |
97 | | -This sample adds pills to the title of the Pipeline definition (Runs) page. |
98 | | - |
99 | | -## QueryParamsHandler |
100 | | - |
101 | | -This sample adds a service that gets loaded on any page whenever a "showMyPanel" query parameter is present |
102 | | -in the URL when any page is loaded. The startup service shows the custom panel from the Panel sample, using |
103 | | -an optional "myPanelTitle" query parameter as the panel title. |
104 | | - |
105 | | -## RepositoryActions |
106 | | - |
107 | | -This sample adds a "Sample repository action" menu item to the repository picker in the header of code hub pages. If a "href" property is provided, clicking on the action will navigate to the given url. If a "uri" is provided, that code will be executed when the action is clicked. |
108 | | - |
109 | | -## RepositoryServiceHub |
110 | | - |
111 | | -This sample adds a "Repository Information" hub to the `Code` hub group. It demonstrates how to interact with the `IVersionControlRepositoryService` to obtain basic information about a user's currently selected Git repository. |
112 | | - |
113 | | -## WorkItemFormGroup |
114 | | - |
115 | | -This sample adds a "Sample WorkItem Form Group" extension to workitem form to show how to interact with the `IWorkItemFormService` service and `IWorkItemNotificationListener`. It gives UI to show case how to change field values using the form service and displaying workitem form notification events. |
116 | | - |
117 | | -This sample also provides a unit testing example with minimal necessary mocks. |
118 | | - |
119 | | -## WorkItemOpen |
120 | | - |
121 | | -This sample adds a "Sample WorkItem Open" hub to the Boards hub group to show how to interact with the `IWorkItemFormNavigationService` service. It gives UI for you to open an existing work item (by id) or open the work item form for a new work item (by work item type). Either of these options open a dialog in the host frame. |
122 | | - |
123 | | -# References |
124 | | - |
125 | | -The full set of documentation for developing extensions can be found at [https://docs.microsoft.com/en-us/azure/devops/extend](https://docs.microsoft.com/en-us/azure/devops/extend/?view=vsts). |
126 | | - |
127 | | -# Contributing |
128 | | - |
129 | | -This project welcomes contributions and suggestions. Most contributions require you to agree to a |
130 | | -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us |
131 | | -the rights to use your contribution. For details, visit <https://cla.microsoft.com>. |
132 | | - |
133 | | -When you submit a pull request, a CLA-bot will automatically determine whether you need to provide |
134 | | -a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions |
135 | | -provided by the bot. You will only need to do this once across all repos using our CLA. |
136 | | - |
137 | | -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). |
138 | | -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or |
139 | | -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
| 15 | +## Known issues |
| 16 | +- There is an issue with unit tests, that has the same symptoms as this: https://github.com/nrwl/nx/issues/812 |
0 commit comments