Entity Framework Utility .ttinclude File

  • Article

This topic provides an overview of the .ttinclude file that contains utility classes that help the ADO.NET templates with the code generation process. This file is used by the ADO.NET EntityObject Generator Template and ADO.NET Self-Tracking Entity Generator Template templates. You should not modify the .ttinclude file. However, you can use the helper functions that are defined in this file in your own templates.

The Visual Basic and C# versions of the .ttinclude file are installed with Microsoft Visual Studio 2010, in the <Visual Studio installation path>\Common7\IDE\Extensions\Microsoft\Entity Framework Tools\Templates\Includes directory.

Use the Include directive to include the file in other text templates. When you add the Include directive to a text template, the system merges the public APIs of the included file with the code in the text template. The Include directive accepts a file name with the full path, or only the name of the included file. If you only specify the name, the text template transformation engine will search well known locations to find the file. For more information, see How to: Include Files in Text Templates. In the following example only the name of the .ttinclude file is specified:

<#@ include file="EF.Utility.CS.ttinclude"#>

Classes defined in .ttinclude

In text templates, the helper functions are enclosed in class feature blocks. The class feature blocks are sourrounded by <#+ and #> tags. The code in this .ttinclude file uses .NET Framework types. Therefore, the appropriate assemblies and the .NET Framework namespaces are included at the beginning of the file. For more information about working with text templates, see Generating Artifacts By Using Text Templates.

Below is the list of some public classes that are defined in the EF.Utility.CS.ttinclude file and short examples of how the classes are used by the ADO.NET EntityObject Generator and ADO.NET Self-Tracking Entity Generator templates.

CodeGenerationTools - Responsible for helping to create source code that is correctly formatted and functional.

Given the entiy name is Course, the following code uses the code object of the CodeGenerationTools type to generate public partial class Course: IObjectWithChangeTracker, INotifyPropertyChanged output into the target source file.

<#=Accessibility.ForType(entity)#>
     <#=code.SpaceAfter(code.AbstractOption(entity))#>partial class
     <#=code.Escape(entity)#><#=code.StringBefore(" : ", 
    code.Escape(entity.BaseType))#><#=entity.BaseType == null ? ": " : 
    ", "#>IObjectWithChangeTracker, INotifyPropertyChanged

MetadataTools - Contains helper methods that access the Entity Framework metadata needed for code generation.

<#MetadataTools ef = new MetadataTools(this);
if (ef.IsKey(edmProperty))
    
#>

MetadataLoader - Responsible for loading EdmItemCollection, StoreItemCollection, and StorageMappingItemCollection objects from an .edmx or .csdl file. The following example initializes the MetadataLoader object and loads the metadata into the metadataWorkspace object.

<#MetadataLoader loader = new MetadataLoader(this);
string inputFile = @"SchoolModel.edmx";
MetadataWorkspace metadataWorkspace = null;
bool allMetadataLoaded =loader.TryLoadAllMetadata(inputFile, out metadataWorkspace);
#>

Accessibility - A static class that encapsulates the retrieval and translation of the code generation annotations in the Entity Framework metadata to a format that is useful in code generation. See the example included with the CodeGenerationTools class description.

CodeRegion - Responsible for creating source code regions. The following code uses CodeRegion to generate #region Primitive Properties output into the target source file.

<#CodeRegion region = new CodeRegion(this, 1);
...
region.Begin("Primitive Properties");
#>

The region will not be generated if no source code is generated for the region.

EntityFrameworkTemplateFileManager - Responsible for splitting various sections of the generated code into separate files. Templates that write out to multiple files use this class because the text template technology does not support generating multiple files. If a text template is part of a Visual Studio project, the generated source files are added as dependents of the template file. The following example uses EntityFrameworkTemplateFileManager to output entity type definitions into separate files.

<#EntityFrameworkTemplateFileManager fileManager = EntityFrameworkTemplateFileManager.Create(this);#>
. . .
<#
// Emit Entity Types
foreach (EntityType entity in ItemCollection.GetItems<EntityType>().OrderBy(e => e.Name))
{
    fileManager.StartNewFile(entity.Name + ".cs");
    BeginNamespace(namespaceName, code);
    WriteEntityTypeSerializationInfo(entity, ItemCollection, code, ef);
#>

FunctionImportParameter - Responsible for collecting together the method parameters and the parameters that need to be sent to the ExecuteFunction method. The following example loops through the collection of function imports defined in the conceptual model and collects the needed parameters for each function.

<#
foreach (EdmFunction edmFunction in container.FunctionImports)
{
    IEnumerable<FunctionImportParameter> parameters = 
        FunctionImportParameter.Create(edmFunction.Parameters, code, ef);
. . . 
}
#>

See Also

Concepts

ADO.NET EntityObject Generator Template
ADO.NET Self-Tracking Entity Generator Template