Publishing an extension for SQL Operations Studio

In my last post I built an extension for SQL Operations Studio in 15 minutes. The next step is to publish this to the extension gallery so everyone can install the extension and start using it. Here’s our end goal — the extension showing up in the gallery when you search for all extensions:

The extension is now live for you to install & use — if you’re wondering how to release your own extension read on. As always please give feedback on our issues page or gitter channel if you run into problems during development.

Summary

Publishing your extension isn’t fully automated yet. If you’ve used Github before most of the steps are fairly straightforward. Here’s what we’ll do:

1. Source control your code and publish to Github (you can skip this section if you’ve ever done this before).
2. Create a Github release and upload your VSIX file. This will be our install page.
3. Edit a file called extensionGallery.json in your browser and submit a PR to publish the extension.

Prerequisites

• An extension.vsix file such as the one we built in our last post.
• A Github account so you can submit a PR with your changes.

1: Source Controlling your project and publishing to Github

We’ll publish our extension on Github. This gives us a nice landing page for anyone who wants to submit issues, see how it’s built so they can build their own, and most importantly, have a release page so that each version of our app can be downloaded.Once it’s created we want to push our extension to it.

• First we need to source control your local extension project. Open your project in Visual Studio Code and run the Git: Initialize Repository command to add it to Git source control.

• Check in your code in the Source Control view, and click the check-mark symbol. You’ll now have all your code source controlled locally and ready to push up to Github.

• Next let’s create the repository and push to it. Open Github.com and click New repository to create your project

• Name it the same as your extension locally. In my case I used SSMSKeymap. Click Create repository and you now have a Github project!

• Now we can push your local project to Github. In your Github page click Clone or Download and copy the URL to your clipboard.

• Now open a Terminal window in VSCode, and run the command git remote add origin <my-github-url>. For instance I ran git remote add origin https://github.com/kevcunnane/ssmskeymap.git.

• Push your code to Github by entering git push --set-upstream origin master. This will push all your code to Github so it’s shared with the world.

2: Creating a Github release for your VSIX extension

On your project’s Github page there’s a releases page where you can publish your VSIX file. Navigate to this and click Draft a new release.

• Enter the tag version for your package (e.g. if it’s called ssmskeymaps-0.2.0.vsix, use 0.2.0), and give it a release name like VSIX 0.2.0. Then drag your VSIX file into the Attach binaries section to upload them, and publish the release.

• As this will be your extension download page, add some information on how to install the extension in Ops Studio.

Now your release is uploaded and ready to publish to the gallery!

3: Publish your extension to the gallery

The marketplace is currently set up as a “gallery” file hosted by the SQL Operations Studio team. We’ll edit this file in a Github fork and then submit a PR to publish it. Once the team accepts your PR, you should see the extension in the gallery.

Forking the Ops Studio repository

Go to https://github.com/Microsoft/sqlopsstudio/tree/release/extensions

• Click the Fork button in the top-right and fork to your own Github account

• Go to your new fork and make sure you’re on the release/extensions branch.

Define your extension as a JSON object

Take the sample extension entry below and update all the placeholder values like <name from package.json> with your own values.

• For the Microsoft.SQLOps.DownloadPage entry you need to copy the address to your release page. This is where your vsix file is downloaded from. In our example this is https://github.com/kevcunnane/ssmskeymap/releases/tag/0.2.0.

• For Microsoft.VisualStudio.Services.Links.Source use you should use your project homepage, e.g. https://github.com/kevcunnane/ssmskeymap.
• For any paths to files inside your Github project (e.g. the package.json, README.md and others) you must use the “RAW” link, which is https://raw.githubusercontent.com/<mygithubid>/<projectname>/master/<filepath> as the prefix. This will allow the content to be read by SQL Operations Studio and displayed correctly to the user.

Sample extension entry:

{
  "extensionId": "<next available extension number, e.g. 15>",
  "extensionName": "<name from package.json>",
  "displayName": "<displayName from package.json>",
  "shortDescription": "<1-line summary of your extension>",
  "publisher": {
    "displayName":"<your name>",
    "publisherId": "<publisher from package.json>",
    "publisherName":"<publisher from package.json>"
  },
  "versions": [
    {
      "version": "<version from package.json>",
      "lastUpdated": "<todays date in US date notation>",
      "assetUri": "",
      "fallbackAssetUri": "fallbackAssetUri",
      "files": [
      {
        "assetType": "Microsoft.SQLOps.DownloadPage",
        "source": "https://github.com/kevcunnane/ssmskeymap/releases/tag/0.2.0"
      },
      {
        "assetType": "Microsoft.VisualStudio.Services.Links.Source",
        "source": "<https link to your Github page, e.g. https://github.com/kevcunnane/ssmskeymap>"
     },
     {
        "assetType": "Microsoft.VisualStudio.Services.Icons.Default",
        "source": "<link to a RAW file for the png icon to show in the gallery, e.g. https://raw.githubusercontent.com/kevcunnane/ssmskeymap/master/visualstudio-keyboard.png>"
      },
      {
        "assetType": "Microsoft.VisualStudio.Services.Content.Details",
       "source": "<link to your README page, e.g. https://raw.githubusercontent.com/kevcunnane/ssmskeymap/master/README.md>"
      },
      {
        "assetType": "Microsoft.VisualStudio.Code.Manifest",
        "source": "<link to your package.json, e.g. https://raw.githubusercontent.com/kevcunnane/ssmskeymap/master/package.json>"
      },
      {
        "assetType": "Microsoft.VisualStudio.Services.Content.License",
        "source": "<link to your license, e.g. https://raw.githubusercontent.com/kevcunnane/ssmskeymap/master/LICENSE.txt>"
      }
      ],
      "properties": [
        { "key": "Microsoft.VisualStudio.Code.ExtensionDependencies", "value":""},
        { "key": "Microsoft.VisualStudio.Code.Engine", "value":"*"}
      ]
    }
  ],
  "statistics": [],
  "flags": "preview"
}

Editing the extensionsGallery.json file

Now that you have your extension defined you can edit the file on Github:

• Open the extensionsGallery.json file in the project root, and click the “edit” button.
• Select all the text and copy it into a new untitled file in VSCode (run command New Untitled File) and change language to JSON (run change language mode and choose JSON).
• After the last entry in the extensions array you will want to add a , and paste in the entry for your extension. See below for the SSMSKeymap entry. After adding this, there should not be any errors in the JSON file.

SSMSKeymap entry in extensionGallery.json

• Commit your changes to your file so it’s now in your fork.

Submit a PR to publish your extension

You’re now ready to submit and publish your extension. If you go back to the release/extension branch page on your fork you’ll see a Compare & pull request button — click this to submit the PR.

• Make sure your pull request title & description make sense (these should match the change you made in the last step).
• Click Create pull request and you’ll be ready to go!

Next steps

You can contact the team at https://gitter.im/Microsoft/sqlopsstudio and let them know you’ve published your extension. The team will aim to validate and publish your extension — mostly verifying the links work and if there are any issues with how it shows in the gallery.