How to add your own code snippets in Visual Studio

Visual Studio (starting from version 2005) gives you the possibility to use the code snippets to insert frequently used code parts quickly using an alias. Try for example to digit “prop” and press TAB to create a full property. The type and the name of the property are parameters of the snippets, they have a default value that can be changed.

Visual studio has a long list of pre-made code snippets available, but obviously not every option that we might need is available. In this post I want to show you how to create your own code snippets.

One task that I perform very often is to check method arguments against null values, in every public method I repeat this piece of code for each parameter.

if( arg == null )
   throw new ArgumentNullException("arg");

Let’s create a code snippet, that I will call “checknullargs”, to automate the creation of this code.

First of all we have to create a new file called “checknullargs.snippet” (you don’t have to call the file in with the same name as the alias, but I recommend to do so, it will be quicker to identify which file contains a specific snippet if you will need to edit or delete them) in the folder %Documents%\Visual Studio %Version%\Code Snippets\%Language%\My Code Snippets, where %Documents% is your Documents folder, %Version% is the visual studio version that you have installed (eg. 2005, 2008, 2010) and %Language% is the programming language that you want to use to write the snippet (and the snippet will be available only for that language).

The code snippet file is a simple XML file with the following structure.

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
	<CodeSnippet Format="1.0.0">
		<Header>
			<!-- Descriptive information here -->
		</Header>
		<Snippet>
			<!-- Code information here -->
		</Snippet>
	</CodeSnippet>
</CodeSnippets>

The file can be opened in visual studio to get full intellisense support.

Inside the Header element let’s add information about our snippet

<Title>checknullarg</Title>
<Shortcut>checknullarg</Shortcut>
<Description>Checks for null arguments</Description>
<Author>Riccardo Munisso</Author>
<SnippetTypes>
	<SnippetType>Expansion</SnippetType>
</SnippetTypes>

Title: is the name of the snippet
Shortcut: is the shortcut that we use inside of visual studio to activate the snippet
Description: description of your snippet
Author: your name!
SnippetTypes / SnippetType: is the type of snippet, can be Expansion or SurroundsWith. An Expansion snippet just add code to the editor, a SurroundsWith snippet surrounds the selected code with the content of the snippet.

Let’s fill now the Snippet section. The snippet section is divided in two parts, a Declarations element that allows us to declare the parameters (the replaceable parts) of our snippets, and the Code element containing the actual code.

<Declarations>
	<Literal>
		<ID>arg</ID>
		<ToolTip>Argument to be checked</ToolTip>
		<Default>arg</Default>
	</Literal>
</Declarations>
<Code Language="csharp"><![CDATA[if ($arg$ == null)
throw new ArgumentNullException("$arg$");
$end$]]>
</Code>

The Declarations element contains a list of Literal elements, one for each parameters of the snippet. For each parameter we have to specify the ID (that needs to be unique), a tooltip and the default value.

The Code element contains the actual code to be inserted. You can insert your parameter using sourrounding them with dollar symbols (in this example $arg$ ).

Note that in the above sample there is a parameter called $end$ that we didn’t declare. This is a predefined value that represents the position of the cursor after the snippet is inserted in the editor. In this case the cursor will be placed after the snippet.

There is also another predefined parameter, called $selected$ that represents the code selected in Visual studio when adding the snippet. This is useful for the SurroundsWith type of snippets.

Once you have created your snippet you will need to restart visual studio for see the changes in the editor.

The full code for the sample snippet can be downloaded here

Happy coding!