In this article, I’ll explain how one can directly check in the Visual Studio extension to the GIT repository, and as soon as the extension is pushed to GIT repository, it automatically deploys to a staging server made on AppVeyor via Continuous Integration
Table of Contents
Introduction
This article is the continuation of "Creating your first Visual Studio VSIX package" article of the series Visual Studio Extensibility. The first part focused on creating a Visual Studio extension to locate a file or folder in Windows Explorer. This article will illustrate how to make your Visual Studio extension deployment ready (i.e., how to deploy the extension to staging server via GIT and publish the extension on Visual Studio market place to make it available to the public).
In this article, I’ll explain how one can directly check in the Visual Studio extension to the GIT repository, and as soon as the extension is pushed to GIT repository, it automatically deploys to a staging server made on AppVeyor via Continuous Integration and compiles the code there and then automatically updates the same extension to the production that is, in our case, Visual Studio Gallery.
Roadmap
Let me again revise the roadmap of this series of Visual Studio Extensibility. The series will be divided into three articles as mentioned below, and we’ll focus more on practical implementations and hands-on rather than going much into theory.
- Visual Studio Extensibility (Day 1): Creating your first visual studio VSIX package
- Visual Studio Extensibility (Day 2): Deploying the VSIX package on staging server and GIT via Continuous Integration
- Visual Studio Extensibility (Day 3): Embedding VSIX package in Visual Studio Isolated Shell
Prerequisites
The prerequisites for this article are running an application that was created in the prior part of the series or a running sample Visual Studio extension application. You would also need to have an account on Github. So please create one.
Before we actually start, I need the readers of this article to download install Extensibility tools written by Mads Kristensen from here.
This article series is also highly inspired with Mads Kristensen’s speech at Build 2016 and his work on Visual Studio extensibility.
Publish Extension on GIT
Open the existing source code for file locater in Visual Studio. Right-click the solution and you’ll see the Extensibility Tools option, and in its context menu an option to "Prepare for Github…". Select that option as shown in the following image:
This will ask a confirmation that certain files in context of GIT would be added to the solution. Click Yes and proceed.
When you click Yes, a Readme file and a changelog file would be added to the solution as shown below, and a lot of other files would be added to the folder on the file system where your code exists.
If you see the Readme file, you’ll see that it is smart enough to pick the information from the manifest file and added the same description "Helps to locate files and folder in windows explorer" inside it.
ChangeLog file is also very important as it provides update to users that indicates the roadmap of your project, the features in the last release and the features to come in the near future. It also keeps track of version number information. The changelog also helps you to create a kind of document for yourself along with details of your project/extension.
Let’s update the ChangeLog file to make it more descriptive w.r.t. our extension.
We call it version no. 1.0 and the date of release. Since it is an Initial release, provide the text saying it is an initial release and the feature (i.e., open the file in Windows Explorer). And on the roadmap, since we do not have anything planned yet, so you can specify Coming Soon… as shown in the last image.
When we prepared the solution for Github, a license was also added to the project folder, so now we have the license and we can add the license to our extension. Open the source.extension.vsixmanifest, there we can see the license option.
Browse for the license file located at the location where other GIT files were added, choose the license file and add it as a link as shown in the following image:
Now right-click the added license file in Resources folder in Visual Studio and open its properties, change the Build Action to Content and Include in VSIX option to true, so that our license is embedded and shipped with the VSIX extension itself.
Now the extension users can see the license when they install the extension.
We also now need to update the Readme file, as it will be available in Visual Studio gallery and the users will get help from those files on what it actually does and how to use it. So we need to update the readme file with some description and clear screen shots that help users to understand the extension better.
Add the text in the Features section to describe the extension like "Open the selected file in Windows Explorer". Feature 1 as "Locate files in Windows Explorer", and give it some descriptive text like "select the file or multiple files and right click" as shown in the below image.
Now add an image at the location below Feature 1.
This will open the folder where you want to save the image, just create a new folder named images, to the location where your source code is and place the image there, it will automatically be added to the Readme.md with the image link as shown in the above image of Readme file. Similarly, add second that shows the opened folder and add some description to the Readme file.
Now the solution is ready to be pushed to GIT. Right click solution, and in the context menu, choose the option of "Add Solution to Source Control" as shown below:
When you click on this option, a dialog will be shown to choose the option for source control.
Choose Git and click OK. You’ll be asked to Configure your user name and email address before you commit the change.
Provide your Git account credentials at this place.
If you do not have the GitHub extension, download it from extensions and updates as shown below:
Install it and now the solution is ready to be committed.
Give your repository a name and publish it to Github. Your source code will be pushed to Github and a repository will be created with the same name as you specified while publish.
Now click on your repository, and you can see the complete source code available on Git, with the readme information that we supplied to the extension.
Continuous Integration Build via Appveyor
Now what we want is that as soon as the source code gets published on Git, it should be compiled automatically and be published to Visual Studio gallery of extensions. For that, we’ll use Appveyor. Right-click the solution, in the Context menu under Extensibility Tools; choose the option to "Prepare for Appveyor".
This option will ask you to add Appveyor.yml, click OK and it will be added to your solution as shown in the following image. This yml file is the build script that is added to the solution.
Commit and push again the changes to Git.
Open the Appveyor website and sign in. You can login via Github here.
When you login with your Github account, you can see all your Github projects here in Appveyor.
Now search for your extension project.
In my case, it is "LocateFileInWindowsExplorer" and click ADD. It opens a new page where you can click on "New Build" as shown below:
Starting new build here means that now Appveyor will communicate to Github, and whenever there is a change in files or code or new code is pushed to GitHub, it automatically starts to build the code available over Github after publishing. You’ll see the console as follows:
And it says our build is a success, so it is a green build. Now go to Settings, and click on Badges. Github has these badges for the builds.
Select the Sample markdown code in Badges option.
Go to Visual Studio, and read me file and replace the badge information with the copied badge.
Now again publish the code. This time when the code is published, we do not have to explicitly start the build for our extension on Appveyor, but it is automatically started and also updates the version number as shown below:
So now, you can see that the version number is incremented to 1.0.1.
When you go to Appveyor now and click on Artifacts, you’ll see the extension got created after the build is success.
And this is now pushed to VSIX gallery as follows:
So this VSIC gallery is our staging environment and all the extensions compiled by AppVeyor gets pushed to this staging environment automatically. You can download your extension and test it. If you click it, you can also see the readme also attached to this extension as shown in below image, so this readme will actually help users to understand and use your extension.
Download the extension to your file location.
Upload the Extension to Visual Studio Gallery and Marketplace
Now, we can upload the extension to Visual Studio gallery. Go to the link visualstudiogallery.msdn.microsoft.com. On the home page, you’ll see an option to upload the extension. Select the option to Upload.
On the next page, you need to provide some details like the extension type. In our case, this is more like a tool, so select the first option (i.e., Tool and click Next).
In the next screen, browse your downloaded extension and upload it via Choose file option, and click on Next.
In the next screen, provide some basic information for the extension like category, tags and cost category. I make this extension Free, but you can choose your option w.r.t. cost. Provide the source control URL, i.e., Git repository URL as shown in the below image. In the description text area, you do not have to write the description. Just go to your Github repository, copy the Readme file content and paste it in this description text area. Click on the agreement checkbox at the bottom and press Contribute button.
Your extension will be uploaded to Visual Studio gallery saying that it will be available to the marketplace shortly.
Now, copy the link address of your Git repository.
Go to the manifest file in the Visual Studio and paste the Git repository address to More Info URL as shown below:
Copy the link address to Changelog as shown in Readme file of Git repository and paste it to Release notes option in manifest file in Visual Studio.
Now from the VSIX gallery, copy the link address of your extension and paste it to the Readme file where it is mentioned to download the extension from as shown in below images.
Optimize Project Structure
Now a few more small things are left to be optimized in our solution. When you run the experimental instance to test the extension and open the About Visual Studio option from the help in menu as shown in below image. You see it is written as LocateFolderCommandExtension, having some random description that we didn’t provide. Then where does it come from?
In the solution explorer, you can find VSPackage.resx file that contains the above mentioned extension title, description, and the icon comes from Resources folder’s LocateFolderCommandPackage.ico, but now since we do not need these files, we can delete them as we already have an icon for the extension and title and description in the manifest file.
After deleting these files, right-click on source.extension.vsixmanifest and click on Auto-sync Resx and Icon files from the context menu.
Doing this will add an icon and a new resx file to source.extension.manifet file with the required icon, title and description details provided on manifest.
And you’ll find a newly generated class named source.extension.cs also under the manifest file.
In the LocateFolderCommandPackage.cs file, delete all irrelevant information like constructor. Now we see that there is a PackageGuid string mentioned in this class file.
That PackageGuidString is also present in the vsct file, so again to avoid the repetition, right-click on vsct file and select an option for Auto-sync VSCT commands as shown in the below image.
After sync, you can now delete the PackageGuidString from LocateFolderCommandPackage.cs and the GUID attribute information from the top and add the GUID from PackageGuids class as shown in the below image:
Now we need to make our extension code more readable and understandable (for example, the file names). So create a new folder under project named Commands and move your command that is LocateFolderCommand to this folder.
Rename LocateFolderCommandPackage.cs to VSPackage and LocateFolderCommandPackage.vsct to VSCommandTable, these names sound more meaningful.
Again, build, commit and push all the changes to Git
As soon as you push the code, Appveyor starts the build automatically.
After the build is green, you can find your extension on the VSIX gallery with an updated version, this time 1.0.2 as shown in the below image:
Download the updated extension again, and in the uploaded extension at Visual Studio market place, again upload this extension by editing the already uploaded extension.
Conclusion
This article explained on how you can publish your extension to Visual Studio market place following certain standards and automatic processes. In the next article of the series, we’ll try to embed this extension into the Visual Studio Isolated shell application.
References
Complete Source Code
Extension at Marketplace
- 14th February, 2017: Initial version
