Template Modification

Using Documentation Within a Template

To make use of the documentation that has been added to the edmx file, modification of the Entity Framework T4 templates is recommended. This template should be a file with a .tt extension. There may be multiple .tt files added by Entity Framework, so the file containing generation of the data model classes should be edited.

Keep in mind that the following is an example, and is not necessarily going to suit all scenarios.

First, open the template file containing class generation and add the following method somewhere within a code section. This method is responsible for actually writing out the contents of a Documentation element to an XML documentation summary section. You may wish to place it at the bottom of the file, just before the final #>.

public string WriteDescription(System.Data.Entity.Core.Metadata.Edm.Documentation docs)
{
    if (docs == null || String.IsNullOrEmpty(docs.Summary))
    {
        return string.Empty;
    }

    return new StringBuilder()
        .AppendLine(CurrentIndent)
        .AppendLine("/// <summary>")
        .AppendFormat("/// {0}", docs.Summary).AppendLine()
        .AppendLine("/// </summary>")
        .ToString();
}

Next, this method will be used in various places throughout the template. These are usually placed before type and type member generation. For example, type generation may look like the following:

<#=codeStringGenerator.UsingDirectives(inHeader: false)#>
<#=codeStringGenerator.EntityClassOpening(entity)#>

To add comments, modify it as in the following:

<#=codeStringGenerator.UsingDirectives(inHeader: false)#>
<#=WriteDescription(entity.Documentation)#><#=codeStringGenerator.EntityClassOpening(entity)#>

Note that a call to WriteDescription has been added just before the call to write the entity class name.

For type members such as properties, there are typically multiple loops over different types of property generation. Each site should be modified. The following demonstrate several examples of this:

Simple Properties

    foreach (var edmProperty in simpleProperties)
    {
#>
    <#=WriteDescription(edmProperty.Documentation)#><#=codeStringGenerator.Property(edmProperty)#>
<#
    }

Navigation Properties

    foreach (var navigationProperty in navigationProperties)
    {
         ...
#>
    <#=WriteDescription(navigationProperty.Documentation)#><#=codeStringGenerator.NavigationProperty(navigationProperty)#>
<#
    }

Complex Properties

    foreach(var complexProperty in complexProperties)
    {
#>
    <#=WriteDescription(complexProperty.Documentation)#><#=codeStringGenerator.Property(complexProperty)#>
<#
    }

... and so on. Then, simply saving the template file should regenerate the code with documentation, if it exists.