BlackWaspTM

This web site uses cookies. By using the site you accept the cookie policy.This message is for compliance with the UK ICO law.

Visual Studio
VS 2005+

Creating Code Snippets with Replacements

Visual Studio 2005 introduced code snippets to allow common code to be quickly inserted into a source file. Snippets can include static text and placeholders that can be replaced after insertion, with help from the integrated development environment.

Code Snippets

In an earlier example I described how you can create your own code snippets, register them and insert them using Visual Studio. The example snippet contained static code for the basic IDisposable pattern. Using the snippet the entire pattern could be added to a C# class file with a few keystrokes.

Replacements

Snippets can be made more useful with the use of replacements. These are named placeholders that are highlighted within the code when the snippet is inserted. You can use the tab key to jump between the placeholders and overtype the default values. This is useful when a snippet includes a variable or member name that you will want to change. The same placeholder literal may be used multiple times for such an item, with all instances being replaced with the typed text.

An example of a standard snippet with replacements is used to create a new property definition. If you type "prop" within a C# code file and then press the tab key twice, a property with a default type and name is inserted. You can tab between these elements and replace the names easily. NB: In Visual Studio 2005 the property also includes a backing store variable that can be renamed.

In this article we will create a new snippet that inserts the basic code for an event that is based upon the EventHandler delegate. I will not explain the basics of creating or registering the snippet, as this was covered in the earlier article.

Creating the Snippet File

We will start by creating the XML for a snippet that includes the basic layout for the event without placeholders. Add the following to a new XML file:

<?xml version="1.0" encoding="utf-8"?>
<CodeSnippet Format="1.0.0"
    xmlns="http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet">
    <Header>
        <Title>Create Event</Title>
        <Author>BlackWasp</Author>
        <Shortcut>ehevent</Shortcut>
        <Description>Code for an event based upon
        the EventHandler delegate.</Description>
        <SnippetTypes>
            <SnippetType>Expansion</SnippetType>
        </SnippetTypes>
    </Header>
    <Snippet>
        <Code Language="CSharp">
        <![CDATA[public event EventHandler MyEvent;
			
        public virtual void OnMyEvent()
        {
            if (MyEvent != null)
                MyEvent(this, EventArgs.Empty);
        }]]></Code>
    </Snippet>
</CodeSnippet>

If you were to register the above snippet, inserting it by typing "ehevent" and pressing the tab key twice would add the following code:

public event EventHandler MyEvent;

public virtual void OnMyEvent()
{
    if (MyEvent != null)
        MyEvent(this, EventArgs.Empty);
}

The snippet would be useful but the naming is poor. Ideally we would like a placeholder that can be replaced wherever the text, "MyEvent" is present, including in the name of the "OnMyEvent" method. To achieve this we can create a replacement.

A replacement consists of a named literal, with a default value, and some placeholders within the code. Any number of literals may be defined within the Declarations element of the XML, which is added inside the Snippet element before the Code tag. Each literal includes a unique ID, a default value and an optional tool tip. When you insert the snippet into your code each placeholder is automatically given the default value.

We only need one literal declaration for the event sample. To declare it with an ID of "EventName", a tool tip of "Enter the event name" and a default value of "MyEvent", add the following XML beneath the opening Snippet tag:

<Declarations>
    <Literal>
        <ID>EventName</ID>
        <ToolTip>Enter the event name</ToolTip>
        <Default>MyEvent</Default>
    </Literal>
</Declarations>

To specify where a literal will be inserted you add the literal name to the code, surrounded with dollar symbols ($). Ours will be declared as "$EventName$". We need to add four placeholders, as follows:

<![CDATA[public event EventHandler $EventName$;
			
public virtual void On$EventName$()
{
    if ($EventName$ != null)
        $EventName$(this, EventArgs.Empty);
}]]>

You can now save and register the snippet. Once registered, create a new C# class file, type "ehevent" and press the tab key twice. Replace the "MyEvent" default text with a more suitable name for an event before moving the cursor away from the placeholder. All four occurrences of the event name will be updated.

25 February 2011