This tutorial guides you through the process of creating a simple application powered by ADO.NET Entity Framework. In less than 5 minutes you will have a ready-to-use data access layer for your business objects.

Please note that this tutorial is not applicable for Entity Framework Core. It is intended for previous Entity Framework versions.

In this walkthrough:

• Introducing the ADO.NET Entity Framework
• Requirements
• Entity Framework v6
• Generating Model from Database
• Querying Data
• Inserting New Data
• Updating Data
• Deleting Data
• Additional Information

Introducing the ADO.NET Entity Framework

ADO.NET Entity Framework is an object-relational mapping (ORM) framework for the .NET Framework. It is designed to enable developers to create data access applications by programming against a conceptual application model instead of programming directly against a relational storage schema. The goal is to decrease the amount of code and maintenance required for data-oriented applications.

Requirements

In order to connect to FreshBooks server you need the corresponding FreshBooks connection parameters, dotConnect for FreshBooks installed and IDE running.

For Entity Framework 6, you will also need a NuGet Visual Studio extension installed since it is used for adding EntityFramework NuGet package. Alternatively you may create model for Entity Framework v4, which don't require NuGet, in this tutorial.

In this sample we will create a simple console application. It could be any other project type as well, but for simplicity's sake we'll use console project throughout the tutorial. Start Visual Studio and create a new console application.

Entity Framework v6

The following actions are required if you want to create an Entity Framework v6 model.

Open the Package Manager Console window and execute the following command in it.

install-package EntityFramework

After this add the following line:

<provider invariantName="Devart.Data.FreshBooks" type="Devart.Data.FreshBooks.Entity.FreshBooksEntityProviderServices, 
Devart.Data.FreshBooks.Entity.EF6, Version=1.0.0.0, Culture=neutral, PublicKeyToken=09af7300eec23701" />

to the entityFramework -> providers section.

<entityFramework>
    <providers>
      <provider invariantName="Devart.Data.FreshBooks" type="Devart.Data.FreshBooks.Entity.FreshBooksEntityProviderServices, 
      Devart.Data.FreshBooks.Entity.EF6, Version=1.0.0.0, Culture=neutral, PublicKeyToken=09af7300eec23701" />
    </providers>
</entityFramework>

Note: replace 1.0.0.0 with the actual assembly version.

After this you need to rebuild the project before running the EDM wizard.

Generating Model from Database

1. In the Solution Explorer right-click on the project and choose Add | New Item.
2. In the dialog select ADO.NET Entity Data Model, click Add. This launches Entity Data Model Wizard.
3. In the wizard select Generate from database, click Next.
4. Pick an existing dotConnect for FreshBooks connection string or create a new one. When creating a new connection select FreshBooks Data Source in the Data Source list, then dotConnect for FreshBooks in the Data provider list. See the screenshot below.
   
5. Agree to include the sensitive data in the connection string.
6. In the Save entity connection settings... box type FreshBooksEntities. This will be the name of the main data access class. Click Next.
7. Select database objects that will be used in the model. Enter FreshBooksModel in the Model Namespace box.
   
8. Click Finish. The model will be generated and opened in EDM Designer.
   

The model you've just generated is ready to use. Its name is Model1.edmx, unless you changed it in the step 2. You can inspect it visually in the designer or take a look behind the scenes with XML Editor.

The wizard creates classes for all selected tables that represent entities. It also creates a descendant of System.Data.Objects.DbContext class, which controls the connection to the database, and the whole data flow. This class includes properties and methods named after your database objects. You will use these members to retrieve and modify data in the context. The code is contained in an autogenerated file Model1.Designer.cs (Model1.Designer.vb).

Note that if you have an association between two properties of non-coinciding numeric types, you can manually change both conceptual and storage types to the type that will be wide enough to include data for each property.

Querying Data

All Entity Framework operations are executed through a DbContext descendant (default since Visual Studio 2012) or through a ObjectContext descendant. In our tutorial, it's a DbContext descendant, which is named FreshBooksEntities. To retrieve data you have to first create an instance of the context, then prepare a query with LINQ to Entities or EntitySQL or their mix, and then access the object returned by the query, which may be a collection of objects or a single object.

Let's try performing a LINQ to Entities query against our model. Add the following block of code to the method Main:

    FreshBooksEntities context = new FreshBooksEntities();
    var query = from it in context.Task
                orderby it.Name
                select it;

    foreach (Task t in query)
        Console.WriteLine("{0} | {1} | {2}", t.Name, t.Billable, t.Rate);

    Console.ReadLine();

    Dim context As New FreshBooksEntities
    Dim query = From it In context.Task
        Order By it.Name
        Select it

    Dim t As Task
    For Each t In query
        Console.WriteLine("{0} | {1} | {2}", t.Name, t.Billable, t.Rate)
    Next

    Console.ReadLine()

As simple as that. You prepare a query and then iterate through it as you would do with a usual collection of objects. The database interaction is performed by Entity Framework in the background. Now let's see who is who in this code sample.

• FreshBooksEntities is the name of the class that knows all about your model and does everything to handle it. You named it in the step 6. All Entity Framework operations are performed within this class's properties and methods. It is recommended that you keep a single instance of the class throughout your application because it consumes lots of resources.
• query, it - these are arbitrary variable names in the LINQ to Entities statement. The former is used as the collection of data objects, the latter is not used outside the statement.
• context.ENTITY refers to a public property of FreshBooksEntities class. This property represents the collection of the corresponding objects in the context.

Here is the project's output in the console:

Note that the LINQ to Entities query code just describes the query. It does not execute it. This approach is known as deferred execution.

Now let's query data from two objects united with a relation. Replace the old code with this:

   // Add references to the following assemblies in your project:
   // Devart.Data.dll,  Devart.Data.SqlShim.dll, Devart.Data.FreshBooks.dll, Devart.Data.FreshBooks.Entity.EF6.dll
   var monitor = new Devart.Data.FreshBooks.FreshBooksMonitor() { IsActive = true };

        FreshBooksEntities context = new FreshBooksEntities();
        var query = from it in context.Clients
                    orderby it.LastName
                    select it;

        foreach (Client c in query)
            Console.WriteLine("{0} | {1} | {2}", c.FirstName, c.LastName, c.Email);

        Console.ReadLine();

   ' Add the references to the following assemblies in your project:
   ' Devart.Data.dll, Devart.Data.SqlShim.dll, Devart.Data.FreshBooks.dll, Devart.Data.FreshBooks.Entity.EF6.dll
   Dim monitor As New Devart.Data.FreshBooks.FreshBooksMonitor()
   monitor.IsActive = True


    Private Sub SurroundingSub()
        Dim context As FreshBooksEntities = New FreshBooksEntities()
        Dim query = From it In context.Clients Order By it.LastName Select it

        For Each c As Client In query
            Console.WriteLine("{0} | {1} | {2}", c.FirstName, c.LastName, c.Email)
        Next

        Console.ReadLine()
    End Sub

This sample is much like the previous one, with exception that it adds the Include method that instructs the query to retrieve data from one more object.

Inserting New Data

What earlier was adding rows to tables, now is just adding new objects to context collections. When you are ready to send the changes to the database, call the SaveChanges() method of the context. Before doing this, you must first set all properties that do not support null (Nothing) values. The SaveChanges() method generates and executes commands that perform the equivalent INSERT, UPDATE, or DELETE statements against the data source.

By Microsoft design, DbContext.SaveChanges() should work within a distributed transaction, but it is not supported by API of FreshBooks. That's why SaveChanges() will submit all DML operations (till the failed one, if any). This code snippet includes enabled FreshBooksMonitor for tracing the SQL statements sent to data source.

Let's add new objects to the data source. Replace the old code with this:

    // Add references to the following assemblies in your project:
    // Devart.Data.dll,  Devart.Data.SqlShim.dll, Devart.Data.FreshBooks.dll, Devart.Data.FreshBooks.EF6.dll
    var monitor = new Devart.Data.FreshBooks.FreshBooksMonitor() { IsActive = true };

    FreshBooksEntities context = new FreshBooksEntities();

    // Create a new contractor
    var c = new Contractor();
    c.Email = "[email protected]";
    context.Contractor.Add(c);

    // Create a task
    var t = new Task();
    t.Name = "new task";
    t.Billable = true;
    t.Rate = 100m;

    // Associate the contract with the task
    t.Contractor.Add(c);
    context.Task.Add(t);

    // Send the changes to the database.
    // Until you do it, the changes are cached on the client side.
    context.SaveChanges();

    // Request the new task from the database
    var query = from it in context.Task.Include("Contractor")
                where it.Name == "new task"
                select it;

    // Since we query for a single object instead of a collection, we can use the method First()
    Task task = query.First();
    Console.WriteLine("{0} | {1} ",
        task.Contractor.First().Email, task.Name);
    Console.ReadLine();

    ' Add the references to the following assemblies in your project:
    ' Devart.Data.dll, Devart.Data.SqlShim.dll, Devart.Data.FreshBooks.dll, Devart.Data.FreshBooks.EF6.dll
    Dim monitor As New Devart.Data.FreshBooks.FreshBooksMonitor()
    monitor.IsActive = True

    Dim context As New FreshBooksEntities

    ' Create a new contractor
    Dim c = New Contractor()
    c.Email = "[email protected]"
    context.Contractor.Add(c)

    ' Create a task
    Dim t = New Task()
    t.Name = "new task"
    t.Billable = True
    t.Rate = 100D

    ' Associate the contract with the task
    t.Contractor.Add(c)
    context.Task.Add(t)

    ' Send the changes to the database.
    ' Until you do it, the changes are cached on the client side.
    context.SaveChanges()

    ' Request the new task from the database
    Dim query = From it In context.Task.Include("Contractor")
                Where it.Name = "new task"
                Select it

    ' Since we query for a single object instead of a collection, we can use the method First()
    Dim task = query.First()
    Console.WriteLine("{0} | {1} ",
        task.Contractor.First().Email, task.Name)
    Console.ReadLine()

The Add methods and others are automatically generated in the context. Such methods exist for every entity in your model.

Updating Data

Entity instances are modified as usual. The only thing to remember is that you have to invoke the SaveChanges() method to send the data to the database.

Append the following block to the existing code and launch the project:

    task.Name = "edited name";
    context.SaveChanges();

    task.Name = "edited name"
    context.SaveChanges()

Deleting Data

To extract an instance from a context use the DeleteObject method of the context. The object is removed from the collection of its type, but not destroyed. To delete the object's data from the database invoke the SaveChanges() method.

You can do this with a block of code like the following:

    context.Task.Remove(task);
    context.Contractor.Remove(contractor);
    context.SaveChanges();

    context.Task.Remove(task)
    context.Contractor.Remove(contractor)
    context.SaveChanges()

Additional Information

Now that you can perform the basic data manipulation with Entity Framework, you can move on to some advanced topics.

We recommend you to use Entity Developer (Devart Entity Model, *.edml) instead of EDM Designer (ADO.NET Entity Data Model, *.edmx) because it is adjusted for working with FreshBooks and offers advanced functionality. Additionally, Entity Developer registers Entity Framework v6 providers in app.config automatically and offers advanced visual designer and support for Database First / Model First approaches for EF Core.

Here are some useful links to MSDN:

• Entity Framework Core
• Entity Framework 6
• Entity Framework 5

For hands-on experience download the separate Entity Framework Query Samples (EF1/EF4/EF5/EF6) package or use samples shipped with dotConnect for FreshBooks. You can access the samples from the Start menu.

To understand deeper the works of Entity Framework engine you can watch the generated SQL statements in dbMonitor.

See Also

Entity Framework section  | Entity Framework Support Overview