Package and publish extensions

TFS 2017

Once you've written your extension, the next step is to package it. Then, you publish or upload it to the Visual Studio Marketplace. Users can install the extension from the Marketplace if it's shared with them. 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.

• 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 the name of your extension

Create a publisher

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

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're not already a member of an existing publisher, you're 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 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.

   

Once the publisher's created, you're directed to manage items, which have no items.

Package an extension

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 publish) your extension.

Get the package tool (tfx-cli)

You can install or update the Cross-platform CLI for Azure DevOps (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 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 then it needs to be optimized. 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 customers have had good success with WebPack to tree shake their dependencies in their tasks.

Publish an extension

Once your extension is 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 isn't 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 an extension

An extension must be shared with an organization before you can install it in Azure DevOps or TFS. Sharing is a requirement during development and testing of an extension, as it's the only way to run an extension.

To share an extension, do the following tasks:

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 an extension

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 continue through the installation process.

Update an 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 (visible to everyone)

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

Unpublish an extension

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've 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 can't 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 so, choose Remove on the menu. This action can't be undone.

Unpublish or remove extension 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 because of legal or security problems, contact the Marketplace team. We'll review the request and manually delete the extension.

Contact

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