The information in this post is out of date.

Visit msdn.com/data/ef for the latest information on current and past releases of EF.

For Code First to a New Database see http://msdn.com/data/jj193542

For Code First to an Existing Database see http://msdn.com/data/jj200620


 

Entity Framework 4.1 RTW is now available and is the first fully-supported go-live release of the DbContext API and Code First development workflow.

This post will provide an introduction to Code First development and how it can be used with the new DbContext API surface. Code First allows you to define your model using C# or VB.Net classes, optionally additional configuration can be performed using attributes on your classes and properties or by using a Fluent API. Your model can be used to generate a database schema or to map to an existing database.

You will need to have Visual Studio 2010 installed to complete this walkthrough.

Mapping to an Existing Database

This walkthrough is going to demonstrate Code First generating the database schema but the same principals apply to mapping to an existing database, with the exception of ‘7. Setting an Initialization Strategy’ which does not apply to existing databases. If Code First is pointed at an existing database that it did not create then it will just attempt to use the specified configuration to access the database. The easiest way to point Code First to an existing database is to add a App/Web.config connection string with the same name as your derived DbContext, for example;

<connectionStrings>
  <add 
    name="MyProductContext" 
    providerName="System.Data.SqlClient" 
    connectionString="Server=.\SQLEXPRESS;Database=Products;Trusted_Connection=true;"/>
</connectionStrings>

 

1. Install EF 4.1

If you haven’t already done so then you need to install Entity Framework 4.1

 

2. Create the Application

To keep things simple we’re going to build up a basic console application that uses the Code First to perform data access:

  • Open Visual Studio 2010
  • File -> New -> Project…
  • Select “Windows” from the left menu and “Console Application”
  • Enter “CodeFirstSample” as the name
  • Select “OK”

 

3. Create the Model

Let’s define a very simple model using classes. I’m just defining them in the Program.cs file but in a real world application you would split your classes out into separate files and potentially a separate project.

Below the Program class definition in Program.cs I am defining the following two classes:

public class Category
{
    public string CategoryId { get; set; }
    public string Name { get; set; }

    public virtual ICollection<Product> Products { get; set; }
}

public class Product
{
    public int ProductId { get; set; }
    public string Name { get; set; }
    public string CategoryId { get; set; }

    public virtual Category Category { get; set; }
} 

 

4. Create a Context

The simplest way to start using the classes for data access is to define a context that derives from System.Data.Entity.DbContext and exposes a typed DbSet<TEntity> for each class in my model.

We’re now starting to use types from EF 4.1 so we need to add a reference to the EntityFramework assembly:

  • Project -> Add Reference…
  • Select the “.NET” tab
  • Select “EntityFramework” from the list
  • Click “OK”

You’ll also need a reference to the existing Entity Framework assembly:

  • Project -> Add Reference…
  • Select the “.NET” tab
  • Select “System.Data.Entity” from the list
  • Click “OK”

Add a using statement for System.Data.Entity at the top of Program.cs

using System.Data.Entity;

Add a derived context below the existing classes that we’ve defined

public class ProductContext : DbContext
{
    public DbSet<Category> Categories { get; set; }
    public DbSet<Product> Products { get; set; }
}

That is all the code we need to write to start storing and retrieving data. Obviously there is quite a bit going on behind the scenes and we’ll take a look at that in a moment but first let’s see it in action.

5. Reading & Writing Data

I’m padding out the Main method in my program class as follows:

class Program
{
    static void Main(string[] args)
    {
        using (var db = new ProductContext())
        {
            // Add a food category 
            var food = new Category { CategoryId = "FOOD", Name = "Foods" };
            db.Categories.Add(food);
            int recordsAffected = db.SaveChanges();

            Console.WriteLine(
                "Saved {0} entities to the database, press any key to exit.",
                recordsAffected);

            Console.ReadKey();
        }
    }
} 

You can now run the application and see that the new category is inserted.

Where’s My Data?

DbContext by convention created a database for you on localhost\SQLEXPRESS. The database is named after the fully qualified name of your derived context, in our case that is “CodeFirstSample.ProductContext”. We’ll look at ways to change this later in the walkthrough.

Model Discovery

DbContext worked out what classes to include in the model by looking at the DbSet properties that we defined. It then uses the default Code First conventions to find primary keys, foreign keys etc.

 

6. Reading & Writing More Data

Let’s pad out the program we just wrote to show a bit more functionality. We are going to make use of the Find method on DbSet that will locate an entity based on primary key. If no match is found then Find will return null. We’re also making use of LINQ to query for all products in the Food category ordered alphabetically by name. Querying uses the exiting LINQ to Entities provider so it supports the same queries that are possible with ObjectSet/ObjectQuery in EF4.

I’m replacing the Main we wrote above with the following:

class Program
{
    static void Main(string[] args)
    {
        using (var db = new ProductContext())
        {
            // Use Find to locate the Food category 
            var food = db.Categories.Find("FOOD");
            if (food == null)
            {
                food = new Category { CategoryId = "FOOD", Name = "Foods" };
                db.Categories.Add(food);
            }

            // Create a new Food product 
            Console.Write("Please enter a name for a new food: ");
            var productName = Console.ReadLine();

            var product = new Product { Name = productName, Category = food };
            db.Products.Add(product);

            int recordsAffected = db.SaveChanges();

            Console.WriteLine(
                "Saved {0} entities to the database.",
                recordsAffected);

            // Query for all Food products using LINQ 
            var allFoods = from p in db.Products
                            where p.CategoryId == "FOOD"
                            orderby p.Name
                            select p;

            Console.WriteLine("All foods in database:");
            foreach (var item in allFoods)
            {
                Console.WriteLine(" - {0}", item.Name);
            }

            Console.WriteLine("Press any key to exit.");
            Console.ReadKey();
        }
    }
} 

 

7. Setting an Initialization Strategy

In the next section we are going to start changing our model which in turn means the database schema needs to change as well. Currently there is no ‘out of the box’ solution to evolve your existing schema in place. Database evolution is something we are currently working on and a sample of the direction we are heading is provided in a recent design blog post.

There is however the opportunity to run some custom logic to initialize the database the first time a context is used in an AppDomain. This is handy if you want to insert seed data for test runs but it’s also useful to re-create the database if the model has changed. In EF 4.1 we include a couple of strategies you can plug in but you can also write custom ones.

For the walkthrough we just want to drop and re-create the database whenever the model has changed, so at the top of the Main method in my Program class I’ve added the following code

Database.SetInitializer<ProductContext>(
new DropCreateDatabaseIfModelChanges<ProductContext>());

 

8. Data Annotations

So far we’ve just let EF discover the model using its default conventions but there are going to be times when our classes don’t follow the conventions and we need to be able to perform further configuration. There are two options for this; we’ll look at Data Annotations in this section and then the fluent API in the next section.

Let’s add a supplier class to our model:

public class Supplier
{
    public string SupplierCode { get; set; }
    public string Name { get; set; }
}

And we also need to add a set to our derived context

public class ProductContext : DbContext
{
    public ProductContext()
    { }

    public DbSet<Category> Categories { get; set; }
    public DbSet<Product> Products { get; set; }
    public DbSet<Supplier> Suppliers { get; set; }
}

Now if we ran our application we’d get an InvalidOperationException saying “EntityType 'Supplier' has no key defined. Define the key for this EntityType.” because EF has no way of knowing that SupplierCode should be the primary key for Supplier.

We’re going to use Data Annotations now so we need to add a reference:

  • Project -> Add Reference…
  • Select the “.NET” tab
  • Select “System.ComponentModel.DataAnnotations” from the list
  • Click “OK

Add a using statement at the top of Program.cs:

using System.ComponentModel.DataAnnotations;

Now we can annotate the SupplierCode property to identify that it is the primary key:

public class Supplier
{
    [Key]
    public string SupplierCode { get; set; }
    public string Name { get; set; }
}

The full list of annotations supported in EF 4.1 is;

  • KeyAttribute
  • StringLengthAttribute
  • MaxLengthAttribute
  • ConcurrencyCheckAttribute
  • RequiredAttribute
  • TimestampAttribute
  • ComplexTypeAttribute
  • ColumnAttribute
    Placed on a property to specify the column name, ordinal & data type
  • TableAttribute
    Placed on a class to specify the table name and schema
  • InversePropertyAttribute
    Placed on a navigation property to specify the property that represents the other end of a relationship
  • ForeignKeyAttribute
    Placed on a navigation property to specify the property that represents the foreign key of the relationship
  • DatabaseGeneratedAttribute
    Placed on a property to specify how the database generates a value for the property (Identity, Computed or None)
  • NotMappedAttribute
    Placed on a property or class to exclude it from the database

 

9. Fluent API

In the previous section we looked at using Data Annotations to supplement or override what was detected by conventions. The other way to further configure the model is via the Code First fluent API. The fluent API is considered a more advanced feature and we would recommend using Data Annotations unless your requirements require you to use the fluent API.

To access the fluent API we override the OnModelCreating method in DbContext, in the following code we are using the fluent API to configure the Name property on Supplier to be required.

public class ProductContext : DbContext
{
    public ProductContext()
    { }

    public DbSet<Category> Categories { get; set; }
    public DbSet<Product> Products { get; set; }
    public DbSet<Supplier> Suppliers { get; set; }

    protected override void OnModelCreating(DbModelBuilder modelBuilder)
    {
        modelBuilder.Entity<Supplier>()
            .Property(s => s.Name)
            .IsRequired();
    }
}

 

Summary

In this walkthrough we looked at Code First development using the EF 4.1. We looked at defining and configuring a model, storing and retrieving data, configuring the database connection, updating the database schema as our model evolved and validating data before it is written to the database.

Support

This is a fully supported release. The ADO.NET Entity Framework Forum can be used for questions relating to this release. Further information about getting technical support can be found at the Microsoft Support website.

Rowan Miller
Program Manager
ADO.NET Entity Framework