Package, publish, unpublish, and install Azure DevOps Services extensions

• 08/29/2016
• 6 minutes to read
• • 
  • 
  • 
  • 
  • 
  • +5

After writing an Azure DevOps Services extension, the next step is to package it. After packaging, extensions are published, or uploaded, to the Visual Studio Marketplace, where they can be installed by users that the extensions are shared with. The Marketplace is a centralized, global repository for private and public extensions, integrations, and other offers from Microsoft.

Publishing Requirements

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

• Ensure the proper permissions are granted to use any images (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 Services vs. AzDO or - any other abbreviation
• Refrain from using brand names in your extension's name

Create a publisher

Every item on the Visual Studio Marketplace, including extensions and integrations, belong to a publisher.

A publisher has a unique identifier and a name. The name is displayed on the cards of items from that publisher on the Marketplace:

A publisher is owned by a user, typically the user that created it, and can also be shared with other users.

1. Sign in to the Visual Studio Marketplace Publishing Portal
2. If you are not already a member of an existing publisher, you'll be prompted to create a publisher. If you're not prompted to create a publisher, scroll down to the bottom of the page and select Publish Extensions underneath Related Sites.
   • Specify an identifer for your publisher, for example: mycompany-myteam
     • This is used as the value for the publisher attribute in your extensions' manifest file.
   • Specify a display name for your publisher, for example: My Team
3. Review the Marketplace Publisher Agreement and select Create

Once the publisher has been created, you're directed to manage items, which has no items.

Package

Extensions are packaged as VSIX 2.0-compatible .vsix files. 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 also publish) your extension.

Get the package tool (tfx-cli)

You can install or update the TFS Cross Platform Command Line Interface (tfx-cli) using npm, a component of Node.js, from your command line.

npm i -g tfx-cli

Package your extension in a .vsix file

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

Check package size

Check the size of the vsix after it is packaged. If greater than 50 MB then it needs to be optimized. To do so, consider the following:

• De-duplicate the common dependences, 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. The one consideration, is the task will not work in disconnected scenarios (no internet). That should just be in the description / docs for the task.
• Some customers have had good success with WebPack to tree shake their dependencies in their tasks.

Publish

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

To upload an extension to the Marketplace:

1. Navigate to the Visual Studio Marketplace Publishing Portal
2. Find the Upload new extension button, navigate to your packaged .vsix file, and select upload.
3. After a quick validation, your extension appears in the extensions list:

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

Protective Scans

As a Marketplace user, one expects to not get malicious software (malware) when they acquire an extension from Visual Studio Marketplace. To ensure this, we run a virus scan on each extension package published. This is performed for each new extension and for each extension update. Until the scan is all clear, we do not publish the extension in Marketplace for public usage.

Stated virus scan is run at extension publish only and not during extension's execution.

We also perform a content scan for each extension in Marketplace. This is performed for each new extension and for each extension update. Through this we avoid surfacing inappropriate or offensive content on the Marketplace pages.

Share

Before an extension can be installed into an organization in Azure DevOps Services, it must be shared with that organization. Sharing is a requirement during development and testing of an extension, as it is the only way to run an extension.

To share an extension so it can be installed:

1. Select the ellipses of an extension item to bring up the menu

2. Select the Share button

   

3. Specify the name of the organization to make this extension visible to

   • For example, to make an extension visible to the dev.azure.com/fabrikam-fiber-inc organization, specify fabrikam-fiber-inc.

Install

To install an extension that has been shared:

1. From your organization home page, select the Marketplace icon in the top right corner and choose "Manage Extensions":

   

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

   

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

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

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

Update

To change an extension that has already been published, update it.

Updating is recommended over removing and re-uploading.

1. Select an extension from the list of displayed items.
2. Right-click and select Update.
3. Browse to the .vsix for your extension and upload it.

The updated version of your extension is automatically 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 (visible to everyone)

For information on making your extension public, visit Make your listing public.

Unpublish

You can unpublish/delist free extensions, if you no longer want to offer them in the Marketplace or published by mistake.

Here are some scenarios where 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 have resolved the problem.
• You published your extension as public by mistake.

To unpublish, select the extension on your publisher page and choose Unpublish on the menu. Your extension is unpublished immediately from the Marketplace, and new users won't be able to install it. Ratings and reviews for your extension stays 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 this, choose Remove on the menu. This action can't be undone.

Unpublish/Remove requirements

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

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

Contact

Send questions about publishing items to the Visual Studio Marketplace to vsmarketplace@microsoft.com.