Using ActiveSnippets

CodeSmith Generator delivers strong integration within Visual Studio and ActiveSnippets are a driver toward increasing developer productivity. ActiveSnippets, at a high level, are CodeSmith Generator templates with exposure to the entire .Net Framework which you can utilize with a few keystrokes inside of Visual Studio. The output of your ActiveSnippet will be rendered right where you expanded on the code editor.

You can watch this video tutorial for more information: 


Visual Studio currently offers support for simple template based snippets. This is a great feature for simple snippets of code, however these templates do not contain any advanced logic or access to rich meta-data. For simple snippets such as creating a simple property shell without any logic, we still recommend using the Visual Studio snippet.

 Things to consider before creating an ActiveSnippet

  • You have access to the entire .Net Framework, SchemaExplorer, XmlProperty, Custom Assemblies, or any other rich meta-data.
  • Complex Objects such as an XmlProperty and SchemaExplorer types can exist as properties in your CodeSmith Template, and similarly act as arguments in an ActiveSnippet.
  • An ActiveSnippet can setup default values for arguments that are fairly static in your template.

Creating an ActiveSnippet Template

The first step in creating an ActiveSnippet is by simply creating a CodeSmith Generator Template.  In this example, we'll create a CodeSmith Generator Template that doubles as an ActiveSnippet and is able to generate properties for a given TableSchema in C#. 

This template can be found in Template Explorer under the ActiveSnippets\CSharp or ActiveSnippets\VisualBasic folders.
For more information on creating a new template please take a look at the following tutorial.

Requirements

The required output needs to look like this for every column in a table.

private int _orderId;
public int OrderId
{
    get { return _orderId; }
    set { _orderId = value; }
}

Writing the Template

When first creating a template, think about the requirements that we defined above and focus and write the template in small steps. This keeps you from getting overwhelmed by writing everything at once.Next, try and think about how you would write the template by outlining some steps in pseudocode. This will make writing the template much easier. Here are a few steps that we used to create this template:

  1. Iterate through the Columns (SchemaExplorer.ColumnSchemaCollection) of the template property SourceTable (SchemaExplorer.TableSchema).
  2. Create both a field and a property to encapsulate the column.
  3. Use a CodeSmith Generator Map to get the correct type for the field and property.
  4. Ensure my field is CamelCased and my Property Name is PascalCased.

Finally, ensure that the template compiles and runs from Template Editor or Template Explorer.

Visual Studio Integration

The next step is to launch Visual Studio, and explore the options available for using ActiveSnippets within Visual Studio. This will help you get a feel for the integration capabilities for using your ActiveSnippets.

To access various ActiveSnippet features, you can use keyboard shortcuts or use the ActiveSnippet menu items. These are located in the Generator submenu on the right hand side of the Visual Studio menu bar. Once the Generator menu is expanded, you will see the menu items for ActiveSnippet's as shown above. The command keyboard shortcut is located to the right of every menu option that has one configured.

ActiveSnippet Configuration

The ActiveSnippet Configuration can be accessed by selecting the ActiveSnippet Configuration menu item located in the Visual Studio Generator sub-menu. The ActiveSnippet Configuration dialog allows you to Add, Remove, Edit or view all ActiveSnippets, Once you've created a template for usage as an ActiveSnippet, you must add the ActiveSnippet which maps to a CodeSmith Generator Template.

ActiveSnippets must be configured inside Visual Studio in order to be used.

Find detailed information on Configuring an ActiveSnippet.

Output ActiveSnippet Usage

ActiveSnippet usage information can be obtained through the CodeSmith Generator Output Window. CodeSmith attempts to find the ActiveSnippet usage information using the context of the current line with focus. To display the output usage for configured ActiveSnippets you can select the Output ActiveSnippet Usage menu item or press Control+Alt+G, Control+Alt+U.

Notable Information

  • Executing Usage with no alias on the editor will display all ActiveSnippets.
  • Executing Usage using part of the prefix, will display a list of all ActiveSnippets starting with that prefix
    • For Example, using "t" by itself will show a list of all ActiveSnippets beginning with a "T".

Expanding an ActiveSnippet

Attempts to execute the ActiveSnippet using the context of the current line with focus.  If there is an ActiveSnippet configured and no errors, CodeSmith Generator will attempt to find the ActiveSnippet by Alias or by Name. If the ActiveSnippet is found, CodeSmith Generator will compile the template if not compiled, and then execute the template with the given arguments. The template output of the ActiveSnippet will be placed on the editor control of Visual Studio.

Syntax

Calling an ActiveSnippet is easy. Once configured, you simply have to enter the alias or name along with any argument parameters. Once you have defined the active snippet you want to expand, you just need to select the Expand ActiveSnippet menu item or press Control+Alt+G, Control+Alt+G.

If you are unsure about an ActiveSnippets usage is, you can select the Output ActiveSnippet Usage menu item or press Control+Alt+G, Control+Alt+U.

By default the shortcut for Expanding an ActiveSnippet is Control+Alt+G, Control+Alt+G.
Example

In the example below we will execute an ActiveSnippet with the name tp and pass it one argument parameter.

tp Petshop.dbo.Orders


  • You can also access an ActiveSnippet by referring to it's full name.
  • You can use complex objects, such as a TableSchema by referring to it's fully qualified name Petshop.dbo.Orders

to execute this active snippet we will select the Expand ActiveSnippet menu item or press Control+Alt+G, Control+Alt+G. The below screenshot shows the code which was generated by this ActiveSnippet.

Notable Information 

  • If there is an error executing an already configured ActiveSnippet, usage information on the discovered ActiveSnippet will be presented. This shows the ActiveSnippet along with all of the arguments for that template.
    • Template is not valid.
      SourceTable is required.
      tp - TableProperties (.cs)
  • If CodeSmith Generator cannot find the desired ActiveSnippet by name or by configured alias, then a full list of all available ActiveSnippets will be presented in the CodeSmith Generator Output Window.