Package and publish extensions

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

Once you've developed your extension, then you can package and publish it to the Visual Studio Marketplace. The Marketplace is a global repository for private and public extensions, integrations, and other offers from Microsoft.

Note

For information on the discovery properties available in your extension's manifest file that helps users discover and learn about your extension, see the Extension Manifest Reference.

Prerequisites

The following list of requirements must be met before you publish to the Marketplace.

  • Install the extension packaging tool (TFX). Run npm install -g tfx-cli from a command prompt.
  • Ensure the proper permissions are granted to use any images, for example, icons, logos, screenshots, and so on.
  • Include a thorough overview.md file to describe your listing in the Marketplace.
  • Include an icon for your extension, which is at least 128x128 pixels in size.
  • When you're referring to Microsoft products, use full names in place of abbreviations, for example, Azure DevOps vs. AzDO or - any other abbreviation.
  • Refrain from using brand names in the name of your extension.

Create a publisher

All extensions and integrations, including extensions from Microsoft, have a publisher. Anyone can create a publisher and publish extensions under it. You can also give other people access to your publisher if a team is developing the extension.

A user owns the publisher, typically the user who created it. The publisher can also be shared with other users.

  1. Sign in to the Visual Studio Marketplace Publishing Portal.

  2. If you're not already a member of an existing publisher, + Create a publisher.

    1. Enter a name in the publisher name field. The ID field should automatically get set based on the name you entered.

    Screenshot showing highlighted button, Create publisher.

    Note

    Make note of the ID. You need to set it in the manifest file of your extension.

    If you're not prompted to create a publisher, scroll down to the bottom of the page and select Publish extensions below Related sites.

    • Specify an identifier for your publisher, for example: mycompany-myteam
      • This identifier is used as the value for the publisher attribute in your extension manifest file.
    • Specify a display name for your publisher, for example: My Team
  3. Review the Marketplace Publisher Agreement, and then select Create.

    Create publisher for extension

Once the publisher's create, you're directed to manage items, but there aren't any items.

Package your extension

To upload your extension, you need to package it as a VSIX 2.0-compatible .vsix file. Microsoft provides a cross-platform command-line interface (CLI) to package and publish your extension.

  1. Open your extension manifest file (vss-extension.json) and set the value of the publisher field to the ID of your publisher. For example:

    {
        ...
        "id": "my-first-extension",
        "publisher": "AnnetteNielsen",
        ...
    }
    
  2. From a command prompt, run the TFX tool's packaging command from your extension directory.

    npx tfx-cli extension create
    

    When it's completed, you see a message indicating your extension has been successfully packaged:

    === Completed operation: create extension ===
    - VSIX: C:\my-first-extension\AnnetteNielsen.my-first-extension-1.0.0.vsix
    - Extension ID: my-first-extension
    - Extension Version: 1.0.0
    - Publisher: AnnetteNielsen
    

Note

An extension/integration's version must be incremented on every update.
If you haven't incremented your extension/integration in the manifest, you should pass the --rev-version command line switch. This increments the patch version number of your extension and saves the new version to your manifest.

Check package size

Check the size of the vsix after it's packaged. If it's greater than 50 MB, you need to optimize it. To do so, see the following considerations:

  • De-duplicate the common dependencies, if any, by stating them once in the extension package.
  • Fetch things at runtime or during install time rather than providing it within the package. Consider using the tool installer lib to pull tool dependencies at runtime. Using the lib offers benefits where the tool is cached by version so for private agents, it won't get downloaded every build. We made it a lib so it can be used outside of tool installer tasks. But, the task won't work in disconnected scenarios (no internet), which should be in the description / docs for the task.
  • Some users have had success with WebPack to tree shake their dependencies in their tasks.

Publish your extension

Once your extension is packaged, you can upload it to the Marketplace under a publisher. The publisher identifier specified in your extension's manifest file must match the identifier of the publisher the extension is uploaded under.

  1. From the management portal, select your publisher from the drop-down menu at the top of the page.

  2. Select New extension > Azure DevOps.

    Screenshot showing New extension  dropdown menu and highlighted Azure DevOps selection.

  3. Drag and drop your file or select it to find your VSIX file, which you created in the previous packaging step, and then choose Upload.

    Upload new extension for Azure DevOps.

    After quick validation, your extension appears in the list of published extensions. Don't worry, the extension is only visible to you.

    Screenshot showing extension in the list of published extensions.

At this point, your extension isn't visible to any accounts and can't be installed until you share it.

Note

Microsoft runs a virus scan on each new and updated extension package published. Until the scan is all clear, we don't publish the extension in the Marketplace for public usage. This way we also avoid surfacing inappropriate or offensive content on the Marketplace pages.

Share your extension

You must share your extension with an organization before you can install it in Azure DevOps. To share an extension, do the following tasks:

  1. From the Marketplace management portal, select your extension from the list, right-click, and then choose Share/Unshare or Publish/Unpublish, depending on the extension.

    Screenshot of menu selection, Share/Unshare.

  2. Select Organization, and then enter the name of your organization. Select Enter.

    Screenshot of Enter button.

  3. Close the panel.

    Your extension can now be installed into this organization.

Install your extension

To install your extension that has been shared, do the following steps.

  1. In the Marketplace, select your extension to open its overview page.

    Screenshot of the Overview page.

Note

Because your extension is private, only you and any member of the organization it is shared with can see this page.

  1. Select Get it free to start the installation process. Select the organization you shared the extension with from the dropdown menu.

    Screenshot showing extension installation dialog.

  2. Select Install.

::: moniker-end

  1. From your organization home page, select the Marketplace icon in the top-right corner and choose Manage extensions.

    Manage Extensions

  2. Find the extension under the Shared with this organization category.

    Shared with me

  3. Select the card to open the item in the Marketplace.

  4. From the item's details page, select Install.

  5. Choose the organization you shared the extension with and continue through the installation process.

Congratulations! You installed your extension into an organization and you're ready to try it.

Try your extension

  1. Select Proceed to organization at the end of the installation wizard to go to the home page of the organization the extension was installed to (https://dev.azure.com/{organization}).
  1. Refresh your browser.

  2. Open Organization settings, and then select Extensions. You should see the new extension on the Installed tab.

    Screenshot of Organization settings, Extensions page.

  1. Open your project.

    Screenshot of project selection.

    If there aren't any projects in your organization, you're prompted to create one.

  2. Go to the Code area and then to the hub contributed by your extension (My Hub).

    My hub

You should see your new extension in the hub.

Debug your extension

To debug the extension using Visual Studio or Browser Developer Tools, change the manifest by adding the baseUri property. This action speeds up the development without the need to redeploy the extension each time you change source code.

{
    ...
    "baseUri": "https://localhost:44300",
    ...
}

When you change the manifest, it loads the extension from your local web server instance. For example, IISExpress in Visual Studio. After you change the manifest, deploy and install this debugging extension only once.

Note

Run your local web server in SSL mode because Azure DevOps demands that the web page is served from a secure source. Otherwise, you get an error in the browser console during the extension IFRAME loading.

Update your extension

To change an extension that's already published, update it.

Tip

We recommend updating the extension over removing and re-uploading. We also recommend having two extensions, for example, publisher.extension and publisher.extension-dev. Publisher.extension is public in the Marketplace, where customers can install it in their Azure DevOps organizations. Publisher.extension-dev is kept private in the Marketplace and can be shared with an organization that you own and control. You don't need to maintain two copies of source code of the extension. You can maintain two manifest files - one for each extension and during packaging of the extension you can provide the respective manifest file to the tfx-cli tool. For more information on arguments required for the tool, see TFX extension commands.

  1. Select an extension from the list of displayed items.
  2. Right-click and select Update for the publisher.extension-dev, for example.
  3. Validate your extension.
  4. Make the same updates to the production version, publisher.extension, for example.
  5. Browse to the .vsix for your extension and upload it.

The updated version of your extension automatically gets installed to accounts that have it already installed. New accounts where the extension is installed in the future also receive the latest version.

Make your extension public

For information on making your extension visible to everyone, see Make your listing public.

Unpublish an extension

You can unpublish free extensions, if you no longer want to offer them in the Marketplace.

The following scenarios cover when you might want to remove your extension from the Marketplace:

  • You developed another extension and no longer want to offer the current one.
  • Your extension has a problem, so you want to remove your extension from the Marketplace until you've resolved the problem.
  • You published your extension as public by mistake.

Certain criteria must be met for an extension to be unpublished or removed:

Action Requirements
Unpublish Only free extensions may be unpublished.
Remove Your extension must have zero (0) installs to be removed.

Important: If you must remove your extension because of legal or security problems, contact the Marketplace team. We'll review the request and manually delete the extension.

  1. Select the extension on your publisher page and choose Unpublish on the menu.

    Your extension is unpublished immediately from the Marketplace, and new users can't install it. Ratings and reviews for your extension stay intact.

To offer your extension again in the Marketplace, choose Publish on the menu.

You can also choose to remove your extension completely from the Marketplace if your extension has zero (0) installs. To do so, choose Remove on the menu. This action can't be undone.