Using Code Snippets in Visual Studio 2005

I want you to know that your illustrious executive editor, Brad Jones, is looking out for you. I proposed this article in my quarterly column calendar and Brad asked me if this was going to be a drag-and-drop article. I answered: No.

His question illustrated why I wanted to write this article. Current versions of Visual Studio.NET support snippets—simply drag and drop some code into the toolbox and you can reuse it anytime you'd like. While useful, this function is not very exciting and it's often overlooked. Code snippets in Visual Studio 2005, however, are far more useful and deserve your attention. Based on XML, they support replaceable parameters, allow inserting assembly references and imports statements, and enable better organization. They also let you share management with other developers easily.

This article is my meager effort to encourage you to take advantage of code snippets. It briefly demonstrates how to create a snippet in Visual Studio 2005 beta 2 using XML.

Half-Baked Beta Bumps

Beta means not quite finished. Think of beta applications as muffins pulled out of the oven before they are baked. Glaringly missing from the VS 2005 beta 2 is a code snippet editor. The official public statement is that the code snippet editor isn't quite ready for users. While waiting for the final release of VS 2005, you can download an external code snippet editor that comes complete with source code from MSDN. The examples in this article use this sample VB code snippet editor, which you can use until VS 2005 ships with its built-in editor.

What Are Code Snippets?

A code snippet is exactly what it sounds like: a small piece of code. Like project templates and project item templates, code snippets are discrete chunks of written code. Also, like templates, code snippets support replaceable parameters, which permit you to customize a snippet for each context.

If you need whole projects or project items, you can use templates. For something smaller or just to show the code in IntelliSense and make it pluggable, use code snippets.

Create a Code Snippet

Code snippets are stored as XML in a file with a .snippet extension. Like all XML, these code snippet files have a specific format. Additionally, the snippet files need to be placed where Visual Studio can locate them. To this end, the snippet manager—which the final section covers—makes it easy to organize snippets.

XML, being based on SGML (Standard Generalized Markup Language), is an elegant concept but an ugly language that isn't very human friendly. However, it is very useful in the Internet age because its text, its extensibility, and its predictable format-simply identify an opening tag and then fill in the blanks between the opening and closing tags. (Almost every tag has a symmetric closing tag with the same name and an additional forward slash (/).)

Snippets support tags for replaceable elements, but the simplest snippets—those that contain literal code with no parameters—just need the code you want to insert. This code is an attribute of the <Code> tag. Listing 1 contains a simple Hello, World! snippet. To create additional snippets, copy and paste the literal code in the [CDATA] attribute with the new snippet code.

Listing 1: XML for a Literal Snippet

<?xml version="1.0"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/
                            2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>Canonical Hello, World! example</Title>
    </Header>
    <Snippet>
      <Code Language="VB"><![CDATA[MsgBox("Hello, World!")]]></Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

Add Imports and References

You add imports and references after the <Snippet> tag. If you want to add an assembly reference, add a <Reference> tag with a nested <Assembly> tag followed by the name of the assembly (see Listing 2). Add <Import><Namespace> tags after the <Reference> tag. The <Imports> tag adds imports statements to the same module that you added the snippet to.

The excerpt in Listing 2 shows how to reference the System.Data.dll assembly and add an imports statement for the System.Collections namespace.

Listing 2: Elided Excerpt from a Snippet File Showing the Tags for an Assembly Reference and a Namespace Imports Statement

<?xml version="1.0"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/
                            2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title />
    </Header>
    <Snippet>
      <References>
        <Reference>
          <Assembly>System.dll</Assembly>
        </Reference>
      </References>
      <Imports>
        <Import>
          <Namespace>System.Collections</Namespace>
        </Import>
      </Imports>
      <Declarations>
...

Add Literal and Object Replacements

Replacements represent elements of your snippet that the user has to provide. To identify a replacement, add a <Declarations> tag at the same level as the <References> and <Imports> tags. If the replacement is a literal, add a <Literal> nested tag; for objects, add an <Object> nested tag. Both literal and object tags include <ID>, <ToolTip>, and <Default> child tags, and the object tag has an extra <Type> child tag that indicates the type of the object.

Using Code Snippets in Visual Studio 2005

Listing 3 shows a declarations section. Listing 4 shows a complete example demonstrating how to create a code snippet that generates a strongly typed collection.

Listing 3: Example Declarations Section for a Code Snippet

<Declarations>
  <Literal>
    <ID>SqlConnString</ID>
    <ToolTip>Replace with a SQL connection string.</ToolTip>
    <Default>"SQL connection string"</Default>
  </Literal>
<Object>
  <ID>SqlConnection</ID>
  <Type>System.Data.SqlClient.SqlConnection</Type>
  <ToolTip>Replace with a connection object in your application.
  </ToolTip>
  <Default>dcConnection</Default>
</Object>
</Declarations>

Listing 4: Complete Code Snippet That Will Stub a Strongly Typed Collection

<?xml version="1.0"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/
                            2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>Create a typed collection</Title>
    </Header>
    <Snippet>
      <References>
        <Reference>
          <Assembly>System.dll</Assembly>
        </Reference>
      </References>
      <Imports>
        <Import>
          <Namespace>System.Collections</Namespace>
        </Import>
      </Imports>
      <Declarations>
        <Literal>
          <ID>CLASS</ID>
          <Default>Customer</Default>
        </Literal>
      </Declarations>
      <Code Language="VB"><![CDATA[Public Class $CLASS$Collection 
        Inherits System.Collections

      Public Default Property Item(ByVal Index As Integer) As $CLASS$
  Get
    Return CType(List(Index), $CLASS$)
  End Get
  Set(ByVal Value As $CLASS$)
    List(Index) = Value
  End Set
  End Property

  Public Function Add(ByVal Value As $CLASS$) As Integer
    Return List.Add(Value)
  End Function
End Class]]></Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

I created the XML snippet file in Listing 4 by entering the code in Listing 5 in the editor tab of the snippets editor.

Listing 5: Using the Snippets Editor Is Easier Than Writing the XML from Scratch

Public Class $CLASS$Collection 
  Inherits System.Collections

  Public Default Property Item(ByVal Index As Integer) As $CLASS$
    Get
      Return CType(List(Index), $CLASS$)
    End Get
    Set(ByVal Value As $CLASS$)
      List(Index) = Value
    End Set
  End Property

  Public Function Add(ByVal Value As $CLASS$) As Integer
    Return List.Add(Value)
  End Function
End Class

As you can see, using the editor is much simpler than writing the XML (in Listing 4). When Visual Studio 2005 ships, you will be able to select code from your projects and create a snippet directly from the code editor.

Manage Snippets

The Tools|Code Snippets Manager is a centralized manager for organizaing code snippets. You can add additional directories; import, add, and remove snippets; and search for snippets online.

Keep in mind that VS 2005 is still in beta, so some elements of the beta Code Snippets Manager may be a bit cantankerous. For now, all you can do is use the temporary code snippets editor and save your snippets to C:\Documents and Settings\yourusername\My Documents\Visual Studio\Code Snippets\Visual Basic\My Code Snippets. As long as you save the files with a .snippet extension and give them titles, they will show up in the IntelliSense snippets dropdown menu (see Figure 1).

Figure 1: The VB Code Snippets Editor

Insert Snippets

After you have created the .snippet file and copied it to the My Code Snippets folder, you can use the snippet to generate code. To insert the snippet, select Edit|Intellisense|Insert Snippet, navigate through the list of snippets—which are organized just as they are in the file system—and select the snippet (see Figure 2).

Figure 2: Ctrl K+Ctrl X Display the List of Snippets

After inserting the snippet, code elements that were marked as replaceable will be highlighted (see Figure 3). Replace the highlighted elements with the actual value. For example, if you want the Customer collection in Figure 3, you can leave the code as is. Otherwise, replace all of the highlighted instances of Customer with the type you will be collecting.

Figure 3: Replaceable Elements Are Highlighted

Snippets Have Come a Long Way

When you follow the examples in this article, keep in mind that VS 2005 is still in beta. Using beta software can be frustrating, but it can also be a lot of fun. Be patient.

In any case, I hope you got a sense of how far code snippets have evolved from simply copying and pasting text in the toolbox. They now offer manageable, shareable code with replaceable elements, assembly references, and imports statements. I'd say that makes for more than a simple a drag-and-drop article.

About the Author

Paul Kimmel is the VB Today columnist for www.codeguru.com and has written several books on object-oriented programming and .NET. Check out his upcoming book UML DeMystified from McGraw-Hill/Osborne (Spring 2005) and Expert One-on-One Visual Studio 2005 from Wrox (Fall 2005). Paul is also the founder and chief architect for Software Conceptions, Inc, founded 1990. He is available to help design and build software worldwide. You may contact him for consulting opportunities or technology questions at pkimmel@softconcepts.com.

If you are interested in joining, sponsoring a meeting, or posting a job, check out www.glugnet.org, the Web page of the Greater Lansing area Users Group for .NET.

Copyright © 2005 by Paul T. Kimmel. All Rights Reserved.



Comments

  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Java developers know that testing code changes can be a huge pain, and waiting for an application to redeploy after a code fix can take an eternity. Wouldn't it be great if you could see your code changes immediately, fine-tune, debug, explore and deploy code without waiting for ages? In this white paper, find out how that's possible with a Java plugin that drastically changes the way you develop, test and run Java applications. Discover the advantages of this plugin, and the changes you can expect to see …

  • Mobile is introducing sweeping changes throughout your workplace. As a senior stakeholder driving mobile initiatives in your organization, you may be lost in a sea of technologies and claims from vendors promising rapid delivery of applications to your employees, customers, and partners. To help explain some of the topics you will need to be aware of, and to separate the must-haves from the nice-to-haves, this reference guide can help you with applying a mobile strategy in the context of application …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds