I recently blogged about using code snippets as a shortcut to writing more code in less time. In this post, I'm going to walk you through the steps to create custom snippets that you can install into Visual Studio for use in your own projects
To get started, let's take a look at the anatomy of a snippet. A snippet is nothing more than an XML file, with a .snippet extension, containing configuration settings. If you open up the file foreach.snippet (located in "<Visual Studio installation directory>\VC#\Snippets\1033\Visual C#") you'll find the following XML, which defines the foreach snippet:
As you can see, the XML used to define the snippet is fairly straight-forward. I'll go over it section by section and explain how each setting is used.
Anatomy of a Code Snippet
After the XML declaration element, a <CodeSnippets> element acts as the root element and contains all the code snippet definitions in the file. While there can certainly be more than one snippet per file, it is usually considered good practice to only define one snippet per file. The parent <CodeSnippets> element also contains a namespace definition, http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet, which is required if you want Visual Studio intellisense when designing your own code snippets.
Inside the <CodeSnippets> element, each snippet is defined by its own <CodeSnippet> element. This element contains a Format attribute, which is used to define the version of snippet. While the version of the snippet is up to the developer, the Format attribute is required.
Each <CodeSnippet> element contains two inner elements, <Header> and <Snippet>. The <Header> element contains all of the snippet's details, such as title, description, author, etc. The <Snippet> element contains the literal, references, and code definitions.
The <Header> element contains any or all of the following elements:
The <Snippet> element contains any or all of the following elements:
Creating a Custom Code Snippet
By way of example, let's create a code snippet which checks the existence of a query string on an ASP.NET page, and redirects a user if the query string does not exist. When designing ASP.NET pages, I often use this piece of code when the page is displaying some sort of data and requires a query string with a value which is used to look up the data in a database. Since I use the same block of code often, having it as a snippet will save me some time when I need to use it in the future.
For starters, let's see how the code should look. I want it to first check if a particular element in the Request.QueryString collection contains a value. If it is null or empty, I want to redirect the user to another page. Here is the code I want to implement:
Now that we know what code we want, we need to determine which pieces of the code are dynamic. That is, which parts of the code can change each time we insert it into a file. In this code block, the only elements that will change are the string literals inside the Request.QueryString indexer and the Response.Redirect method. We will need to define these two items as Literals in our code snippet.
Once we know the basic requirements for our snippet, we can go ahead and create a new snippet file. In Visual Studio, click File | New | File..., select Xml File, and click Open. (Note: you do not have to have a project or solution open, nor do you have to close out of an open project or solution, to create a new snippet)
Once the new XML file has opened in the IDE, we want to save it with a .snippet extension, so click File | Save <XML Filename>.xml As... and enter a new name for the snippet. I am going to call this one querystring. Choose the .snippet file extension from the Save as type: drop down list and click Save.
Now in our querystring.snippet file we should have nothing more than an XML declaration. First we'll go ahead and add the basic structure to our snippet with the following XML elements:
Since this is our first crack at the new snippet, we'll keep the default version by leaving Format's value at 1.0.0. Next we'll add some basic information to our header. We will give the <Title> and <Shortcut> elements a value of querystring, then we'll add a description and author as well. Finally, let's add a single <SnippetType> of Expansion. Remember that this <SnippetType> causes the snippet to be inserted at the current cursor position.
Next we will define the elements in our <Snippet> element. We'll first need to declare two <Literal> elements in the <Declarations> section which will define the two dynamic pieces of our snippet. We'll call the first querystring, since it will be used to define the name of the query string our code will check for, and we will give it a default value of id. The second <Literal> will be called page, since it will be used to define the name of the page we will redirect users to if the query string doesn't exist, and we'll give it a default value of Default.aspx. Finally, we'll add the code block itself within the <Code> element. This element must have a Language attribute with a value of csharp, and its contents will be embedded in a CDATA element. The code is wrapped in this element in case its content breaks the structure of the XML document.
And here is what our finalized code snippet looks like:
The Code Snippets Manager
To insert the newly created code snippet, we can use Visual Studio's Code Snippets Manager. To open the manager, click Tools | Code Snippets Manager or type Ctrl + K, Ctrl + B. In the manager, snippets are separated by language, and then further by category. Notice the Location bar near the top of the window. This shows the location where each snippet can be found, allowing users to navigate to and edit pre-installed snippets themselves. As you can see, there are tons of snippets built in to Visual Studio right out of the box.
You can add a folder to hold your own snippets by clicking the Add... button and selecting the folder of your choice. This folder will then appear in the Code Snippets Manager and can be used to store imported snippets. To import your code snippet, make sure the correct Language is selected, then click the Import... button. Navigate to the location of your .snippet file, highlight it, and hit the Open button. A new window will appear, asking you to select the folder into which the snippet should be imported.
Choose an existing folder, or a folder you have created on your own, and click Finish. Congratulations! You have created your first code snippet. You can now try it out by simply typing its shortcut in your code and selecting it from the intellisense menu.