Package, publish, unpublish, and install Team Services extensions

Last Update: 4/28/2017

After writing a Visual Studio Team 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.

NOTE

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

Publishing Requirements

Below is a list of requirements that must be checked before publishing to the Marketplace.

  • Ensure the proper permissions are granted to use any images (icons, logos, screenshots, etc.).
  • Include a thorough overview.md file to describe your listing in the Marketplace.
  • Include an icon for your extension which is atleast 128x128 pixels in size.
  • When referring to Microsoft products, use full names in place of abbreviations.
    • e.g. Visual Studio Team Services vs. VSTS.
  • 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:

Marketplace card showing extension with publisher name

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 idenitifer for your publisher, for example: mycompany-myteam
      • This will be 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 click Create

Once the publisher has been created, you'll be directed to the manage items, which will have 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
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 will increment the patch version number of your extension and save the new version to your manifest.

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 will appear in the extensions list: first

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

Share

Before an extension can be installed into a Visual Studio Team Services account, it must be shared with that account. 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. Click an extension from the list of displayed items
  2. Click the Share button
  3. Specify the name of the Visual Studio Team Services account to make this extension visible to.
    • For example, to make an extension visible to the fabrikam-fiber-inc.visualstudio.com account, specify fabrikam-fiber-inc.

Install

To install an extension that has been shared:

  1. From your Team Services account 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 account category:
    Shared with me
  3. Click the card to open the item in the Marketplace
  4. From the item's details page, click the Install button
  5. Choose the account 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. Click 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 will be unpublished immediately from the Marketplace, and new users won’t be able to install it. Ratings and reviews for your extension will 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 this, choose Remove on the menu. This action cannot be undone.

Unpublish/Remove requirements

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 due to legal or security problems, contact the Marketplace team. We will review the request and manually delete the extension.

Contact

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