Merge Strategies

Merge strategies answer the question: how do you customize generated code without losing your changes when you regenerate it? Instead of overwriting the output file, CodeSmith Generator merges the template output with the file that's already there.

Built-in merge strategies

Merge strategy	Use it when
InsertRegion	The file is mostly hand-written, and Generator owns a single named region inside it.
PreserveRegions	The file is mostly generated, and you keep your own code in one or more named regions.
InsertClass	You want to replace or insert a whole C# or Visual Basic class in an existing file.

If none of these fit, you can write your own merge strategy.

Applying a merge strategy

A merge strategy is applied when Generator writes output to a file, so you use it with an output in a Generator project:

• In the Manage Outputs dialog, choose the merge strategy for an output and enter its initialization string.

• In the project file (.csp), set the mergeType and mergeInit attributes of a property set:

  <propertySet name="InsertRegionSample.cs" output="InsertRegionSample.cs" template="InsertRegionSample.cst"
               mergeType="InsertRegion" mergeInit="RegionName=Sample Generated Region" />
  

mergeType is the merge strategy's alias (InsertRegion, PreserveRegions or InsertClass) or a fully qualified type name. mergeInit is the initialization string: a list of Name=Value settings separated by semicolons. Each merge strategy page lists the settings it accepts.

Projects run the same way from Visual Studio, the command line and MSBuild, so the merge happens wherever you generate. In template code, the RenderToFile overloads that take a merge strategy do the same for sub-templates.

Region markers

InsertRegion and PreserveRegions find regions with a pair of regular expressions per language. The Language setting in the initialization string picks the language; if you leave it out, Generator uses the TargetLanguage of the template's CodeTemplate directive. The language is matched against these keys, ignoring case:

Language keys	Region markers
C#, CSharp, CS	#region Name … #endregion
VB, VB.NET, VisualBasic	#Region "Name" … #End Region
SQL, T-SQL	--region Name … --endregion
XML, HTML	<!-- region Name --> … <!-- endregion -->
JS, JavaScript, TypeScript	// region Name … // endregion

To support another language, or to change the markers, edit LanguageRegionDefinitions in the Merge category of the Engine page in the Options dialog. Each definition has a set of language keys and a start and an end regular expression; the start expression captures the region name in a group called name. The same page lists the merge strategy aliases in MergeStrategyAliases.

Samples

Generator ships with merge strategy samples for C#, Visual Basic, T-SQL, XML and JavaScript. In Template Explorer, open the Examples\Merge folder of the samples. Each language folder contains a template, an existing output file and a MergeSamples.csp project that runs the merge.

You can also watch a walkthrough: CodeSmith Generator - Merge Strategies (video).