延伸模組指令清單參考

  • 發行項

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。
識別碼 延伸模組的標識碼。 此標識碼是一個字串，在相同發行者的延伸模塊之間必須是唯一的。 它必須以字母或數值字元開頭，並包含 'A' 到 'Z'、'a' 到 'z'、'0' 到 '9' 和 '-' （連字元）。 範例：sample-extension。
version 指定延伸模組版本的字串。 格式 major.minor.patch應為 ，例如 0.1.2 或 1.0.0。 您也可以針對下列格式新增第四個數位： 0.1.2.3
name 延伸模組的簡短人類可讀取名稱。 限制為200個字元。 範例："Fabrikam Agile Board Extension"。
publisher 發行者的標識碼。 此標識碼必須符合發佈擴充功能的標識碼。 請參閱 建立和管理發行者。
categories 字串數位，代表延伸模組所屬的類別。 至少必須提供一個類別，而且您可能包含的類別數目沒有限制。 有效值： 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}}/ 。 如果您的延伸模組的內容是使用延伸模組封裝，則此屬性應該保留空白。
貢獻 對系統的貢獻陣列。
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"
            }
        }
    ]
}

探索屬性

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

屬性 描述 附註
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 上銷售延伸模組，您可以使用 旗標和__BYOLENFORCED標籤標記它Paid（開頭為兩個底線）：

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

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

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

您也需要在延伸模組指令清單中新增區段，以覆寫付費授權。 未來，我們會移除付費授權檢查，而不再需要覆寫。 目前，請確定您的擴充功能如預期般顯示。 每個覆寫都包含「標識碼」和「行為」。 “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 - CustomerQnASupport 属性

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

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

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

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

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

屬性

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

  • enablemarketplaceqna - 布爾值字段，針對 Marketplace 或自定義 Q&A 設定為 true;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.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 （read） 授與讀取使用者、其授權，以及他們可存取的專案和延伸模組的能力。
vso.memberentitlementmanagement_write MemberEntitlement Management （write） 授與管理使用者、其授權，以及他們可存取的專案和延伸模組的能力。
擴充 vso.extension 延伸模組（讀取） 授與讀取已安裝擴充功能的能力。
vso.extension_manage 延伸模組 （讀取和管理） 授與在已安裝擴充功能上安裝、卸載及執行其他系統管理動作的能力。
vso.extension.data 延伸模組資料（讀取） 授與讀取已安裝延伸模組所儲存之數據（設定和檔）的能力。
vso.extension.data_write 延伸模組資料（讀取與寫入） 授與讀取和寫入已安裝延伸模組所儲存之數據（設定和檔）的能力。
圖形和身分識別 vso.graph 圖表（讀取） 授與讀取使用者、群組、範圍和群組成員資格資訊的能力。
vso.graph_manage 圖表（管理） 授與讀取使用者、群組、範圍和群組成員資格資訊的能力，以及新增使用者、群組和管理群組成員資格的能力。
vso.identity 身分識別（讀取） 授與讀取身分識別和群組的能力。
vso.identity_manage 身分識別（管理） 授與讀取、寫入及管理身分識別和群組的能力。
機器群組 vso.machinegroup_manage 部署群組 （讀取、管理） 提供管理部署群組和代理程式集區的能力。
市場平台 vso.gallery Marketplace 授與公用和私人項目和發行者的讀取許可權。
vso.gallery_acquire Marketplace （取得） 授與讀取許可權，以及取得專案的能力。
vso.gallery_publish Marketplace （發佈） 授與讀取許可權，以及上傳、更新和共享專案的能力。
vso.gallery_manage Marketplace （管理） 授與讀取許可權，以及發佈和管理專案和發行者的能力。
通知 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 設定 （讀取和寫入） 授與建立和讀取設定的能力。
Symbols 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 Token 管理員 istration 授與管理現有令牌的能力（檢視和撤銷）給組織系統管理員。
使用者設定檔 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.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 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 需要在雲端環境中執行 Yes Yes
environment/onprem 需要在內部部署環境中執行 Yes Yes
api-version/{version} 需要特定 API 版本（最小值） No Yes
extension/{id} 需要安裝/啟用特定擴充功能 No Yes
contribution/{id} 需要提供特定貢獻 No Yes
contributionType/{id} 需要特定貢獻類型可供使用 No .是

注意

  • 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 - 磁碟上資源的路徑，其可相對於您的根目錄。
  • addressable – （選擇性） 如果您想要讓檔案成為 URL 可尋址，請將 設定 為 true 。 默認值為 false。
  • packagePath – （選擇性） 套件內資源的路徑。 預設為根目錄中磁碟上的相對路徑。
  • contentType – 檔案的 MIME 類型。 根據擴展名和OS設定，預設為最佳猜測。
  • assetType – （選擇性） 指定 VSIX 指令清單中資產專案之 Type 屬性的值。 也可以是字串數位，在此情況下，會為此檔案新增多個資產專案。 默認為 packagePath。
  • lang – （選擇性） 此資產的語言。 本地化的檔案是以 Accept-Language 標頭為基礎提供。 保留空白以表示此檔案為預設語言（或後援）。 相同檔案的當地語系化版本應該具有相同的 assetType。

投稿文章

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

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

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

貢獻類型

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

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

屬性描述具有下列屬性：

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

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

參考貢獻和類型

使用唯一標識碼來參考參與和貢獻類型。 具有 屬性的type參考型別，並使用 屬性參考其他參與targets專案。

  • 完整參與參考包含發行者標識碼、延伸模組標識碼和貢獻/類型標識碼，並以點 （.. ） 分隔。 例如， 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」。

若要顯示來自其他服務的徽章，請連絡 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"
            }
        }
    ]
}