Visual Studio Code Snippets - Part 2 - Creating Code Snippets

Sat, 05 Apr 2008 08:35:00 GMT

Following on from my previous post on code snippets, here's instalment two! In this part, I want to guide you through creating your own basic code snippets, in part three, we will cover a few "advanced" features of code snippets.

To avoid any confusion, I will demo everything in Visual Studio 2005 since 2008 has a few features that may take us away from what we are doing here.

Creating a Code Snippet

Snippets are basically just XML files that contain some code and metadata. As covered in the introductory post, the code is inserted when you type the shortcut into Visual Studio. The XML files are then stored in "My Code Snippets" (or another folder of your choosing) for use by the IDE. There are a number of ways to create these XML files, and I will talk you through a couple of them.

Good Ol' Fashioned Text Editor

Obviously, XML is plain text and can be edited in Notepad, Notepad2 (or your text editor of choosing). I like to use Notepad2 for my basic text editing, and here is a screen shot of my "ToDo" code snippet within Notepad2:

As you can see, it looks pretty straightforward. I strongly recommend that if you are going to create code snippets in this way, then you copy and paste and existing one and edit that. This makes sure you don't miss any details, and its obvious "what does what". This is especially useful if you are new to code snippets.

Snippy

While using a text editor is fine, I find that when you are creating a lot of these, or trying to maintain them, then you start to get fed up with it. So I began searching the Internet for a code snippet editor. A Google returns a lot of results and I tried several until I found Snippy. Snippy is a lightweight, simple tool (now found on CodePlex). The screen shot to the right is the same "ToDo" code snippet in Snippy:

So, I found Snippy and stuck with it, I didn't want anything fancy, just something to make my life easier, so lets go through creating a code snippet in Snippy!

Walkthrough

NOTE: In the following scenario, I know I could use generic events etc. but I have opted for the explicit declarations so the code is clear to anyone unfamiliar with generics.

OK, let's outline the scenario:

I don't know about you, but I create utility methods to raise my Events, since you need to check that the Event is not null, as well as possibly allowing the Event to be raised by subclasses of a superclass, such as the following:

   1: public delegate void MyEventHandler();   2: public event MyEventHandler MyEvent;   3:     4: // event can only be raised by this class.   5: void RaiseMyEvent()   6: {   7:     if (MyEvent != null)   8:     {   9:         MyEvent();  10:     }  11: }  12:    13: void Foo()  14: {  15:     // ... some stuff  16:     RaiseMyEvent();  17: }  18:    19: public delegate void MyEventHandler2(EventArgs e);  20: public event MyEventHandler2 MyEvent2;  21:    22: // this event can be raised by this class, and subclasses.  23: protected void RaiseMyEvent2(EventArgs e)  24: {  25:     if (MyEvent2 != null)  26:     {  27:         MyEvent2(e);  28:     }  29: }  30:    31: void Bar()  32: {  33:     // some other stuff...  34:     RaiseMyEvent2(new EventArgs());  35: }

So as you can see, the code is pretty simplistic, and repetitive. This is an ideal example of when a code snippet would be useful.

Creating the Code Snippet in Snippy

So, lets make this into a code snippet! Fire up Snippy and you will be presented with a blank form. Enter the following info into the fields provided. These fields are pretty self-explanatory, but "Shortcut" deserves a special mention, this is the shortcut that you type in Visual Studio, so keep it short and understandable:

Title: RaiseEvent Wrapper
Shortcut: re
Author: Your Name (obviously replacing with your own name!)
Description: Creates a wrapper method for raising an event. The method is marked as protected, allowing subclasses to raise the event. (or whatever you feel is appropriate)

Ignore the "namespaces" section, this doesn't seem to do anything (yet).

Literals and Objects

The next section is the "Literals & Objects" section. So "what are these?" you ask. Well, in a code snippet you have replaceable values that you can tab through, as described in Part 1. Literals & Objects are these replaceable values, but they are each intended for different meanings.

Literals are should be things like text and values that exist within the code snippet and may be used after. So things like variable names, connection string etc. should be defined as Literals.

Objects are elements that are normally defined outside of the code snippet, such as Forms, controls. Object references require that the type is specified.

NOTE: Snippy makes no differentiation between Literals and Objects and treats them equally (i.e. no type specification. I have suffered no negative side-effects of just defining everything as "Literal" although of I have yet to investigate this to see the difference between the two (added to ToDo!).

I often find that it is easier to complete this section after writing the code, so lets go ahead and put the code in first.

The Code

Paste in the following base code taken from the above sample into the big text box in the "Code" section:

   1: protected void RaiseMyEvent2(EventArgs e)   2: {   3:     if (MyEvent2 != null)   4:     {   5:         MyEvent2(e);   6:     }   7: }

OK, first off, we need to identify what elements of the code are going to change when we use it, from the RaiseEvent code, we will need to change:

The method name to "RaiseEventName", where "EventName" is the name of the event we are raising.
"EventArgs" to the type name of the EventArgs that we are passing.
"MyEvent2" (in both parts of the "if" statement to the Event name.

So, we essentially need two pieces of information, the event name, and the EventArgs type. It would also be useful if the "EventArgs" type defaulted to "EventArgs" since all classes should derive from this.

So we know what we need to replace, so before we need to set the placeholders within the code that will later be replaced by the customised values. You do this by adding an ID to the code, surrounded in dollar symbols ($). As with code, name your values appropriately. We will call our placeholder ID's "$name$" and "$argstype$". Edit the code in the "Code" TextBox to:

   1: protected void Raise$name$($argstype$ e)   2: {   3:     if ($name$ != null)   4:     {   5:         $name$(e);   6:     }   7: }

As you can see, its pretty straightforward what is going on here, the placeholders defined will be replaced with the values we enter when using the code snippet in the IDE.

Once the code has been entered, change the "Language" drop down list to whatever language the code is in. This is important because Visual Studio will only allow you to use C# code snippets in C# source, C++ snippets in C++ source and so on.

Now we need to go back to our Literals and Objects and define the Literals that we are going to be replacing.

Literals Revisited

Click the "Add" button to add a Literal, we will start with the Event Name.

Enter the following into the fields provided and click "OK":

ID: name
ToolTip: Enter the name of the Event, as declared in "public event ..."
Default Value: EventName
Function: [leave blank]
Declaration Type: Select "Literal" from the drop-down list.
Ensure "Editable" is checked.

This tells the code snippet (or the IDE) that when creating the code snippet, any elements in the code block defined as "$name" will be replaced by what we enter. In Visual Studio, the text entered for ToolTip will be displayed, and it will default to "EventName". The "Editable" flag indicates that we want to be able to tab through it and change it.

That said, lets go ahead and define the Literal for the "argstype" element.

ID: argstype
ToolTip: The Type name for the EventArgs class being used for this Event.
Default Value: EventArgs
Function: [leave blank]
Declaration Type: Select "Literal" from the drop-down list.
Ensure "Editable" is checked.

OK, that's it! We are done, lets go ahead and save the snippet!

Saving the Snippet

Click File > Save As. Then navigate to where you want to save the code snippets, I recommend you save them in My Documents > Visual Studio 2005 (or 2008) > Code Snippets > [Language] > My Code Snippets. As this folder is automatically monitored by the IDE for code snippets. Lets go ahead and name the file "RaiseEvent Wrapper Method".

Once saved, we can close Snippy and return to the Visual Studio IDE.

Using the Snippet

Simply go to the point in the code where you want to insert the code snippet and enter the shortcut and press TAB twice, in this example, the shortcut was "re", and here are the results:

Excellent! As you can see, we can then type over the "EventName" with our own event name, and TAB to and replace the EventArgs type definition (if required). This is an excellent example of not only boosting productivity for mundane code, but also enforcing naming conventions by using and adhering to templates.

Points to Note:

Notice how the IDE only allows one "tabbable" placeholder and automatically updates the other references.
If you duplicate shortcuts, Visual Studio will prompt you to select the appropriate shortcut (nice to see someone was thinking ahead!). This is great if you want to set up similar code blocks but keep the number of shortcuts to remember down (for example, another RaiseEvent block that takes no event args can share the "re" shortcut).

Summary

So in this post we:

Looked at creating basic snippets to use within Visual Studio.
Created a basic code snippet that creates a method to act as a wrapper for RaiseEvent calls.
Then enabled us to customise the code block by defining our own Event name and EventArgs type.
Looked at some of the key points when using code snippets, such as duplication of shortcuts and the number of tabbable placeholders.

In the next instalments of this series, we will look at some more advanced code snippets such as using functions and creating larger code blocks.

I hope you found this post useful and as always, if you have any questions/comments, then please feel free to comment below!

Technorati Tags: Visual Studio,Code Snippet,Productivity,Code Block,Snippy

Visual Studio Code Snippets - Part 1 - Using Code Snippets

Tue, 01 Apr 2008 20:40:00 GMT

I recently read this blog post from Peter Lanoie, a great guy who I met through p2p.wrox.com about Visual Studio code snippets, it really got me thinking that I should post my own experiences to try and get more people into using them, and perhaps sharing their own snippets.

A Code What?

Not sure what a code snippet is? Well, a code snippet is simply some code that can be inserted into Visual Studio by typing a shortcut. These are designed to be time savers, as well as provide the added benefits of consistency of coding standards and style.

For example, lets take the most common, as mentioned in Peter's post, the property.

Whenever we write classes we need to define fields and properties to enable the outside world (code?) to access it. We can literally do hundreds of these over the course of a project. So it quickly becomes very annoying creating them. Situations like this are the ideal scenarios where a code snippet can save A LOT of time.

OK, Sounds Good, How Do I Use It?

Inserting a code snippet is easy, thanks to Intellisense. As I said before, each code snippet can be assigned a shortcut, you simply type in this shortcut into your code, and Intellisense will pop up and let you know that you can insert a snippet, see the image, here I am inserting the 'prop' (Property) code snippet:

Now, you are probably asking, "fine, I see the 'prop' and the nice Intellisense description, but where's my code?!" Good question, once the item code snippet is highlighted in Intellisense, you simply press TAB twice to insert it, you then get the following:

But I Don't Want an 'int' and I Don't Want It Called "MyProperty"!

That's fine, they are just the defaults! As you may have noticed, the 'int' and 'MyProperty' are highlighted, this means that you can TAB through them and replace their text. In my example, I want a string called 'Name', so I:

Type 'pro' (Intellisense picks it up the 'prop' as the closest match).
I press TAB twice. The code is inserted.
I type 'string' and the 'int' is replaced.
I press TAB again and the cursor moves to 'My'Property' and selects it.
I type 'Name' and 'MyProperty' is replaced.

IMPORTANT NOTE: I am using Visual Studio 2008 for this, which has automatic properties (which is what Peter's post was discussing), note, then you are using 2005, you also have the ability to tab over the private field declaration, as shown below:

Notice when you change the private field declaration, the values in the getter/setter change? Neat!

These are a powerful part in your arsenal of weapons to help make you a more productive developer/programmer. Use Them! One this I am always conscious of is "how long do I spend doing this, is this too long? Can I speed it up?". If you find you are writing the same/similar blocks of code more than once/twice a day, it may well be an excellent candidate for a snippet. For example consider these scenarios:

Comment block headers.
"ToDo" notes.
Wrapper methods.
Standard Exception type declarations.
"Using" statements, of both types! (as in 'using System' and 'using (Graphics g ...)'
Templates for double-buffered graphics.
Data access code, query execution etc.

Think about the common code that you type daily and whether or not it may be worth "snipping" it.

Remember, they are freely definable, in part two, I will go over how to create them!

Technorati Tags: visual studio,code snippet,productivity

The Ramblings of Rob Cooper: Visual Studio