Entity Framework 6.0

So you want to contribute to EF?

Part 2: The code

This is the second part of a series providing some background to those who may want make contributes to the Entity Framework. This post will cover the high-level organization of the code describing the assemblies created and some of the namespaces used.

What is the code base like?

The Entity Framework has been developed over a number of years by many developers at a big company. Some of the code dates back to the WinFS days. The result of this is a code base that is, to say the least, not as clean as it could be. Feel free to complain about this if you want. Better yet be constructive in suggesting ways to improve the code or submit contributions that make those improvements.

What gets built?

The process for getting the EF source code and building it can be found on the EF CodePlex site. The build generates several assemblies and NuGet packages.

Product assemblies

Tooling assemblies

Test assemblies

See part 3 of this series for information about the tests.

NuGet packages

The build combines the product and tooling assemblies into two NuGet packages:

Code organization

There are two things that effect the EF code organization more than anything else. The first is the historical split between core code and the DbContext/Code First code; the second is underpinning of the EF core code by the Entity Data model (EDM).

I have written more details about the high-level architecture of EF and its EDM underpinnings in part 5 of this series, so I'm not going to cover that here. Instead I'm going to talk here about the split between the core code and the DbContext/Code First code.

The EF 4.1 code split

The first two versions of EF were released as part of the .NET Framework. At about the time that the second version of EF (called EF4 to align with .NET 4) was released a group of people were already working on features that became Code First and the DbContext APIs. These features formed an out-of-band (OOB) release called EF 4.1. Significantly, this code was never included in the .NET Framework.

The obvious consequence of this is that since EF 4.1 the Entity Framework has consisted of two code bases—the code in the .NET Framework which we refer to as the core, and the OOB code for DbContext/Code First. The OOB code was dependent on the core, but the core didn't know anything about the OOB code.

The EF6 merge

With the move to open source for EF6 these two code bases have been brought together since all of EF6 is being released OOB and none of it is part of the .NET Framework. But when you look at the source code you will still see the historical separation. Generally speaking, code which comes from the core has been moved into namespaces under System.Data.Entity.Core.

The core code is not considered the primary public API going forward. In many situations it is treated as internal code that the DbContext and Code First APIs use for their implementation but not something that EF developers will work with directly. It remains public for those applications that make use of ObjectContext and the older APIs and because there are some scenarios that require dropping down to these lower-level APIs.

Most of the dependencies still go from the DbContext/Code First code to the core code and not the other way round. However, this separation is sometimes artificial and was forced by the model in which the releases were made. This means as we evolve the design of EF6 and beyond we are not trying to maintain this as a hard boundary, but rather we try to ensure that the abstractions and dependencies are appropriate going forward.

The namespaces

The main namespaces for EntityFramework.dll are:

String resources

It must be possible to localize every string that the Entity Framework product assemblies use. This means that any time code uses a string (such as in an exception message) the English string must be placed in the appropriate Resources.resx file (which can be found in the Properties folder) and given a name.

The Resouces.tt file is a T4 template used to create some helper methods that can be used to access localized strings. After adding a string to the resx file right-click on Resources.tt and choose “Run Custom Tool” to generate the helper methods. Examples of how this all works are easy to find in the code.

Summary

The EF build generates the main EF runtime assembly (EntityFramework.dll) and two providers together with everything needed to create the EF NuGet packages and Migrations tooling.

If there is anything here that you need more information about don't hesitate to contact me or others on the EF team. In the next post I'll look at the EF tests.


This page is up-to-date as of July 19th, 2012. Some things change. Some things stay the same. Use your noggin.