Visual NHibernate can be customized in many ways. Today we’ll look at the built-in template engine. You can easily create the exact output you need by tweaking the built-in templates or creating new custom templates.

Visual NHibernate currently has two built-in templates:

• The standard NHibernate template
• The new Sharp Architecture template.

Template Editor

The template editor enables you to specify how the generated files and folders should be laid out in the destination folder, WYSIWYG style. Script can be written to generate dynamic files, while static files such as images and DLLs can also be included in the output.

The code editor has IntelliSense and syntax-highlighting, as well as live feedback about errors. Compile errors are underlined in red squiggly lines. They also appear in the errors grid and cause the title-bar to change color from green to red.

Find and replace can be accessed via the standard keyboard shortcuts (Ctrl+F, Ctrl+Shift+F, Ctrl+H, Ctrl+Shift+H).

Laying out folders and files

Add the first folder or file by right-clicking the ‘Output Folder’ node in the treeview.

Folders and files can have iterators. You can generate either a single file, or generate one file or folder per Entity, Table, Column, Component or View. If you select an iterator then you will have access to the iterator in script via a lowercase name, such as entity.Name or table.Name.

File-names and folder-names can be dynamic and can contain script:

Folders

Add a folder by right-clicking on the parent folder.

Dynamic files

A dynamic file is one in which the body is created dynamically via script. Add a file by right-clicking on the parent folder.

Static files

A static file is one that is distributed as-is. It can be an image file, a readme file, a DLL etc.

Static files need to be added to the Resources collection. To do this, select the Resources tab on the left then click the Add button to select the file.

Scripting

Dynamic files output text. Create dynamic content by using either ASP-style delimiters <%...%> or T4-style delimiters <#...#>.

Select the delimiter style towards the top right corner of the screen.

Writing output

Dynamic text can be inserted into the document in a number of ways:

1. Mixing script and output text, similar to ASP
2. Placeholders: <%=entity.Name%>
3. Write(text)
4. WriteLine(text)
5. WriteFormat(formatText, args)
6. WriteIf(boolean expression, trueText)
7. WriteIf(boolean expression, trueText, falseText)

Skipping files

A dynamic file can be skipped via script by setting SkipThisFile = true and returning the reason. For example:

if (!Project.Settings.UseFluentNHibernate)
{
    SkipThisFile = true;
    return “Project.Settings.UseFluentNHibernate is false”;
}

Testing

Visual NHibernate has a smooth edit-test cycle, giving immediate feedback on your template and scripts. It also enables you to test individual entities, tables, views etc.

1. Create your template script
2. Select the ‘Test’ tab
3. If the file has an iterator, select the iterator you want to test with. Example: if you’ve specified that one file should be created for each entity, then select an entity to test with. If the iterator is a table then a list of tables will be presented for you to make a selection.
4. Click the ‘Test’ button to run the test.
5. The script will execute and display the generated text (file-body) or errors if they occur.

Scripting API

The API available for scripting exposes all details about the current project. You have full access to all properties or entities, tables, relationships etc.

The editor has full IntelliSense and the API is easily discoverable:

Here’s a small portion of the API:

• CurrentFilePath: Gets or sets the path of the file being written. You can override the path specified in the filename editor via code.
• SkipThisFile: Set this to true to stop the current file from being generated. Return the reason for skipping. This reason will be displayed when testing this dynamic file.
• Project: Object containing all project-level variables, objects and settings.
  • Project.Settings: The Settings object allows access to the values of all settings on the Settings tab.
  • Project.Entities: A collection of all entities.
  • Project.Components: A collection of all components.
  • Project.Tables: A collection of all tables.
  • Project.Views: A collection of all views.
  • Project.OutputFolder: The path of the output folder selected by the user.

Extend your existing NHibernate projects

Visual NHibernate can reverse-engineer your existing NHibernate Visual Studio projects. Your existing code becomes the model. This enables you to create new code based on your existing code. Create a new template, import your existing code, generate new code.

Conclusion

Custom templates give you a tremendous amount of freedom and power. The best way to learn about the capabilities of templates is to inspect the built-in templates. Download Visual NHibernate, have a play, and tell us what you think.

---

comments powered by Disqus