拡張機能マニフェスト リファレンス

  • [アーティクル]

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

必須の属性

次のプロパティが必要です。

プロパティ 説明 メモ
manifestVersion マニフェスト形式のバージョンに対応する数値。 1 でなければなりません。
ID 拡張機能の識別子。 ID は、同じ発行元の拡張機能間で一意である必要がある文字列です。 アルファベットまたは数字で始まり、'A' から 'Z'、'a' から 'z'、'0' から '9'、および '-' (ハイフン) を含める必要があります。 例: sample-extension。
version 拡張機能のバージョンを指定する文字列。 などの0.1.21.0.0形式major.minor.patchにする必要があります。 次の形式の 4 番目の数値を追加することもできます。 0.1.2.3
name 人間が判読できる拡張機能の短い名前。 200 文字に制限されます。 例: "Fabrikam Agile Board Extension"。
publisher 発行元の識別子。 この識別子は、拡張機能が公開されている識別子と一致する必要があります。 パブリッシャーの作成と管理に関するページを参照してください。
カテゴリ 拡張機能が属するカテゴリを表す文字列の配列。 少なくとも 1 つのカテゴリを指定する必要があり、含めるカテゴリの数に制限はありません。 有効な値: 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"
        }
    ]
}

省略可能な属性

ランタイム属性

プロパティ 説明 メモ
scopes 拡張機能に必要なアクセス許可を一覧表示する承認スコープ (文字列) の配列。 たとえば、 vso.workvs.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"
            }
        }
    ]
}

探索属性

これらの省略可能なプロパティは、ユーザーが拡張機能を検出して学習するのに役立ちます。

プロパティ 説明 メモ
説明 拡張機能を説明するいくつかの文。 200 文字に制限されます。 説明は、拡張機能の "エレベーター ピッチ" である必要があります。これは、Marketplace で拡張機能を説明し、ユーザーがそれをインストールすることを望むいくつかの行です。 以下の の例を参照する
アイコン 拡張機能を表すアイコンのディクショナリ。 有効なキー: default BMP、GIF、EXIF、JPG、PNG、TIFF 型の (128 x 128 ピクセル)。 (512 x 512 ピクセル) などの large 他のキーは、今後サポートされる可能性があります。 各キーの値は、拡張機能内のアイコン ファイルへのパスです
tags ユーザーが拡張機能を見つけるのに役立つ文字列タグの配列。 例: agile、 project management、、 task timer、など。
スクリーン ショット コンテンツに含められなかった画像の配列。 スクリーンショットはコンテンツで取り上げられるほど価値が高く、拡張機能の質の高い市場の詳細ページを作成するために使用する必要があります。 コンテンツに含まれていない重要度の低い画像には、スクリーンショットを使用します。 各イメージは 1366 x 768 ピクセルである必要があります。 各項目の path パスは、拡張子内のファイルへのパスです。
content ユーザーに対する拡張機能を記述するコンテンツ ファイルのディクショナリ。 すべての 拡張機能には、ソリッド コンテンツが含まれている必要があります。 これは、拡張機能で実行できることをユーザーに表示する方法です。 必要に応じて、豊富で消耗品なスクリーンショットを含めます。 overview.md基本コンテンツの部分としてファイルを含めます。 各ファイルは、GitHub Flavored Markdown 形式であると見なされます。 各項目の path パスは、拡張機能の Markdown ファイルへのパスです。 有効なキー: details. その他のキーは、今後サポートされる可能性があります。
リンク ユーザーが拡張機能の詳細を知り、サポートを受け、移動するのに役立つリンクの辞書。 有効なキー: getstarted - 最初の手順、セットアップまたは使用方法。 learn - ユーザーが拡張機能やサービスをより深く理解するのに役立つより深いコンテンツ。 license - エンドユーザーライセンス契約。 privacypolicy - 拡張機能のプライバシー ポリシー。 support - 拡張機能のヘルプとサポートを受ける。 各キーの値は、リンクの絶対 URL であるフィールドを持つ uri オブジェクトです
リポジトリ 拡張機能のソース コード リポジトリを記述するプロパティのディクショナリ 有効なキー: type - リポジトリの種類。 例: git。 uri - リポジトリの絶対 URL。
バッジ 承認されたバッジ サイトから、TravisCI、Appveyor などの外部メタデータ バッジへのリンクの 配列 有効なキー: href - バッジを選択するときにユーザーが移動するリンク。 uri - 表示するバッジ画像の絶対 URL。 description - ホバー時に表示されるバッジの説明。
ブランド ブランド関連のプロパティの辞書。 有効なキー: color - 拡張機能または発行元の主色。16 進数 (#ff00ff)、RGB (rgb(100,200,50))、またはサポートされている HTML カラー名 (青) を指定できます。 theme- 色を補完します。暗いブランドの色には濃色を使用し、明るいブランド色には明るい色を使用します。

拡張機能をパブリックにマークする

既定では、Azure DevOps Marketplace 内のすべての拡張機能はプライベートです。 公開元とパブリッシャーが共有するアカウントにのみ表示されます。 発行元が検証された場合は、拡張機能マニフェストでフラグを Public 設定することで、拡張機能をパブリックにすることができます。

{
    "galleryFlags": [
        "Public"
    ]
}

または:

{
    "public": true
}

詳細については、「パッケージ/発行/インストール」を参照してください。

拡張機能をプレビュー段階に設定する

Marketplace のユーザーが拡張機能を試す準備ができているが、まだいくつかのバグを解決したり、関数を追加したりする場合は、次のように previewマークできます。

{
    "galleryFlags": [
        "Preview"
    ]
}

拡張機能を有料プレビューとしてマークする

Marketplace で拡張機能を販売する場合は、有料プレビューとしてマークします。 無料としてマークされた拡張機能を有料に変更することはできません。

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

拡張機能を有料としてマークする

Marketplace で拡張機能を販売する場合は、フラグと__BYOLENFORCEDタグ (2 つのアンダースコアで始まる) でマークPaidできます。

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

Marketplace で拡張機能を Paid 有料としてマークするには、フラグと __BYOLENFORCED タグの両方が存在する必要があります。 ライセンス持ち込み (BYOL) は、拡張機能の発行元が、Azure DevOps 拡張機能用に Microsoft によって提供されていないため、拡張機能の課金とライセンスのメカニズムを提供することを意味します。 プライバシー ポリシー、サポート ポリシー、およびエンドユーザーライセンス契約を定義するには、すべての有料拡張機能が必要です。 また、パブリッシャーは、Marketplace の [価格] タブのコンテンツを次のように提供する必要があります。

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

また、有料ライセンスをオーバーライドするには、拡張機能マニフェストに新しいセクションを追加する必要があります。 今後、有料ライセンス チェックを削除し、オーバーライドは不要になります。 ここでは、拡張機能が期待どおりに表示されていることを確認します。 各オーバーライドは、"ID" と "動作" で構成されます。 "ID" は、マニフェストで定義されているコントリビューションの ID と一致する必要があります。

"licensing": {

      "overrides": [

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

有料の BYOL 拡張機能で試用期間が提供されている場合 (お勧めします)、試用期間を日数で指定できます。

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

Note

Azure DevOps をターゲットにしたいが、拡張機能のダウンロード オプションを表示したくない場合は、タグ (2 つのアンダースコアで始まる) を拡張機能マニフェストに追加__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

Marketplace Q & A - CustomerQnASupport プロパティ

Visual Studio Marketplace のすべての拡張機能には、拡張機能ユーザーとパブリッシャーの間で 1 対 1 のパブリック会話を許可する Q&A セクションがあります。 パブリッシャーは、Marketplace の Q&A、GitHub の問題、またはカスタムの Q&A URL を選択できます。 マニフェストの CustomerQnASupport プロパティを使用して、Marketplace で Q&A を無効にすることができます。

既定のエクスペリエンス (マニフェストへの変更は必要ありません)

  • GitHub リポジトリを使用する拡張機能の場合、Marketplace は Q&A セクションのユーザーを関連する GitHub の問題にリダイレクトします。
  • GitHub リポジトリのない拡張機能の場合、Marketplace Q&A が有効になります。

既定のオプションとは異なるエクスペリエンスの場合は、マニフェストで CustomerQnASupport プロパティを使用します。

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

プロパティ

[カスタマー Q & A サポート] セクションのプロパティ:

  • enablemarketplaceqna - marketplace の場合は true に設定、Q&A を無効にする場合は false に設定されたブール型フィールド
  • url - 文字列、カスタム Q&A の URL

Q と A のサポートの使用状況を示す例

例: カスタム Q と A を使用した拡張機能

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

例: GitHub リポジトリを使用した拡張機能が、GitHub の問題ではなく Marketplace Q & A を使用する

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

例: Q セクションと A セクションを無効にする拡張機能

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

スコープ

拡張機能では、1 つ以上のスコープを定義できます。 これらのスコープによって、拡張機能がアクセスできるリソースと、それらのリソースに対する実行が許可される操作が決まります。 拡張機能マニフェストで指定するスコープは、拡張機能に発行されたアクセス トークンに設定されたスコープです。 詳細については、「認証とセキュリティ」を参照してください。

スコープが指定されていない場合、拡張機能にはユーザー プロファイルと拡張機能データへのアクセスのみが提供されます。

サポートされているスコープ

カテゴリ 範囲 名前 説明
エージェント プール 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 (書き込み) ユーザー、ライセンス、およびアクセスできるプロジェクトと拡張機能を管理する権限を付与します。
拡張機能 vso.extension 拡張機能 (読み取り) インストールされている拡張機能を読み取る権限を付与します。
vso.extension_manage 拡張機能 (読み取りと管理) インストールされている拡張機能のインストール、アンインストール、その他の管理操作の実行を許可します。
vso.extension.data 拡張機能データ (読み取り) インストールされている拡張機能によって格納されたデータ (設定とドキュメント) を読み取る機能を付与します。
vso.extension.data_write 拡張データ (読み取りと書き込み) インストールされている拡張機能によって格納されているデータ (設定とドキュメント) の読み取りと書き込みを行う機能を付与します。
グラフと ID vso.graph グラフ (読み取り) ユーザー、グループ、スコープ、およびグループ メンバーシップ情報を読み取る機能を付与します。
vso.graph_manage グラフ (管理) ユーザー、グループ、スコープ、およびグループ メンバーシップ情報を読み取り、ユーザー、グループ、およびグループ メンバーシップを追加する機能を付与します。
vso.identity ID (読み取り) ID とグループを読み取る機能を付与します。
vso.identity_manage ID (管理) ID とグループの読み取り、書き込み、管理を行う機能を付与します。
マシン グループ vso.machinegroup_manage 展開グループ (読み取り、管理) デプロイ グループとエージェント プールを管理する機能を提供します。
Marketplace vso.gallery マーケットプレース パブリックおよびプライベートのアイテムとパブリッシャーへの読み取りアクセスを許可します。
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 ファイルのセキュリティ保護 (読み取り、作成、管理) セキュリティで保護されたファイルの読み取り、作成、管理を行う機能を付与します。
Security vso.security_manage セキュリティ (管理) セキュリティアクセス許可の読み取り、書き込み、管理を行う権限を付与します。
サービス接続 vso.serviceendpoint サービス エンドポイント (読み取り) サービス エンドポイントを読み取る機能を付与します。
vso.serviceendpoint_query サービス エンドポイント (読み取りとクエリ) サービス エンドポイントの読み取りとクエリを実行する機能を付与します。
vso.serviceendpoint_manage サービス エンドポイント (読み取り、クエリ、管理) サービス エンドポイントの読み取り、クエリ、管理を行う機能を付与します。
Settings 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 トークン 管理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.CloudMicrosoft.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.ServerMicrosoft.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,)"
        }
    ]
}

インストールのターゲットと要求の使用

インストールターゲットと需要は、拡張機能または統合が互換性のある製品/サービスの正しいビューをユーザーに提示するために一緒に使用されます。 たとえば、インストール 先 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 クラウド環境で実行する必要がある はい はい
environment/onprem オンプレミス環境で実行する必要がある はい はい
api-version/{version} 特定の API バージョンが必要です (最小) いいえ はい
extension/{id} 特定の拡張機能をインストールまたは有効にする必要があります いいえ はい
contribution/{id} 特定のコントリビューションが使用可能である必要がある いいえ はい
contributionType/{id} 特定の投稿の種類を使用できる必要があります いいえ イエス

Note

  • 拡張機能に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 - コントリビューションの参照 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" は、以前に "ms.vss-web.hub" のショートカットとしてメンションされた "vss-web" 拡張機能内で使用できます。

ターゲット設定コントリビューション

一部のコントリビューションは、他のコントリビューションの対象となるコンテナーとして機能します。

  • ハブ コントリビューションは、ハブ グループをターゲットにすることができます。 ページがレンダリングされると、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/
  • isitメインtained.com/
  • marketplace.visualstudio.com/
  • snyk.io/
  • travis-ci.com/
  • travis-ci.org/
  • vsmarketplacebadges.dev/
  • bithound.io/
  • deepscan.io/
  • githost.io/
  • gitlab.com/
  • opencollective.co/

Note

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