Chapter 12: Customizing the Development Environment 353 including CSharp VisualBasic, Web, and more, each folder corresponding to folders in the VS New Item window. Under each folder is a locale code—for instance, English is 1033— and you would copy the file into the locale folder for the category you wanted the project template to appear in. Unlike templates in the local item templates folder, where all you need to do is copy the file, item templates in the global item templates folder don’t automatically show up. To test the global item templates scenario, you should remove the item template from your local item templates folder. You must close down VS and execute the following in a command window, which you should open by selecting Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools | right-click Visual Studio Command Prompt (2010) and select Run As Administrator. This will take a few minutes to run, but afterward you’ll see the project appear in the VS New Item window. This command imports all of the item templates from the global item templates folder into VS: devenv /installvstemplates If later you decide you don’t want a given template to appear in the VS New Item window, remove the item template from the global item templates folder(s) and run the preceding command again. This section showed you how to add new project and item templates to VS, but sometimes you just want to add a common bit of code while you’re programming. The next section shows you how to add your own custom code snippets to VS. Creating Custom Snippets If you’ve been using VS snippets, as described in Chapter 2, you’ll know how much time they can save when writing common blocks of code. In time, you’ll wonder why certain items aren’t already covered by snippets, especially if you’re a C# developer who has noticed that VB has many more snippets. Even if you’re a VB developer with the plethora of available snippets, you might find blocks of code that will make you more productive when written in the form of a snippet. This chapter takes you to the next level in working with snippets by showing you how to create and manage your own snippets. Creating a New Snippet VB already has a snippet for Sub and Function, but C# doesn’t. Since C# doesn’t have as many snippets as VB, I’ll show you how to create a snippet in C#, but the process is similar for a VB snippet. To create a new snippet, you can either work from an existing snippet file or start from scratch. I’ll show you how to find and open existing snippets first. 354 Microsoft Visual Studio 2010: A Beginner’s Guide Examining Existing Snippets Snippets that ship with VS are located at \Program Files\Microsoft Visual Studio 10.0 under a folder for the language (VC#, VB, XML, and more) you need to find a snippet for. There, you’ll either find one or more folders named with language codes (English is 1033) or a folder named Snippets. For some languages, the language code is at a higher level and the Snippets folder is under that or vice versa; regardless, you’ll be looking for the Snippets folder that contains items with a .snippet file extension. The file path for C# is \Program Files\Microsoft Visual Studio 10.0\VC#\Snippets\1033. Beneath the Snippets folder, you’ll see additional folders that serve to categorize other snippets. We’re going to open the for snippet because it contains several features that give you a good idea of how snippets work. It might help if you open a blank file by pressing CTRL-N, selecting Visual C# Class, and naming the file anything you want, and try the for snippet before going further; it will give you a good idea of what the snippet is supposed to be doing. Alternatively, you can review the description of the for snippet in Chapter 2. The .snippet extension is registered with VS, so you can double-click the for.snippet file in the Snippets folder and it will open in VS. Listing 12-1 shows what this file looks like. Listing 12-1 Inside the for snippet <?xml version="1.0" encoding="utf-8" ?> <CodeSnippets xmlns= "http://schemas.microsoft.com/VisualStudio/2005/CodeSnippet"> <CodeSnippet Format="1.0.0"> <Header> <Title>for</Title> <Shortcut>for</Shortcut> <Description>Code snippet for 'for' loop</Description> <Author>Microsoft Corporation</Author> <SnippetTypes> <SnippetType>Expansion</SnippetType> <SnippetType>SurroundsWith</SnippetType> </SnippetTypes> </Header> <Snippet> <Declarations> <Literal> <ID>index</ID> <Default>i</Default> <ToolTip>Index</ToolTip> </Literal> Chapter 12: Customizing the Development Environment 355 <Literal> <ID>max</ID> <Default>length</Default> <ToolTip>Max length</ToolTip> </Literal> </Declarations> <Code Language="csharp"><![CDATA[for (int $index$ = 0; $index$ < $max$; $index$++) { $selected$ $end$ }]]> </Code> </Snippet> </CodeSnippet> </CodeSnippets> As shown in Listing 12-1, a snippet is an XML file where all data is defined by begin and end tags arranged in a hierarchy. Inside of the CodeSnippet tags are Header and Snippet elements. Inside of the Header element is a Shortcut element that defines the prefix you must type in the VS editor to use the snippet. The Title and Description tags define what displays for Intellisense in VS when the shortcut is being typed. Author tells who wrote the snippet. The SnippetTypes element defines the two ways to use a snippet: Expansion and SurroundsWith. Chapter 2 describes many snippets that work via Expansion. However, SurroundsWith snippets are also very useful. To use a SurroundsWith snippet, highlight the code that you want to surround, press CTRL-SPACE, and select the snippet. After selecting the snippet, the snippet template will appear in VS, with its blocks surrounding the highlighted text. Since the for loop has a block that can contain statements, it makes sense that the for snippet is both a SurroundsWith and Expansion snippet. The Snippet element in Listing 12-1 contains a Declarations and Code element, where the declarations are used in the code. Thinking about how snippet templates work, remember that your cursor is positioned on blocks of code that you change and tab through to complete the snippet. The blocks of code to be filled in correspond to Literal elements in the declaration. Each Literal element has an ID that is used in the Code to define where the Literal is located. Default describes the data shown in the template before you start typing. Whenever you’re filling in a snippet template, you can hover over the data field and a tooltip will describe what information should go into the data field. This tooltip is defined in the Tooltip element of the snippet definition. The ID of each literal is defined in the Code element. Inside the Code element is the code for the snippet. The variables in the code with $ prefix and suffix help define how the snippet template works. Notice that $index$ and $max$ match Literal elements in the Declarations element; this is where you must 356 Microsoft Visual Studio 2010: A Beginner’s Guide fill in data items when filling in the snippet template in VS. The $end$ variable defines where the cursor ends up after the snippet is complete (after pressing ENTER in the snippet template). You’ll want to locate $end$ where a developer would normally continue typing. The $selected$ variable is used with SurroundsWith snippets, defining the relationship of selected text with where snippet code should be. Now that you have a basic familiarity with snippets, the next section brings you to the next level as you actually create a new snippet. Creating New Snippets To create a new snippet, you can either work from an existing snippet file or start from scratch. If you work from an existing snippet, find and open the snippet closest to what you want to do, using the techniques described in the preceding section. Starting from scratch, there is a quick way to get started using a snippet snippet; that’s right, there is a snippet that helps you create new snippets. As you learned in the preceding section, snippets are defined as XML files. Fortunately, VS has a nice XML editor that supports XML snippets. So, when I say that we’re going to create a snippet from scratch, that’s not quite true, because we’re going to leverage VS to get a quick start. In the following steps, I’ll show you how to create a snippet you can use to add a C# method to a class quickly: 1. With VS open, press CTRL-N and create a new XML file. If you were opening the file from an existing project, you would need to provide a name, which would be meth .snippet. The new XML file has a single line, which is called an XML prefix. 2. Move to the line below the XML prefix, press CTRL-K-X, type sn to select Snippet in the Intellisense list, and press ENTER. You’ll see an XML snippet template with the values for Title, Author, Shortcut, Description, ID, and Default. 3. Fill in data and tab through the snippet template as follows: Title as Method Snippet, Author as <your name>, Shortcut as meth, Description as Create a New Method, ID as access, and Default as public. Press ENTER when complete. 4. The resulting snippet still needs code and template item definitions, which is accomplished by filling in the Code element and adding needed Literal elements. First, modify the code element as follows: <Code Language="csharp"> <![CDATA[$access$ $return$ $methodName$($paramList$) { $end$ } ]]> </Code> Chapter 12: Customizing the Development Environment 357 5. In addition to access, the code example in the preceding step includes variables for return, methodName, and paramList. Add Literal elements for each of these variables, where the ID is the variable name and the Default is set to return as void, methodName as MethodName, and paramList as int p1. 6. Save the file and name it meth.snippet. The next section will explain where to put the file, but for now put it in a location that you can remember so you can copy it later. BTW, the Save File dialog box has Snippet Files (*.snippet) for a Save A Type option, which you can use to ensure the snippet has the correct file extension. You now have a workable snippet. Listing 12-2 shows the snippet in its entirety. Additionally, notice how each Literal has a Tooltip to help the user of the snippet fill in each data item. Also, notice that the Language attribute of the Code element is spelled csharp, rather than C#. These small nuances, such as the spelling for a language, could make the snippet file invalid. A good troubleshooting technique is to open a similar snippet predefined for VS, as described in the preceding section, and compare formats to see if you might have mistyped something. The next section will explain what to do with this snippet file so that you can begin using it. Listing 12-2 A custom method snippet <?xml version="1.0" encoding="utf-8"?> <CodeSnippet Format="1.0.0" xmlns="http://schemas.microsoft.com /VisualStudio/2005/CodeSnippet"> <Header> <Title>Method Snippet</Title> <Author>Joe Mayo</Author> <Shortcut>meth</Shortcut> <Description>Create a New Method</Description> <SnippetTypes> <SnippetType>SurroundsWith</SnippetType> <SnippetType>Expansion</SnippetType> </SnippetTypes> </Header> <Snippet> <Declarations> <Literal> <ID>access</ID> <Default>public</Default> <ToolTip>Access modifier</ToolTip> </Literal> 358 Microsoft Visual Studio 2010: A Beginner’s Guide <Literal> <ID>return</ID> <Default>void</Default> <ToolTip>Return value</ToolTip> </Literal> <Literal> <ID>methodName</ID> <Default>MethodName</Default> <ToolTip>Name of Method</ToolTip> </Literal> <Literal> <ID>paramList</ID> <Default>int p1</Default> <ToolTip> Comma-separated list of parameters </ToolTip> </Literal> </Declarations> <Code Language="csharp"> <![CDATA[ $access$ $return$ $methodName$($paramList$) { $end$ }]]> </Code> </Snippet> </CodeSnippet> Managing the Snippet Library To use a snippet, you can either copy the snippet into a VS folder or use a VS tool called the Snippet Manager. This section will explain how to make the method snippet, created in the preceding section, available to your code. File Folders Holding Snippets The local snippets folder is located at \Users\<your name>\Documents\Visual Studio 2010\Code Snippets. You’ll see a set of folders for each language/technology, which each have subfolders for organizing snippets. Copy and paste the snippet file into one of these folders, such as Visual C#\My Code Snippets, and the snippet will be immediately available to your code. The local snippets folder makes a snippet available to your machine login. Y ou can also make the snippet available to everyone who logs on to the machine by copying the snippet to a global snippet folder, located at \Program Files\Microsoft Visual Studio Chapter 12: Customizing the Development Environment 359 10.0\. You’ll see language technology folders, such as VC# for C# or VB for VB. Within those folders, you’ll either see folders for language codes (English is 1033) or a Snippets folder. Drilling down two levels, through the language code folders and Snippet folders (whichever shows first), you’ll see more snippets and subfolders that organize the snippets for that language/technology. Copy the snippet into the folder where you feel it belongs. The snippet will be immediately available to your code. Working with system file folders can be cumbersome, so VS offers a tool to help organize snippets, the Snippets Manager. Using the Snippets Manager The Snippets Manager allows you to import new snippets and organize existing snippets. Either select Tools | Code Snippets Manager or press CTRL-K, CTRL-B. You’ll see the Snippets Manager window, shown in Figure 12-7. The Language drop-down shows what type of snippets you can work with. The folders show how snippets are organized. Use the Add and Remove buttons to manage folders. Click the Import button to find and make new snippets available to the application. As you’ve seen, snippets give you a well-specified way to quickly write code. However, there is a capability that is even more powerful, which is macros, discussed next. Figure 12-7 The Snippets Manager window 360 Microsoft Visual Studio 2010: A Beginner’s Guide Writing Macros When the productivity features that ship with VS and custom snippets don’t give you enough power, the next step is to consider creating a macro, which is a repeatable set of actions that you can record and re-run multiple times. An example of when a macro is useful is whenever you find yourself continuously repeating the same set of actions in VS. This section will show you how to create and run a macro that uses VS features to create a customized block of code for validating strings. Recording a Macro When creating business objects, it’s common to validate input parameters to ensure they are valid. One such validation is enforcing that calling code pass a required parameter. The example in this section shows you how to write a macro for validating that a string- type parameter is not null, empty, or white space (such as a space or tab). To get started, create a new Console project and add a Class file with the following method to the project, which simulates adding a new customer: C#: using System; class Customer { public int AddNewCustomer(string firstName, string lastName) { int newCustID = 0; // Logic to add customer return newCustID; } } VB: Public Class Customer Function AddNewCustomer( ByVal firstName As String, ByVal lastName As String) As Integer Dim newCustID As Integer = 0 ' Logic to add customer . open by selecting Start | All Programs | Microsoft Visual Studio 2010 | Visual Studio Tools | right-click Visual Studio Command Prompt (2010) and select Run As Administrator. This will take. snippets first. 354 Microsoft Visual Studio 2010: A Beginner’s Guide Examining Existing Snippets Snippets that ship with VS are located at Program FilesMicrosoft Visual Studio 10.0 under a folder. powerful, which is macros, discussed next. Figure 12-7 The Snippets Manager window 360 Microsoft Visual Studio 2010: A Beginner’s Guide Writing Macros When the productivity features that ship with