Using ActiveSnippets

Introduction

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.

NOTE: 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

• 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#. 

Requirements:

My 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; }

        }

Steps:

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

Template:

Ensure that the template compiles and runs fine from CodeSmith Studio/Explorer before trying to use it in Visual Studio.

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.

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

To Access the Menu:

VS Menu -> Tools -> CodeSmith

Menu Items

Once expanded, you will see the CodeSmith related menu items for ActiveSnippets and [CodeSmith Template Explorer|http://docs.codesmithtools.com/display/Generator/CodeSmith+Explorer+in+Visual+Studio]. The command keyboard shortcut is located to the right of every menu option that has one configured.

ActiveSnippet Options

Expand 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 will attempt to find the ActiveSnippet by Alias or by Name. If the ActiveSnippet is found, CodeSmith 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 (see Configuring ActiveSnippets), you simply have to enter the alias or name along with any argument parameters.

Example:

• alias param1, param2
  • 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
    

Shortcut - Using CTRL-E, CTRL-E*

This is the same as using the Keyboard Shortcut for expanding an ActiveSnippet. By default the shortcut is CTRL-E, CTRL-E, to expand an ActiveSnippet.

NOTE: An ActiveSnippet will always have to be compiled the first time prior to being executed.

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 can not find the desired ActiveSnippet by name or by configured alias, then a full list of all available ActiveSnippets will be presented in the CodeSmith Output window.

Output ActiveSnippet Usage

ActiveSnippet usage information can be obtained through the CodeSmith Output Window. CodeSmith attempts to find the ActiveSnippet usage information using the context of the current line with focus.

Shortcut - Using CTRL-E, CTRL-R

This is the same as using the Keyboard Shortcut for expanding an ActiveSnippet. By default the shortcut is CTRL-E, CTRL-E, to expand an ActiveSnippet.

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".

ActiveSnippet Configuration

This menu option allows you to view all ActiveSnippets, Add/Remove an ActiveSnippet, and Configure ActiveSnippets. Once you've created a template for usage as an ActiveSnippet, you must add the ActiveSnippet which maps to a CodeSmith Template.

Find detailed information on Configuring an ActiveSnippet.