The official source of information on Managed Providers, DataSet & Entity Framework from Microsoft
It is now recommended to use the DbContext template described in this blog post. It will generate simpler POCO entities and a context class derived from DbContext which provides a simpler API.
The POCO Template can be used to generate persistence ignorant entity types from an Entity Data Model. The goal of this walkthrough is to demonstrate a basic scenario of its use with Entity Framework.
Note: While the following walkthrough uses C#, all the concepts described here apply to the Visual Basic version of the template which is available here.
The solution includes a project named POCOTemplateWalkthrough that is a Console Application. To facilitate us focusing on how to use the POCO Template, the solution already contains the following files:
Normally, when you start a new project using Entity Framework you can import a model from an existing database. In version 4.0, you can now create a database starting from the model. To learn more about the Model-First feature, see this blog post.
If you open the “Blogging.edmx” file, this is what you will see:
Five simple classes are used to model a blogging application: Blog represents an actual blog. A Person can act as the owner of a blog, but also as the author of a Post or a Comment, which both inherit from the abstract class Entry. A Blog can have multiple Posts, and in turn, each Post can have several Comments.
Notice that we are using foreign key associations in this model: Blog has both Owner and OwnerID properties. It is important to note, however, that exposing foreign key in entities is not a requisite for Entity Framework or the POCO Template.
By default, a model created with the Entity Data Model Designer produces entity classes based on System.Data.Objects.DataClasses.EntityObject, which provides basic services to entities, such as change notification, identity and relationship management. Special attributes are used to decorate classes and properties, so that Entity Framework can at runtime relate each class and property with the corresponding property in the model. In order to see the kind of code that is generated by default, expand the Blogging.edmx associated files by clicking on the arrowhead close to it, and then open the file Blogging.Designer.cs:
POCO stands for Plain-Old CLR Objects. POCO support in Entity Framework 4.0 means that these EntityObject-based types can be replaced with much simpler classes. POCO entity types are not required to inherit from any particular class and do not need attributes to map to the homologous elements in the model. Instead, types and properties in the objects and in the model are associated at runtime simply based on their names.
For an overview of POCO entities support you can read parts 1, 2 and 3 of this blog series on POCO and Entity Framework, and also this post on the use of patterns with Entity Framework 4.0.
One of the advantages of POCO entities is that they are simple. So in general, it is very easy to write them by hand. However, when you have an Entity Data Model as the starting point and want your entity classes to be POCO, the POCO Template can provide a good jumpstart by generating POCO classes that correspond to the model instead of the default EntityObject classes.
In order to do this, you can right-click on an empty area of the “Blogging.edmx” canvas and select “Add Code Generation Item...”
This will bring up the Add New Item dialog, in which you can choose which Template you wish to use. The POCO Template can normally be found under the Visual C# Items or the Visual Basic Items category.
On this screen select “ADO.NET POCO Entity Generator” and type “Blogging.tt” as the name of the new item. Then click on the “Add” button.
Note: A Security Warning dialog will appear each time a T4 generates code from a template in your machine:
Normally, T4 template files generate code when they are added to a project or when they are saved. If you have downloaded and installed the template form a trusted source, you can click “OK”.
Once you have added the POCO template, your project will look like this:
When you choose the POCO Template two T4 template files are added to your project. In this case one is called “Blogging.Context.tt” and the other is called “Blogging.tt”. T4 stands for Text Template Transformation Toolkit, and is a template engine that ships with Visual Studio. The Entity Framework POCO Template leverages T4 to allow you to customize code generation.
The “Blogging.tt” file is responsible for generating a file for each EntityType and ComplexType in the “Blogging.edmx” model. For instance, the POCO version of the Blog class looks like this:
“Blogging.tt” also generates a file called “Blogging.cs”, which contains a FixupCollection<T> class used by the POCO classes to keep the opposite ends of a relationships in sync.
For example in the model we’ve been using when you set a Comment's Author to a particular person the FixupCollection<T> class ensures that the Person's Comments collection will contain the Comment too.
The second template (“Blogging.Context.tt”) produces a strongly typed ObjectContext for the “Blogging.edmx” model. You use this strongly typed ObjectContext to interact with your database.
Note that each time you edit and save any T4 template the dependent files are regenerated, so you shouldn’t edit the generated files directly, or your changes will be lost. If you wish to modify the generated code, you can modify one or both of these templates.
Note: Why two templates?
The primary goal of the POCO template is to produce persistence ignorant entity classes.
However, the strongly typed ObjectContext derives from ObjectContext, which is an Entity Framework class. So this template must live in a project with a reference to the Entity Framework.
By splitting the template into two, one part that generates the Entity Types and Complex Types and one that generates a strongly typed context, it makes it possible not only to have Entities and ComplexType that are persistence ignorant but further to put those classes in an assembly / project that has no persistence aware code in it at all.
The next few steps show how to do this.
To continue, add a new Class Library project to the solution called Entities.
You can remove the class1.cs file created by default in the new project.
Now, in the POCOTemplateWalkthrough project, add a project reference to the Entities Project:
Next, move the “Blogging.tt” file into the Entities project. To do that, you can simply drag & drop the file into the Entities project in the Solution Explorer window, while you hold the Shift key at the same time.
The POCO Template T4 template files need to be able to read metadata from the EDM model in order to generate the right code. Since we have moved the template, the relative location of the Model has changed, therefore we need to fix the template so its link back to the model is correct again. To do this you can modify a line close to the top of the template from from:
string inputFile = @ “Blogging.edmx” ;
To:
string inputFile = @ “..\POCOTemplateWalkthrough\Blogging.edmx”;
This is simply a relative path from the template’s new location to the Blogging.edmx file in the other project.
Once you’ve done this Save the template, and this will regenerate the POCO entity classes. You can check that the contents of the file “Blogging.cs” under “Blogging.tt” has the right contents to verify that the path entered above is correct:
Also, notice the Entities project has no reference to the System.Data.Entity (aka the Entity Framework), and is completely persistence ignorant.
The classes in the Entities project are now in the “Entities” namespace rather than the “POCOTemplateWalkthrough” namespace, so you need to modify the namespace used by the context template. Otherwise the compiler won’t find the entity types and the solution won’t compile. You can do this by setting the value of the “Custom Tool Namespace” property to “Entities” in the property browser of the template item.
Once you do this, save the template file again (i.e. by pressing Ctrl+S) and you should be able to compile the solution without errors.
Now that we are done producing POCO classes it is time to verify that we can add some data to the database and get it back again using our POCO classes and the Entity Framework.
First, add this using statement at the top of the “Program.cs” file:
using Entities;
Then modify the Main() method by adding the following two blocks of code:
using (var ctx = new BloggingContainer()) { var person = new Person(); person.EmailAddress = "billg@microsoft.com"; person.Firstname = "Bill"; person.Surname = "Gates"; ctx.People.AddObject(person); ctx.SaveChanges(); Console.WriteLine("Saved {0}", person.Firstname); } using (var ctx = new BloggingContainer()) { var person = ctx.People.First(); Console.WriteLine("Found {0}", person.Firstname); }
After following all the steps described before, you should be able to compile and run the code and see the following screen:
The entity type, complex type and ObjectContext classes generated by the POCO Template are all partial classes. Therefore, it is often possible to extend the behavior of entities by just adding a partial class containing additional code to the project.
In other cases it might be better to modify the templates themselves to generate different code. Indeed, the whole point of a template-based solution is that you can decide the behavior you want only once, and then obtain the desired output from different models by applying a modified template.
Modifying the T4 Template files consists of modifying a text file, but it is beyond the scope of this basic walkthrough. Customization of T4 templates for entity code generation is described in this post.
Creating your own T4 template is not covered in this walkthrough either. You can expect future posts to explore more in depth this area. In the meanwhile, it is worth mentioning that T4 provides a mechanism by which you can write common utilities that you share across templates, in something called include files. The POCO template uses an include file called EF.Utility.CS.ttinclude. This include provides a number of utility feature that make writing T4 templates for Entity Framework easier, among others:
Diego Vega and Alex James Entity Framework Team