InsertRegion Merge Strategy

The InsertRegion merge strategy is useful when you need to generate a single region of code within a file that is otherwise not authored by CodeSmith. The file must already exist with the appropriate region marked. CodeSmith preserves the rest of the file untouched. When using the InsertRegion merge strategy, you specify an initialization string in this format:

RegionName=<RegionName>;Language=<Language>

For example,

/merge:InsertRegion="RegionName=Sample Generated Region;Language=C#;"

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, Copyright.cst,  that can generate boiler plate copyright notices in a format suitable for insertion in Visual Basic code:

<%@ CodeTemplate Language="VB" TargetLanguage="VB" Description="Copyright notice generator." %>
<%@ Property Name="CompanyName" Type="System.String" Category="Strings" Description="Your company name." %>
<%@ Property Name="ClientName" Type="System.String" Category="Strings" Description="Client company name." %>
' This module is delivered as licensed content as defined
' in the contract between <%= ClientName %> and <%= CompanyName %>.
' Copyright (c) <%= System.DateTime.Now.Year %> <%= CompanyName %>
' All other rights reserved.

Next, the Copyright.xml property set XML file with metadata for this template:

<?xml version="1.0" encoding="utf-8"?>
<codeSmith>
  <propertySet>
    <property name="CompanyName">CodeSmith Tools, LLC</property>
    <property name="ClientName">Doe Industries</property>
  </propertySet>
</codeSmith>

HelloWorld.vb is a Visual Basic source code file with a region suitable for inserting the generated copyright notice. Note that this file also contains some code that CodeSmith should leave untouched:

Public Class HelloWorld
#Region "Copyright Notice"
    'CodeSmith will insert the copyright notice here
#End Region
    Public Sub New()
    End Sub
    Public Sub SayHello()
        ' CodeSmith will leave this code intact
        MessageBox.Show("Hello World")
    End Sub
End Class

The result is to change HelloWorld.vb to look like this:

Public Class HelloWorld
#Region "Copyright Notice"
' This module is delivered as licensed content as defined
' in the contract between Doe Industries and CodeSmith Tools, LLC.
' Copyright (c) 2011 CodeSmith, LLC
' All other rights reserved.
#End Region
    Public Sub New()
    End Sub
    Public Sub SayHello()
        ' CodeSmith will leave this code intact
        MessageBox.Show("Hello World")
    End Sub
End Class

CodeSmith preserves everything outside of the specified region, including the region markers. This means that you can change the metadata for the generation process and regenerate as often as you want without affecting anything outside of the specified region.