Property Directive

Owned by Autumn Wilkins (Unlicensed)
Last updated: Aug 09, 2022 by Blake Niemyjski
3 min read

To declare a property, you use a Property directive. For example, this directive defines a property named ClassName of type System.String:

<%@ Property Name="ClassName" Type="System.String" Category="Context" Description="The name of the class to be generated." %>

Property Directive Attributes

The Property directive has nine possible attributes. The Name and Type attributes are required, and the other attributes are optional.

Name

The Name attribute is used as the name of the property when it is displayed on the template's property sheet in CodeSmith Explorer. This is also the variable name that is used to store the value of the property within the template. This must be a legal variable name within the template's language. For example, if the template uses C# as its language, then the name must follow the rules for C# variables.

Type

The Type attribute specifies the .NET type of the property. This parameter can be any .NET data type, though for complex types you may need to specify an Editor attribute to allow the user to successfully supply a value for the property.

For scalar types, you must use Base Class Library types such as String or Int32 rather than language-specific types such as string or int.

Default

The Default attribute is used to set the default value for this property. If you omit this attribute, then CodeSmith Generator does not supply a default value for the property.

Category

The Category attribute specifies what category this property should appear under in the CodeSmith Explorer property sheet. If you omit this attribute, CodeSmith Generator will place the property in a category named Misc.

Description

The Description attribute supplies descriptive text to be displayed at the bottom of the property sheet when this property is selected.

Optional

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

Editor

The Editor attribute specifies the GUI editor that will be used in the property grid for this property. This is equivalent to placing an [EditorAttribute] on a code property. UITypeEditors are marked as deprecated and will be removed in a future version.

You should specify the editors full name when using the Editor attribute.

<%@ Property Name="ModelDirectory" Type="System.String" Editor="System.Windows.Forms.Design.FolderNameEditor, System.Design, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" %>
For a full list of available editors please see the following page.
EditorBase

The EditorBase attribute specifies the base type for the editor. If none is specified, then UITypeEditor is assumed. UITypeEditors are marked as deprecated and will be removed in a future version.

Serializer

The Serializer attribute specifies the IPropertySerializer type to use when serializing the property's values. This is equivalent to using a [PropertySerializerAttribute] on a code property.

OnChanged

The OnChanged attribute specifies the event handler to fire when the property value changes.

DeepLoad

The DeepLoad attribute is only used on SchemaExplorer objects. When set to true, SchemaExplorer will grab all your schema information in advance saving make multiple round trips back to your database.

Declaring a Property From the CodeBehind

Declaring a property from code is essentially like creating a property in any class. The most notable options using Attributes to help you describe your property, it's location, and it's editor.

Example:

private string aliasFilePath;

  [Editor(typeof(System.Windows.Forms.Design.FileNameEditor), typeof(System.Drawing.Design.UITypeEditor))]
  [Category("01. General")]
  [Optional]
  [DefaultValue("")]
  [Description("Optional File Path to a table/object alias file.")]
  public string AliasFilePath
  {
   get {return this.aliasFilePath;}
   set {this.aliasFilePath = value;}
  }

EditorAttribute - Specifies which editor to use in the Property Sheet.
CategoryAttribute - Specifies a Property Sheet group this option belongs to.
OptionalAttribute - If declared the property will be marked as optional.
DefaultValue - Specify the default value for the property.
DescriptionAttribute - Used to create a description for the selected property.
CodeTemplatePropertyAttribute - Has been depreciated.