共用方式為

延伸模組指令清單參考

  • 發行項

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

每個擴充功能都有一個 JSON 指令清單檔，可定義擴充功能的基本資訊。 檔案也會定義其擴充及增強體驗的方式。 本文說明如何為 Azure DevOps 的擴充功能建立清單。

提示

請參閱使用 Azure DevOps 擴充功能 SDK 進行擴充功能開發的最新檔。

在延伸模組資料夾的根目錄建立名為 vss-extension.json 的檔案。 此檔案包含必要的屬性，例如延伸模組的識別碼及其安裝目標，並指定可以執行的地方。 它也會定義延伸模組所做出的貢獻。

請查看典型清單的下列範例：

{
    "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"
        }
    ]
}

如需輸入的相關資訊，請參閱 ...

必要屬性

這些屬性是必要的：

財產 描述 附註
manifestVersion 與清單格式版本對應的數字。 應該是 1。
識別碼 延伸模組的標識碼。 此ID是一個字串，在相同發行者的擴充套件之間必須是唯一的。 它必須以字母或數值字元開頭，並包含 'A' 到 'Z'、'a' 到 'z'、'0' 到 '9' 和 '-' （連字元）。 範例：sample-extension。
版本 指定延伸模組版本的字串。 格式 major.minor.patch應為 ，例如 0.1.2 或 1.0.0。 您也可以針對下列格式新增第四個數位： 0.1.2.3
name 擴充套件的簡短人類可讀名稱。 限制為200個字元。 範例："Fabrikam Agile Board Extension"。
publisher 發行者的標識碼。 此識別碼必須與擴充功能發布時的識別碼一致。 請參閱 建立和管理發行者。
類別 字串陣列，代表擴充功能所屬的類別。 至少必須提供一個類別，而且您可能包含的類別數目沒有限制。 有效值： Azure Repos、 Azure Boards、 Azure Pipelines、 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（而非本機資源庫）取得延伸模組，請使用先前所述的類別。
      - 如果您要直接與使用 TFS <=2018 的客戶共用延伸模組（也就是不是透過 Visual Studio Marketplace），請改用下列類別：程式代碼、規劃和追蹤、建置和發行、測試、共同作業和整合。 如果您需要透過Visual Studio Marketplace 和直接與 TFS <= 2018 客戶共用，則必須有 2 個延伸模組套件。
目標 整合或擴充功能所支援的產品和服務。 如需詳細資訊，請參閱 安裝目標。 物件的陣列，其中每個物件都有一個 id 欄位，指出下列其中一項：
    - Microsoft.VisualStudio.Services（適用於 Azure DevOps 或 TFS 的擴充功能）、
    - Microsoft.TeamFoundation.Server（適用於 TFS 的擴充功能）、
    - Microsoft.VisualStudio.Services.Integration（與 Azure DevOps 或 TFS 搭配運作的整合）、
    - Microsoft.TeamFoundation.Server.Integration （與 TFS 搭配運作的整合）

必要屬性的範例

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

選用屬性

運行時間屬性

屬性 描述 附註
範疇 授權範圍陣列（字串）列出延伸模組所需的許可權。 例如， vso.work 和 vs.code_write 表示您的延伸模組需要工作專案的唯讀存取權，以及原始程式碼的讀取/寫入存取權（和相關資源）。 安裝擴充功能時，會向用戶顯示範圍。 如需詳細資訊，請參閱 範圍的完整清單。
要求 需求陣列（字串），列出擴充功能所需的功能。 例如， api-version/3.0 表示您的延伸模組使用 3.0 版 API，因此無法在不支援此版本的舊版產品中執行。 如需詳細資訊，請參閱 需求的完整清單。
baseUri （選擇性） 延伸模組貢獻所指定之所有相對 URL 的基底 URL。 例如： https://myapp.com/{{account.name}}/ 。 如果您的擴充功能的內容已經與擴充功能一起封裝，則此屬性應保持空白。
貢獻 對系統的貢獻陣列。
貢獻類型 擴充功能所定義的貢獻類型陣列 
{
    "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"
            }
        }
    ]
}

發現屬性

這些選擇性屬性可協助使用者探索並瞭解您的延伸模組：

屬性 描述 附註
description 描述延伸模組的幾個句子。 限制為200個字元。 描述應該是您延伸模組的「簡短推介」——在 Marketplace 中用幾行描述您的延伸模組，並讓使用者想要安裝它。 請參閱下列範例
圖示 代表延伸模組的圖示字典。 有效密鑰： default BMP、GIF、EXIF、JPG、PNG 和 TIFF 類型的 128x128 像素）。 未來可能支援其他索引鍵，例如 large （512x512 像素）。 每個機碼的值都是延伸模組中圖示檔案的路徑
標記 字串標籤標的陣列，可協助使用者尋找您的延伸模組。 範例： agile、 project management、 task timer等。
螢幕快照 無法包含在內容中的影像陣列。 當您的內容中展示時，螢幕快照會更有價值，應該用來協助製作您的延伸模組的高品質市場詳情頁面。 對於內容未收錄的較不重要影像，請使用螢幕快照。 每個影像應為1366x768像素。 每個專案的path是該擴充功能中檔案的路徑。
內容 描述您擴充功能給使用者的內容檔案詞典。 每個 延伸模組都應該包含紮實的內容。 這樣您就可以向使用者展示您的擴充功能能夠執行的功能。 使其豐富、易於理解，並在需要時包含螢幕快照。 包含overview.md檔案作為您的基礎內容。 每個檔案都假設為 GitHub Flavored 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 Marketplace 中的所有擴充功能都是私人的。 只有發行者和被發行者共用的帳戶才能看到它們。 如果您的發行者已驗證，您可以在延伸模組指令清單中設定 Public 旗標，讓擴充功能公開：

{
    "galleryFlags": [
        "Public"
    ]
}

或：

{
    "public": true
}

如需詳細資訊，請參閱 套件/發佈/安裝。

將延伸模組標示為處於預覽狀態

如果您的延伸模組已準備好讓 Marketplace 上的使用者嘗試，但您仍在處理一些 Bug 或新增函式，您可以將它標示為 preview：

{
    "galleryFlags": [
        "Preview"
    ]
}

將延伸模組標示為付費預覽

如果您想要在 Marketplace 上銷售延伸模組，請將它標示為 付費預覽。 標示 為免費 延伸模組無法變更為 付費。

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

將擴充功能標示為付費

如果您想要在 Marketplace 上銷售延伸模組，您可以使用Paid旗標和__BYOLENFORCED標籤標記它（標籤開頭為兩個底線）：

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

Paid旗標和__BYOLENFORCED標籤都必須存在，才能在 Marketplace 中將延伸模組標示為付費。 自備授權 （BYOL） 表示延伸模組的發行者會提供延伸模組的計費和授權機制，因為 Azure DevOps 擴充功能Microsoft並未提供它。 所有付費延伸模組都必須定義隱私策略、支援原則和使用者許可協定。 發行者必須提供 Marketplace 中定價索引標籤的內容，如下所示：

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

您還需要在擴充功能清單中新增一個區段，以覆蓋付費授權。 未來，我們會取消付費授權檢查，也不再需要使用覆蓋選項。 目前，請確定您的擴充功能如預期般顯示。 每個覆蓋設定都包含「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 - 商標

卡片

Marketplace Q & A - 顧客問答支持 屬性

Visual Studio Marketplace 上的所有延伸模組都有 [問題和解答] 區段，以允許延伸模組使用者與發行者之間的一對一公開交談。 發行者可以選擇 Marketplace 問題和解答（Q&A）、GitHub 問題或自定義問答 URL。 您可以使用指令清單中的 CustomerQnASupport 屬性，在 Marketplace 中停用 Q&A。

預設體驗 （不需要變更指令清單）

  • 針對具有 GitHub 存放庫的擴充功能，Marketplace 會將 Q&A 區段中的使用者重新導向至相關聯的 GitHub 問題。
  • 對於沒有 GitHub 存放庫的擴充套件，Marketplace 問與答功能將會啟用。

如需與其中一個預設選項不同的體驗，請使用 指令清單中的 CustomerQnASupport 屬性。

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

屬性

客戶問答支援區段的屬性：

  • enablemarketplaceqna - 布爾值字段、針對 Marketplace 設定為 true ，或針對自定義 Q&A;false 表示停用 Q&A
  • url - 字串，自定義問答的 URL

顯示 Q & A 支援使用方式的範例

範例：使用自定義Q & A的擴充功能

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

範例：使用 GitHub 存放庫擴充功能，但使用 Marketplace Q & A 而非 GitHub 問題

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

範例：停用Q & A 區段的延伸模組

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

範圍

在您的延伸模組中，您可以定義一或多個範圍。 這些範圍會決定延伸模組可以存取哪些資源，以及允許在這些資源上執行的作業。 您在延伸模組清單中指定的範圍是設定在發行給延伸模組的存取令牌上的範圍。 如需詳細資訊，請參閱 驗證和安全性。

如果未指定任何範圍，則只會提供對使用者配置檔和延伸模組數據的存取權。

支援的範圍

類別 範圍 名稱 高風險 描述 繼承來源
進階安全性 vso.advsec AdvancedSecurity（讀取） Yes 授與讀取警示、結果實例與分析實例的能力。
vso.advsec_write AdvancedSecurity （讀取和寫入） Yes 授與在 sarif 中上傳分析的能力 vso.advsec
vso.advsec_manage AdvancedSecurity （讀取、寫入和管理） Yes 提供能夠在 sarif 中上傳分析的權限 vso.advsec_write
代理池 vso.agentpools 代理程式集區 （讀取） 提供檢視任務、資源集區、佇列、代理程式，以及代理程式目前正在執行或最近完成的工作的能力。
vso.agentpools_manage 代理程式集區（讀取、管理） Yes 授予管理集區、佇列和代理程式的權限。 vso.agentpools
vso.environment_manage 環境（讀取、管理） Yes 授與管理集區、佇列、代理程式和環境的能力。 vso.agentpools_manage
分析 vso.analytics 剖析（閱讀） 授與查詢分析數據的能力。
稽核 vso.auditlog 稽核記錄檔 （讀取） 允許使用者讀取稽核記錄。
vso.auditstreams_manage 稽核串流 （讀取） Yes 授予使用者管理稽核流的權限。 vso.auditlog
建置 vso.build 組建（閱讀） 授與存取組建成品的能力，包括建置結果、定義和要求，以及能夠透過服務攔截接收有關建置事件的通知。 vso.hooks_write
vso.build_execute 編譯（讀取與執行） Yes 授與存取組建成品的能力，包括建置結果、定義和要求，以及能夠將組建排入佇列、更新組建屬性，以及透過服務攔截接收建置事件的相關通知的能力。 vso.build
代碼 vso.code 程式代碼 （讀取） 授予讀取原始程式碼和有關提交、變更集、分支及其他版本控制相關物件的元數據的能力。 還授與搜尋程式碼的能力，並透過服務掛鉤取得版本控制事件的通知。 vso.hooks_write
vso.code_write 程式代碼 （讀取和寫入） Yes 提供讀取、更新及刪除原始程式碼的權限，並存取有關認可、變更集、分支及其他版本控制工件的元數據。 也授予建立和管理拉取請求及程式碼審查的能力，以及透過服務勾點接收版本控制事件的通知。 vso.code
vso.code_manage 程式代碼 （讀取、寫入和管理） Yes 賦予讀取、更新和刪除原始程式碼的能力，並存取認可、變更集、分支及其他版本控制工件的相關元數據。 同時授與建立和管理程式代碼存放庫、建立和管理提取要求和程式代碼檢閱，以及透過服務攔截接收版本控制事件的通知的能力。 vso.code_write
vso.code_full 程式代碼 （完整） Yes 提供對原始碼、關於提交、變更集、分支和其他版本控制元素的完整訪問權限。 同時授與建立和管理程式代碼存放庫、建立和管理提取要求和程式代碼檢閱，以及透過服務攔截接收版本控制事件的通知的能力。 也包含對用戶端 OM API 的有限支援。 vso.code_manage
vso.code_status 代碼（狀態） 授與讀取和寫入提交狀態及拉取請求狀態的能力。
線上的伺服器 vso.connected_server 線上的伺服器 授與從內部部署連線伺服器存取所需端點的能力。
權利 vso.entitlements 權利（閱讀） 提供授權權利端點的唯讀存取權，以取得帳戶權利。
vso.memberentitlementmanagement 成員權益管理 （讀取） 授與讀取使用者、其授權，以及他們可存取的專案和延伸模組的能力。
vso.memberentitlementmanagement_write 會員權益管理（寫入） Yes 授與管理使用者、其授權，以及他們可存取的專案和延伸模組的能力。 vso.memberentitlementmanagement
擴充 vso.extension 擴充功能（讀取） 授與讀取已安裝擴充功能的能力。 vso.profile
vso.extension_manage 擴充功能（讀取和管理） Yes 授與在已安裝擴充功能上安裝、卸載及執行其他系統管理動作的能力。 vso.extension
vso.extension.data 擴充功能資料（讀取） 授與讀取已安裝延伸模組所儲存之數據（設定和檔）的能力。 vso.profile
vso.extension.data_write 擴充功能資料（讀取與寫入） 授與讀取和寫入已安裝延伸模組所儲存之數據（設定和檔）的能力。 vso.extension.data
Github 連線 vso.githubconnections GitHub 連結（閱讀） 授與讀取 GitHub 連線和 GitHub 存放庫數據的能力。
vso.githubconnections_manage GitHub Connections（讀取和管理） Yes 授與讀取和管理 GitHub 連線與 GitHub 存放庫數據的能力 vso.githubconnections
圖形和身分識別 vso.graph 圖表（閱讀） 授與讀取使用者、群組、範圍和群組成員資格資訊的能力。
vso.graph_manage 圖表（管理） Yes 授與讀取使用者、群組、範圍和群組成員資格資訊的能力，以及新增使用者、群組和管理群組成員資格的能力。 vso.graph
vso.identity 身分識別（讀取） 授與讀取身分識別和群組的能力。
vso.identity_manage 身分識別（管理） Yes 授與讀取、寫入及管理身分識別和群組的能力。 vso.identity
機器群組 vso.machinegroup_manage 部署群組 （讀取、管理） Yes 提供管理部署群組和代理程式集區的能力。 vso.agentpools_manage
市場平台 vso.gallery 市場 授予公用和私人項目及發行者的讀取權限。 vso.profile
vso.gallery_acquire 市集（購買） 授與讀取權限，以及取得項目的能力。 vso.gallery
vso.gallery_publish Marketplace （發佈） Yes 授與讀取權限，以及上傳、更新和分享項目的權限。 vso.gallery
vso.gallery_manage Marketplace （管理） Yes 授予讀取權限及發布和管理項目與發行者的能力。 vso.gallery_publish
通知 vso.notification 通知（已讀） 提供訂閱和事件元數據的讀取權限，包括可篩選的欄位值。 vso.profile
vso.notification_write 通知（寫入） 提供對訂閱的讀寫存取權，以及對事件元數據的讀取權限，包括可篩選的欄位值。 vso.notification
vso.notification_manage 通知（管理） 提供對訂閱的讀取、寫入和管理權限，以及事件元數據的讀取權限，包括可篩選的欄位值。 vso.notification_write
vso.notification_diagnostics 通知（診斷） 提供存取權以檢視與通知相關的診斷記錄，並允許為個別訂閱啟用診斷功能。 vso.notification
封裝 vso.packaging 包裝（讀取） 授予瀏覽資訊流與套件的權限。 vso.profile
vso.packaging_write 封裝（讀取與寫入） Yes 授與建立和讀取訂閱源及套件的能力。 vso.packaging
vso.packaging_manage 封裝（讀取、寫入和管理） Yes 授與建立、讀取、更新以及刪除訂閱源和套件的能力。 vso.packaging_write
管線資源 vso.pipelineresources_use 管線資源（使用） Yes 授與核准管線使用受保護資源的要求的能力：代理程式集區、環境、佇列、存放庫、安全檔案、服務聯機和變數群組。
vso.pipelineresources_manage 管線資源（使用和管理） Yes 授與管理受保護資源或管線使用受保護資源之要求的能力：代理程式集區、環境、佇列、存放庫、安全檔案、服務連線和變數群組。 vso.pipelineresources_manage
專案和小組 vso.project 專案和團隊（閱讀） 授與讀取專案和小組的能力。
vso.project_write 專案和團隊（讀取和寫入） 授予讀取及更新專案和小組的能力。 vso.project
vso.project_manage 專案和團隊（讀取、寫入和管理） Yes 授與建立、讀取、更新和刪除專案和小組的能力。 vso.project_write
發行 vso.release 釋出（閱讀） 授與讀取發行成品的能力，包括發行、發行定義和發行環境。 vso.profile
vso.release_execute 釋放（讀取、寫入和執行） Yes 授予讀取和更新發行成果的能力，包括發行版本、發行定義、發行環境，以及將新發行排入佇列的能力。 vso.release
vso.release_manage 發行 （讀取、寫入、執行和管理） Yes 授予讀取、更新和刪除發行工件的能力，包括發行版本、發行定義和發行環境，以及排隊和核准新發行的能力。 vso.release_manage
安全檔案 vso.securefiles_read 安全檔案 （讀取） Yes 授與讀取安全檔案的能力。
vso.securefiles_write 安全檔案 （讀取、建立） Yes 授與讀取和建立安全檔案的能力。 vso.securefiles_read
vso.securefiles_manage 安全檔案 （讀取、建立和管理） Yes 授與讀取、建立和管理安全檔案的能力。 vso.securefiles_write
安全性 vso.security_manage 安全性（管理） Yes 授與讀取、寫入和管理安全性許可權的能力。
服務連線 vso.serviceendpoint 服務端點（讀取） 授與讀取服務端點的能力。 vso.profile
vso.serviceendpoint_query 服務端點 （讀取和查詢） 授與讀取和查詢服務端點的能力。 vso.serviceendpoint
vso.serviceendpoint_manage 服務端點（讀取、查詢和管理） Yes 授與讀取、查詢及管理服務端點的能力。 vso.serviceendpoint_query
服務鉤子 vso.hooks 服務掛鉤（讀取） 授予讀取服務鉤子的訂閱和元數據的能力，包括支援的事件、消費者和動作。 （不再公開。 vso.profile
vso.hooks_write 服務掛勾（讀取和寫入） 授予創建和更新服務鉤子訂閱並讀取元數據的能力，包括支援的事件、消費者和動作。 （不再公開。 vso.hooks
vso.hooks_interact 服務掛鉤（互動） 授予能力以對透過服務勾點接收的事件進行互動和執行動作。 （不再公開。 vso.profile
設定 vso.settings 設定（讀取） 授予讀取設定的權限。
vso.settings_write 設定（讀取與寫入） 賦予建立和讀取設定的權限。
Symbols vso.symbols 符號（讀取） 授與讀取符號的能力。 vso.profile
vso.symbols_write 符號（讀取和寫入） 授與讀取和寫入符號的能力。 vso.symbols
vso.symbols_manage 符號（讀取、寫入和管理） 授與讀取、寫入和管理符號的能力。 vso.symbols_write
工作組 vso.taskgroups_read 工作群組（讀取） 賦予能夠讀取工作群組的能力。
vso.taskgroups_write 任務組（讀取、建立） 授與讀取和建立工作組的能力。 vso.taskgroups_read
vso.taskgroups_manage 工作組（讀取、建立和管理） Yes 授予讀取、建立和管理工作群組的能力。 vso.taskgroups_write
小組儀錶板 vso.dashboards 團隊儀錶板（閱讀） 賦予讀取團隊儀錶板資訊的能力。
vso.dashboards_manage 團隊儀錶板（管理） 提供管理小組資訊控制台的能力。 vso.dashboards
測試管理 vso.test 測試管理（閱讀） 授與讀取測試計劃、案例、結果和其他測試管理相關成品的能力。 vso.profile
vso.test_write 測試管理（讀取和寫入） 授與讀取、建立和更新測試計劃、案例、結果和其他測試管理相關成品的能力。 vso.test
討論串 vso.threads_full PR 線程 授予讀取和寫入拉取請求評論線程的權限。
代幣 vso.tokens 委派的授權令牌 Yes 授與管理委派授權令牌給使用者的能力。
vso.tokenadministration 令牌管理 Yes 授與管理現有令牌的能力（檢視和撤銷）給組織系統管理員。
使用者設定檔 vso.profile 使用者設定檔（讀取） 授與您閱讀個人資料、帳戶、集合、專案、小組和其他最上層組織資料的能力。
vso.profile_write 使用者個人資料（編輯） 授予對您的個人檔案進行寫入的權限。 vso.profile
變數群組 vso.variablegroups_read 變數群組（讀取） 授與讀取變數群組的能力。
vso.variablegroups_write 變數群組（讀取、建立） 授與讀取和建立變數群組的能力。 vso.variablegroups_read
vso.variablegroups_manage 變數群組（讀取、建立和管理） Yes 授與讀取、建立和管理變數群組的能力。 vso.variablegroups_write
Wiki vso.wiki Wiki（閱讀） 授與讀取Wiki、Wiki頁面和Wiki附件的能力。 同時授與搜尋Wiki頁面的能力。
vso.wiki_write Wiki （讀取與寫入） 授與讀取、建立和更新Wiki、Wiki頁面和Wiki附件的能力。 vso.wiki
工作專案 vso.work 工作項目（讀取） 授予讀取工作項目、查詢、面板、區域路徑和迭代路徑，以及其他工作項目追蹤相關元數據的能力。 同時授予執行查詢、搜尋工作項目，以及透過服務勾點接收工作項目事件通知的能力。 vso.hooks_write
vso.work_write 工作項目 （讀取與寫入） 授予讀取、建立和更新工作專案及查詢的能力，更新看板元數據，讀取區域與迭代路徑等其他工作專案追蹤相關元數據，執行查詢，以及透過服務鉤接收到工作專案事件通知。 vso.work
vso.work_full 工作專案（完整） 授與工作項目、查詢、待辦專案、計劃及工作專案追蹤元數據的完整存取權。 也可讓您透過服務鉤子接收工作項目事件通知。 vso.work_write
用戶冒充 user_impersonation 用戶冒充 Yes 具有 Visual Studio Team Services REST API 的完整存取權。 請謹慎要求和/或同意此範圍，因為它非常強大！

變更已發佈延伸模組的範圍

您可以變更已發佈延伸模組的範圍。 如果您先前已安裝擴充功能（且已授權先前的一組範圍），請先授權新的範圍，才能升級至最新版本。

擴充功能設定中心中的 [需要的動作] 區段會向使用者顯示，如果有安裝的話，哪些已安裝的擴充功能需要授權：

範圍變更

然後，系統管理員可以檢閱並授權新的範圍集合：

範圍變更對話框

安裝目標

顧名思義，安裝目標會定義您可以安裝擴充功能的產品和服務。 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.Integration 和 Microsoft.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 正式版發行和更新 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,)"
        }
    ]
}

使用安裝目標和需求

安裝目標和需求會一起使用，向使用者呈現延伸模組或整合所相容產品/服務的正確檢視。 例如，將安裝目標指定為Microsoft.VisualStudio.Services且需求為api-version/3.0，表示擴充套件可與 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 需要在雲端環境中執行 Yes Yes
environment/onprem 需要在內部部署環境中執行 Yes Yes
api-version/{version} 需要特定 API 版本（最小值） 否 Yes
extension/{id} 需要安裝/啟用特定擴充功能 不 Yes
contribution/{id} 需要提供特定貢獻 不 Yes
contributionType/{id} 需要有一個特定的貢獻類型可供使用 不 Yes

注意

  • 只有當您的擴充功能具有需要在特定環境中執行的拓撲相關需求時，才使用environment/cloud和environment/onprem。
  • extension、 contribution和 contributionType 需求會在安裝時進行評估，而且要求已在組織/集合中安裝並啟用指定的延伸模組。

檔案

延伸模組中您想包含的檔案，可以在 files 區段中引用。 您可以新增資料夾與個別檔案：

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

屬性

[檔案] 區段的屬性：

  • path - 磁碟上資源的路徑，其可相對於您的根目錄。
  • addressable – （選擇性） 如果您想要讓檔案成為 URL 可尋址，請將 設定 為 true 。 默認值為 false。
  • packagePath – （選擇性） 套件內資源的路徑。 預設為從根目錄開始的磁碟相對路徑。
  • contentType – 檔案的 MIME 類型。 根據副檔名和作業系統設定，預設為最佳估計。
  • assetType – （選擇性） 指定 VSIX 指令清單中資產專案之 Type 屬性的值。 也可以是字符串陣列，在這種情況下，會為此檔案新增多個資產條目。 默認為「packagePath」。
  • lang – （選擇性） 此資產的語言。 本地化的檔案是以 Accept-Language 標頭為基礎提供。 留空以表示此檔案為預設語言（或備用語言）。 相同檔案的當地語系化版本應該具有相同的 assetType。

貢獻

每個參與專案都有下列屬性：

  • id - 參與的參考識別碼（字串）。 讓每個貢獻標識碼在延伸模組內是唯一的。 請參閱 參考貢獻和類型。
  • type - 此參與的貢獻類型ID。
  • description - （選擇性）描述所提供貢獻的字串。
  • targets - 一個貢獻識別碼的陣列，作為貢獻目標（撥款對象）。 請參閱 目標參與。
  • properties - （選擇性） 物件，其中包含參與類型中所定義之參與的屬性。

如需詳細資訊，請參閱 貢獻模型概觀。

貢獻類型

每個參與專案都有下列屬性：

  • id - 參與類型的參考識別碼（字串）。 讓每個貢獻類型標識碼在延伸模組內是唯一的。 請參閱 參考貢獻和類型。
  • name - 參與類型的易記名稱。
  • description - （選擇性） 字串，更詳細地描述貢獻類型用途。
  • properties - （選擇性） 將屬性名稱對應至屬性描述的字典。 這些屬性描述此類型貢獻可使用的必需和選擇性屬性。

屬性描述具有下列屬性：

  • description - （選擇性） 描述屬性用途的字串。
  • required - （選擇性） 布爾值，如果為 true，表示此類型的所有貢獻都需要 屬性。
  • type - 屬性可以擁有的值類型，可以是字串、uri、guid、布爾值、整數、double、dateTime、array 或 物件。

如需詳細資訊，請參閱 貢獻模型概觀。

參考貢獻和類型

使用唯一標識碼來參考參與和貢獻類型。 使用型別的屬性進行參考，並使用type屬性參考其他貢獻。

  • 完整參與參考包含發行者標識碼、延伸模組標識碼和貢獻/類型標識碼，並以點 （.. ） 分隔。 例如，ms.vss-web.hub 是由「ms」（Microsoft）發行者所發布的「vss-web」延伸模組中，具有「hub」識別碼的貢獻之完整識別碼。
  • 相對 貢獻參考可能會在延伸模組指令清單內用於該相同延伸模組內對另一個貢獻或貢獻類型的參考。 在此情況下，不會包含發行者和延伸模組標識符，而且標識符是點 （.），後面接著貢獻標識符。 例如，“.hub” 可用於先前提及的 “vss-web” 延伸模組中，做為 “ms.vss-web.hub” 的快捷方式。

目標參與

某些貢獻會作為其他貢獻的目標容器。

  • 樞紐貢獻可以針對樞紐群組進行。 當頁面顯示時，Web UI 會展示針對所選中心群組的所有中心貢獻。 中樞群組是以中樞群組集合為目標，其定義一組顯示在指定導覽區域中的中樞群組，例如專案層級管理員頁面。
  • 不同類型的貢獻可以針對功能表：動作、超連結動作和動作提供者。 動作和超連結動作提供單一功能表項目。 動作提供者可以提供多個動態功能表項。 針對給定的功能表，條目會匯總至針對該特定功能表貢獻的所有（其中任何類型）參與項目。

新增中樞圖示

如需將圖示新增至首頁的資訊，請參閱首頁圖示指引。

支援的徽章服務

Marketplace 僅支持來自下列受信任服務的徽章：

  • 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」。

若要顯示另一項服務的徽章，請連絡 開發人員社群 客戶支援。

範例運送清單

以下擴充功能會在已完成的組建操作選單中新增一個動作，並在[建置中樞]群組中加入一個中樞。

{
    "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"
            }
        }
    ]
}