CodeSmith Template Syntax Reference

最新推荐文章于 2023-02-06 23:48:57 发布

mike1983

最新推荐文章于 2023-02-06 23:48:57 发布

阅读量1.9k

点赞数

分类专栏： .NET工具文章标签： reference assembly properties include parameters tags

本文链接：https://blog.csdn.net/mike1983/article/details/407620

版权

.NET工具专栏收录该内容

8 篇文章 0 订阅

订阅专栏

CodeSmith Template Syntax Reference

This goal of this document is to provide a reference to the various tags and objects that can be used during the creation of CodeSmith templates. This document is not meant to be an introduction to CodeSmith, if this is what you are looking for then please refer to the quick start guide.

Directive Tags

Directive tags appear at the top of a template and are used to set a number of different properties about a template.

CodeTemplate Directive

The CodeTemplate directive is the only required directive and is used to specify general properties of the template, including properties like what language the template is written in or a description of the template.

Following is an example CodeTemplate directive:

<%@ CodeTemplate Language="C#" TargetLanguage="C#" Description="Generates a class." %>

CodeTemplate Directive Parameters

This section will describe the various parameters that can be used with the CodeTemplate directive.

Language

The language attribute specifies what language will be used to write the template. C#, VB.NET, and Jscript can all be used to develop CodeSmith templates.

TargetLanguage

The target language attribute does not directly affect the output of your template in any way. This attribute is only used to classify your template based on what kind of code it is generating, since technically you could use CodeSmith to generate anything from C# to COBOL.

Description
The description attribute is used to describe your template in a general way, this is used to identify your template in the CodeSmith explorer.

Inherits

By default all CodeSmith templates inherit from CodeSmith.Engine.CodeTemplate, this class provides the basic functionality of the template; much like the Page class provides the basic functionality of an ASP.NET page. The Inherits attribute can be used to modify what class your template inherits from, this new class must inherit from CodeSmith.Engine.CodeTemplate though. CodeSmith must also be able to find this class which means you will also need an assembly directive pointing to the assembly that contains this class, for more information on this directive please see that section of this document.

Template inheritance can be used for a number of different reasons, but primarily you will use it to include a set of helper methods in a number of different templates. For more information on this topic please look for the Template Inheritance document.

Src

In some ways the Src property is very similar to the Inherits property, they both allow you to include functionality from another class in your template. The difference between the two properties is that the Src property can be used to dynamically compile a class file with your template, whereas the Inherits property requires you to supply the already compiled class and assembly. To use the Src property you simply need to set the value of this property to the source file of the class you want to include in your template.

Debug

The Debug attribute is used to determine wether or not debug symbols should be included in the generated assembly. Setting this attribute to True will enable you to set break points in your template using the System.Diagnostics.Debugger.Break() method.

Property Directive

The property directive is used to declare a parameter that will be specified when the template is run, and whose value can then be accessed throughout the template.

Following is an example of a Property Directive:

<%@ Property Name="ClassName" Type="String" Default="Class1" Category="Context" Description="The name of the class to generate" Optional="true" %>

Property Directive Parameters

This section will describe the various parameters that can be used with the Propert Directive.

Name

The name of the property is used when the parameter is displayed in the property panel of the CodeSmith Explorer. The name also acts as the variable name that is used to store the value of this property, because it is used as a variable name it must be a legal variable name in the language you are using.

Type

The type parameter is used to declare what .NET type this property is. This parameter can be any valid .NET data type, from a simple type like the String, to an external type like SchemaExplorer.DatabaseSchema. Please note that the types must be Base Class Library types, meaning you need to use String or Int32 instead of string of int.

Default

The default parameter is used to set the default value for this property.

Category

The category parameter specifies what category this property should appear under in the CodeSmith Explorer property panel.

Description

The description parameter specifies what will appear at the bottom of the property panel when this property is selected.

Optional

The optional parameter specifies whether or not this property is optional. If a user does not specify a parameter that is not optional then CodeSmith will not let them proceed. A value of true means the parameter is not required, and false means it is required.

Assembly Directive

The Assembly directive can be used to reference an external assembly from your template.

Following is an example of the assembly directive.

<%@ Assembly Name="SchemaExplorer" %>

CodeSmith automatically loads a number of different assemblies including System, System.Diagnostics, System.ComponentModel, Microsoft.VisualBasic, and CodeSmith.Engine.

Assembly Directive Parameters

Name

This is the fully qualified name of the assembly that you want to reference from your template. The assembly must exist in the Global Assembly Cache, in the same directory as CodeSmith or in the same directory as the template (.cst) file.

Import Directive

The Import directive is used to import a namespace for use in your template, this is the same as the Imports keyword in VB.NET or the using keyword in C#.

Following is an example of the assembly directive.

<%@ Import Name=”SchemaExplorer” %>

Import Directive Parameters

Name

The Name parameter is the fully qualified name of the namespace to be imported. Remember that you must also load the assembly that contains this namespace if it is not already loaded by default. (See the above section)

Template Syntax

The section will focus on the various other tags that make up a template.

Code Tags

Code tags are used to include .NET code in the body of your template. There are three different types of code tags including <% %> and <%= %>.

<% %> Tags

These tags are used for any amount of code that does not directly provide output for the template. (You can use the response object from these tags, but that will be covered later).

Here is an example of these tags using C#

<% foreach (ColumnSchema column in SourceTable.Columns) { %>

<% } %>

This sample will loop through each column in the supplied table, and output a 1 to the template. This is not very useful, as we probably want to output something like the name of the column, that is where the next tag comes into the picture.

<%= %> Tags

These tags are used to output a string to the template, whatever code is used between these tags must resolve to a simple string.

Here is an example of these tags using C#

<% foreach (ColumnSchema column in SourceTable.Columns) { %>

<%= column.Name %>

<% } %>

Since column.Name is a string it will be sent to the template output.

Script Tags

Script tags are used to include a piece of code in your template that is not used to directly affect the output of the template. This is the best place to put helper methods that you might call throughout the rest of your template. The script tag must have the runat=”template” parameter specified, otherwise it will be treated as simple text.

Here is an example of using script tags.

private string GetColumnName(ColumnSchema cs)

{

return cs.Name;

}

</script>

<% foreach (ColumnSchema cs in SourceTable.Columns) { %>

<%= GetColumnName(cs) %>

<% } %>

Using script tags you can minimize the amount of code that is included between the <% %> tags, making your templates more readable and manageable.

Include Tags

Just like in ASP.NET you can still use include tags to include the contents of a text file into your template, but also just like in ASP.NET this is not always the best way to accomplish your goal.

Here is an example of using the include tag:

In most cases it is better to implement the functionality that you want to use in multiple templates in an assembly and then call those methods from the assembly, but there are certain cases where an include tag might server you better.

Comment Tags

Comment tags can be used to include comments in your template without affecting the output of your template. The comment character for CodeSmith is – and can be used inside the <% %> code tags.

Here is an example of using the comment tag:

<%-- This is a comment --%>

CodeSmith Objects

There are a number of objects that CodeSmith exposes that can be of use when writing templates, and this section will document what some of the more common methods and properties of those objects are and how they can be used.

CodeTemplate Object

From within your template, “this” (or “Me” in VB.NET) references the CodeTemplate object of the current template.

CodeTemplate Methods

public virtual void GetFileName()

You can override this method to set a default output filename for this template. Otherwise CodeSmith will set its own filename based on the template name and TargetLanguage.

public virtual int GetHashCode()

This method returns a unique number based on the contents of the template file. This can be used to detect if the template has changed, as when the contents change so with this hash code.

CodeTemplate Properties

Response

This property can be used to access the current TextWriter object, which can be used to write directly to the output of the template. See below for more information.

CodeTemplateInfo

This property can be used to access the current CodeTemplateInfo object which contains information about the current template. See below for more information.