ADO.NET Self-Tracking Entity Generator Template

This topic provides an overview of the ADO.NET Self-Tracking Entity Generator template included with Visual Studio 2010. The topic also shows how to customize the text template. The ADO.NET Self-Tracking Entity Generator template generates the object-layer code that consists of the typed ObjectContext and entity classes that contain self-tracking state logic. Use self-tracking entities when working with N-tier applications. For more information, see Working with Self-Tracking Entities (Entity Framework) and Walkthrough: Serialize Self-Tracking Entities (Entity Framework).

The ADO.NET Self-Tracking Entity Generator template consists of two text template files: <model name>.tt and <model name>.Context.tt. The <model name>.Context.tt template generates the typed ObjectContext. The <model name>.tt template generates the self-tracking entity types.

Both text templates begin with built-in directives that instruct the text template processing engine how to process the template. Note, that the text templates include the .ttinclude file. The .ttinclude file contains utility classes that help the ADO.NET templates 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, the code instantiates and initializes the helper classes that are defined in the .ttinclude file.

Dim code As New CodeGenerationTools(Me)
Dim ef As New MetadataTools(Me)
Dim loader As New MetadataLoader(Me)
Dim region As New CodeRegion(Me)

Dim fileManager As EntityFrameworkTemplateFileManager = EntityFrameworkTemplateFileManager.Create(Me)

CodeGenerationTools code = new CodeGenerationTools(this);
MetadataTools ef = new MetadataTools(this);
MetadataLoader loader = new MetadataLoader(this);
CodeRegion region = new CodeRegion(this);

EntityFrameworkTemplateFileManager fileManager = EntityFrameworkTemplateFileManager.Create(this);

The code also initializes the inputFile string. If you move the templates from the project that contains the .edmx file into another project, you must modify the inputFile string to the relative location of the .edmx file.

Dim inputFile As String = "SchoolModel.edmx"

string inputFile = @"SchoolModel.edmx";

The following two sections discuss specifics of what each .tt file generates.

<model name>.Context.tt

The <model name>.Context.tt template generates two source files. The source files appear under the <model name>.Context.tt file in Solution Explorer.

• A file named <model name>.Context.cs (or vb). The generated source code contains the definition for the typed ObjectContext class. The definition includes:

  • Constructor overloads. The constructors set proxy creation to false and register the ObjectMaterializedEventHandler. For information about POCO ("plain-old" CLR objects) and proxy objects, see Working with POCO Entities (Entity Framework).

  • ObjectSet properties.

  • Function import methods (if any are defined in the conceptual model).

• A file named <model name>.Context.Extensions.cs (or vb). The generated source file contains two ApplyChanges extension methods (one for ObjectContext and the other for ObjectSet) and private methods that support the ApplyChanges method. The ApplyChanges method examines the change tracking information in the graph of self-tracking entities and infers the set of operations that must be performed to reflect the changes in the database.

<model name>.tt

The <model name>.tt template generates multiple source files. The source files appear under the <model name>.tt file in Solution Explorer.

• A file called <model name>.cs (or .vb), which contains the following:

  • The definition for the ObjectChangeTracker helper class. An ObjectChangeTracker instance contains and tracks information about all changes made to types that implement IObjectWithChangeTracker. ObjectChangeTracker is part of the data contract of self-tracking objects and is therefore serialized with them.

  • The definition for the IObjectWithChangeTracker interface. The interface is implemented by the self-tracking entities and contains a single read-only property to retrieve the ObjectChangeTracker for an entity.

  • Extension methods defined for IObjectWithChangeTracker types that allow manipulation of the entity state through the ObjectChangeTracker. The following is the list of the extension methods: MarkAs[State], StartTracking, StopTracking and AcceptChanges. For information about what each of the extension method does, see Working with Self-Tracking Entities (Entity Framework).

  • The definition for TrackableCollection of T that derives from ObservableCollection. Each entity that has collection navigation properties registers a handler for the CollectionChanged event on the TrackableCollection of T for that navigation property. The handler performs the change tracking and the logic that synchronizes both ends of the relationship.

  • The definition of the INotifyComplexPropertyChanging interface. The interface provides an event that occurs when complex properties change. The change can be either an assignment of a new complex type instance to a complex property or a change to a scalar property on a complex type instance.

  • The definition of the ObjectState enumeration. The ObjectState enumerator list consists of the following constants: Unchanged, Added, Modified, and Deleted.

  • There are other types in the file that are used to store state information within ObjectChangeTracker. For more information, view the generated <model name>.cs or <model name>.vb file.

• A file for each entity type and complex type defined in the conceptual model: <entity or complex type name>.cs (vb).

  • Entity types are partial classes that implement IObjectWithChangeTracker and INotifyPropertyChanged (to support two-way data binding in Windows Forms, WPF, and Silverlight).

    The DataContract attribute is added at the top of the class to allow the class to be serialized. Also, IsReference = true is specified on the DataContract attribute. This means the serialization for this type is a deep serialization.

    The KnownType attributes are added at the top of the class. There is one KnownType attributes for each type that this entity type has a navigation property to.

    The definition of entity classes include the following: primitive properties, complex properties, navigation properties, the ChangeTracker property, and methods that help with relationships synchronization logic.

  • Complex types are partial classes that implement INotifyComplexPropertyChanging and INotifyPropertyChanged.

Customizing the Object-Layer Code

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, modify the text blocks in your .tt file. The text block is defined outside of the <# and #> tags. To change the name of the typed object context, open the <model name>.Context.tt file and add the word (for example, My) right 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.

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

See Also

Concepts

Entity Framework Utility .ttinclude File

Other Resources

Working with Self-Tracking Entities (Entity Framework)
Walkthrough: Serialize Self-Tracking Entities (Entity Framework)