LINQ to Entities leverages the LINQ parser to begin processing the query, whereas ObjectQuery uses a different parser. After each has gone through its first transition, they both follow the same path. Let’s take a look at how each query is turned into the eventual store command.

How EntityClient turns command trees into store commands

The newly created command tree is still expressed in terms of the entities in the model’s conceptual layer. So at this point, the processor uses EDM mappings to transform the terms of the command tree into the tables, columns, and other objects of the database. This process might run through the command tree a number of times to simplify the demands made in the query before it comes up with an equivalent of the database’s tables and columns. Once this new version of the tree has been created, it is sent to the store provider (e.g., SqlClient), which will know how to convert the command tree into its native command text.

Entity Framework provider writers use the common schema of a command tree to create their functionality for generating SQL from the command tree. For example, a SqlClient provider will transform the tree into T-SQL that SQL Server can execute; an Oracle provider will transform the tree into a proper PL/SQL command.

Figure 9-2 shows the steps these queries take to get to the data store.

Figure 9-2. How the various query styles get to the data store

Writing Entity SQL is not always simple. Although the process is familiar to those who already write store commands, it is different enough that it will probably take some time before the syntax rolls naturally from your fingertips. Query builder methods can be quite useful, as the methods are discoverable through IntelliSense and take away some of the pain of remembering the exact syntax.

In Chapter 4, you built a variety of queries using the CreateQuery method with an Entity SQL expression as its parameter. You also used query builder methods. Examples 9-1 and 9-2 are intended to refresh your memory.

VB
Dim qStr = "SELECT VALUE c " & _
                  "FROM PEF.Contacts AS c " & _
                  "WHERE c.FirstName='Robert'"
Dim contacts = context.CreateQuery(Of Contact)(qStr)

C#
var queryStr = "SELECT VALUE c " +
                "FROM PEF.Contacts AS c " +
                "WHERE c.FirstName='Robert'";
var contacts = context.CreateQuery<Contact>(queryStr);

VB
Dim contacts = context.Contacts _
               .Where("it.FirstName = 'Robert'")

C#
var contacts = context.Contacts
               .Where("it.FirstName = 'Robert'")

Both sets of code define the same ObjectQuery, which searches for contacts whose first name is Robert. Neither will actually return results until something forces the query to be executed.

The query builder methods may still require that you write part of the expression, such as the Where predicate it.FirstName='Robert' in Example 9-2, but they are still a great deal easier than using the CreateQuery method.

VB
Partial Public Class PEF
        Inherits Global.System.Data.Objects.ObjectContext

C#
 public partial class PEF : global::System.Data.Objects.ObjectContext

VB
<Global.System.ComponentModel.BrowsableAttribute(false)>  _
Public ReadOnly Property Contacts() As _
          Global.System.Data.Objects.ObjectQuery(Of Contact)
 Get
   If (Me._Contacts Is Nothing) Then
     Me._Contacts = MyBase.CreateQuery(Of Contact)("[Contacts]")
   End If
   Return Me._Contacts
  End Get
End Property

C#
public global::System.Data.Objects.ObjectQuery<Contact> Contacts
{
  get
  {
    if ((this._Contacts == null))
      this._Contacts = base.CreateQuery<Contact>("[Contacts]");
    return this._Contacts;
  }
}

context.Contacts.Where("it.FirstName='Robert'").Take(10)

You have already seen some of the members of ObjectQuery, such as the query builder methods and the Include method. Additional methods and properties are available that will help you better understand the role of ObjectQuery. Here are some that you can see when inspecting an ObjectQuery in the debugger.

Figure 9-3 shows an ObjectQuery in debug mode with its properties, as well as a way to access the results. Figure 9-4 shows a LINQ to Entities query in the debugger; as you can see, LINQ to Entities exposes the results directly, but also contains an ObjectQuery.

Figure 9-3. An ObjectQuery called contacts in the debugger, showing the various properties of ObjectQuery

Figure 9-4. A LINQ to Entities query in the debugger, showing that the LINQ to Entities query contains an ObjectQuery

If you want to get to ObjectQuery properties and methods from a LINQ to Entities query, you can cast the LINQ to Entities query to ObjectQuery.

ToTraceString

One very helpful ObjectQuery method is ToTraceString, which displays the native store command that will be created from your query. Figure 9-5 shows some code that calls ToTraceString and the value the method returns at runtime.

Figure 9-5. Viewing the native command that will be generated from an ObjectQuery using the ToTraceString method while debugging

Example 9-5 demonstrates casting a LINQ to Entities query to an ObjectQuery in order to call the ToTraceString method.

Example 9-5. Casting a LINQ to Entities query to use ObjectQuery methods such as ToTraceString

VB
Dim contacts = From c In context.Contacts
               Where c.FirstName = "Robert"
Dim str = CType(contacts, Objects.ObjectQuery).ToTraceString

C#
var contacts = from c in context.Contacts
    where c.FirstName == "Robert"
    select c;
var str = ((Objects.ObjectQuery)contacts).ToTraceString();

context.CreateQuery(Of Contact)
("SELECT VALUE c
    FROM PEF.Contacts AS c
    WHERE c.FirstName='Robert'")

SELECT  VALUE c
FROM PEF.Contacts AS c
WHERE c.FirstName='Robert'

context.Contacts
.Where("it.FirstName = 'Robert'")
.OrderBy("it.LastName")

SELECT VALUE it
FROM (
SELECT VALUE it
FROM (
[Contacts]
) AS it
WHERE
it.FirstName = 'Robert'
) AS it
ORDER BY
it.LastName

From c In context.Contacts
Where c.FirstName = "Robert"

So far, the query has been defined but no data retrieval has actually occurred. Query execution occurs when the Entity Framework retrieves the data from the store. Queries can be executed implicitly or explicitly.

In previous chapters, you enumerated over the results of a query (using VB’s For Each or C#’s foreach). Enumerating over a query will force a query to execute implicitly. You don’t need to specifically say “go get the data.” The fact that you are attempting to work with the query results will cause the Entity Framework to do that for you.

Another way to force execution is to append the ToList or ToArray LINQ method to a query. Example 9-6 appends ToList to the CreateQuery method to execute the query immediately and return a list of Contact entities.

VB
Dim contacts =  context.CreateQuery(Of Contact)(queryStr).ToList()

C#
var c2 = context.CreateQuery<Contact>(queryStr).ToList();

ObjectQuery has an Execute method, which also forces execution, but it requires a parameter to define MergeOptions for the objects that result, as shown in the following code:

VB
Dim contacts = context.Contacts.Execute(MergeOption.AppendOnly)

C#
var contacts = context.Contacts.Execute(MergeOption.AppendOnly);

Four merge options influence how newly returned objects impact objects that may already exist in memory. MergeOption is also a property of the ObjectQuery, so you can set the value directly even when you’re not using the Execute method.

AppendOnly is the default, and it will be used when you don’t set the option directly while executing queries without the Execute method. However, with Execute, you must set this parameter, even if you just want the AppendOnly default.

You used Execute in the preceding chapter for the Windows Forms data-binding example. Execute does not return an ObjectQuery, but rather a type called ObjectResult. An ObjectQuery contains all of the metadata about the query itself, the query expression, the connection information, and more, as well as any results (after the query has been executed). When you use the Execute method, however, you have only the results, not the metadata. Using Execute is beneficial in some scenarios, but in others, its limitations, such as the fact that you can enumerate over ObjectResults only once, might be a problem.

Because MergeOption impacts what happens with the returned data, its purpose will make more sense after we have discussed some additional topics. We’ll return to MergeOption in more detail later in this chapter.

By default, ObjectContext will use the connection string defined in the application’s app.config file that has the same name as the name of the context’s EntityContainer. For example, when the EntityContainer name is BAEntities, Object Services will search for a connection string named BAEntities in the app.config file. If no matching connection string is found and no override is provided, an exception will be thrown at runtime. The exception reads “The specified named connection is either not found in the configuration, not intended to be used with the EntityClient provider, or not valid.”

You can override the default behavior in a number of ways. One way to override the default is to supply a different connection string name in the constructor of the ObjectContext. This string needs to be available in the app.config file as well. Example 9-7 uses the connection string named connString to create an ObjectContext.

VB
Dim context=new PEF("Name=connString")

C#
var context = new PEF("Name=connString");

Another way to override the default is to supply an EntityConnection object instead. This would be the same EntityConnection that is used with the EntityClient provider. By creating an explicit EntityConnection, you can manipulate that EntityConnection prior to instantiating a context with it. Example 9-8 creates the EntityConnection but does not do anything special with it. You will learn a lot more about manipulating an EntityConnection in Chapter 16.

VB
Dim econn = New EntityConnection("name=connString")
Dim context = New PEF(econn)

C#
var econn = new EntityConnection("name=connString");
var context = new PEF(econn);

So, what’s next? You’ve got your ObjectQuery all set. You know the ObjectQuery will do all of the work to create a command tree. Somehow, the command tree gets handed off to the EntityClient provider along with the database connection string provided by the ObjectContext. If you dig into the Entity Framework assemblies using Reflector, you will find that the ObjectContext calls on EntityClient to do the job of creating the connection and executing the command on the data store.

As you saw with the EntityClient queries in Chapter 3, EntityClient returns an EntityDataReader, not objects.

When objects are returned from queries, ObjectContext creates pointers to each entity, in effect, caching references to these entities. ObjectContext not only keeps track of all of these entities, but also keeps track of other information regarding those entities, including their state, their original and current values, and their relationships to one another.

When objects are returned from queries, they are managed by the ObjectContext by default. The only responsibility of an entity object is to know what its current state is, that is, to know the current values of its properties.

The properties of an entity class are the scalar and navigation properties that define the schema of that entity. For example, the BreakAway Contact class has only the following properties: ContactID, FirstName, LastName, AddDate, ModifiedDate, Title, Customer, Addresses, and Lodging. These are the same properties that are in the entity in the model.

You can look into the classes to see what the code looks like. Example 9-9 shows the Visual Basic code related to the FirstName scalar property.

VB
<Global.System.Data.Objects.DataClasses.EdmScalarPropertyAttribute _
         (IsNullable:=false),_
         Global.System.Runtime.Serialization.DataMemberAttribute()>  _
Public Property FirstName() As String
  Get
    Return Me._FirstName
  End Get
  Set
    Me.OnFirstNameChanging(value)
    Me.ReportPropertyChanging("FirstName")
    Me._FirstName = Global.System.Data.Objects.DataClasses. _
                    StructuralObject.SetValidValue(value, false, 50)
    Me.ReportPropertyChanged("FirstName")
    Me.OnFirstNameChanged
  End Set
End Property

Private _FirstName As String

Partial Private Sub OnFirstNameChanging(ByVal value As String)
End Sub

Partial Private Sub OnFirstNameChanged()
End Sub

The code generator created two events for the FirstName property: OnFirstNameChanged and OnFirstNameChanging. These partial methods are defined in the class to enable you to add code to handle these events. You will learn how to extend the classes’ event handling and other code in Chapter 10.

Each entity class also has a single method whose name begins with the word Create. These are factory methods that allow you to create a new instance of that class. The arguments of the Create methods take values for each non-nullable scalar property in the class. For the Contact class, you may notice that the Title parameter is not being used by the CreateContact method shown in Example 9-10. That’s because Title is a nullable property.

VB
Public Shared Function CreateContact(ByVal contactID As Integer, _
 ByVal firstName As String, ByVal lastName As String, _
 ByVal addDate As Date, ByVal modifiedDate As Date) As Contact
  Dim contact As Contact = New Contact
  contact.ContactID = contactID
  contact.FirstName = firstName
  contact.LastName = lastName
  contact.AddDate = addDate
  contact.ModifiedDate = modifiedDate
  Return contact
End Function

C#
public static Contact CreateContact(int contactID,
 string firstName, string lastName, global::System.DateTime addDate,
 global::System.DateTime modifiedDate)
{
    Contact contact = new Contact();
    contact.ContactID = contactID;
    contact.FirstName = firstName;
    contact.LastName = lastName;
    contact.AddDate = addDate;
    contact.ModifiedDate = modifiedDate;
    return contact;
}

Once you have used this function to create a new contact, you can add additional properties in the code.

You won’t find much more when looking in the classes generated from the model. The entity class itself has no properties for keeping track of its state changes. It only maintains the current values of its properties.

The entity does, however, inherit from EntityObject, and therefore it exposes two additional properties that come from EntityObject: EntityKey and EntityState.

EntityKey is a critical class for keeping track of individual entities. It contains the entity’s identity value, which could be from a single property, such as ContactID, or could be a composite key that depends on a number of the entity’s properties. Figure 9-7 shows an EntityKey for a BreakAway Contact. It says that this entity belongs to the BAEntities container and to the Contacts EntitySet, and that its key property is composed of only one property, ContactID, whose value is 1.

The ObjectContext reads the EntityKey information to perform many of its functions. For example, when the context merges objects, locates entities in the cache, or creates EntityReference values. The type information is not included in the EntityKey. Instead, the EntitySetName indicates to which EntitySet the object with this key belongs.

This little class is one of the most important classes in the Entity Framework. It acts as an object’s passport throughout the application’s runtime.

Figure 9-7. An object’s EntityKey, which includes critical identity information for each object

By default, anytime the ObjectContext performs a query, if any of the returned objects already exist in the cache the newly returned copies of those objects are ignored. The EntityKeys are instrumental in enabling this to happen. The EntityKeys of the objects returned from a query are checked, and if an object with the same EntityKey (within the same EntitySet; e.g., Contacts) already exists in the cache, the existing object is left untouched. You can control this using an ObjectQuery property called MergeOption, which was introduced briefly earlier in this chapter. The four possibilities for MergeOption are as follows:

There are two ways to define MergeOptions. The first is to use the MergeOption method of ObjectQuery, as shown in the following code:

VB
Dim contacts = context.CreateQuery(Of Contact)(queryString)
contacts.MergeOption = MergeOption.PreserveChanges

C#
var contacts = context.CreateQuery<Contact>(queryString);
contacts.MergeOption = MergeOption.PreserveChanges;

The second way to define a MergeOption is as a parameter of ObjectQuery.Execute, as you saw earlier in this chapter.

Remember that you can cast a LINQ to Entities query to an ObjectQuery and use ObjectQuery methods, including MergeOption, as you did with ToTraceString earlier in this chapter.

The ObjectContext knows about the state of an object through change tracking. Every entity implements the IEntityWithChangeTracker interface. Recall that the PropertyChanging and PropertyChanged events in the model classes represent part of the change-tracking functionality. When an object’s property is changed, the IEntityWithChangeTracker interface reports this change to the designated ChangeTracker—that is, the current ObjectContext, which updates the appropriate value of that object’s ObjectStateEntry. For this to work, the Object inherits internal functions from IEntityWithChangeTracker.

This interface has a public member—the SetChangeTracker method—that allows you to identify which ObjectContext is responsible for the change tracking. These methods are used internally, and although they may seem tempting in some scenarios, you will almost always be better off not using them directly.

I have mentioned the topic of attaching and detaching objects a number of times in this chapter. Objects whose changes and relationships are being managed by the context are considered to be attached. EntityObject instances that are in memory but are not being managed by the context are considered to be detached, and even have their EntityState value set to Detached.

Attaching and detaching can happen implicitly thanks to the internal functionality of the Entity Framework, or explicitly by calling the methods in your code.

You have seen that an object that is attached to an ObjectContext has its state and its relationships managed by that context. You also know that an object that is detached has no state. And you have dealt with many objects in the coding samples that were automatically attached to the ObjectContext as the result of executing a query; you even added an object or two using the Add and Attach methods. Now you will look a little more closely at explicitly attaching and detaching objects.

VB
context.Attach(myObject)

C#
context.Attach(myObject);

VB
context.AttachTo("Contacts",myContact)

C#
context.AttachTo("Contacts",myContact);

VB
Dim typeEKey =  _
 New EntityKey("BAEntities.CustomerTypes", "CustomerTypeID", 1)
newcust.CustomerTypeReference.EntityKey = typeEKey

C#
var typeEKey =
 new EntityKey("BAEntities.CustomerTypes", "CustomerTypeID", 1);
newcust.CustomerTypeReference.EntityKey = typeEKey;

ApplyPropertyChanges is an extremely useful method of ObjectContext because it so handily solves the problem of using detached objects to perform updates. If you have an object in the context and a copy of that object that is detached, you can update the attached object with properties from the detached object. The method needs the name of the EntitySet to find the attached entity and the object that will be used to update the attached entity. The signature for ApplyPropertyChanges is as follows:

VB
ApplyPropertyChanges(entitySetName as String, changed as Object)

C#
ApplyPropertyChanges(string entitySetName, Object changed)

Here’s how it works. The context looks at the changed object passed into the second parameter. If that object does not have an EntityKey, the context can build one based on the metadata of the EntitySet defined in the first parameter. For example, the Contacts EntitySet is defined to return Contact entities, and the Contact property that is used for the EntityKey is ContactID. That’s enough information to construct the EntityKey if necessary. With the EntityKey in hand, the context looks for an attached entity in the Contacts EntitySet with a matching EntityKey. Once that is found, it compares the scalar values of the attached entity to the detached entity and updates any of the properties in the attached entity with new values from the incoming object. As those changes are made, the ObjectStateEntry and EntityState are impacted. When it comes time to call SaveChanges, the new values will be sent to the server.

ApplyPropertyChanges will update only scalar values. It does not touch navigation properties. You will see in later chapters how to use ApplyPropertyChanges in a graph.

You spent a good deal of time learning about the ObjectContext.SaveChanges method in action in Chapter 5. This is an important function of Object Services. Here we’ll take a look at a few more features of SaveChanges.

A little-known fact about the SaveChanges method is that it returns an integer representing the number of ObjectContext objects that were affected.

As you will learn in more detail later in this book, this number includes not only entity objects, but also relationship objects that the ObjectContext maintains. Therefore, if you create a new entity and then add that entity to the EntityCollection of another entity, a relationship object is created to represent the relationship between the two entities. Initially, that object has an EntityState of Added because it is a new object. If you move a child entity from one parent to the other, the relationship object that represented the first relationship is deleted and a new one is created to reflect the new end (the new parent).

After the SaveChanges call, all of the changes will be accepted in the ObjectContext and every object’s EntityState will become Unchanged. So, whether that object is an entity or a relationship it will be counted in the number returned by SaveChanges.

ObjectContext has one public event, SavingChanges, which occurs when SaveChanges is called. It is your only opportunity to validate or impact the entities before the commands are created.

The code you insert into SavingChanges will run before the API performs the actual SaveChanges method.

In this single location, you can perform validation on all of the entities that the ObjectContext is managing. This could be a little daunting, as you are more likely used to organizing validation information within individual classes. Unfortunately, with the Entity Framework, you’ll need to pile this business logic all into one place, or at least make all of the calls to perform validation in this one event.

You’ll learn how to implement SavingChanges in the next chapter.

Data concurrency is the bane of any data access developer trying to answer the question “What happens if more than one person is editing the same record at the same time?”

The more fortunate among us deal with business rules that say “no problem, last one in wins.” In this case, concurrency is not a problem.

More likely, it’s not as simple as that and there is no silver bullet to solve every scenario at once.

Be default, the Entity Framework will take the path of “last one in wins,” meaning that the latest update is applied even if someone else updated the data between the time the user retrieved the data and the time he saved it. You can customize the behavior using a combination of attributes in the EDM and methods from Object Services.

Chapter 18 will deal with this topic in depth, but here is a short overview of the functionality provided.

Object Services operations performed against the data store, such as queries or the SaveChanges method, are transactional by default. You can override the default behavior using System.Transaction.TransactionScope, EntityTransaction, or one of the other System.Data.Common.DbTransaction classes, such as SqlClient.SqlTransaction. EntityTransaction inherits from DbTransaction as well.

By default, the last step of SaveChanges is to accept all changes to the objects. This means that in the ObjectStateEntry, the original values are replaced with the current values and the object’s EntityState is set to Unchanged. This is especially important with respect to values that are generated on the server. This action will use those returned values as well.

However, when SaveChanges is inside your transaction, the changes don’t come back from the server until you call DbTransaction.Commit or TransactionScope.Complete. Because of this, you need to set AcceptChangesDuringSave, the SaveChanges argument, to False. Additionally, after the Commit or Complete is called, you will need to manually call ObjectContext.AcceptAllChanges.

You’ll find more information on transactions in Chapter 16.

Data is serialized in order for it to be transmitted across boundaries and processes, most commonly with remote or message-based services.

Entity classes generated from the EDM are extended with the Serializable and DataContractAttribute attributes, as shown in the following code:

<Global.System.Data.Objects.DataClasses.EdmEntityTypeAttribute _
    (NamespaceName:="BAEntities", Name:="Contact"),  _
 Global.System.Runtime.Serialization.DataContractAttribute(),  _
 Global.System.Serializable()>  _
Partial Public Class Contact
   Inherits Global.System.Data.Objects.DataClasses.EntityObject
. . .
End Class

System.Serializable enables the object to be binary-serialized or XML-serialized. Binary serialization is used implicitly in ASP.NET, though in some scenarios you may need to explicitly code the serialization to persist or stream data. XML serialization is most commonly used to send messages to and from web services. The DataContractAttribute enables serialization for exchanging data with Windows Communication Foundation (WCF) services.

In addition, EntityKeys are serialized along with the object. This means the object can be transmitted between applications and services, in some cases with very little effort on the part of the developer.

VB
<OperationContract()> _
  Function GetContact(ByVal contactID As Integer) As Contact

C#
[OperationContract()]
  Contact GetContact(int contactID );

VB
Using context As New BreakAwayEntities
  Dim contact = From c In Context.Contacts _
                Where c.ContactID = contactID
  Return contact.FirstOrDefault
End Using

C#
using (BreakAwayEntities context = new BreakAwayEntities())
{
  var cust = from c in context.Contacts.Include("Customer")
             where c.ContactID == contactID
             select c;
  return cust.FirstOrDefault();
}

Private Sub GetCustFromService()
  Dim proxy = New BreakAwayCommonService.BreakAwayCommonServiceClient
  Dim cust = proxy.GetCustomer(21)
  Console.WriteLine("{0} {1}", cust.FirstName.Trim, cust.LastName)
End Sub

EntityCollection and ObjectQuery both implement IListSource, which enables them to bind to data-bound controls. Because the objects implement INotifyPropertyChanges, you can use them in two-way binding, which means that updates made in the control can be sent back to the objects automatically.

In Chapter 8, you wrote a Windows Forms application that bound data to a BindingSource that in turn tied the data to various binding controls. You also performed data binding with WPF objects. In both applications, when updating the form’s controls those changes were automatically made in the objects. This occurred thanks to the IListSource.

ASP.NET data-bound and list controls also support data binding. Because of the nature of web pages, however, you’ll need to pay attention to postbacks and their impact on change tracking. You can bind directly to the DataSource properties of the controls, or use a client-side EntityDataSource control. Although LINQDataSource does support read-only use of LINQ to Entities queries, it is more closely focused on LINQ to SQL and doesn’t support everything in LINQ to Entities. Therefore, it’s best to use EntityDataSource instead.

In the next chapter, you will focus on using the ASP.NET EntityDataSource to build data-bound web pages. Some of the chapters appearing later in the book will demonstrate how to use business layers with Windows Forms and ASP.NET applications.

You can use your own classes in Object Services in two ways. The simplest way is to inherit from EntityObject, which tightly binds your class to the Entity Framework. This is how the default code-generated classes are defined. In scenarios where the EntityObject constrains your classes and architecture too much, you can directly implement IEntityChangeTracker, IEntityWithKey, and IEntityWithRelationships interfaces to take full advantage of Object Services.

The use of custom classes with these interfaces is referred to as IPOCO, which adds the term Interface to the Plain Old CLR Objects (POCO) acronym. POCO describes classes that are not bound to .NET classes. The Entity Framework does not fully support POCO, but with interfaces, it is more loosely coupled than when the classes inherit from EntityObject.