ADO.NET EntityObject Generator Template

Article
02/21/2011

This topic gives an overview of the ADO.NET EntityObject Generator template included with Visual Studio 2010, The topic also shows how to customize the text template. The ADO.NET EntityObject Generator template generates the typed ObjectContext and EntityObject derived entity classes (object-layer code).

The ADO.NET EntityObject Generator template generates the same code as the default code generated by the Entity Designer. The ADO.NET EntityObject Generator template consists of one text template file: <model name>.tt. The <model name>.tt template outputs one source file, <model name>.cs (or .vb), which appears under <model name>.tt in Solution Explorer.

<model name>.tt File Code Overview

First, the code uses built-in directives to instruct the text template processing engine how to process the template. The text template includes the .ttinclude file that contains utility classes that help with the code generation process. For more information about .ttinclude file, see Entity Framework Utility .ttinclude File.

<#@ template language="VB" debug="false" hostspecific="true"#>
<#@ include file="EF.Utility.VB.ttinclude"#>
<#@ output extension = ".vb" #>

<#@ template language="C#" debug="false" hostspecific="true"#>
<#@ include file="EF.Utility.CS.ttinclude"#>
<#@ output extension=".cs"#>

Then, it creates an instance of the UserSettings type that lets the user specify how the code should be written out. For example, this type determines whether camel case is used for field names or if the AddTo methods are added to the typed object context class in the generated code.

<#
    Dim userSettings As UserSettings =
        New UserSettings With _
        { _
            .SourceCsdlPath = "SchoolModel.edmx", _
            .ReferenceCsdlPaths = new string () {}, _
            .FullyQualifySystemTypes = True, _
            .CreateContextAddToMethods = True, _
            .CamelCaseFields = False _
        }

ApplyUserSettings(userSettings)
#>

<#
UserSettings userSettings =
        new UserSettings
        {
            SourceCsdlPath = @"SchoolModel.edmx",
            ReferenceCsdlPaths = new string[] {},
            FullyQualifySystemTypes = true,
            CreateContextAddToMethods = true,
            CamelCaseFields = false,
        };

ApplyUserSettings(userSettings);
#>

Then, the code instantiates and initializes the helper classes that are defined in the .ttinclude file. Some local variables are initialized as well.

<#
Dim loader As New MetadataLoader(Me)
Dim ef As New MetadataTools(Me)
Dim region As New CodeRegion(Me)
Dim code As New CodeGenerationTools(Me) With {.FullyQualifySystemTypes = userSettings.FullyQualifySystemTypes, .CamelCaseFields = userSettings.CamelCaseFields}

ItemCollection = loader.CreateEdmItemCollection(SourceCsdlPath, ReferenceCsdlPaths.ToArray())
ModelNamespace = loader.GetModelNamespace(SourceCsdlPath)
Dim namespaceName As String = code.VsNamespaceSuggestion()
UpdateObjectNamespaceMap(namespaceName)
#>

<#
MetadataLoader loader = new MetadataLoader(this);
MetadataTools ef = new MetadataTools(this);
CodeRegion region = new CodeRegion(this);
CodeGenerationTools code = new CodeGenerationTools(this){FullyQualifySystemTypes = userSettings.FullyQualifySystemTypes, CamelCaseFields = userSettings.CamelCaseFields};

ItemCollection = loader.CreateEdmItemCollection(SourceCsdlPath, ReferenceCsdlPaths.ToArray());
ModelNamespace = loader.GetModelNamespace(SourceCsdlPath);
string namespaceName = code.VsNamespaceSuggestion();
UpdateObjectNamespaceMap(namespaceName);
#>

After the initialization, a mixture of text blocks and code blocks is used to generate the text for the output file. The foreach (For Each in Visual Basic) loops are used to write out the text that is based on the metadata information returned by the GetSourceSchemaTypes helper function. The GetSourceSchemaTypes helper function is defined in the <model name>.tt file and calls the GetItems method to get all the items of the specified type from this item collection. The following is the description of the code that is written out to the <model name>.cs or <model name>.vb file:

EDM relationship metadata.
Typed ObjectContext definition. The class definition includes: constructor overloads, ObjectSet properties, AddTo methods (if the UserSettings.CreateContextAddToMethods is set to true) and function import methods (if any are defined in the conceptual model).

The following code from the <model name>.tt file writes out the typed ObjectContext class.
```
<#=Accessibility.ForType(container)#> Partial Class <#=code.Escape(container)#>
    Inherits ObjectContext
```
```
<#=Accessibility.ForType(container)#> partial class <#=code.Escape(container)#> : ObjectContext
```
If the container name is SchoolEntities, the following code is generated in the <model name>.cs or <model name>.vb file:
```
Public Partial Class SchoolEntities
    Inherits ObjectContext
```
```
public partial class SchoolEntities : ObjectContext
```
Entity type classes. These classes derive from EntityObject and include attributes that define how entity types in the object layer are mapped to entity types in the conceptual model. The definition of entity classes includes factory methods and primitive, complex, and navigation properties.
Complex type classes. These classes derive from ComplexObject and include attributes that define how complex types in the object layer are mapped to complex types in the conceptual model.

Then, the helper functions are defined. In text templates, the helper functions are enclosed in class feature blocks. You denote class feature tags by using <#+ and #>.

Customizing the Object-Layer Code

If you want to customize the way the object-layer code is generated, you must modify the .tt file. You may want to modify the name of the typed object context; add new or modify existing properties or attributes on entity types; or have the entity type inherit from some interface. To customize the object-layer code, you can modify the text blocks in your .tt file (the text block is outside of the <# and #> tags).

To change the name of the typed object context, add the word (for example, My) before all occurrences of <#=code.Escape(container)#>. Then, if in the .edmx file the container's name is SchoolEntities, in the generated code the container's name will be MySchoolEntities.

You can also customize the generated code by changing the values of the fields of the UserSettings type. For example, set FullyQualifySystemTypes to false if you do not want the generated code to have the fully qualified system types.

For more information, see How to: Customize Object-Layer Code Generation (Entity Data Model Designer).

ADO.NET EntityObject Generator Template

<model name>.tt File Code Overview

Customizing the Object-Layer Code

Additional resources