Бөлісу құралы:


Упаковка и публикация интеграции в Marketplace

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

У вас есть инструмент, служба или продукт, который интегрируется с Azure DevOps или Team Foundation Server (TFS)? В этом случае помогите пользователям найти его, публикуя его в Visual Studio Marketplace. Marketplace — это однократный магазин для частных лиц и команд, чтобы найти инструменты, расширяющие и расширяющие возможности.

Просмотрите Marketplace примеры других интеграции и расширений.

Примечание.

Если вы ищете сведения о упаковке и публикации расширений, проверка из пакетов и расширений публикации.

Требования к публикации

Перед публикацией в Marketplace необходимо выполнить следующий список требований.

  • Установите средство упаковки расширений (TFX). Запустите npm install -g tfx-cli из командной строки.
  • Убедитесь, что необходимые разрешения предоставляются для использования изображений, например значков, логотипов, снимков экрана и т. д.
  • Добавьте подробный overview.md файл, чтобы описать список в Marketplace.
  • Добавьте значок расширения, размер которого составляет не менее 128x128 пикселей.
  • Если вы ссылаетесь на продукты Майкрософт, используйте полные имена вместо аббревиаций, например Azure DevOps и AzDO или любую другую аббревиацию.
  • Воздерживайтесь от использования фирменной марки в имени вашего расширения.

Необходимые элементы

  1. Логотип пикселя 128x128 (формат PNG или JPEG), представляющий интеграцию, самостоятельно или вашу компанию или организацию
  2. Не менее одного снимка экрана, на котором показана интеграция
  3. Вызов действия или URL-адрес начала работы (где пользователи должны начать работу с интеграцией)

Шаги

Публикация в Marketplace — это итеративный процесс, который начинается с создания файла манифеста, который определяет характеристики интеграции и обнаружения ключей (например, снимки экрана, логотипы и содержимое обзора). Эта информация используется для представления интеграции пользователям в Marketplace, например:

Пример

Jenkins для Azure DevOps

Примечание. Термин используется extensionв документации, указанной ниже. Расширения — это другой тип элемента Marketplace и совместное использование множества сходств с точки зрения обнаружения в качестве интеграции.

Нужна помощь в получении интеграции в Marketplace? Связаться с нами. И, да, этот адрес электронной почты отслеживается реальными людьми.

Создание издателя

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

Пользователь владеет издателем, как правило, пользователем, создавшим его. Вы также можете поделиться издателем с другими пользователями.

  1. Войдите на портал публикации Visual Studio Marketplace.

  2. Если вы еще не являетесь членом существующего издателя, и создайте издателя. Введите имя в поле имени издателя. Поле идентификатора должно автоматически задаваться в зависимости от введенного имени.

    Снимок экрана: выделенная кнопка

    Примечание.

    Запишите идентификатор, так как его необходимо задать в файле манифеста расширения.

    Если вам не предлагается создать издателя, прокрутите вниз до нижней части страницы и выберите "Опубликовать расширения" под связанными сайтами.

    • Укажите идентификатор издателя, например: mycompany-myteam Этот идентификатор используется в качестве значения атрибута в файле манифеста publisher расширения.
    • Укажите отображаемое имя издателя, например: My Team
  3. Просмотрите соглашение издателя Marketplace и нажмите кнопку "Создать".

    Создание издателя для расширения

После создания издателя вы будете перенаправлены для управления элементами, но нет элементов.

Создание папки для хранения манифеста элемента и других ресурсов

Прежде чем упаковать интеграцию в качестве расширения, необходимо создать папку home для хранения некоторых необходимых ресурсов в этой папке:

  1. Создайте папку, вызываемую images для хранения:
    • Логотип для интеграции (128x128 пикселей)
    • Снимки экрана (1366x768 пикселей)
  2. Создание файла с именем overview.md
    • Описание интеграции здесь
    • Дополнительные сведения о Markdown см. в статье GitHub Flavored Markdown
  3. Создание файла с именем vss-integration.json
    • Этот файл — это файл манифеста в Marketplace, который содержит множество свойств для описания расширения в списке Marketplace. Здесь можно просмотреть ссылку на манифест расширения.

Манифест расширения

  1. vss-integration.json Заполните файл следующим кодом JSON:

    {
        "manifestVersion": 1,
        "id": "myservice",
        "version": "1.0.0",
        "name": "My Service",
        "publisher": "mycompany",
        "description": "Awesome tools to help you and your team do great things everyday.",
        "targets": [
            {
                "id": "Microsoft.VisualStudio.Services.Integration"
            }
        ],    
        "icons": {
            "default": "images/service-logo.png"
        },
        "categories": [
            "Plan and track"
        ],
        "tags": [
            "working",
            "people person",
            "search"
        ],
        "screenshots": [
            {
                "path": "images/screen1.png"
            },
            {
                "path": "images/screen2.png"
            }
        ],
        "content": {
            "details": {
                "path": "overview.md"
            },
            "license": {
                "path": "fabrikam-license-terms.md"
            }
        },
        "links": {
            "getstarted": {
                "uri": "https://www.mycompany.com/help/getstarted"
            },
            "learn": {
                "uri": "https://www.mycompany.com/features"
            },
            "support": {
                "uri": "https://www.mycompany.com/support"
            }
        },
        "branding": {
            "color": "rgb(34, 34, 34)",
            "theme": "dark"
        }
    }
    
  2. Обновите JSON с помощью следующей ссылки:

Эти свойства обязательны:

Свойство Описание Основание
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)

Эти необязательные свойства помогают пользователям обнаруживать и узнать о расширении:

Свойство Описание Основание
описание Несколько предложений, описывающих расширения. Ограничено 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 — дополняет цвет; используйте темные цвета фирменной символики или свет для более светлых цветов фирменной символики.

Страница сведений

  • 1 — описание
  • 2 — значок
  • 3 — категории
  • 4 — снимки экрана
  • 5 — содержимое (подробности)
  • 6 — ссылки
  • 7 — фирменная символика

карта

Убедитесь, что атрибут public получает значение false (или не задан вообще), чтобы избежать преждевременного появления расширения или интеграции для всех пользователей в Marketplace.

Упаковка манифеста и ресурсов

Получение средства пакета (tfx-cli)

Вы можете установить или обновить кроссплатформенный интерфейс командной строки для Azure DevOps (tfx-cli) с помощью npmкомпонента Node.js из командной строки.

npm i -g tfx-cli

Упаковка интеграции в VSIX-файле

tfx extension create --manifest-globs vss-extension.json

Примечание.

При каждом обновлении необходимо увеличить версию расширения или интеграции.
Если вы не добавили расширение или интеграцию в манифесте, передайте переключатель командной --rev-version строки. Это увеличивает номер версии исправления расширения и сохраняет новую версию в манифесте.

Публикация интеграции в Marketplace

После упаковки расширения его можно отправить в Marketplace под издателем. Идентификатор publisher , указанный в файле манифеста расширения, должен соответствовать идентификатору издателя, в котором отправляется расширение.

  1. На портале управления выберите издателя в раскрывающемся меню в верхней части страницы.

  2. Выберите новое расширение>Azure DevOps.

    Снимок экрана: раскрывающееся меню нового расширения и выделен выбор Azure DevOps.

  3. Перетащите файл или выберите его, чтобы найти файл VSIX, созданный на предыдущем шаге упаковки, а затем нажмите кнопку "Отправить".

    Снимок экрана: отправка нового расширения для Azure DevOps.

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

    Снимок экрана: расширение в списке опубликованных расширений.

На этом этапе расширение не отображается для учетных записей и не может быть установлено до тех пор, пока вы не поделились им.

Примечание.

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

Общий доступ к интеграции

Прежде чем установить интеграцию с организацией в Azure DevOps или TFS, необходимо поделиться ею с этой организацией. Общий доступ — это требование во время разработки и тестирования интеграции, так как это единственный способ выполнения интеграции.

Чтобы предоставить общий доступ к интеграции, выполните следующие задачи:

  1. Выбор интеграции из списка отображаемых элементов
  2. Нажмите кнопку "Общий доступ"
  3. Укажите имя организации, чтобы сделать эту интеграцию видимой.
    • Например, чтобы сделать интеграцию видимой для организации dev.azure.com/fabrikam-fiber-inc , укажите fabrikam-fiber-inc.

Обновление элемента

Чтобы изменить уже опубликованное расширение, обновите его.

Совет

Рекомендуется обновить расширение при удалении и повторной отправке. Мы также рекомендуем использовать два расширения, напримерpublisher.extension.publisher.extension-dev Publisher.extension является общедоступным в Marketplace, где клиенты могут установить его в своих организациях Azure DevOps. Publisher.extension-dev хранится в закрытом режиме в Marketplace и может быть предоставлен общий доступ к организации, которой вы владеете и управляете. Вам не нужно поддерживать две копии исходного кода расширения. Вы можете поддерживать два файла манифеста — по одному для каждого расширения и во время упаковки расширения можно предоставить соответствующий файл манифеста средству tfx-cli. Дополнительные сведения о аргументах, необходимых для средства, см. в командах расширения TFX.

  1. Выберите расширение из списка отображаемых элементов.
  2. Щелкните правой кнопкой мыши и выберите пункт "Обновить " для publisher.extension-devпримера.
  3. Проверьте расширение.
  4. Например, publisher.extensionвнесите те же обновления в рабочую версию.
  5. Перейдите к VSIX для расширения и отправьте его.

Обновленная версия расширения автоматически устанавливается в учетные записи, которые уже установлены. Новые учетные записи, в которых расширение установлено в будущем, также получают последнюю версию.

Сделать интеграцию общедоступной (видимой для всех)

Сведения о том, как сделать интеграцию общедоступной, см. в разделе "Сделать список общедоступным".