As a CodeFluent architect, you may wonder how you could generate a human readable document of your model without having to write it manually. The answer is to use the CodeFluent template engine. This article gives you some basic understanding of how to write a template to generate a Rich Text File document (containing formatting, logo, etc) and also provide a ready to use template that you can customize according to your own needs.
All projects developed with CodeFluent are based on models. A model is always composed of a set of entities. These entities contain properties, methods, rules, etc. In order to provide to people outside of the development team, an explanation of the CodeFluent model in a formatted document could be appreciated. To generate this document, a developer can use the template associated with this article. Nevertheless, the CodeFluent model must be enriched with the desired documentation using CodeFluent message with a dedicated attribute. This attribute is available at entity, property and method levels. Here’s a simplified sample model:
<cf:entity
name=“Customer“>
<cf:message
class=“_doc“>Simple customer</cf:message>
<cf:property
name=“Id“>
<cf:message
class=“_doc“>Technical identifier</cf:message>
</cf:property>
<cf:property
name=“Phone“>
<cf:message
class=“_doc“>Phone number of the customer</cf:message>
</cf:property>
<cf:method
name=“LoadByPhoneNumber“
body=“load(Phone) where Phone = @Phone“>
<cf:message
class=“_doc“>Load customer by phone number</cf:message>
</cf:method>
</cf:entity>
By the way, after generation, the properties and methods of the generated business object layer (BOM) will contain new tags in standard .NET format as illustrated hereafter:
Entity level
///
<summary>Customer entity</summary>
public
partial
class
Customer
Property level
///
<summary>Phone number of the customer</summary>
public
string Phone {
get { return
this._phone; }
set { this._phone = value; this.EntityState = CodeFluent.Runtime.CodeFluentEntityState.Modified; this.OnPropertyChanged(new System.ComponentModel.PropertyChangedEventArgs(“Phone”)); }
}
Method level
///
<summary>Load customer by phone number</summary>
public
static System.Data.IDataReader PageDataLoadByPhoneNumber(CodeFluent.Runtime.PageOptions pageOptions, string phone)
Using CodeFluent template engine, we developed a template to generate a full documentation. Note that the CodeFluent Template producer supports text files format such as RTF files. To describe our example, we created a RTF file named [Template]Model documentation.rtf with Microsoft Word. We then edited our template and added some code using CodeFluent API.
Let’s quickly describe the template inside:
-
First, retrieve all entities of the model:
EntityCollection entities = Producer.Project.Entities;
-
For each entity in the model, retrieve the comment at entity level using GetMessage method:
CultureInfo currentCulture = new
CultureInfo(1033);
Message messageGlobal = entity.GetMessage(“_doc”, currentCulture);
-
And do the same for methods and properties:
CultureInfo culture = new
CultureInfo(1033);
IList properties = new
List<Property>();
IList methods = new
List<Method>();
foreach (Property property in entity.Properties)
{
Message messageProperty = property.GetMessage(“_doc”, currentCulture);
if (messageProperty != null)
properties.Add(property);
}
foreach (Method method in entity.Methods)
{
Message messageMethods = method.GetMessage(“_doc”, currentCulture);
if (messageMethods != null)
methods.Add(method);
}
You can notice that we use the english culture (1033) but you can localize your documentation using “cultureName” attribute inside your model. For example, if you want to translate your comment into french, proceed as follows:
<cf:message
class=“_doc“
cultureName=“fr“>Entité client</cf:message>
Then, you can get the message value:
[%foreach (Property property in properties) { Message currentMessage = property.GetMessage("_doc", currentCulture);%] [%= currentMessage.Value %] [%}%]
Let’s have a look at the generated RTF document:
How to use the provided template?
Put your template file into a directory of your choice and use the “template producer” in your project in order to produce the output documentation file:
<cf:producer
name=“Template Producer“
typeName=“CodeFluent.Producers.CodeDom.TemplateProducer, CodeFluent.Producers.CodeDom“>
<cf:configuration
sourceDirectory=“Templates\Doc“
targetDirectory=“.\Generated\“
outputEncoding=“iso-8859-1“/>
</cf:producer>
We hope that from now on, all your CodeFluent projects will be fully documented .
This article is only a little overview of CodeFluent templating mechanism and CodeFluent API features. You will find the sample code and the generated documentation inside the following zip code. You can find the corresponding materials here.
Antoine Diekmann – SoftFluent
