开发 Web 扩展

项目
08/16/2022

Azure DevOps Services |Azure DevOps Server 2022 |Azure DevOps Server 2020 |Azure DevOps Server 2019 |TFS 2018

使用扩展通过新的 Web 体验、仪表板小组件、生成任务等增强 Azure DevOps。可以使用 HTML、JavaScript 和 CSS 等标准技术开发扩展。它们打包并发布到 Visual Studio 市场，然后可以安装到组织中。

提示

使用 Azure DevOps 扩展 SDK 查看有关扩展开发的最新文档。

本教程将指导你创建第一个 Web 扩展，其中包括以下任务。

安装所需的工具
读取扩展的本地目录
创建扩展清单文件和中心贡献
打包扩展并将其发布到市场
在组织中测试扩展

需要帮助? 将问题发布到Azure DevOps Services 开发者社区。

先决条件

必须具有以下权限和安装。

你是组织所有者。如果没有组织，可以免费创建组织。
安装 Node.js。
通过从命令提示符运行 npm install -g tfx-cli ， (TFX) 安装扩展打包工具。

创建目录和清单

扩展由一组包含所需清单文件的文件组成。将其打包到 .vsix 文件中并发布到 Visual Studio Marketplace。

创建一个目录来保存扩展所需的文件：
```
mkdir my-first-extension
```
在此目录中，初始化新的 NPM 包清单：
```
npm init -y
```
此文件介绍扩展所需的库。
安装 Microsoft VSS Web 扩展 SDK 包并将其保存到 NPM 包清单：
```
npm install vss-web-extension-sdk --save
```
此 SDK 包含一个 JavaScript 库，该库提供与扩展嵌入的页面通信所需的 API。

使用以下内容在扩展目录的根目录中创建一 vss-extension.json 个名为的扩展清单文件：

{
    "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/vss-web-extension-sdk/lib",
            "addressable": true,
            "packagePath": "lib"
        }
    ]
}

注意

该 public 属性控制扩展是否对 Visual Studio Marketplace 上的每个人可见。在开发过程中使扩展保持私密。

使用以下内容在扩展目录的根目录中创建一 my-hub.html 个名为的文件，该文件适用于视图 (也称为中心) 参与 Web 体验。

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <script src="lib/VSS.SDK.min.js"></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>
    <script type="text/javascript">
        VSS.init();
        VSS.ready(function() {
            document.getElementById("name").innerText = VSS.getWebContext().user.name;
        });
    </script>
</head>
<body>        
    <h1>Hello, <span id="name"></span></h1>
</body>
</html>

扩展目录应类似于以下示例。

|-- my-hub.html
|-- node_modules
    |-- @types
    |-- vss-web-extension-sdk
|-- package.json
|-- vss-extension.json

现在可以打包、发布和测试扩展。

打包和发布扩展

创建发布者

所有扩展（包括来自 Microsoft 的扩展）都在发布者下。任何人都可以创建发布者并在其下发布扩展。如果团队正在开发扩展，还可以向其他人授予对发布者的访问权限。

登录到 Visual Studio Marketplace 管理门户。
如果还没有发布者，系统会提示你创建一个发布服务器。
在“创建发布服务器”窗体中，在发布者名称字段中输入姓名。 ID 字段应根据名称自动设置：

注意

记下 ID。需要在扩展的清单文件中设置它。

现在，你已准备好打包扩展并将 (上传) 发布到市场。将此浏览器窗口保持打开状态，因为打包扩展后将返回此处。

打包扩展

(打开扩展清单文件) vss-extension.json 并将字段的值 publisher 设置为发布者的 ID。例如：
```
{
    ...
    "id": "my-first-extension",
    "publisher": "AnnetteNielsen",
    ...
}
```
VSS Web 扩展 SDK 需要 TFX。如果尚未安装，请打开命令提示符并运行以下命令。
```
npm install -g tfx-cli
```

在命令提示符下，从扩展目录运行 TFX 工具的打包命令。

npx tfx-cli extension create

完成后，会看到一条消息，指示扩展已成功打包：

=== Completed operation: create extension ===
- VSIX: C:\my-first-extension\AnnetteNielsen.my-first-extension-1.0.0.vsix
- Extension ID: my-first-extension
- Extension Version: 1.0.0
- Publisher: AnnetteNielsen

上传扩展

从管理门户中，从页面顶部的下拉列表中选择发布者。
选择 “新建扩展”，然后选择 “Azure DevOps”。
拖放文件或选择该文件以查找在上一打包步骤中创建的 VSIX 文件，然后选择 “上传”。

几秒钟后，扩展会显示在已发布的扩展列表中。别担心，扩展仅对你可见。

安装扩展

若要测试扩展，必须将其安装到 Azure DevOps 中的组织。安装需要是组织所有者 (或拥有) 所需的权限。由于扩展是专用的，因此必须先将其与要安装到的组织共享。

从管理门户中，从列表中选择扩展，右键单击，然后选择 “共享/取消共享” 或“ 发布/取消发布”，具体取决于扩展：Share = 发布和取消共享 = 取消发布。
选择 “组织”，然后输入组织的名称。选择 Enter。
关闭面板。

现在可以将此扩展安装到此组织中。
在市场中，选择扩展以打开其概述页。

注意

由于扩展是专用的，因此只有你和它与之共享的组织的任何成员才能看到此页面。

选择“ 免费获取 ”以启动安装过程。从下拉菜单中选择你与该扩展共享的组织。
选择“安装” 。

祝贺你！扩展现已安装到组织中，并已准备好进行测试。

试用扩展

扩展为项目级代码区域贡献了一个名为“My Hub”的视图。让我们导航到它。

在安装向导结束时，选择“ 继续到组织 ”，导航到安装扩展的组织的主页， () https://dev.azure.com/{organization} 。

选择要导航到其中的任何项目：

如果组织中没有任何项目，系统会提示创建一个项目。
导航到“代码”区域，然后导航到扩展 (“我的中心 ”) 参与的中心：

选择 “组织设置”，然后选择“ 扩展 ”以查看新安装的扩展。

提示

安装扩展后，请确保刷新浏览器。应会在左侧窗格中的主中心（已将扩展添加到）的左窗格中看到新的扩展中心。如果未看到新的扩展中心，请将此问题发布到Azure DevOps Services 开发者社区。

调试扩展

若要使用 Visual Studio 或浏览器开发人员工具调试扩展，并在每次更改源代码时重新部署扩展即可加快开发速度，需要更改清单添加 baseUri 属性：

{
    ...
    "baseUri": "https://localhost:44300",
    ...
}

更改清单会从本地 Web 服务器实例加载扩展。例如，Visual Studio 中的 IISExpress。更改清单后，仅部署并安装此调试扩展一次。

注意

在 SSL 模式下运行本地 Web 服务器，因为 Azure DevOps 要求从安全源提供网页，否则你在扩展 IFRAME 加载期间在浏览器控制台中获取错误。

后续步骤

浏览扩展示例