Package and Publish an integration to the Marketplace

Last Update: 3/28/2017

Do you have a tool, service, or product that integrates with Visual Studio Team Services or Team Foundation Server? If so, help users find it by publishing it on the Visual Studio Marketplace. The Visual Studio Marketplace is a one-stop-shop for individuals and teams to find tools that extend and enhance the experience.

Browse the marketplace to see examples of other integrations and extensions.

Note: If you're looking for packaging and publishing information for extensions, check out Package & Publish Extensions.

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.

What you will need

  1. 128x128 pixel logo (PNG or JPEG format) representing your integration, yourself, or your company/organization
  2. Minimum of 1 screen shot showing your integration
  3. Call to action / get started URL (where users should go to get started with your integration)

Steps

Publishing to the Marketplace is an iterative process that starts with creating a manifest file that defines your integration and key discovery characteristics (like screen shots, logos, and overview content). This information is used to present your integration to users on the Marketplace, for example:

example

Jenkins for Visual Studio Team Services

Note: you will see the term extension used in documentations referenced below. Extensions are another type of Marketplace item and share many similarities from a discovery standpoint as integrations.

Need help getting your integration on the Marketplace? Contact us. And, yes, this e-mail address is monitored by real people.

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.

Create a folder to contain your item manifest and other assets

Before you package your integration as an extension, you'll need to create a home folder to contain some required assets, within this folder:

  1. Create a folder called images to contain:
    • Logo for your integration (128x128 pixels)
    • Screen shots (1366x768 pixels)
  2. Create a file called overview.md
  3. Create a file called vss-integration.json
    • This is your Marketplace listing's manifest file, it contains many properties to describe your extension in your Marketplace listing. You can browse the extension manifest reference here

Extension Manifest

  1. Fill your vss-integration.json file with the following JSON:

    {
        "manifestVersion": 1,
        "id": "myservice",
        "version": "1.0.0",
        "name": "My Service",
        "publisher": "mycompany",
        "description": "Awesome tools to help you and your team do great things everyday.",
        "targets": [
            {
                "id": "Microsoft.VisualStudio.Services.Integration"
            }
        ],    
        "icons": {
            "default": "images/service-logo.png"
        },
        "categories": [
            "Plan and track"
        ],
        "tags": [
            "working",
            "people person",
            "search"
        ],
        "screenshots": [
            {
                "path": "images/screen1.png"
            },
            {
                "path": "images/screen2.png"
            }
        ],
        "content": {
            "details": {
                "path": "overview.md"
            },
            "license": {
                "path": "fabrikam-license-terms.md"
            }
        },
        "links": {
            "getstarted": {
                "uri": "https://www.mycompany.com/help/getstarted"
            },
            "learn": {
                "uri": "https://www.mycompany.com/features"
            },
            "support": {
                "uri": "https://www.mycompany.com/support"
            }
        },
        "branding": {
            "color": "rgb(34, 34, 34)",
            "theme": "dark"
        }
    }
    
  2. Update the JSON using the following reference:

These properties are required:

Property Description Notes
manifestVersion A number corresponding to the version of the manifest format. This should be 1.
id The extension's identifier. This is a string that must be unique among extensions from the same publisher. It cannot contain the '.' character and is limited to 100 characters. Example: sample-extension.
version A string specifying the version of an extension. Should be in the format major.minor.patch, for example 0.1.2 or 1.0.0
name A short, human-readable name of the extension. Limited to 200 characters. Example: "Fabrikam Agile Board Extension"
publisher The identifier of the publisher. This identifier must match the identifier the extension is published under. See Create and manage a publisher.
targets The products and services supported by your integration or extension. See installation targets for more details. This is an array of objects, where each object has an id field indicating one of the following:
  • Microsoft.VisualStudio.Services (extensions that works with Team Services or TFS)
  • Microsoft.TeamFoundation.Server (extension that works with TFS)
  • Microsoft.VisualStudio.Services.Integration (integrations that works with Team Services or TFS)
  • Microsoft.TeamFoundation.Server.Integration (integrations that work with TFS)

These optional properties help users discover and learn about your extension:

Property Description Notes
description A few sentences describing the extensions. Limited to 200 characters. The description should be your extension's "elevator pitch" - a couple of lines to describe your extension in the marketplace and make people want to install it. See the example below
icons Dictionary of icons representing the extension. Valid keys: default (128x128 pixels). Other keys such as large (512x512 pixels) may be supported in the future
The value of each key is the path to the icon file in the extension
categories Array of strings representing the categories your extension belongs to. Limited to 3. First is considered the default. Valid values: Build and release, Collaborate, Code, Developer samples, Plan and track, Integrate, and Test
tags Array of string tags to help users find your extension. Examples: agile, project management, task timer, etc.
screenshots Array of images that could not be included in your ***content. Screenshots are more valuable when featured in your **content, and should be used there to help make a quality market details page for your extension. Use **screenshots* for less important images not featured in your content.
  • Each image should be 1366x768 pixels
  • The path of each item is the path to the file in the extension
content Dictionary of content files that describe your extension to users. Every extension should include solid content—it's how you'll show users what your extension can do; make it rich, consumable, and include screenshots where necessary
  • Include an overview.md file as your base content piece
  • Each file is assumed to be in GitHub Flavored Markdown format
  • The path of each item is the path to the markdown file in the extension
Valid keys: details. Other keys will be supported in the future.
links Dictionary of links that help users learn more about your extension, get support, and move. Valid keys:
  • getstarted - first steps, how to setup or use
  • learn - deeper content to help users better understand your extension or service
  • license - end user license agreement
  • privacypolicy - privacy policy for an extension
  • support - get help and support for an extension
The value of each key is an object with a uri field, which is the absolute URL of the link
repository Dictionary of properties describing the source code repository for the extension Valid Keys:
  • type - Type of repository. Example: git
  • uri - Absolute URL of the repository
badges Array of links to external metadata badges like TravisCI, Appveyor etc Valid keys:
  • href - Link the user will navigate to when clicking the badge
  • uri - The absolute URL of the badge image to be displayed
  • description - Description of the badge, to be displayed on hover
branding Dictionary of brand-related properties.* Valid keys:
  • color - primary color of the extension or publisher; can be a hex (#ff00ff), RGB (rgb(100,200,50)), or supported HTML color names (blue)
  • theme - complements the color; use dark for dark branding colors, or light for lighter branding colors

Details page

  • 1 - description
  • 2 - icon
  • 3 - categories
  • 4 - screenshots
  • 5 - content (details)
  • 6 - links
  • 7 - branding

card

Make sure the "public" attribute is set to "false" (or not set at all) to avoid your extension or integration from becoming prematurely visible to all users on the Marketplace.

Package your manifest and assets

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 integration 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 your integration to the Marketplace

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 your integration

Before an integration 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 integration, as it is the only way to run an integration.

To share an integration so it can be installed:

  1. Click an integration 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 integration visible to.
    • For example, to make an integration visible to the fabrikam-fiber-inc.visualstudio.com account, specify fabrikam-fiber-inc.

Update an item

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 integration public (visible to everyone)

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