Package and publish extensions

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

Once you develop your extension, 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 refer 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. You can also share the publisher 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. Enter a name in the publisher name field. The ID field should automatically get set based on the name you entered.

   

   Note

   Make note of the ID, as 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.

   

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

Package your extension

To upload your extension, 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
   

   A message displays indicating your extension is 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

Increment the version of your extension or integration in the manifest with every update.
Use the --rev-version command line switch. This switch 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 gets packaged. If it's greater than 50 MB, you need to optimize it. To do so, see the following considerations:

• Deduplicate common dependencies by stating them once in the extension package.
• Fetch dependencies at runtime or during install time rather than including them in the package. Consider using the tool installer library to pull tool dependencies at runtime. This approach caches the tool by version for private agents, preventing downloads for every build. The tool installer library doesn't work in disconnected scenarios (no internet), which should be mentioned in the task description or documentation.
• Use WebPack to tree shake dependencies in 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.

   

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.

   

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

   

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

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.

   

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

   

3. Close the panel.

Your extension can now be installed into this organization.

Install your extension

To install your shared extension, do the following steps.

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

   

   Note

   Since your extension is private, only you and members of the organization it's shared with can see this page.

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

   

3. Select Install.

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}).

2. Refresh your browser.

3. Open Organization settings, and then select Extensions.

   

You should see the new extension on the Installed tab.

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

While you develop your extension or integration for the Marketplace, keep it private. To make your extension available publicly, set the public flag to true in your manifest.

Qualifications

To have a public listing on the Marketplace, your integration or extension must meet the following qualifications:

• Works with or extends Azure DevOps.
• You, or your company, own, develop, and are licensed to distribute and advertise the integration or extension.
• The extension or integration is actively maintained.

Microsoft might also request a demo and to review the content planned for your Marketplace entry.

Top Publisher

The Top Publisher program is only available for publishers with Azure DevOps extensions or integrations. It's not applicable for Visual Studio IDE and Visual Studio Code extension publishers.

The Top Publisher program recognizes publishers with commitment to their customers and the Marketplace through exemplary policies, quality, reliability, and support. Once you become a Top Publisher, all of your public offerings display the Top Publisher badge.

Top Publisher requirements

The Top Publisher program in the Marketplace is designed to help you evaluate or acquire Azure DevOps extensions and integrations with confidence. The Top Publisher badge implies that the publisher shows commitment to their customers and the Marketplace through exemplary policies, quality, reliability, and support. It's for publishers with one or more global Azure DevOps extensions or integrations and isn't applicable for Visual Studio IDE and Visual Studio Code extension publishers.

Marketplace assigns the badge to a publisher after carefully reviewing the publisher across the following parameters:

• Privacy policy
• Licensing policy
• Support policy
• Documentation
• Q & A responsiveness
• Ratings and reviews for their offerings
• Active uptake and install count for their offerings
• Management of at least one public extension for Azure DevOps
• Public extension with more than 5,000 installs and an active install count exceeding 1000

You can expect timely support and a good overall experience when you get an extension from a Top Publisher. Check out the offerings from the Top Publishers.

For more information on adding policies to your offering, see the extension manifest.

1. Update your publisher profile.

   Through the publisher profile, you can showcase all of your offerings in one place along with key publisher-related information. To provide the information, which shows up in the profile, do the following steps:

   a. Sign in to https://marketplace.visualstudio.com/manage/publishers using the account with which you publish and manage your offerings in the Visual Studio Marketplace.

   b. Select the publisher and complete the About you section in the Details tab. c. Save your changes and select View profile to see how it appears to consumers. You can use this profile page to evangelize your offerings.

Note

This program certifies the publisher, not the software, or security of their extensions and integrations. We recommend reviewing the safety information when evaluating offerings from a publisher. If you got an extension from a Top Publisher and aren't satisfied with your experience, consider engaging with the publisher first.

Apply to be a Top Publisher

1. Sign in to Marketplace management portal using the account with which you publish and manage your offerings in Marketplace.
2. Select the publisher and go to its Top Publisher tab. Have one or more global Azure DevOps (Server/Service) extensions or integrations for the tab to appear.
3. If you meet the previously listed requirements and are the publisher's owner, you can apply for the program. Upon application, an email gets sent to the Marketplace team to review your case. They respond within 10 business days with next steps, clarifying questions, or the grant of the badge.

The team likely considers other parameters, such as active uptake of your offerings, install/get started counts, and ratings & reviews across your offerings before granting the badge. Microsoft reserves the right to grant, reject, or revoke the Top Publisher badge at any time.

Once a publisher is a Top Publisher, all its future updates and offerings must meet the previously listed requirements.

Respond to Marketplace extension reviews

You can respond to reviews that customers leave for your extensions in the Visual Studio Marketplace. Find and select Reply next to a review if you have one of the following permissions: owner, creator, or contributor.

You can leave only one response. Avoid using reviews as a support forum. If you need more details, please provide a support alias for the reviewer to contact. You can then resolve their problems externally and update your reply with a resolution.

Guidelines for publisher responses

Keep the Visual Studio Marketplace an open, inviting, respectful, and helpful place for customers to find, try, install, and review extensions. Communication plays an important role in keeping a healthy community. To help create this environment, here are guidelines for publishers responding to customer reviews. Think deeply about your customer interactions and reflect on the spirit of the customer experience that the Marketplace is trying to create.

• Reserve reviews for customer comments. Use Reply only to respond to a review.
• Respect all customer opinions. Treat comments as feedback without debate, criticism, or argument.
• Ensure your responses add value and are relevant to your customers' comments.
• Focus on precisely addressing questions or problems. If you need more details, ask the customer to contact you over email rather than discussing in reviews. When you resolve the problem, update your reply with the resolution. You can edit your reply like customers can edit their reviews.
• Flag any inappropriate reviews, such as spam, abusive, or offensive content, for our review.

Request to void a review

As a publisher, you can appeal to void a review if the issue reported is because of the Marketplace or underlying platform. If the issue is valid, Marketplace admins void the rating. You can Appeal from ratings and review section on your extension hub page.

Unpublish an extension

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

Consider removing your extension from the Marketplace in the following scenarios:

• You developed a new extension and no longer want to offer the current one.
• Your extension has a problem, and you want to remove it from the Marketplace until you resolve the issue.
• 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 might 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 Customer Support at the Developer Community. We 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, select Publish from the menu.

If your extension has zero installs, you can choose to remove it completely from the Marketplace. To do so, select Remove from the menu. You can't reverse this action.

Extension reporting hub

Once your extension is available in the Visual Studio Marketplace, you can use the Reports feature. With this feature, you can track and analyze how the extension is performing and take required actions. To visit the extension hub, browse to your publisher page and select the extension or select the Reports link on the extension details page.

Acquisition

You can view acquisition-related data in this tab for the selected period.

• Aggregated acquisition in the selected period for overall acquisition
• Aggregated acquisition split by extension downloads Azure DevOps connected install for free extension
• Aggregated acquisition split by trials Azure DevOps connected buy for paid extension
• Daily trend of extension page views with acquisition for Azure DevOps and connected server
• Conversion percentage from page views to acquisition

For paid extensions, all transactional details for buy and trials are available with date, organization name, trial end date, and quantity. You can use the Contact action to communicate with your users. For more information, see the Contact section provided later in this article.

Uninstall

You can view the following statistics:

• How many organizations uninstalled your extension
• Daily trend of uninstall extensions
• Detailed feedback shared during uninstalls
• Top uninstall reasons

You can use search for text and dates to analyze and draw more insights from the detailed feedback.

For paid extensions, you can use the Contact action to communicate with your users. Contact section provided later in this article for more details.

Ratings and review

This tab gives you the following information:

• Average rating for the selected period versus overall rating
• Average rating by number of reviewers
• Daily trend of average rating

The details section provides all the reviews and your responses in transactional view.

You can Reply to a review or Edit a previous response and better manage engagement with your extension users. You can also Appeal to void a rating if the issue reported is because of the Marketplace or underlying platform. If the issue is valid, we void the rating.

Manage engagement

The Q & A tab provides a snapshot of all questions from your extension users, with nonresponded queries at the top. You can reply to or edit previous responses to better manage engagement with your extension users.

Export to Excel

All data elements available in the reports page are also available for download in XLS format to aid creating your own custom reports.

Contact

For paid extensions, you can use the Contact action to communicate with your users. This feature is available only for publishers with Contributor+ access on the extension.

Marketplace brokers the first communication with the user as our privacy policy doesn't allow direct sharing of customer email addresses. Only users who opted in for communication receive the email. The last contacted date for an organization is updated after sending a communication.

Important

Follow the guidance on transactional and promotional communication. Publishers found to be sending promotional communication or spamming users get added to a blocklist and lose access to the Contact feature for all their extensions.

Transactional communication: Emails conveying critical information necessary for the continued use of the extension or service, such as:

• Critical security notices
• Transaction confirmations
• Product recall notices
• Specific feedback requests
• Service discontinuation notices

Promotional emails: Emails used to market your extension, product, service, website, or event, such as:

• Invitations to events or webcasts
• Information about new marketing or partner programs
• Offers to obtain value-added content
• Newsletters containing promotional content

For more information, see the Marketplace Publisher Agreement.

Terminology	Description
Page views	Total number of extension detail page views. Repeated views are counted.
Azure DevOps Services installs	Total number of organizations the extension is installed in. Repeated installs on the same organization get counted.
Azure DevOps Server installs	Total number of collections the extension is installed in. Repeated installs on the same collection get counted. Disconnected server data isn't available.

Related articles

• Develop a web extension
• Explore extensibility points