Generating without the Umbraco UI

Overview

LINQ to Umbraco supports the ability to generate the .NET classes without using the Umbraco UI. This is useful if you are yet to create the Umbraco instance but want to start designing the document types (using the DTML format) or wish to use the Visual Studio extensions for LINQ to Umbraco.

One final word of warning, HERE BE DRAGONS.

DocType Markup Language

The DocType Markup Language (DTML) is the core of how LINQ to Umbraco creates the .NET type representations, denoted by the .dtml file extension.
It is a modified version of the XML which is used when exporting Umbraco DocTypes (and that used in the Packaging system). A lot of the XML is the same, but there are a few unneeded nodes and a few additional nodes.
An XSD has been created which can be used to generate a valid XML document from (and which is used by the generation tools). The XSD is included in the Umbraco.Linq.Core assembly.
Generally the XML document will be generated by the DTMetal tool but it is also possible to write the XML yourself if the Umbraco instance is yet to be set up.
The advantage of this is that as a developer it is possible to write the .NET components before the Umbraco instance has even been started.

DTMetal

DTMetal is the LINQ to Umbraco implementation of the SQLMetal application which is shipped with Visual Studio 2008 for command-line generation of LINQ to SQL files.
DTMetal is a console application which can be run in two modes, DTML (XML) generation or class generation.
All the command-line arguments can be obtained by running:
$> DTMetal.exe –help

Command line reference

Global arguments
Argument Allowed values Purpose Additional Information
-help: N/A; Shows help documentation All additional arguments are ignored if this is provided
-mode: xml/ class; Specifies the generation mode

XML mode arguments

Argument Allowed values Purpose Additional Information
-connectionString: Any valid Umbraco connection string; Database connection string to generate the DTML against; Must contain Umbraco DataLayer information
-output: Any valid folder path; Specifies the folder the DTML file will generate into; Filename is DataContextName.dtml
-dataContext: Prefix for the UmbracoDataContext class; Optional. Default is “Umbraco”
-disablePluralization: N/A When specified pluralization of the collections are not pluralized

Class mode arguments

Argument Allowed Value Purpose Additional Information
-dtml: Any valid DTML file; Specifies the DTML file to generate the classes from
-language: csharp/ vb .NET language to generate the code as; Optional. Default C# (csharp)
-namespace: Full namespace to put the classes within; Option. Default is “Umbraco”

The DTML file

When generating DTML in the XML mode it will interrogate the Umbraco database and create an XML file which maps out how the DocTypes are defined. The DTML includes the following information about a DocType:
• Name
• Alias
• Parent DocType (if applicable)
• Properties
o Property Name
o Property Alias
o Umbraco property type
o .NET property type
• Allowed child types
The information stored within the DTML file is then used to generate the .NET classes for LINQ to Umbraco.