扩展清单参考

  • 项目

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

每个扩展都有一个 JSON 清单文件，用于定义有关该扩展的基本信息。 该文件还定义了如何扩展和增强体验。 本文介绍如何为扩展创建到 Azure DevOps 的清单。

提示

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

创建一个在扩展文件夹的根目录下命名 vss-extension.json 的文件。 此文件包含所需的属性，如扩展的 ID 及其安装目标，可在其中运行。 它还定义扩展所做出的贡献。

请参阅典型清单的以下示例：

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "categories": [
        "Azure Boards"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "content": {
        "details": {
            "path": "readme.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ],
    "files": [
        {
            "path": "launch.html",
            "addressable": true
        },        
        {
            "path": "node_modules/vss-web-extension-sdk/lib",
            "addressable": true,
            "packagePath": "lib"
        }
    ]
}

必需属性

这些属性是必需的：

properties 说明 说明
manifestVersion 对应于清单格式版本的数字。 应为 1。
ID 扩展的标识符。 此 ID 是一个字符串，在来自同一发布服务器的扩展之间必须是唯一的。 它必须以字母或数字字符开头，并通过“Z”、“a”到“z”、“0”到“9”和“-”（连字符）包含“A”。 示例：sample-extension。
version 指定扩展版本的字符串。 应采用格式 major.minor.patch，例如 0.1.2 或 1.0.0。 还可以为以下格式添加第四个数字： 0.1.2.3
name 扩展的简短、可读名称。 限制为 200 个字符。 示例："Fabrikam Agile Board Extension"。
publisher 发布者的标识符。 此标识符必须与发布扩展的标识符匹配。 请参阅 “创建和管理发布者”。
类别 表示扩展所属类别的字符串数组。 必须至少提供一个类别，并且没有限制可以包含的类别数。 有效值：Azure Repos、、Azure PipelinesAzure Boards、Azure Test Plans和Azure Artifacts。

注意：
    - 如果要以编程方式发布扩展，请使用 tfx-cli 的版本 >=0.6.3。
    - 如果使用 Azure DevOps 扩展任务扩展 发布，请确保其版本为 >1.2.8。 由于最近的范围更改，可能需要批准扩展更新。
    - 以前提及的类别在 Visual Studio Marketplace 和 Azure DevOps Server 2019 及更高版本中本机存在。 对于面向早期版本的 TFS 的扩展：
      - 如果 TFS 客户在连接的上下文中通过 Visual Studio Marketplace（而不是本地库）获取扩展，则使用前面所述的类别。
      - 如果要直接（即不是通过 Visual Studio Marketplace）与使用 TFS <=2018 的客户共享扩展，请改用以下类别：代码、计划和跟踪、生成和发布、测试、协作和集成。 如果需要通过 Visual Studio Marketplace 直接与 TFS <= 2018 客户共享，则需要有 2 个扩展包。
目标 集成或扩展支持的产品和服务。 有关详细信息，请参阅 安装目标。 一个对象数组，其中每个对象都有一个 id 字段，指示下列值之一：
    - Microsoft.VisualStudio.Services（适用于 Azure DevOps 或 TFS 的扩展）、
    - Microsoft.TeamFoundation.Server（适用于 TFS 的扩展）、（适用于 Azure DevOps 或 TFS 的集成）、Microsoft.VisualStudio.Services.IntegrationMicrosoft.TeamFoundation.Server.Integration
    -
    - （适用于 TFS 的集成）

所需属性的示例

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

可选属性

运行时属性

properties 说明 说明
scopes 授权范围（字符串）数组，其中列出了扩展所需的权限。 例如， vso.work 并 vs.code_write 指示扩展需要对工作项具有只读访问权限，以及对源代码（和相关资源）的读/写访问权限。 安装扩展时向用户显示范围。 有关详细信息，请参阅 范围的完整列表。
要求 一系列需求（字符串），其中列出了扩展所需的功能。 例如， api-version/3.0 指示扩展使用版本 3.0 API，因此无法在不支持此版本的旧产品中运行。 有关详细信息，请参阅 需求的完整列表。
baseUri （可选）扩展贡献指定的所有相对 URL 的基 URL。 例如：https://myapp.com/{{account.name}}/。 如果扩展的内容与扩展一起打包，则此属性应留空。
贡献 对系统的贡献数组。
contributionTypes 扩展定义的贡献类型的数组 
{
    "scopes": [
        "vso.work",
        "vso.code_write",
        "vso.build_execute"
    ],
    "demands": [
        "api-version/3.0"
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}

发现属性

这些可选属性可帮助用户发现并了解扩展：

properties 说明 说明
说明 描述扩展的几个句子。 限制为 200 个字符。 描述应该是扩展的“电梯间距”-几个行来描述你的扩展在市场中，并让人们想要安装它。 请参阅以下示例
图标 表示扩展的图标字典。 有效密钥： default BMP、GIF、EXIF、JPG、PNG 和 TIFF 类型（128x128 像素）。 将来可能支持其他键，例如 large （512x512 像素）。 每个键的值是扩展中图标文件的路径
tags 用于帮助用户查找扩展的字符串标记数组。 示例： agile、 project management、 task timer等等。
截图 无法包含在内容中的图像数组。 在内容中特别推荐时，屏幕截图更有价值，应该使用它来帮助为扩展创建高质量的市场详细信息页面。 对于内容中未特别推荐的不太重要的图像，请使用屏幕截图。 每个图像应为 1366x768 像素。 path每个项是扩展名中文件的路径。
content 描述用户扩展的内容文件的字典。 每个 扩展都应包括实心内容。 这是你将如何向用户显示扩展可以执行的操作。 使其丰富、易耗，并在必要时包括屏幕截图。 overview.md将文件作为基本内容块包含。 每个文件都假定采用 GitHub 风格 Markdown 格式。 path每个项是扩展名中 Markdown 文件的路径。 有效键： details. 将来可能支持其他密钥。
链路 帮助用户详细了解扩展、获取支持和移动的链接字典。 有效密钥： getstarted - 第一步，如何设置或使用。 learn - 更深入的内容，帮助用户更好地了解扩展或服务。 license - 最终用户许可协议。 privacypolicy - 扩展的隐私策略。 support - 获取扩展的帮助和支持。 每个键的值是一个 uri 具有字段的对象，该字段是链接的绝对 URL
存储库 描述扩展源代码存储库的属性字典 有效密钥： type - 存储库的类型。 示例： git。 uri - 存储库的绝对 URL。
徽章 来自 已批准的锁屏提醒网站中的外部元数据锁屏提醒（如 TravisCI、Appveyor 等）的链接数组 有效密钥： href - 在选择锁屏提醒时，用户导航到该链接。 uri - 要显示的锁屏提醒图像的绝对 URL。 description - 在悬停时显示的锁屏提醒说明。
品牌 与品牌相关的属性的字典。 有效键： color - 扩展或发布者的主要颜色;可以是十六进制（#ff00ff）、RGB（rgb（100,200,50）或支持的 HTML 颜色名称（蓝色）。 theme- 补充颜色;将深色用于深色品牌颜色，或浅色品牌颜色。

标记扩展公共

默认情况下，Azure DevOps 市场中的所有扩展都是专用的。 它们仅对发布者共享的发布者和帐户可见。 如果发布者已验证，可以通过在扩展清单中设置 Public 标志来公开扩展：

{
    "galleryFlags": [
        "Public"
    ]
}

或：

{
    "public": true
}

有关详细信息，请参阅 包/发布/安装。

将扩展标记为预览版

如果你的扩展已准备好供市场用户尝试，但仍要处理一些 bug 或添加函数，则可以将其 preview标记为：

{
    "galleryFlags": [
        "Preview"
    ]
}

将扩展标记为付费预览版

如果打算在市场中销售扩展，请将其标记为 付费预览版。 标记为 免费 扩展的扩展不能更改为 付费。

{
    "galleryFlags": [
        "Paid",
        "Preview"
    ]
}

将延期标记为付费

如果要在市场中销售扩展，可以使用标志和__BYOLENFORCED标记标记对其进行Paid标记（以两个下划线开头）：

{
    "galleryFlags": [
        "Paid"        
    ],
     "tags": [        
        "__BYOLENFORCED"
    ]
}

Paid标志和__BYOLENFORCED标记都需要存在，才能将扩展标记为在市场中付费。 自带许可（BYOL）是指扩展的发布者提供扩展的计费和许可机制，因为 Microsoft 不提供 Azure DevOps 扩展的计费和许可机制。 所有付费扩展都需要定义隐私策略、支持策略和最终用户许可协议。 此外，发布者必须提供市场中定价选项卡的内容，如下所示：

{
    "content": {
        "details": {
            "path": "overview.md"
        }, 
        "pricing": {
            "path": "pricing.md"
        }
    }
}

还需要在扩展清单中添加一个新部分来替代付费许可。 将来，我们将删除付费许可检查，不再需要替代。 目前，请确保扩展按预期显示。 每个替代都包含一个“ID”和一个“行为”。 “ID”必须与清单中定义的贡献的 ID 匹配。

"licensing": {

      "overrides": [

        { "id": "my-hub", "behavior": " AlwaysInclude" }
      ]
    }

如果你的付费 BYOL 扩展提供试用期（我们建议这样做），则可以指定试用期（以天为单位）：

{
    "galleryproperties": {
        "trialDays": "30"
    } 
}

注意

如果要面向 Azure DevOps，但不希望显示 扩展的“下载 ”选项，请将标记（以两个下划线开头）添加到 __DoNotDownload 扩展清单。 如果要将扩展从以前提供的计费和许可从 Microsoft 移动到 BYOL 模型，请与我们联系以获取合适的步骤。

更多属性的示例

{
    "description": "Awesome tools to help you and your team do great things everyday.",
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "license-terms.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/tools"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ]
}

详细信息页示例

  • 1 - 说明
  • 2 - 图标
  • 3 - 类别
  • 4 - 屏幕截图
  • 5 - 内容（详细信息）
  • 6 - 链接
  • 7 - 品牌打造

card

市场问答 - CustomerQnASupport 属性

Visual Studio Marketplace 上的所有扩展都有一个 Q&A 部分，用于允许扩展用户和发布者之间的一对一公共对话。 发布者可以在市场 Q&A、GitHub 问题或自定义 Q&A URL 之间进行选择。 可以使用清单中的 CustomerQnASupport 属性在市场中禁用 Q&A。

默认体验 （无需更改清单）

  • 对于 GitHub 存储库的扩展，市场会将 Q&A 部分中的用户重定向到关联的 GitHub 问题。
  • 对于没有 GitHub 存储库的扩展，已启用市场 Q&A。

对于与默认选项之一不同的体验，请使用 清单中的 CustomerQnASupport 属性。

{
    "CustomerQnASupport": {
        "enablemarketplaceqna": true,
        "url": "http://uservoice.visualstudio.com"
    } 
}

属性

“客户问答支持”部分的属性：

  • enablemarketplaceqna - 布尔字段，对于市场设置为 true 或自定义 Q&A;如果禁用 Q&A，则为 false
  • url - 字符串，自定义 Q&A 的 URL

显示 Q & A 支持使用情况的示例

示例：使用自定义 Q & A 的扩展

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true",
        "url": "http://uservoice.visualstudio.com"
    } 
}

示例：使用 GitHub 存储库进行扩展，但使用市场 Q & A 而不是 GitHub 问题

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"true"
    } 
}

示例：扩展禁用 Q & A 部分

{
     "CustomerQnASupport": {
        "enablemarketplaceqna":"false"
    } 
}

作用域

在扩展中，可以定义一个或多个范围。 这些范围确定扩展可以访问哪些资源以及允许对这些资源执行的操作。 在扩展清单中指定的作用域是在颁发给扩展的访问令牌上设置的范围。 有关详细信息，请参阅 身份验证和安全性。

如果未指定任何范围，则仅提供对用户配置文件和扩展数据的访问权限。

支持的范围

类别 范围 名称 描述
代理池 vso.agentpools 代理池（读取） 授予查看代理的任务、池、队列、代理以及当前正在运行或最近完成的作业的功能。
vso.agentpools_manage 代理池（读取、管理） 授予管理池、队列和代理的能力。
vso.environment_manage 环境（读取、管理） 授予管理池、队列、代理和环境的能力。
分析 vso.analytics 分析（读取） 授予查询分析数据的能力。
审核 vso.auditlog 审核日志 （读取） 授予向用户读取审核日志的功能。
vso.auditstreams_manage 审核流 （读取） 向用户授予管理审核流的能力。
生成 vso.build 生成(读取) 授予访问生成项目（包括生成结果、定义和请求）的能力，以及通过服务挂钩接收有关生成事件的通知的能力。
vso.build_execute 生成（读取和执行） 授予访问生成项目（包括生成结果、定义和请求）以及排队生成、更新生成属性的功能，以及通过服务挂钩接收有关生成事件的通知的能力。
代码 vso.code 代码(读取) 授予读取有关提交、更改集、分支和其他版本控制项目的源代码和元数据的能力。 此外，还可以通过服务挂钩搜索代码并获取有关版本控制事件的通知。
vso.code_write 代码（读取和写入） 授予读取、更新和删除源代码、访问有关提交、更改集、分支和其他版本控制项目的元数据的能力。 此外，还授予创建和管理拉取请求和代码评审以及通过服务挂钩接收有关版本控制事件的通知的能力。
vso.code_manage 代码（读取、写入和管理） 授予读取、更新和删除源代码、访问有关提交、更改集、分支和其他版本控制项目的元数据的能力。 此外，还授予创建和管理代码存储库、创建和管理拉取请求和代码评审以及通过服务挂钩接收有关版本控制事件的通知的能力。
vso.code_full 代码（完整） 授予对源代码、有关提交、更改集、分支和其他版本控制项目的完全访问权限。 此外，还授予创建和管理代码存储库、创建和管理拉取请求和代码评审以及通过服务挂钩接收有关版本控制事件的通知的能力。 还包括对客户端 OM API 的有限支持。
vso.code_status 代码（状态） 授予读取和写入提交和拉取请求状态的能力。
连接服务器 vso.connected_server 已连接的服务器 授予从本地连接服务器访问所需的终结点的能力。
权利 vso.entitlements 权利（阅读） 提供对许可权利终结点的只读访问权限，以获取帐户权利。
vso.memberentitlementmanagement MemberEntitlement Management （读取） 授予读取用户、其许可证以及可以访问的项目和扩展的能力。
vso.memberentitlementmanagement_write MemberEntitlement Management （write） 授予管理用户、其许可证以及可以访问的项目和扩展的能力。
扩展 vso.extension 扩展（读取） 授予读取已安装扩展的功能。
vso.extension_manage 扩展（读取和管理） 授予对已安装扩展进行安装、卸载和执行其他管理操作的功能。
vso.extension.data 扩展数据（读取） 授予读取已安装扩展存储的数据（设置和文档）的能力。
vso.extension.data_write 扩展数据（读取和写入） 授予读取和写入已安装扩展存储的数据（设置和文档）的能力。
Graph 和标识 vso.graph 图形（读取） 授予读取用户、组、范围和组成员身份信息的能力。
vso.graph_manage Graph （管理） 授予读取用户、组、范围和组成员身份信息以及添加用户、组和管理组成员身份的功能。
vso.identity 标识(读取) 授予读取标识和组的能力。
vso.identity_manage 标识（管理） 授予读取、写入和管理标识和组的能力。
计算机组 vso.machinegroup_manage 部署组（读取、管理） 提供管理部署组和代理池的功能。
市场 vso.gallery 市场 授予对公共和私有项和发布者的读取访问权限。
vso.gallery_acquire 市场 （获取） 授予读取访问权限和获取项的能力。
vso.gallery_publish 市场（发布） 授予读取访问权限以及上传、更新和共享项的能力。
vso.gallery_manage 市场（管理） 授予读取访问权限以及发布和管理项和发布者的能力。
通知 vso.notification 通知（已读） 提供对订阅和事件元数据的读取访问权限，包括可筛选字段值。
vso.notification_write 通知（写入） 提供对订阅的读取和写入访问权限，以及对事件元数据的读取访问权限，包括可筛选字段值。
vso.notification_manage 通知（管理） 提供对订阅的读取、写入和管理访问权限，以及对事件元数据的读取访问权限，包括可筛选字段值。
vso.notification_diagnostics 通知（诊断） 提供对通知相关的诊断日志的访问权限，并提供为单个订阅启用诊断的功能。
打包 vso.packaging 打包（读取） 授予读取源和包的能力。
vso.packaging_write 打包（读取和写入） 授予创建和读取源和包的能力。
vso.packaging_manage 打包（读取、写入和管理） 授予创建、读取、更新和删除源和包的功能。
管道资源 vso.pipelineresources_use 管道资源（使用） 授予批准管道使用受保护资源的请求的功能：代理池、环境、队列、存储库、安全文件、服务连接和变量组。
vso.pipelineresources_manage 管道资源（使用和管理） 授予管理受保护资源或管道使用受保护资源的请求的能力：代理池、环境、队列、存储库、安全文件、服务连接和变量组。
项目和团队 vso.project 项目和团队(读取) 授予读取项目和团队的能力。
vso.project_write 项目和团队（读取和写入） 授予读取和更新项目和团队的能力。
vso.project_manage 项目和团队（读取、写入和管理） 授予创建、读取、更新和删除项目和团队的能力。
版本 vso.release 发布（阅读） 授予读取发布项目（包括发布、发布定义和发布环境）的能力。
vso.release_execute 发布（读取、写入和执行） 授予读取和更新发布项目的功能，包括发布、发布定义和发布环境，以及对新版本进行排队的能力。
vso.release_manage 发布（读取、写入、执行和管理） 授予读取、更新和删除发布项目（包括发布、发布定义和发布环境）以及排队和批准新版本的功能。
保护文件 vso.securefiles_read 安全文件 （读取） 授予读取安全文件的能力。
vso.securefiles_write 安全文件（读取、创建） 授予读取和创建安全文件的能力。
vso.securefiles_manage 安全文件（读取、创建和管理） 授予读取、创建和管理安全文件的能力。
安全性 vso.security_manage 安全性（管理） 授予读取、写入和管理安全权限的能力。
服务连接 vso.serviceendpoint 服务终结点（读取） 授予读取服务终结点的能力。
vso.serviceendpoint_query 服务终结点（读取和查询） 授予读取和查询服务终结点的能力。
vso.serviceendpoint_manage 服务终结点（读取、查询和管理） 授予读取、查询和管理服务终结点的能力。
设置 vso.settings 设置（阅读） 授予读取设置的能力。
vso.settings_write 设置（读取和写入） 授予创建和读取设置的能力。
符号 vso.symbols 符号（已读） 授予读取符号的能力。
vso.symbols_write 符号（读取和写入） 授予读取和写入符号的能力。
vso.symbols_manage 符号（读取、写入和管理） 授予读取、写入和管理符号的能力。
任务组 vso.taskgroups_read 任务组（已读） 授予读取任务组的能力。
vso.taskgroups_write 任务组（读取、创建） 授予读取和创建任务组的能力。
vso.taskgroups_manage 任务组（读取、创建和管理） 授予读取、创建和管理任务组的能力。
团队仪表板 vso.dashboards 团队仪表板（阅读） 授予读取团队仪表板信息的能力。
vso.dashboards_manage 团队仪表板（管理） 授予管理团队仪表板信息的能力。
测试管理 vso.test 测试管理（读取） 授予读取测试计划、用例、结果和其他测试管理相关项目的能力。
vso.test_write 测试管理（读取和写入） 授予读取、创建和更新测试计划、事例、结果和其他测试管理相关项目的能力。
线程 vso.threads_full PR 线程 授予读取和写入拉取请求批注线程的能力。
标记 vso.tokens 委派的授权令牌 授予向用户管理委派授权令牌的能力。
vso.tokenadministration 令牌管理员 向组织管理员授予管理现有令牌（查看和撤销）的能力。
用户配置文件 vso.profile 用户配置文件(读取) 授予读取配置文件、帐户、集合、项目、团队和其他顶级组织项目的能力。
vso.profile_write 用户配置文件（写入） 授予写入配置文件的功能。
变量组 vso.variablegroups_read 变量组（读取） 授予读取变量组的能力。
vso.variablegroups_write 变量组（读取、创建） 授予读取和创建变量组的能力。
vso.variablegroups_manage 变量组（读取、创建和管理） 授予读取、创建和管理变量组的能力。
Wiki vso.wiki Wiki （阅读） 授予读取 Wiki、Wiki 网页和 Wiki 附件的功能。 此外，还授予搜索 Wiki 页面的能力。
vso.wiki_write Wiki （读取和写入） 授予读取、创建和更新 Wiki、Wiki 网页和 Wiki 附件的功能。
工作项 vso.work 工作项(读取) 授予读取工作项、查询、版块、区域和迭代路径以及其他工作项跟踪相关元数据的能力。 此外，还授予执行查询、搜索工作项以及通过服务挂钩接收有关工作项事件的通知的能力。
vso.work_write 工作项(读取和写入) 授予读取、创建和更新工作项和查询、更新板元数据、读取区域和迭代路径、其他工作项跟踪相关元数据、执行查询以及通过服务挂钩接收有关工作项事件的通知的能力。
vso.work_full 工作项（完整） 授予对工作项、查询、积压工作、计划和工作项跟踪元数据的完全访问权限。 此外，还可以通过服务挂钩接收有关工作项事件的通知。
用户模拟 user_impersonation 用户模拟 对 Visual Studio Team Services REST API 具有完全访问权限。 请谨慎请求和/或同意此范围，因为它非常强大！

更改已发布扩展的范围

可以更改已发布扩展的范围。 如果以前安装了扩展（并授权了以前的范围集），则必须授权新范围，然后才能升级到最新版本。

扩展设置中心的“所需操作”部分显示用户，如果有，已安装的扩展需要授权：

scope-change

然后，管理员可以查看和授权新的范围集：

scope-change-dialog

安装目标

顾名思义，安装目标定义可在其中安装扩展的产品和服务。 Microsoft.VisualStudio.Services 是最常见的安装目标，指示该扩展可以安装到 Azure DevOps 中。

扩展或集成的安装目标是通过 targets 清单中的字段指定的。

支持的扩展标识符：

  • Microsoft.VisualStudio.Services.Cloud：安装到 Azure DevOps Services 中
  • Microsoft.TeamFoundation.Server：安装到 Azure DevOps Server
  • Microsoft.VisualStudio.Services：安装到两者中。 快捷方式 Microsoft.VisualStudio.Services.Cloud 和 Microsoft.TeamFoundation.Server 版本 [14.2,)

集成支持的标识符：

  • Microsoft.VisualStudio.Services.Cloud.Integration：与 Azure DevOps Services 集成
  • Microsoft.TeamFoundation.Server.Integration：与 Azure DevOps Server 集成
  • Microsoft.VisualStudio.Services.Integration：与两者集成。 和Microsoft.VisualStudio.Services.Cloud.IntegrationMicrosoft.TeamFoundation.Server.Integration

有关详细信息，请参阅 扩展点。

安装目标示例

示例：适用于 Azure DevOps 的扩展

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

示例：仅适用于 Azure DevOps Services 的扩展

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        }
    ]
}

还可以在集成清单中使用安装目标。 例如，使用但未安装到 Azure DevOps 中的产品、应用或工具。

示例：与 Azure DevOps 配合使用的集成

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ]
}

示例：仅适用于 Azure DevOps Server 的集成

{
    "targets": [
        {
            "id": "Microsoft.TeamFoundation.Server.Integration"
        }
    ]
}

安装目标版本

某些安装目标标识符（例如 Microsoft.TeamFoundation.Server 和 Microsoft.TeamFoundation.Server.Integration）支持可选版本范围。 此可选版本范围进一步阐明了支持扩展或集成的受支持版本。

版本或版本范围是通过 version 安装目标对象上的字段指定的。 此值可以是：

  • 特定版本，例如： 15.0 （仅限 2017 RTM）
  • 一系列受支持的版本，例如： [14.0) （2015 RTM 及更高版本）、 [14.3,15.1] （2015 Update 3 到 2017 Update 1）。 使用以下方法优化范围值：
    • [：最低版本（非独占）
    • ]：最大版本（非独占）
    • (：最低版本独占
    • )：最大版本独占

Azure DevOps Server 的版本号：

版本 发行版本 版本
2010 所有发布 10.0
2012 所有发布 11.0
2013 RTM 和更新 12.0, 12.1, 12.2, 12.3, 12.4
2015 RTM 和更新 14.0, 14.1, 14.2, 14.3
2017 RTM 和更新 15.0, 15.1
2018 RTM 和更新 16.0
2019 RTM 和更新 17.0
2020 RTM 和更新 18.0

显示版本的示例

示例：适用于 Azure DevOps 的扩展

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[15.0,)"
        }
    ]
}

快捷方式

Microsoft.VisualStudio.Services 是 Azure DevOps 的快捷方式。

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ]
}

等效于：

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Cloud"
        },
        {
            "id": "Microsoft.TeamFoundation.Server",
            "version": "[14.2,)"
        }
    ]
}

使用安装目标和需求

安装目标和需求一起使用，向用户提供扩展或集成与之兼容的产品/服务的正确视图。 例如，使用需求api-version/3.0指定安装目标Microsoft.VisualStudio.Services，这意味着该扩展适用于 Azure DevOps。

提示

有关 REST API 的详细信息，请参阅 REST API 参考。

示例：使用版本 3.0 API 的扩展

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ]
}

解析为以下安装目标：

  1. Microsoft.VisualStudio.Services.Cloud
  2. Microsoft.TeamFoundation.Server版本： [15.0,)

示例：使用版本 2.0 API 的集成

{
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services.Integration"
        }
    ],
    "demands": [
        "api-version/2.0"
    ]
}

解析为以下安装目标：

  1. Microsoft.VisualStudio.Services.Cloud.Integration
  2. Microsoft.TeamFoundation.Server.Integration版本： [14.0,)

需求

通过需求，可以指定扩展所需的功能和其他功能。 可以使用这些要求来限制可以发布或安装扩展的位置。

Visual Studio Marketplace 使用的需求列出扩展与的产品和环境兼容，这有助于客户了解扩展是否适用于其 Azure DevOps 版本。

请参阅以下示例，了解如何在扩展清单中指定需求。

{
    "demands": [
        "api-version/3.0",
        "contribution/ms.vss-dashboards-web.widget-catalog"
    ]
}

在此示例中，扩展需要 3.0 版 API，这意味着它只能安装到 Azure DevOps。 它还要求在 ms.vss-dashboards-web 集合中安装扩展（及其 widget-catalog 贡献），然后才能安装扩展。

支持的需求

类型 描述 是否已在发布时进行检查？ 是否已在安装时进行检查？
environment/cloud 需要在云环境中运行 是 是
environment/onprem 要求在本地环境中运行 是 是
api-version/{version} 需要特定的 API 版本（最低） 否 是
extension/{id} 需要安装/启用特定扩展 否 是
contribution/{id} 需要提供特定贡献 否 是
contributionType/{id} 需要提供特定的贡献类型 否 是

注意

  • environment/onprem仅在扩展具有需要在该特定环境中运行的拓扑相关要求时才使用environment/cloud。
  • extension、 contribution和 contributionType 需求在安装时进行评估，并要求已在组织/集合中安装和启用指定的扩展。

文件

本 files 部分引用要包含在扩展中的任何文件的位置。 可以添加文件夹和单个文件：

{
    "files": [
        {
            "path": "hello-world.html", "addressable": true
        },
        {
            "path": "scripts", "addressable": true
        },
        {
            "path": "images/logo.png", "addressable": true, "packagePath": "/"
        }
    ]
}

属性

“文件”部分的属性：

  • path - 磁盘上资源的路径，该路径可以相对于根目录。
  • 可 寻址 - （可选） 如果希望文件可寻址 URL，则设置为 true 。 默认为 false。
  • packagePath – （可选）包中资源的路径。 默认为根目录中磁盘上的相对路径。
  • contentType – （可选） 文件 MIME 类型。 默认为基于文件扩展名和 OS 设置的最佳猜测。
  • assetType – （可选） 指定 VSIX 清单中资产项的 Type 属性的值。 也可以是字符串数组，在这种情况下，会为此文件添加多个资产条目。 默认为 packagePath。
  • lang – （可选） 此资产的语言。 本地化文件基于 Accept-Language 标头提供。 留空以表示此文件处于默认（或回退）语言。 同一文件的本地化版本应具有相同的 assetType。

发布内容

每个贡献项具有以下属性：

  • id - 供稿的引用 ID （字符串）。 每个贡献的 ID 在扩展中必须是唯一的。 请参阅 引用贡献和类型。
  • type - 此贡献的 contributionType 的 ID。
  • description - （可选） 描述贡献提供的内容的字符串。
  • targets - 贡献面向的一组贡献 ID（参与）。 请参阅 目标贡献。
  • properties - （可选） 一个对象，该对象包含参与类型中定义的参与的属性。

有关详细信息，请参阅 贡献模型概述。

参与类型

每个贡献项具有以下属性：

  • id - 贡献类型的引用 ID （字符串）。 每个贡献类型的 ID 在扩展中必须是唯一的。 请参阅 引用贡献和类型。
  • name - 贡献类型的友好名称。
  • description - （可选） 一个字符串，用于更详细地描述贡献类型。
  • properties - （可选） 一个字典，用于将属性名称映射到属性说明。 这些属性描述此类型的必需属性和可选属性可以使用。

属性说明具有以下属性：

  • description - （可选） 描述属性用途的字符串。
  • required - （可选） 布尔值，如果为 true，则指示此类型的所有贡献都需要该属性。
  • type - 属性可以具有的值的类型，可以是字符串、uri、guid、布尔值、整数、double、dateTime、数组或对象。

有关详细信息，请参阅 贡献模型概述。

引用贡献和类型

使用唯一标识符引用贡献和贡献类型。 使用type属性引用类型，并引用属性targets的其他贡献。

  • 完整贡献引用包括发布者标识符、扩展标识符和贡献/类型标识符，用点（.）分隔。 例如， ms.vss-web.hub 是“ms”（Microsoft）发布者发布的“vss-web”扩展中“hub”标识符的贡献的完整标识符。
  • 相对 贡献引用可用于扩展清单中对同一扩展内其他贡献或贡献类型的引用。 在这种情况下，不包括发布者和扩展标识符，标识符是一个点（.），后跟贡献标识符。 例如，“.hub”可能在之前提及的“vss-web”扩展中使用，作为“ms.vss-web.hub”的快捷方式。

目标贡献

某些贡献充当其他贡献的目标容器。

  • 中心贡献可以面向中心组。 呈现页面时，Web UI 会显示面向所选中心组的所有中心贡献。 中心组面向中心组集合，该集合定义显示在给定导航区域中的一组中心组，例如项目级管理页面。
  • 不同类型的贡献可以面向菜单：操作、超链接操作和操作提供程序。 操作和超链接操作提供单个菜单项条目。 操作提供程序可以提供多个动态菜单项。 对于给定菜单，项会跨所有贡献（其中任何类型）聚合，以特定菜单贡献为目标。

添加中心图标

有关将图标添加到中心的信息，检查中心图标指南。

支持的锁屏提醒服务

市场仅支持以下受信任服务中的锁屏提醒：

  • api.travis-ci.org/
  • badge.fury.io/
  • badges.frapsoft.com/
  • badges.gitter.im/
  • badges.greenkeeper.io/
  • cdn.travis-ci.org/
  • ci.appveyor.com/
  • codeclimate.com/
  • codecov.io/
  • coveralls.io/
  • david-dm.org/
  • gemnasium.com/
  • img.shields.io/
  • isitmaintained.com/
  • marketplace.visualstudio.com/
  • snyk.io/
  • travis-ci.com/
  • travis-ci.org/
  • vsmarketplacebadges.dev/
  • bithound.io/
  • deepscan.io/
  • githost.io/
  • gitlab.com/
  • opencollective.co/

注意

将“vsmarketplacebadge.apphb.com”替换为“vsmarketplacebadges.dev”。

若要显示另一个服务的锁屏提醒，请联系 vsmarketplace@microsoft.com。

示例清单

以下扩展为已完成的生成上下文菜单以及生成中心组提供操作：

{
    "manifestVersion": 1,
    "id": "tools",
    "version": "0.1.0",
    "name": "Fabrikam Tools",
    "publisher": "fabrikam",
    "description": "Awesome tools to help you and your team do great things everyday.",
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "demands": [
        "api-version/3.0"
    ],
    "icons": {
        "default": "images/fabrikam-logo.png"
    },
    "scopes": [
        "vso.work",
        "vso.code_write"
    ],
    "categories": [
        "Plan and track"
    ],
    "tags": [
        "working",
        "people person",
        "search"
    ],
    "branding": {
        "color": "rgb(34, 34, 34)",
        "theme": "dark"
    },
    "screenshots": [
        {
            "path": "screenshots/screen1.png"
        },
        {
            "path": "screenshots/screen2.png"
        }
    ],
    "content": {
        "details": {
            "path": "overview.md"
        },
        "license": {
            "path": "eula.md"
        }
    },
    "links": {
        "home": {
            "uri": "https://www.fabrikam-fiber-inc.com"
        },
        "getstarted": {
            "uri": "https://www.fabrikam-fiber-inc.com/help/getstarted"
        },
        "learn": {
            "uri": "https://www.fabrikam-fiber-inc.com/features"
        },
        "support": {
            "uri": "https://www.fabrikam-fiber-inc.com/support"
        },
        "repository": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools"
        },
        "issues": {
            "uri": "https://github.com/fabrikam-fiber-inc/tools/issues"
        }
    },
    "repository": {
        "type": "git",
        "uri": "https://github.com/fabrikam-fiber-inc/myextension"
    },
    "badges": [
        {
            "href": "https://travis.ci/fabrikam-fiber-inc/myextension",
            "uri": "https://travis.ci/fabrikam-fiber-inc/myextension.svg?branch=master",
            "description": "TravisCI build for the project"
        },
        {
            "href": "https://ci.appveyor.com/projects/fabrikam-fiber-inc/myextension",
            "uri": "https://ci.appveyor.com/api/projects/status/vlg2sgs2y7tsdxpj4c?svg=true",
            "description": "AppVeyor build for the project"
        }
    ],
    "contributions": [
        {
            "id": "showCommits",
            "type": "ms.vss-web.action",
            "description": "Adds a menu action from builds grid to show associated items.",
            "targets": [
                "ms.vss-build-web.completed-build-menu"
            ],
            "properties": {
                "title": "View associated items",
                "uri": "launch.html"
            }
        }
    ]
}