PreserveRegions Merge Strategy

The PreserveRegions merge strategy is useful when you need to preserve multiple custom regions in a file that is otherwise authored by CodeSmith. The file must already exist with the custom sections marked by appropriate region markers. CodeSmith transfers the marked regions to the template output when regenerating the file. When using the PreserveRegions merge strategy, you specify an initialization string in this format:

RegionNameRegex=<RegexExpression>;Language=<Language>

For example,

RegionNameRegex=^[ \t]*(?i:Custom);Language=T-SQL;

Given this initialization string, CodeSmith will search for a region named "Sample Generated Region" marked by C# style region markers. The generated code will be inserted in place of the contents of this region. The Language attribute in the initialization string is a key into the HKEY_CURRENT_USER\Software\CodeSmith\v5.3\MergeStrategyAlias registry node. This node contains regular expressions for defining the region markers for each supported language. By default, CodeSmith recognizes region markers for VB, C#, and T-SQL, but you can add your own regular expressions to the file to extend this support if you need to.

Here's an example so you can see how all the pieces fit together. First, a template, CustomClass.cst. Note that the template defines two empty C# regions. These are the regions that will be used to preserve custom code that already exists in the output file.

<%@ CodeTemplate Language="C#" TargetLanguage="C#" Description="Custom class generator." %>
<%@ Property Name="ClassName" Type="System.String" Description="Name of the class." %>
#region Keep copyright
#endregion

class <%= ClassName %>
{
    public <%= ClassName %>()
    {
        // Insert default constructor code here
    }

    #region Keep custom methods
    #endregion
}

Next, the existing output file, Engine.cs:

#region Keep copyright
Copyright (c) 2011 CodeSmith Tools, LLC
#endregion

class Engine
{
    public Engine()
    {
        // Insert default constructor code here    
    }

    #region Keep custom methods
    public string UniqueID()
    {
        return("E8472");
    }
    #endregion
}

And the resulting changes to Engine.cs:

#region Keep copyright
Copyright (c) 2011 CodeSmith LLC
#endregion

class Driver
{
    public Driver()
    {
        // Insert default constructor code here
    }

    #region Keep custom methods
    public string UniqueID()
    {
        return("E8472");    
    }
    #endregion
}