Using a CodeSmith Generator Map

Introduction

A CodeSmith Generator Map provides an easy way to manage dictionary maps for doing word translation lookups in code. This used to be a a frequent and cumbersome challenge that a template writer must face when trying to map types from disparate systems. A prime example is working from data types from an RDBMS which don't match those of the programming language you are writing for. Typically, what happens is the template writer would have to create a long switch case statement for every lookup.

Example:

Old way you would manage a lookup:

public string GetSqlDbType(DataObjectBase column)

{
    switch (column.NativeType)
    {
        case "bigint": return "BigInt";
        case "binary": return "Binary";
        case "bit": return "Bit";
        case "char": return "Char";
        case "datetime": return "DateTime";
        case "decimal": return "Decimal";
        case "float": return "Float";
        case "image": return "Image";
        case "int": return "Int";
        case "money": return "Money";
        case "nchar": return "NChar";
        case "ntext": return "NText";
        case "numeric": return "Decimal";
        case "nvarchar": return "NVarChar";
        case "real": return "Real";
        case "smalldatetime": return "SmallDateTime";
        case "smallint": return "SmallInt";
        case "smallmoney": return "SmallMoney";
        case "sql_variant": return "Variant";
        case "sysname": return "NChar";
        case "text": return "Text";
        case "timestamp": return "Timestamp";
        case "tinyint": return "TinyInt";
        case "uniqueidentifier": return "UniqueIdentifier";
        case "varbinary": return "VarBinary";
        case "varchar": return "VarChar";
        default: return "_UNKNOWN_" + column.NativeType;
    }
}

Map Editor

CodeSmith now makes this an easy process using the Map Editor control that allow you to Create and Manage your own CodeSmith Map lists. CodeSmith also ships several of the most common mapping scenarios and it's output is in a familiar XML format allowing the developer community to contribute and share maps they create as well through a new Map File Gallery at the CodeSmith Community.

Example:
The map depicted to the right is a map of fully qualified system types to their C# language keyword type.

Name:
The map name is also the filename so consider choosing a name that is fairly descriptive of what the map's intent is. 

NOTE: When CodeSmith attempts to discover a map by name, it first looks in the configuration directories, the template directories and you can also give it a relative or full path.

Description:
A description field of what the maps intent is for.

Return Key:
The return key check box indicates whether or not to return the original key from the map if the key is not found within the map. This is important because there can be many situations where there might not be an entry for the key and it's value, but you would still like the key returned instead of null.

Example:
In the image to the left, it's converting a fully qualified type to it's C# equivalent keyword. In cases where one doesn't exist, such as System.DateTime or System.Guid, you could still use the original key, System.DateTime, which would be completely valid.

Case Sensitive:
The Case sensitive check box determines whether or not to search for the key and consider case sensitivity. Often, word dictionaries do not require case sensitivity since most use keys that are unique by name.

Find More:
Launches a browser session to browse the online gallery of community collaborated maps.

Developing using a CodeSmith Map

Using a map is quite easy and very flexible. You simply register the map using the Map Directive (see highlighted green image below). Once the map has been registered, you simply reference the map and pass it the value similar to using another Collection class.

Example:

<%@ Map Name="CSharpAlias" Src="System-CSharpAlias" Description="System to C# Type Map" %>
<%@ Map %>

Directive Attributes
Name: The reference name of the map specified to use in code.(required)
Src: The file-name reference to the map file. Adding the extension name is not required.(required)
Description: A Description field for the Map Register directive.
Reverse: When you require to translate the lookup back to the key from the value, you can reverse the map. You simply Load the Collection using the reverse overloaded method.
Default: The default value to return the key is not found.

API Access:

You can interface with a map from code simply by loading the map by name.

Common API Usage:

This mimics the usage of the mapping in the image above which uses a declarative model.

MapCollection list = MapCollection.Load("System-CSharpAlias.csmap");
list.ReturnKeyWhenNotFound = true;
Response.Write(list[column.SystemType.FullName]);

Reverse Map:
Call the overloaded Load method when requiring to load the map with the key value pairs swapped.

MapCollection list = MapCollection.Load(string mapName, bool reverseMap);
Debug.Assert(list[myValue]  == myKey);

NOTE: See the CodeSmith API help for more API Coverage.