Code Snippets

Copy and Paste

Of course, copying and pasting code remains available. The main disadvantages are that the Clipboard is a shared resource—the contents of the Clipboard can be altered by another application. Clipboard data is not retained across logon sessions. Visual Studio lets developers copy source code directly to the toolbox. The code is then preserved on the toolbox for future placement. This is not as elegant as a snippet but sometimes quicker and more convenient—especially when a custom snippet is required. Code placed on the toolbox is preserved between Visual Studio and logon sessions. Unlike the Clipboard, the toolbox is not a shared resource and is available only to Visual Studio.

There are two methodologies for placing code on the toolbox. Select the code and copy to the Clipboard. Next click on the toolbox and paste the code. You can also drag the code onto the toolbox. A button is then created on the toolbox for the code. Multiple passages of code can be added to the toolbox. Moving the mouse over a code button in the toolbox displays the saved code. Click a code button to insert the code at the cursor. As a best practice, create a separate tab on the toolbox to group code. Intermingling code with nonrelated buttons can be confusing. A toolbox populated with source code is shown in Figure 4-30. A tab called Code was added to the toolbox to group the source code.

Figure 4-30: Toolbox with code

Insert a Code Snippet

There are several ways to insert code snippets into source code. IntelliSense is probably the simplest method. Code snippets appear in the completion list as a torn page. Use a complete word to select the code snippet and then press Tab to insert. Alternatively, double-click the snippet in the completion list.

Use the following techniques to select and insert code snippets. Inserting a snippet is called code expansion.

• Insert a code snippet using IntelliSense. The completion list includes snippets.

• Insert a code snippet from a menu using the Insert Snippet menu command. Insert Snippet is also available from the shortcut menu in the Code Editor. You will be prompted to insert the name of the snippet. Find the Insert Snippet menu command on the Edit menu and the IntelliSense submenu. The resulting completion list includes only code snippets. This is called the snippet picker.

• Ctrl+K and then Ctrl+X is the keyboard shortcut for the Insert Snippet menu command.

• Insert a code snippet using Auto IntelliSense. Position the cursor where the snippet should be inserted, type the name of snippet, and then press Tab twice.

Some code snippets are templates and contain editable fields. After inserting the code snippet, a developer customizes the template by assigning values to each field. The first field is selected automatically when the code snippet is inserted. Other fields in the code template are color-highlighted. There can be multiple instances of a field in the same code snippet. For example, there are several instances of the i field in the code snippet of the for keyword. The first instance of a field is color-highlighted and editable. Remaining instances are notated with a dotted border. Tab moves to the next field, whereas Shift-Tab moves to the previous file. You can double-click to select a field. Fields with tooltips display the tip when the field is selected. Figure 4-31 shows the code snippet of the for keyword. It has the ‘i' and length fields. Figure 4-32 presents the snippet with the fields customized.

Figure 4-31: Code snippet of the for keyword

Figure 4-32: Customized code snippet

When using a Surround With template, select the target code first and then insert the snippet. The snippet will surround the code. For example, the following code increments a counter:

int count = 0;
Console.WriteLine(++count);
if (count == 10)
{
    break;
}

This is the result of selecting the code and inserting the code snippet for the while keyword:

while (true)
{
    int count = 0;
    Console.WriteLine(++count);
    if (count == 10)
    {
        break;
    }
}

Default Snippets

Visual Studio 2005 has default snippets for tasks that are routine for developers. The default is a mixture of expansion and surround with code snippets. Default snippets appear in the IntelliSense completion list and the code snippet picker. Table 4-4 lists some of the default code snippets.

Code Snippets Manager

Use the Code Snippets Manager to manage snippets, including adding, removing, importing, and searching for snippets.

The Code Snippets Manager is available on the Tools menu. (See Figure 4-33.) The folders shown in the Code Snippets Manager are snippet directories. Open a folder to view individual snippets. For each snippet, the follow information is provided:

• Description of the code snippet

• Alias or shortcut of the code snippet

• Snippet type

• Author of the snippet

Figure 4-33: Code Snippets Manager

The Add button in the dialog box adds another directory to the list of code snippet directories. A code snippets directory contains code snippet files, which are XML files with the .snippet suffix. For C#, the default snippets directories are My Code Snippets, Refactoring, and Visual C#. The Remove button removes a snippet directory from the list. The Import button imports a code snippet file. Use the Search Online button to browse for code snippets. This button opens a general search window, in which developers can search for the code snippets. When you find the code snippet you're searching for, you can download it to the local machine.

Downloading snippets found online can pose security problems. A snippet is not guaranteed to have innocuous XML. In addition, the snippet might hide malicious scripts. The Help URL element defined in the snippet might stealthily launch a script. Also, code snippets can silently add references. Malicious calls are then possible to functions in the reference. Long snippets can hide potentially harmful code. Be careful when downloading code snippets with database access, code-access security, role-base security, or validation code. As a best practice, carefully review the source code of code snippets that are downloaded before using in an application.

Creating Snippets

You can create custom code snippets to encapsulate reusable code not found in a default snippet, which allows you to maintain private libraries of reusable code. Different industries might benefit from specialized code snippets. For example, a developer of medical software may have a need for medical code snippets. Developers of legal software could benefit from legal code snippets. I am confident that vendors will publish industry-specific code snippets in the future.

Custom code snippets are created in XML files. Microsoft publishes an XML schema for code snippets. Code snippet files should have the .snippet extension. When the schema is set, Visual Studio 2005 offers IntelliSense on the XML elements and attributes, which helps considerably in creating properly formed code snippet files. You can group custom snippets in directories. Add these directories to the Code Snippets Manager to make using the custom snippets more convenient.

The XML schema for code snippets defines the structure of a code snippets file. For a complete explanation of the schema, visit the Code Snippet Schema Reference at http://msdn2.microsoft.com/en-us/library/ms171418(en-us,vs.80).aspx. Some parts of the schema are discussed in the next few pages.

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

<CodeSnippet>
  <!-Insert code snippet here. -->
</CodeSnippet>

<Header>
  <Title>StringBuilder</Title>
  <Shortcut>sb</Shortcut>
  <Description>Creates a new String Builder</Description>
  <Author>Donis Marshall</Author>
</Header>

<Snippet>
  <References>
    <Reference>
      <Assembly>System.Text.Dll</Assembly>
    </Reference>
  </References>
  <Imports>
    <Import>
      <Namespace>System.Text</Namespace>
    </Import>
  </Imports>

<Declarations>
  <Literal>
    <ID>Name</ID>
    <Default>mytext</Default>
    <ToolTip>Name of new StringBuilder</ToolTip>
  </Literal>
  <Literal>
    <ID>Size</ID>
    <ToolTip>Capacity of String</ToolTip>
  </Literal>
</Declarations>

<![CDATA[snippetcode]]>

<Code Language="CSharp">
  <![CDATA[StringBuilder $Name$=]]>
  <![CDATA[    new StringBuilder($Size$);]]>
</Code>

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
  <CodeSnippet Format="1.0.0">
    <Header>
      <Title>StringBuilder</Title>
      <Shortcut>sb</Shortcut>
      <Description>Creates a new String Builder</Description>
      <Author>Donis Marshall</Author>

    </Header>
    <Snippet>
      <References>
        <Reference>
          <Assembly>System.Text.Dll</Assembly>
        </Reference>
      </References>
      <Imports>
        <Import>
          <Namespace>System.Text</Namespace>
        </Import>
      </Imports>
      <Declarations>
        <Literal>
          <ID>Name</ID>
          <Default>mytext</Default>
          <ToolTip>Name of new StringBuilder</ToolTip>
        </Literal>
        <Literal>
          <ID>Size</ID>
          <ToolTip>Capacity of String</ToolTip>
        </Literal>
      </Declarations>
      <Code Language="CSharp">
        <![CDATA[StringBuilder $Name$=]]>
        <![CDATA[new StringBuilder($Size$);]]>
      </Code>
    </Snippet>
  </CodeSnippet>
</CodeSnippets>

Create a Code Snippet Walkthrough

The section provides a walkthrough for creating a code snippet. Before creating a snippet, it is best to write and test the code. Convert the code into a code snippet only after a successful code compilation. Custom code snippets should be placed in dedicated directories reserved for custom snippets. Make sure that the directory is eventually added as a code snippet directory using the Code Snippets Manager.

This walkthrough creates a code snippet that reflects the methods of a type. This code tests the proposed snippet:

// Snippet starts
Type t = typeof(Object);
string typename = t.Name;
string typenamespace = t.Namespace;
MethodInfo [] methods = t.GetMethods();
// Snippet ends
Console.WriteLine("Type Name:"+typename);
Console.WriteLine("Namespace Name:"+typenamespace);
foreach (MethodInfo method in methods)
{
    Console.WriteLine(method.Name);
}

These are the steps for creating the preceding snippet:

1. Create an XML file in Visual Studio. The filename of the code snippet is reflectmethod.snippet.

2. All snippet files begin with the CodeSnippets, CodeSnippet, and Header elements, which name the file schema and describe the basic attributes of the code snippet:

   <?xml version="1.0" encoding="utf-8"?>
   <CodeSnippets xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
     <CodeSnippet Format="1.0.0">
       <Header>
         <Title>ReflectMethod</Title>
         <Shortcut>rm</Shortcut>
         <Description>Reflects methods of a type.</Description>
         <Author>Donis Marshall</Author>
       </Header>
     </CodeSnippet>
   </CodeSnippets>
   

3. Reflection requires the Reflection namespace. Import the System.Reflection namespace with an Import element, which is defined within the Imports element. The System.Reflection namespace is declared in the System.DLL, which is automatically referenced from managed code. For that reason, a Reference element is not needed.

   <Snippet>
     <Imports>
       <Import>
         <Namespace>System.Text</Namespace>
       </Import>
     </Imports>
   </Snippet>
   

4. The code snippet has four fields, which name the type, type instance, namespace, and MethodInfo array. The type instance is an object field. The other fields are literals and contained within the code snippet. Defaults for the fields are gleaned from the code used to test the code snippet. Fields are defined within the Declarations element with literal and object elements:

   <Declarations>
     <Literal>
       <ID>Instance</ID>
       <Default>t</Default>
       <ToolTip>Name of instance.</ToolTip>
     </Literal>
     <Literal>
       <ID>TypeName</ID>
       <Default>typename</Default>
       <ToolTip>Name of type.</ToolTip>
     </Literal>
     <Literal>
       <ID>TypeNamespace</ID>
       <Default>typenamespace</Default>
       <ToolTip>Namespace of type.</ToolTip>
     </Literal>
     <Literal>
   
       <ID>Methods</ID>
       <Default>Methods</Default>
       <ToolTip>Type methods</ToolTip>
     </Literal>
     <Object>
       <ID>Type</ID>
       <Default>Object</Default>
       <ToolTip>object type</ToolTip>
       <Type>System.Object</Type>
     </Object>
   </Declarations>
   

5. Paste the code for the snippet into <![CDATA]> elements, which are placed within the Code element. Add extra line feeds to separate lines of source code. After pasting the code, substitute the field names into the code:

   <Code Language="CSharp">
     <![CDATA[Type $Instance$ = typeof($Type$);
     ]]>
     <![CDATA[string $TypeName$ = $Instance$.Name;
     ]]>
     <![CDATA[string $TypeNamespace$ = $Instance$.Namespace;
     ]]>
     <![CDATA[MethodInfo [] $Methods$ = $Instance$.GetMethods();
     ]]>
   </Code>
   

6. Save the file for the code snippet in the directory reserved for custom code snippets.

7. Test the snippet in Visual Studio 2005. Open a source file and insert the code snippet using the code snippet picker. Figure 4-34 shows the snippet.

Figure 4-34: Reflect Method snippet