Shipping Visual Studio snippets in an extension
Snippets are the little shortcuts available in Visual Studio for all the different languages. Here's a well known C# code snippet in action:
It just shows up in Intellisense and when you hit TAB, it folds out into this:
So snippets are really useful and boosts productivity. You can even write your own very easily – it's just simple XML files. Here's a great walkthrough on how to create individual snippet files. It's a bit old, but the format is the same for Visual Studio 2012/2013.
Up until very recently, I was convinced that you couldn't ship snippets as part of a Visual Studio extension (.vsix). I've always thought it would be great if we could share useful code snippets but there wasn't really a vehicle for distributing them efficiently.
Then I stumbled upon a huge collection of awesome jQuery code snippets made specifically for Visual Studio. However, you had to manually download the snippets in a zip file and copy them to a specific location to work. I didn't like that. It would be so much better with a simple installer. So I decided to figure out how to create a Visual Studio extension for those snippets. Here's how to do it.
Creating the extension
The first thing you need is to download and install the SDK for Visual Studio 2012 or 2013. Then open Visual Studio and hit New Project… and select C# –> Extensibility –> VSIX Project:
That gives you an empty extension project containing only one file – source.extension.vsixmanifest. We need that file later.
First we need to create a suitable folder structure for our snippet files (.snippet) and we need to be very specific in the naming of our folders. Here's what the folder structure could look like when I have 2 C# snippets:
I've created a folder named Snippets and then added a folder for each language I want to provide snippets for. Inside each of the language folders you need to add yet a new folder and give it the name you want to show up in the Code Snippet Manager (example below is from the SideWaffle Template Pack).
Make sure to mark each .snippet file as Content to be included in the VSIX extension:
Adding a package file
Now we must add a new text file to the root of our project and call it whatever.pkgdef. We need this file to set some registry keys when the extension is installed. Any registry changes applied by the pkgdef file will automatically be reverted again when the extension is uninstalled.
If we only want C# snippets, then add the following lines to the pkgdef file:
// C# snippets
[$RootKey$\Languages\CodeExpansions\CSharp\Paths]
"MySnippets"="$PackageFolder$\Snippets\CSharp\MySnippets"
You can add more lines for other languages. Here's an example of a pkgdef file containing registry keys for all languages supporting snippets.
And finally, we must register the pkgdef file with our VSIX extension. We do that by opening the source.extension.vsixmanifest file and navigate to the Assets tab. Then click the New button and fill in the dialog like this:
Then click OK. Also, make sure you have entered a name in the Author field in the .vsixmanifest file:
Testing it
You are now ready to test your extension. Simply hit F5 (or Ctrl+F5) to launch a new instance of Visual Studio – this is what's called the Experimental Instance which is used for extension building. It might take a minute the first time you open it.
When the experimental instance of Visual Studio is loaded, go to Tools –> Code Snippet Manager… and make sure MySnippets are loaded correctly:
That's it. You only need to do these steps once and every modification to existing snippets or addition of new snippets are automatically picked up and added to the extension.
Since I only wanted to provide C# snippets, I can delete all the other folders. My folder structure now looks like this:
Very simple and clean IMO.
The only thing left to do is to upload our extension to the Visual Studio Gallery. It's very simple and all we need is to build our project and locate the output file MySnippets.vsix in the bin folder.
The bin folder may contain a few other files, but we are only interested in the .vsix file since this is the one to upload to the Gallery.
I hope this helps clarify thing a bit. Have fun writing snippets!