Справочник по манифесту расширения

Статья
03/25/2024

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

У каждого расширения есть JSON-файл манифеста, который определяет основные сведения о расширении. Файл также определяет, как он может расширить и улучшить интерфейс. В этой статье показано, как создать манифест для расширения в Azure DevOps.

Совет

Ознакомьтесь с нашей новой документацией по разработке расширений с помощью пакета SDK для расширений Azure DevOps.

Создайте файл с именем 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`.
ИД	Идентификатор расширения.	Th ID — это строка, которая должна быть уникальной среди расширений одного издателя. Он должен начинаться с алфавитного или числового символа и содержать "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	Идентификатор издателя.	Этот идентификатор должен соответствовать идентификатору, в котором публикуется расширение. См. статью "Создание и управление издателем".
Категории	Массив строк, представляющих категории, к которой принадлежит расширение. Необходимо указать по крайней мере одну категорию и не ограничивать количество категорий, которые могут быть включены.	Допустимые значения: `Azure Repos`, , `Azure BoardsAzure Pipelines`, `Azure Test Plans`и `Azure Artifacts`. Примечания: — Используйте версию >=0.6.3 tfx-cli, если вы публикуете расширение программным способом. — Если вы используете расширение "Задачи расширения " 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),- `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"
        }
    ]
}

Необязательные атрибуты

Атрибуты среды выполнения

Свойство	Описание	Основание
область	Массив разрешений область авторизации (строк), необходимых вашему расширению.	Например, и `vs.code_write` указывает, `vso.work` что расширение должно иметь доступ только для чтения к рабочим элементам и доступ на чтение и запись к исходному коду (и связанному ресурсу). Области отображаются пользователю при установке расширения. Дополнительные сведения см. в полном списке область.
Требования	Массив запросов (строк) содержит список возможностей, необходимых вашему расширению.	Например, указывает, `api-version/3.0` что расширение использует API версии 3.0 и поэтому не может работать в старых продуктах, которые не поддерживают эту версию. Дополнительные сведения см. в полном списке требований.
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` (128x128 пикселей) типа BMP, GIF, EXIF, JPG, PNG и TIFF. Другие ключи, такие как `large` (512x512 пикселей), могут поддерживаться в будущем. Значение каждого ключа — путь к файлу значка в расширении
теги	Массив строковых тегов, помогающие пользователям найти расширение.	Примеры: `agile`, `project management`, `task timer`и т. д.
Скриншоты	Массив изображений, которые не могут быть включены в содержимое.	Снимки экрана являются более ценными при использовании в вашем контенте и должны использоваться там, чтобы помочь сделать страницу сведений о рынке качества для вашего расширения. Используйте снимки экрана для менее важных изображений, которые не представлены в содержимом. Каждое изображение должно составлять 1366x768 пикселей. Каждый `path` элемент — это путь к файлу в расширении.
content	Словарь файлов содержимого, описывающих расширение для пользователей.	Каждое расширение должно содержать твердое содержимое. Вот как вы покажете пользователям, что может сделать расширение. Сделайте его богатым, потребляемым и включите снимки экрана при необходимости. `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
}

Дополнительные сведения см. в разделе "Package/Publish/Install".

Пометка расширения, который должен быть в предварительной версии

Если расширение готово для пользователей в Marketplace, но вы по-прежнему работаете с несколькими ошибками или добавлением функции, вы можете пометить его как preview:

{
    "galleryFlags": [
        "Preview"
    ]
}

Пометить расширение как платную предварительную версию

Если вы планируете продать расширение в Marketplace, пометьте его как платную предварительную версию. Расширение, помеченное бесплатно, не может быть изменено на платную.

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

Пометить расширение как платное

Если вы хотите продать расширение в Marketplace, его можно пометить флагом Paid и __BYOLENFORCED тегом (начинается с двух подчеркивания):

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

Paid Флаг и __BYOLENFORCED тег должны присутствовать, чтобы пометить расширение как платное в Marketplace. Перенос собственной лицензии (BYOL) означает, что издатель расширения предоставляет механизм выставления счетов и лицензирования расширения, так как он не предоставляется расширениями Microsoft для Azure DevOps. Все платные расширения необходимы для определения политики конфиденциальности, политики поддержки и лицензионного соглашения конечного пользователя. Кроме того, издатели должны предоставить содержимое для вкладки цен в Marketplace следующим образом:

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

Кроме того, необходимо добавить новый раздел в манифест расширения, чтобы переопределить платное лицензирование. В будущем мы удаляем платную лицензию проверка и больше не требуем переопределения. Теперь убедитесь, что расширение отображается должным образом. Каждая переопределение состоит из идентификатора и "поведения". Идентификатор должен соответствовать идентификатору вкладов, определенных в манифесте.

"licensing": {

      "overrides": [

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

Если платное расширение BYOL предлагает пробный период (рекомендуется), можно указать длину пробной версии в днях:

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

Примечание.

Если вы хотите нацелиться на Azure DevOps, но не хотите отображать параметр "Скачать " для расширения, добавьте __DoNotDownload тег (начинается с двух подчеркивания) в манифест расширения. Если вы перемещаете расширение из ранее предлагаемого выставления счетов и лицензирования от Корпорации Майкрософт к модели 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-адресом Q&A. Вы можете отключить Q&A в Marketplace с помощью свойства CustomerQnASupport в манифесте.

Интерфейс по умолчанию (изменения манифеста не требуются)

Для расширений с репозиторием GitHub Marketplace перенаправляет пользователей из раздела Q&A на связанные проблемы GitHub.
Для расширений без репозитория GitHub включена функция Q&A Marketplace.

Для использования одного из вариантов по умолчанию используйте свойство CustomerQnASupport в манифесте.

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

Свойства

Свойства раздела "Вопросы и поддержка клиента":

enablemarketplaceqna — логическое поле, для параметра true для Marketplace или пользовательского Q&A; false для отключения Q&A
URL-адрес — строка, URL-адрес для настраиваемого Q&A

Примеры использования поддержки 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`	Код (полный)	Предоставляет полный доступ к исходному коду, метаданным о фиксациях, наборах изменений, ветвях и других артефактах управления версиями. Кроме того, предоставляет возможность создавать репозитории кода и управлять ими, создавать запросы на вытягивание и проверки кода, а также получать уведомления о событиях управления версиями с помощью перехватчиков служб. Также включает ограниченную поддержку API клиентских OM.
	`vso.code_status`	Код (состояние)	Предоставляет возможность считывания и записи состояния запроса на вытягивание и фиксацию.
сервер Подключение	`vso.connected_server`	сервер Подключение	Предоставляет возможность доступа к конечным точкам, необходимым с локально подключенного сервера.
Объемы обслуживания	`vso.entitlements`	Права (чтение)	Предоставляет доступ только для чтения к конечной точке прав лицензирования для получения прав учетной записи.
	`vso.memberentitlementmanagement`	Управление MemberEntitlement (чтение)	Предоставляет возможность читать пользователей, их лицензии, а также проекты и расширения, к которые они могут получить доступ.
	`vso.memberentitlementmanagement_write`	Управление MemberEntitlement (запись)	Предоставляет возможность управлять пользователями, их лицензиями, а также проектами и расширениями, к которым они могут получить доступ.
Расширения	`vso.extension`	Расширения (чтение)	Предоставляет возможность чтения установленных расширений.
	`vso.extension_manage`	Расширения (чтение и управление)	Предоставляет возможность устанавливать, удалять и выполнять другие административные действия в установленных расширениях.
	`vso.extension.data`	Данные расширения (чтение)	Предоставляет возможность считывать данные (параметры и документы), хранящиеся установленными расширениями.
	`vso.extension.data_write`	Данные расширения (чтение и запись)	Предоставляет возможность чтения и записи данных (параметров и документов), хранящихся установленными расширениями.
Graph и identity	`vso.graph`	Graph (чтение)	Предоставляет возможность читать сведения о членстве пользователей, групп, область и групп.
	`vso.graph_manage`	Graph (управление)	Предоставляет возможность считывать сведения о членстве пользователей, групп, область и групп, а также добавлять пользователей, группы и управлять членством в группах.
	`vso.identity`	Удостоверение (чтение)	Предоставляет возможность чтения удостоверений и групп.
	`vso.identity_manage`	Удостоверение (управление)	Предоставляет возможность чтения, записи и управления удостоверениями и группами.
Группа компьютеров	`vso.machinegroup_manage`	Группа развертывания (чтение, управление)	Предоставляет возможность управления пулами групп развертывания и агентов.
Marketplace	`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`	Параметры (чтение и запись)	Предоставляет возможность создавать и читать параметры.
Символы	`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`	Группы переменных (чтение, создание и управление)	Предоставляет возможность чтения, создания групп переменных и управления ими.
Вики	`vso.wiki`	Вики-сайт (чтение)	Предоставляет возможность читать вики-страницы, вики-страницы и вики-вики-вложения. Кроме того, предоставляет возможность поиска на вики-страниц.
	`vso.wiki_write`	Вики-сайт (чтение и запись)	Предоставляет возможность читать, создавать и обновлять вики-страницы, вики-страницы и вики-вложения.
Рабочие элементы	`vso.work`	Рабочие элементы (чтение)	Предоставляет возможность считывать рабочие элементы, запросы, доски, области и пути итерации и другие связанные метаданные рабочих элементов. Кроме того, предоставляет возможность выполнять запросы, выполнять поиск рабочих элементов и получать уведомления о событиях рабочих элементов с помощью перехватчиков служб.
	`vso.work_write`	Рабочие элементы (чтение и запись)	Предоставляет возможность читать, создавать и обновлять рабочие элементы и запросы, метаданные доски обновления, области чтения и итерации пути других связанных метаданных рабочих элементов, выполнять запросы и получать уведомления о событиях рабочих элементов с помощью перехватчиков служб.
	`vso.work_full`	Рабочие элементы (полные)	Предоставляет полный доступ к рабочим элементам, запросам, невыполненной работе, планам и метаданным отслеживания рабочих элементов. Кроме того, предоставляет возможность получать уведомления о событиях рабочих элементов с помощью перехватчиков служб.
Олицетворение пользователя	`user_impersonation`	Олицетворение пользователя	Полный доступ к REST API Visual Studio Team Services. Запрос и /или согласие на это область с осторожностью, так как это очень мощно!

Изменение область опубликованного расширения

Вы можете изменить область опубликованного расширения. Если вы ранее установили расширение (и авторизировали предыдущий набор область), перед обновлением до новой версии необходимо авторизовать новые область.

В разделе "Обязательные действия" центра параметров расширения отображается пользователь, который, если есть, установленные расширения требуют авторизации:

область-change

Затем администратор может просмотреть и авторизовать новый набор область:

диалоговое окно область-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 (только RTM 2017)
Диапазон поддерживаемых версий, например [14.0) (2015 RTM и более поздних версий), [14.3,15.1] (обновление 3 до 2017 с обновлением 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.

Пример. Расширение, использующее API версии 3.0

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

Разрешает следующие целевые объекты установки:

Microsoft.VisualStudio.Services.Cloud
Microsoft.TeamFoundation.ServerВерсия: [15.0,)

Пример. Интеграция, использующая API версии 2.0

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

Разрешает следующие целевые объекты установки:

Microsoft.VisualStudio.Services.Cloud.Integration
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 (минимальная)	No	Да
`extension/{id}`	Требуется установить или включить определенное расширение.	No	Да
`contribution/{id}`	Требуется, чтобы конкретный вклад был доступен	No	Да
`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": "/"
        }
    ]
}

Свойства

Свойства раздела "Файлы":

путь — путь к ресурсу на диске, который может быть относительно корневого каталога.
адресируемый — (необязательно) Установите значение true , если вы хотите, чтобы файл был url-адресируемым. По умолчанию используется значение false.
packagePath — (необязательно) Путь к ресурсу в пакете. По умолчанию относительный путь на диске из корневого каталога.
contentType — (необязательно) тип MIME файла. По умолчанию лучше всего угадать на основе расширений файлов и параметров ОС.
assetType — (необязательно) Укажите значение атрибута Type записи ресурса в манифесте VSIX. Также может быть массив строк, в этом случае для этого файла добавляются несколько записей активов. По умолчанию используется packagePath.
lang — (необязательно) Язык этого ресурса. Локализованные файлы обслуживаются на основе заголовка Accept-Language. Оставьте пустым для обозначения этого файла язык по умолчанию (или резервный вариант). Локализованные версии одного и того же файла должны иметь тот же ресурсType.

Участие в проекте

Каждая запись вклада имеет следующие свойства:

id — идентификатор ссылки (строка) для вклада. Идентификатор каждого вклада должен быть уникальным в пределах расширения. См . ссылки на вклады и типы.
тип — идентификатор объекта contributionType этого вклада.
description — (необязательно) Строка, описывающая предоставленный вклад.
целевые показатели — массив идентификаторов вкладов, предназначенных для этого вклада (способствует). См. статью "Целевые вклады".
properties — (необязательно) Объект, содержащий свойства для вклада, как определено в типе вклада.

Дополнительные сведения см. в обзоре модели вклада.

Типы вкладов

Каждая запись вклада имеет следующие свойства:

id — идентификатор ссылки (строка) для типа вклада. Идентификатор каждого типа вклада должен быть уникальным в пределах расширения. См . ссылки на вклады и типы.
name — понятное имя типа вклада.
description — (необязательно) Строка, описывающая более подробное описание типа вклада.
properties — (необязательно) Словарь, который сопоставляет имена свойств с описаниями свойств. Эти свойства описывают обязательные и необязательные свойства, которые могут использовать вклады этого типа.

Описания свойств имеют следующие свойства:

description — (необязательно) Строка, описывающая, для чего используется свойство.
обязательный — (необязательно) логическое значение, указывающее, что свойство требуется для всех вкладов этого типа.
тип значения, которое может иметь свойство, которое может быть строкой, uri, guid, логическим числом, целым числом, double, dateTime, массивом или объектом.

Дополнительные сведения см. в обзоре модели вклада.

Ссылка на вклады и типы

Используйте уникальные идентификаторы для ссылки на вклады и типы вкладов. Ссылочные типы со свойством type и ссылки на другие вклады со свойством targets .

Полная ссылка на вклад включает идентификатор издателя, идентификатор расширения и идентификатор типа, разделенный точкой (.). Например, полный идентификатор для вклада с идентификатором "hub" в расширении vss-web, ms.vss-web.hub опубликованном издателем ms (Майкрософт).
Относительные ссылки на вклад могут использоваться в манифесте расширения для ссылки на другой вклад или тип вклада в рамках этого же расширения. В этом случае идентификаторы издателя и расширения не включаются, а идентификатор является точкой (.), за которой следует идентификатор вклада. Например, ".hub" может использоваться в расширении vss-web упоминание ранее в качестве ярлыка для ms.vss-web.hub.

Целевые вклады

Некоторые вклады действуют как контейнеры, предназначенные для других вкладов.

Вклад центра может быть предназначен для групп концентраторов. При отрисовки страницы в веб-интерфейсе отображаются все вклады Концентратора, предназначенные для выбранной группы концентраторов. Группы концентраторов нацелены на коллекцию групп концентраторов, которая определяет набор групп концентраторов, которые отображаются в заданной области навигации, например страницы администрирования уровня проекта.
Различные типы вкладов могут целевые меню: действие гиперссылки и поставщик действий. Действия и действия гиперссылки предоставляют записи в элементе единого меню. Поставщик действий может предоставлять несколько динамических элементов меню. Для данного меню элементы агрегируются во всех вкладах (любого из этих типов), предназначенных для конкретного вклада в меню.

Добавление значка концентратора

Сведения о добавлении значка в центр проверка руководства по значку концентратора.

Поддерживаемые службы индикаторов событий

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

Справочник по манифесту расширения

Требуемые атрибуты

Примеры обязательных атрибутов

Необязательные атрибуты

Атрибуты среды выполнения

Атрибуты обнаружения

Пометка общедоступного расширения

Пометка расширения, который должен быть в предварительной версии

Пометить расширение как платную предварительную версию

Пометить расширение как платное

Пример дополнительных свойств

Пример страницы сведений

Marketplace Q и A — свойство CustomerQnASupport

Свойства

Примеры использования поддержки Q и A

Пример: расширение с помощью настраиваемого Q и A

Пример. Расширение с репозиторием GitHub, но использование Marketplace Q и A вместо проблем с GitHub

Пример: расширение, отключающее раздел Q и A

Области

Поддерживаемые область

Изменение область опубликованного расширения

Целевые объекты установки

Примеры целевых объектов установки

Пример. Расширение, которое работает с Azure DevOps

Пример. Расширение, которое работает только с Azure DevOps Services

Пример. Интеграция, которая работает с Azure DevOps

Пример. Интеграция, которая работает только с Azure DevOps Server

Целевые версии установки

Примеры версий

Пример. Расширение, которое работает с Azure DevOps

Ярлыки

Использование целевых объектов установки и требований

Пример. Расширение, использующее API версии 3.0

Пример. Интеграция, использующая API версии 2.0

Требования

Поддерживаемые требования

Файлы

Свойства

Участие в проекте

Типы вкладов

Ссылка на вклады и типы

Целевые вклады

Добавление значка концентратора

Поддерживаемые службы индикаторов событий

Пример манифеста

Обратная связь

Обратная связь

Дополнительные ресурсы