Code Snippets (2)


How To: Create your own code snippets

Okay, so what I will do here is explain you how to create your own code snippets to use in Visual Studio 2010 without using any add-ins related to snippet designing. A post on snippet designers / explorers and how you can use them to build better snippets faster will come sometime next week I believe, but this time I can’t promise.

PART 1: CREATING A SIMPLE CODE SNIPPET

So let’s get started. Open up your Visual Studio and go to File – New File (or Ctrl + N) and create a new XML file. Don’t worry about the file’s name at this point as it is not that important. An XML file with a line of code will automatically be generated for you. So, the first thing we need to do in this brand new file is to add the CodeSnippets namespace and a CodeSnippet element to it right after the first line; to do so copy-paste the code below:

<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
   <CodeSnippet Format="1.0.0">
   </CodeSnippet>
</CodeSnippets>

Now we can really start work on our snippet. First thing we need to do is set up the header of our snippet. The header can contain various information like the Title, Description, Author,  Keywords in case you want to make your snippet available online, a Shortcut for your snipped and also a HelpUrl where people can go and ask for help in case something doesn’t work as expected. I suggest you always add a title and a description to your snippets even if they are not mandatory.

Here’s an example of a header containing all possible elements:

<Header>
   <Title>MessageBox</Title>
   <Description>Opens up a message box displaying "Hello World!".</Description>
   <Author>StartDebugging.net</Author>
   <Keywords>
      <Keyword>messagebox</Keyword>
      <Keyword>helloworld</Keyword>
   </Keywords>
   <Shortcut>hellobox</Shortcut>
   <HelpUrl>http://startdebugging.net</HelpUrl>
</Header>

Now that the header is set up, we can start writing the code. First thing here is creating the actual Snippet element right after the end of the Header element. Your code should look like this now:

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

The code which we want the snipped to insert must be added in the Code element of the Snippet between <![CDATA[ and ]]> brackets. In this example, as you’ve probably figured out from the description, our code snippet will simply display a message box containing the text “Hello World!”.  Bellow you can see how the Code element of the snippet looks like after adding the code.

<Snippet>
   <Code Language="CSharp">
      <![CDATA[MessageBox.Show("Hello World!");]]>
   </Code>
</Snippet>

As you can see above, my Code element has a property named Language which is set to CSharp. Make sure that you set that language accordingly. You can write code snippets for VB, CSharp, VJSharp and XML.

Also, another element which you can add to the Snippet is References. Unfortunately this is not supported for C# so you will have to add them manually in our case. Otherwise, here’s how you can add a reference:

<Snippet>
   <References>
      <Reference>
         <Assembly>System.Windows.Forms.dll</Assembly>
      </Reference>
   </References>
   <Code Language="VB">
      ...
   </Code>
</Snippet>

So here’s the entire code of the snippet:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
   <CodeSnippet Format="1.0.0">
      <Header>
         <Title>MessageBox</Title>
         <Description>Opens up a message box displaying "Hello World!".</Description>
         <Author>StartDebugging.net</Author>
         <Keywords>
            <Keyword>messagebox</Keyword>
            <Keyword>helloworld</Keyword>
         </Keywords>
         <Shortcut>hellobox</Shortcut>
         <HelpUrl>http://startdebugging.net</HelpUrl>
      </Header>
      <Snippet>
         <Code Language="CSharp">
            <![CDATA[MessageBox.Show("Hello World");]]>
         </Code>
      </Snippet>
   </CodeSnippet>
</CodeSnippets>

Now that we’re done writing the snippet it’s time to save it. So File – Save as to the following path:

Drive:\...\Documents\Visual Studio Version\Code Snippets\Language\

which in our case is

Drive:\...\Documents\Visual Studio 2010\Code Snippets\Visual C#\

using the .snippet file extension – for example messagebox.snippet.

Now that you’ve saved it, it’s time to add it to your Visual Studio 2010. So go to Tools – Code Snippets Manager (or Ctrl + K, Ctrl + B), click on Import  and open the snippet we previously saved. After opening it you will be asked to which languages to add it, in our case simply check Visual C#.

Create a new project or open an already existing one (C# project) and go somewhere where you can write some C# code. Now, inserting a snippet can be done two ways: one – hit Ctrl + K, Ctrl + X, select Visual C# (or any other language for that matter) and then select the snippet you want to insert (ours is called MessageBox – we set this name using the Title tag); – second way is by typing the shortcut (ours is called hellobox – we set this name using the Shortcut tag in the header) and pressing double TAB. And there you go, your snippet is inserted.

PART 2: USING LITERALS

Now that you know how to create, save and use a code snippet it’s time to learn how to create a little bit more complex ones – and here I’m referring to literals.

Since I couldn’t think of a better definition for literals, here’s the one I found on msdn:

The Literal element is used to identify a replacement for a piece of code that is entirely contained within the snippet, but will likely be customized after it is inserted into the code.

So let’s say you have a code snippet in which you use a variable name 10 times. You insert that code snippet into your code and you decide that the variable name must be changed so you go ahead and replace the old variable name with the new variable name in all 10 cases. What literals allow you to do is define a piece of code inside your snippet which you can use several times, and after you insert that snippet into your code if you change that defined piece of code in one place, then it will change in all the other places where you used it. You can think of them as variables if you want.

So, let’s put them in practice. Let’s create a code snippet for inserting dependency properties in our silverlight projects. The code for registering a dependency property with a property changed event handler is the one below:

public bool IsSelected
{
   get { return (bool)GetValue(IsSelectedProperty); }
   set { SetValue(IsSelectedProperty, value); }
}
public static readonly DependencyProperty IsSelectedProperty = DependencyProperty.Register("IsSelected", typeof(Boolean), typeof(Page), new PropertyMetadata(OnIsSelectedPropertyChanged));
private static void OnIsSelectedPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
{
   Page control = d as Page;
}

As you can see, the property name is used several times as well as the property type, so what we’re gonna do is define a literal for each of them + one literal for the class name. They look like this:

<Snippet>
   <Declarations>
      <Literal>
         <ID>PropertyName</ID>
         <Default>PropertyName</Default>
         <ToolTip>The name of the dependency property.</ToolTip>
      </Literal>
      <Literal>
         <ID>PropertyType</ID>
         <Default>PropertyType</Default>
         <ToolTip>The type of the dependency property.</ToolTip>
      </Literal>
      <Literal>
         <ID>ClassName</ID>
         <Default>ClassName</Default>
         <ToolTip>The name of the owner class.</ToolTip>
      </Literal>
   </Declarations>
</Snippet>

As you can see, each of my literals has three fields: ID – used to identify replaceable portions of code, Default – representing the default value of the literal when the snippet is inserted and ToolTip which is a small description of he literal which shows up at mouse over.

Having these literals set up what we need to next is replace the already defined names and types in our code with literals. This is done by using $ID$ instead of the predefined value (ex: $PropertyName$, $PropertyType$, $ClassName$).

This is how your code should look like inside the snippet after adding the literals:

<Code Language="CSharp">
   <![CDATA[// Defines a DependencyProperty named $PropertyName$ of type $PropertyType$ for the $ClassName$ class.
   public $PropertyType$ $PropertyName$
   {
      get { return ($PropertyType$)GetValue($PropertyName$Property); }
      set { SetValue($PropertyName$Property, value); }
   }
   public static readonly DependencyProperty $PropertyName$Property = DependencyProperty.Register("$PropertyName$", typeof($PropertyType$), typeof($ClassName$), new PropertyMetadata(On$PropertyName$PropertyChanged));
   private static void On$PropertyName$PropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
   {
      $ClassName$ control = d as $ClassName$;
   }]]>
</Code>

And here is the complete code:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
   <CodeSnippet Format="1.0.0">
      <Header>
         <Title>sldp</Title>
         <Description>Defines a dependency property to use in Silverlight.</Description>
         <Author>StartDebugging.net</Author>
         <Keywords>
            <Keyword>silverlight</Keyword>
            <Keyword>dependencyproperty</Keyword>
         </Keywords>
         <Shortcut>sldp</Shortcut>
         <HelpUrl>http://startdebugging.net</HelpUrl>
      </Header>
      <Snippet>
         <Declarations>
            <Literal>
               <ID>PropertyName</ID>
               <Default>PropertyName</Default>
               <ToolTip>The name of the dependency property.</ToolTip>
            </Literal>
            <Literal>
               <ID>PropertyType</ID>
               <Default>PropertyType</Default>
               <ToolTip>The type of the dependency property.</ToolTip>
            </Literal>
            <Literal>
               <ID>ClassName</ID>
               <Default>ClassName</Default>
               <ToolTip>The name of the owner class.</ToolTip>
            </Literal>
         </Declarations>
         <Code Language="CSharp">
            <![CDATA[// Defines a DependencyProperty named $PropertyName$ of type $PropertyType$ for the $ClassName$ class.
            public $PropertyType$ $PropertyName$
            {
               get { return ($PropertyType$)GetValue($PropertyName$Property); }
               set { SetValue($PropertyName$Property, value); }
            }
            public static readonly DependencyProperty $PropertyName$Property = DependencyProperty.Register("$PropertyName$", typeof($PropertyType$), typeof($ClassName$), new PropertyMetadata(On$PropertyName$PropertyChanged));
            private static void On$PropertyName$PropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
            {
               $ClassName$ control = d as $ClassName$;
            }]]>
         </Code>
      </Snippet>
   </CodeSnippet>
</CodeSnippets>



Improve productivity by using code snippets

Code snippets are a great way of improving your productivity because they allow you to define pieces of code which you can later on insert into your projects by using a short alias.

Although they’ve been in Visual Studio for quite some time not many people know what they are, what exactly they do and how to use them in their advantage. Hearing about them is one thing, using them it’s another thing. Almost every one of us (those who write code) used them at least once in our lives and the best example I can think of while saying this is: foreach. I mean, how many times have you typed in foreach and then pressed TAB twice for some code to magically appear at your cursor’s location? Yea, that’s a code snippet! And there is a lot more from where that came from. There are code snippets for things like class definition, constructors, destructors, structures, for, do-while, etc. and a complete list (for C#) can be found here: Visual C# Default Code Snippets.

But those are just a small part of what code snippets can offer, those are the default code snippets that come with Visual Studio. The really nice thing about code snippets is that you can define your own and then use them to insert code in your projects wherever and whenever you want.  I will try and create a simple tutorial on how to create your own code snippet sometime next week, until then you can check out this page.

For those of you looking for a couple of general snippets to add to the already existing one, there’s a nice project on codeplex which contains exactly 38 C# code snippets ready to be added to your collection. Adding them to your Visual Studio is easy: just download the zip file from the link mentioned above and extract the file. Then go to Tools -> Code Snippet Manager or press Ctrl + K, Ctrl + B and click on Import. Browse to the folder where you’ve extracted the zip file, select all the code snippets inside the folder and hit Open, then select which folder / category to add them in (My Code Snippets by default) and click finish. And voila! they are ready to be used. To try them out and see if they really work you can try for example typing task or thread somewhere and hitting TAB twice – your code should be automatically inserted.

So, that’s it for now. As I’ve promised, how to create your own code snippets and maybe also something about some snippet designers coming up next week.