Creating a Custom Code Snippet

Monday, October 29, 2007

Creating a Custom Code Snippet is pretty easy to do -- you just fire up your favorite text editor, write some XML, and save the results in a *.snippet file. If you use Visual Studio as your text editor, you can even get some XML Intellisense, which is always nice. I am going to create a code snippet called rw.snippet, which will simply expand to Response.Write();, and leave your cursor inside the parenthesis (something I use far too often, along with Trace.Write(), for debugging).

To get started, create an empty text file in Notepad (or similar), and add the following lines to indicate that you want to write a custom code snippet.

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
<CodeSnippet Format="1.0.0">
</CodeSnippet>
</CodeSnippets>

Now save the file as rw.snippet (I would recommend saving it in your Visual Studio 2005\Code Snippets\[Language]\My Code Snippets folder) and close out of NotePad. Open the file in Visual Studio (note: since the file has the *.snippet extension, it should now be registered to open with Visual Studio by default). You should see the XML scheema information that you copied earlier, and you should get some next text highlighting as well.

Inside the <CodeSnippet> tag, you can add header information inside a <Header> tag, including a Title, Shortcut (the keyboard shortcut to be used), Description and more. You can use Intellisense to see all the possibilities. For now, I'll add the following information:

<Header>
<Title>rw</Title>
<Shortcut>rw</Shortcut>
<Description>Code snippet for generating Response.Write</Description>
<Author>Scott K</Author>
<SnippetTypes>
<SnippetType>Expansion</SnippetType>
</SnippetTypes>
</Header>

Next, you create the <Snippet> tag where the actual implementation will take place. Inside the snippet tag, you can define variables (literals/objects) to be filled in later (called Declarations) as well as the <Code> section containing your actual snippet content. The <Code> tag itself can define a few properties, like the declaration 'delimiter', 'kind' (to filter snippets based on code location), and 'language' (mainly helpful for organization) options. Inside the <Code> tag, you will create a <![CDATA[]]> section which will hold the snippet body as a plain string. The Snippet section for my Response.Write() snippet will look like the following:

Here, 'end' is a built-in declaration for the position the cursor will end up after expanding the snippet, and since we didn't change the delimiter is it defaulted to $. So the complete code for the rw.snippet file is:

<?xml version="1.0" encoding="utf-8" ?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
<CodeSnippet Format="1.0.0">
<Header>
<Title>rw</Title>
<Shortcut>rw</Shortcut>
<Description>Code snippet for Response.Write</Description>
<Author>Scott K</Author>
<SnippetTypes>
<SnippetType>Expansion</SnippetType>
</SnippetTypes>
</Header>
<Snippet>
<Code Language="csharp">
<![CDATA[Response.Write($end$);]]>
</Code>
</Snippet>
</CodeSnippet>
</CodeSnippets>

Once you have saved your file, inside Visual Studio click on Tools->Code Snippets Manager. Now choose the Import Option, navigate to your file save location and choose rw.snippet Choose where to put the snippet (I chose Visual C#) and click OK. Thats it! Now when you are typing in a normal coding environment, type rw and you will see the code snippet paper icon appear with rw in Intellisense. Press tab to expand out this snippet, and you will get Response.Write(); with your cursor ready for action inside the parenthesis.

Now the you have a working snippet, you may want to create a more complex snippet with custom declarations. All you have to do is add declarations to the <Snippet> tag and give them IDs, and then reference those IDs inside your CDATA[] block. For example, I will create a variable name declaration called var and then add it to the rw snippet I just created (disclaimer: this is just for demonstration purposes, obviously the following code would not be very helpful) which will print out a string. The declarations section would look like this:

<Declarations>
<Literal>
<ID>var</ID>
<ToolTip>Name for the string variable</ToolTip>
<Default>var</Default>
</Literal>
</Declarations>

And then the new CDATA[] section would look like this:

<![CDATA[string $var$ = "Hello World";
Response.Write($var$);
$end$]]>

When you expand that out as a code snippet and fill in the var name, you'll get a code block like this:

string helloString = "Hello World";
Response.Write(helloString);

That's really all there is to it -- for more advanced snippets you can look at the built in ones that Microsoft wrote, but this tutorial should give you all the tools you need to write some pretty advanced and time saving snippets.

2 Comments