This topic is the top node in the MSDN documentation for the upcoming “Code-First” release.

Entity Framework

This release of Entity Framework introduces a new “productivity api”, and enables ”Code First” development. For more information, see What’s New

The Entity Framework is an “Object-Relational Mapper”, which reduces the “impedance mismatch” between the object-oriented world of .Net developers, and the world of relational databases. It enables developers to primarily interact with an application’s conceptual model, using familiar object-oriented techniques. In the Entity Framework you can work with data in the form of domain-specific objects and properties, such as customers and customer addresses, without having to concern yourself with the underlying database tables and columns where this data is stored. Developers can issue data access operations against the conceptual model, and EF takes care of translating the operations into relational database actions.

Overview

There are two major layers in an Entity Framework application:

The modeling layer; and

The object layer.

The modeling layer contains three components:

A conceptual model consisting of domain-specific entity types and relationships, based on an Entity Data Model (EDM);

a database schema that defines tables and relationships; and

a mapping between the conceptual model and the database schema.

The Entity Framework uses the mapping component to transform operations against entity objects such as create, read, update, and delete, into equivalent operations in the database.

The Entity Framework object layer contains typed Common Language Runtime (CLR) objects, which reflect the entities and relationships defined in the conceptual model. These objects can be consumed by programming languages. The exact format of the types is controlled by options you provide to the Entity Framework.

Mapping and Modeling

There are three different ways to create the mapping layer and the object layer.

“Model First”: graphically create a conceptual model first, using the Entity Data Model Designer, and then generate a database based on the metadata built by the tool from that model. For more information, see Tutorial: Creating a Conceptual Model using Tools .

It can infer a conceptual model based on the object types and additional configurations that you define. The mapping metadata is generated during runtime based on a combination of how you defined your domain types and additional configuration information that you provide in code. The Entity Framework generates the database as needed based on the metadata..

There is a Frequently Asked Questions (FAQs) web page for Entity Framework that has a lot of great information, at http://www.ef-faq.org . It’s a good place to go when you are first getting started with Entity Framework, since the questions you have are likely shared by others, and so may already be answered for you at this site.

I’ve just agreed to manage this web site, so if you have questions that you think ought to be in the FAQs, just add a comment to this posting.

Another way to add questions is to join the project, and create a build that includes your questions, notify me, and I will handle merging in your code. The project homepage gives you the information you need to do this. Since it’s open source, you could also make a fix for one of the work items the same way.

I’ll be ramping up this week and next, and then will likely address some of the minor fixes in the work item list just to get familiar with the build process. After that, one high priority fix is to go to a single-question-per-page format, to improve page discoverability by search engines such as Bing and Google.

Again, feel free to post proposed FAQs. It’s notable that none of the existing FAQs address Code-First development or other new features in the CTP5 release of Entity Framework: surely there must be some questions out there. It’s also likely possible that some of the answers may have broken due to new releases, or there are better solutions available with the new simplified “productivity api”.

This is a preview of the top-level MSDN topic for the new “Code-First” release of Entity Framework. The goal of this topic is to give a very high-level overview of Entity Framework, and to mention briefly what’s new (there is a separate “What’s New” topic that I’ll post next week, most likely).

Note that none of the links work, and the formatting is a bit off because the content has gone directly to the web (via this blog) rather than through Microsoft’s publishing process for MSDN.

You can post feedback in the comments section, and I will consider incorporating parts of it in the final version of this topic, if appropriate.

Entity Framework (Code-First Release)

This release of Entity Framework introduces a set of enhancements and features that increase productivity and enable ”Code First” development. For more information, see What’s New
The Entity Framework is an “Object-Relational Mapper”, which is intended to reduce the “impedance mismatch” between the object-oriented world of .Net developers, and the world of relational databases. It enables developers to primarily interact with an application’s conceptual model, using familiar object-oriented techniques. In the Entity Framework you can work with data in the form of domain-specific objects and properties, such as customers and customer addresses, without having to concern yourself with the underlying database tables and columns where this data is stored. Developers can issue data access operations against the conceptual model, and EF takes care of translating the operations into relational database actions.Overview
There are three major data components in an EF application:
1. A conceptual model consisting of domain-specific entity types and relationships, based on an Entity Data Model (EDM);
2. a database schema that defines tables and relationships; and
3. a mapping between the conceptual model and the database schema.
The Entity Framework uses the mapping component to transform operations against entity objects such as create, read, update, and delete, into equivalent operations in the database layer.
Entity Framework generates a run-time object layer by transforming the types and relationships defined in the conceptual model into typed Common Language Runtime (CLR) objects, so that they can be consumed by programming languages. The exact format of the generated types is controlled by options you provide to the Entity Framework.Mapping and Modeling
There are three different ways to create the conceptual model, the database schema, and the mapping between them.
1. “Database First”: starting with an existing database, generate a conceptual model from it, using the Entity Data Model Tools. In this case a default conceptual model and mapping are generated, which you can customize using the Entity Data Model Designer. For more information, see Tutorial: Creating a Conceptual Model from an Existing Database using Tools.
2. “Model First”: graphically create a conceptual model first, using the Entity Data Model Designer, and then generate a database based on the metadata built by the tool from that model. For more information, see Tutorial: Creating a Conceptual Model using Tools .
3. “Code First” (new in this release of Entity Framework): define your object model in code. The Entity Framework will infer a conceptual model based on the object types and additional configurations that you define. The mapping metadata is generated during runtime based on a combination of how you defined your domain types and additional configuration information that you provide in code. The Entity framework generates the database as needed based on the metadata.. For more information, see Tutorial: Creating a Conceptual Model using Code and Mapping and Modeling a Conceptual Model .Working with Objects
Entity Framework provides tools that automatically generate an object layer based on the conceptual model. The object layer code contains definitions of classes corresponding to the entity types, and an object context, which is a container for in-memory objects.
The Entity Framework object layer provides facilities to do the following:
1. execute queries against the conceptual model;
2. materialize data returned from the data source as objects;
3. track changes that were made to the objects;
4. handle concurrency;
5. propagate object changes back to the data source; and
6. bind objects to controls.In this SectionWhat’s New Mapping and Modeling a Conceptual Model Applying Additional Configurations to a Conceptual Model Working with Entities Querying with LINQ to EntitiesSee AlsoADO.NET Entity Framework

Videos are a great way to get started with a new technology! If done well, you can just sit back and watch things happen. Many people rate videos as one of their favorite ways to learn things. Personally, I like to combine a video with a detailed step-by-step written tutorial: the video shows me what is possible, and sometimes that is enough; but often, to really assimilate a new technology, I also need to actually do something myself, which is where the written tutorial comes in.

MSDN has a great series of beginner-videos about Entity Framework, by Julie Lerman. They are listed on two different pages.

I found these videos to be on just the right level for myself, as a newcomer to Entity Framework. Each one was well focussed, the content was presented clearly, and they were organized in a professional way. I recommend them in conjunction with other step-by-step written tutorials, if you are also a newcomer with a hands-on learning style like myself.

The videos’ author, Julie Lerner, has written a book about Entity Framework (Programming Entity Framework), and also has a blog, which looks well worth following.

My one complaint is that it is hard to find these videos via search. They do not show up in Bing or Google when you search with “Entity Framework 4 Getting Started Video”. The easiest way to get to them is by navigating through the MSDN portal. From there you can click on Data Developer Center, assuming that you already know Entity Framework is hidden inside there. From there you can click on Entity Framework, and on that page you click on Beginners Guide.

CTP5 is the final preview of a future release that will include the Code First feature, and the simplified API surface (aka DbContext). The production version of this release will be available Q1 of 2011. The authoritative source for this information is not me however: this information is all derived from the first blog post in the above list. And if there is a conflict between what I say and the ADO.Net team blog, believe them, not me!

I and my colleague Julia will be producing the MSDN Library documentation for this release. We’ve got ourselves a provisional table of contents, and have divided up topics. We intend to link to other content out on the web, so if you have a favorite article, tutorial, “how-to”, etc. let me know.

We will of course be documenting the features of this release, but our emphasis is shifting towards describing real customer scenarios. In the past, I’ve had problems with documentation that was totally feature-focused, since if I wasn’t familiar with the technology, then I often couldn’t figure out what one could do with a feature or what it was good for. So we’d like to identify the major customer scenarios, and focus on them.

I’m finally ready to start the tutorial, (Getting Started), which is a top link in Bing/Google searches for “Entity Framework Tutorial”. I haven’t blogged for a while: someone found bugs in an automation tool that I wrote, so I got to be a developer again. This post is a bit longer than I usually do.

The key audience for a “Getting Started” topic is beginners. The goal is to get them past all the nits and pitfalls that prevent them from getting anything at all done.

It’s tricky writing for them: you must give them enough context so they learn something, and understand what is going on; but don’t drown them in unnecessary details. I like to tell them stuff right when they are using it: the “Just in Time” approach.

Is this just my personal opinion, based on how I learn technology? Would someone with a different learning style prefer a different approach? That’s a legitimate question, and it’s hard to get into the head of someone with a different learning style. My main evidence for this approach is the usability studies we did of the WCF Getting Started Tutorial, where we found that it greatly improved people’s ability to complete the tutorial.

The EF Getting Started does not use this approach. The section starts with three conceptual overview topics about Entity Framework, followed by a tutorial which accompanies each step with limited discussion.

Here’s my bottom-line critique of the section. First, since I was able to successfully complete the tutorial, the section succeeds in its main objective. However, although the overview topics are very informative and contain lots of information, IMHO this level of detail is overkill for beginners. These topics should be moved to a separate “EF Overview” section that might follow this section. Also, the tutorial steps need a bit more context added to each of them.

I’ll walk through the section in detail. I’m very interested in your feedback: whether you agree with this critique, and what your experience was in going through the tutorial. New releases of Entity Framework are coming, so we are unlikely to go back and rewrite this tutorial; but your opinions and feedback can affect how we write future tutorials.

The first topic is Generating Models and Mappings, which starts off describing the three XML-based languages underlying EF. This is pretty scary, because the term “language” made me think I’d be coding in it. To be fair, the topic does say that the XML files are generated. But if so, then why are they telling me about them in such detail? Then the topic tells me about a command line tool (EdmGen.exe) which is never referenced in the tutorial, followed by a discussion of keys, which should be integrated with the tutorial steps. Finally we get to “The School Model”, which discusses the tables in the database. This content should go into the first section of the Quickstart topic (Creating the School Sample Database).

The next topic, Mapping a Conceptual Model to a Storage Model, discusses the three XML languages used in EF, and gives samples of each, which implies that the tutorial will be using the XML. This is both scary and untrue (again, too much detail for a beginner).

The final overview topic, Working With Entity Data: also too detailed. It starts off discussing “client views”, which are never referenced in the tutorial, and then shows an EF architecture diagram, which provides more detail than the tutorial uses. Next the topic discusses “Querying Objects” and the ObjectContext class, and what to do about the LazyLoadingEnabled property. It then shows me two code samples from the actual tutorial. Since I have yet to do a single step of the tutorial, I have no context for any of this.

It turns out that the ObjectContext class is the key to connecting the conceptual model in the application to the SQL Server objects in the database. All of the code that actually messes with data uses methods in this class. Unfortunately this wasn’t clear to me when first reading this section, because the discussion of it is buried amidst a flood of other details. These discussions ought to be right next to the code snippets in the Quickstart section.

Finally I get to the Quickstart overview topic, which tells me what I will learn, how the tutorial is structured, and what the requirements are to run it — pretty well organized.

I was able to run the steps just fine, so Getting Start succeeds in its main goal. I hit some minor nits due to windows titles changing after the topics were written, but this is a constant hazard of writing about evolving software. The main thing I would change is to add more context and explanation to each step, rather than have all the content in the three preceding topics.

The first step is Creating the School Sample Database, which includes a huge chunk of inline code to copy, followed by a section that describes how to display the database structure by using the Object Browser.

It would be nice to hide the code, by having it be downloaded from somewhere, since there are readers who will not realize that there is stuff to read after the code. Also, this section uses one tool to display the db structure, while Generating Models and Mappings uses a different tool: for simplicity and consistency, only one tool should be used. I would discuss the db structure a bit, and mention that the Person table includes students (non-null enrollment date) and instructors (non-null hire date). I’d contrast this with the Course table, which contains common data, and which is linked to the OnlineCourse and OnsiteCourse tables. I might also talk about keys here.

The third step, Generating the School .edmx File, is at the right level of detail, describing the two models (conceptual and data store) and the mapping between them.

The fourth step, Querying Entities and Associations, connects the UI to the database by providing read access. The fact that the SQL query logic is expressed using LINQ should be called out and discussed. Since the ObjectContextclass is used, some discussion of it would fit well, since that appears to be how a call to a C# object manages to retrieve rows from the database.

So what do you think? I’m pretty opinionated about how to write for beginners: how new people learn a technology is very interesting to me, and important for Microsoft to understand. Do these comments resonate with you? Or did you find the tutorial spot on? Let me know!

How do you find answers to questions about a Microsoft technology? How can a writer make what they write easy to find? And what tutorials about Entity Framework (“EF”) are available?

Finding Answers

Studies say you probably start with search engines like Bing or Google, which often link to topics in our documentation. Next you might use the MSDN library table of contents in order to get some context for the topic, or to find related topics. On the other hand, the search engine may lead you to someone in the community who has an answer just as good as ours, or better if they have some special expertise.

Most people do not start by looking in the MSDN Library table of contents. Writers such as myself probably do this more, since we have become very familiar with it because the topics we write are often part of the MSDN Library. Once I’ve found where some topics are, it’s often faster for me to use the table of contents than to use search.

I’m curious if anyone else has had my problem finding EF in the table of contents. Perhaps I’m the odd one who uses the table of contents to find things.

Making Topics Discoverable

You might think I’m obsessing about trivia, but as a writer, it’s very important that readers can find what I write. We worry a lot about “discoverability”, because it affects where our topics appear in search engines.

Anyway, after not finding EF in the table of contents, I did what most people do: I typed in “Entity Framework”, and both Bing and Google showed “tutorial” as one of the possible selections, so I clicked on that.

Tutorials about Entity Framework

Bing turned up over a million hits, and Google found 186,000. The first link listed by both search engines was to this topic in MSDN: Getting Started. Clicking this link took me to an overview of the tutorial, which walks through how to reverse-engineer an existing database into the Entity Framework. This is certainly a common customer scenario, and I’ll describe my experience with it in another post.

Another obvious scenario is creating a model from scratch. Are there other scenarios you care about? Should there be other tutorials that address these scenarios? Is the Getting Started tutorial at the right level as an introduction to EF? Do we need other tutorials at a more advanced level?

Here are a few interesting sounding non-Microsoft search engine links. It might be good if Microsoft’s EF documentation pointed to some of them (warning: I have not walked through these yet):

There are many more tutorials out there, and you can find some videos by searching on “Entity Framework Tutorial Video”. Anyone got a favorite tutorial you think we ought to link to from MSDN? Maybe you’ve written one yourself?