Chapter 16 Understanding Entities Through Objects After completing this chapter, you will be able to: Access the properties of an entity through a standard object instance Add, update, and delete database content by modifying object properties Carry out query-like actions using standard method calls One of the main advantages of the Entity Framework (EF) is that you can manage database content using standard .NET objects that reflect the conceptual nature of the data. Behind the scenes, various XML models, generated language code blocks, and provider interactions make this possible. But the complexity exists solely to fulfill the promise of providing simplic- ity in handling the main business logic of your application. Imagine being able to modify the Name property of a Customer object in code and have that change propagate to the database— all without having to write any of the code to make that happen. This chapter introduces Object Services, the part of the Entity Framework that makes that promise a reality. This Framework layer makes the transition from database to model to objects—or vice versa—possible. In a way, the Entity Framework is the Object Services layer because that layer is responsible for the core functionality of the Framework. Visual Studio makes working with the Framework easy because access to its functionality is enhanced by visual designers and Entity SQL scripts. This chapter focuses on the objects themselves; you’ll see how to add, modify, and remove them in a way that directly affects the external data store. Note The exercises in this chapter all use the same sample project, which is a tool that provides editing features for a table of customers. While you will be able to run the application after each exercise, the expected results for the full application might not appear until you complete all exercises in the chapter. Managing Entity Data Through Objects Object Services manages the entire lifetime of data through the Entity Framework, from determining how to translate the storage-layer model into the appropriate provider-level actions, to shuttling data through the model and into usable .NET objects. Earlier chapters 268 in this book introduced some of these modeling concepts. This time, the focus is on the last part: exposing data through objects. Accessing Entity Data Through Objects The object layer source code that Object Services generates from the Conceptual Schema Definition Language (CSDL)-based conceptual model consists of classes that derive from a set of generic base classes. Each conceptual model element has some object-level counterpart that appears as C# or Visual Basic source code in the ModelName.Designer.cs or ModelName. Designer.vb file. The following base classes play key support roles in implementing the con- ceptual model in code: System.Data.Objects.DataClasses.EntityObject This is the base class for all enti- ties. If your entity model includes a Customer entity, the generated code includes a Customer class that derives from this EntityObject class. Individual entity properties ap- pear as standard .NET properties within the derived class. System.Data.Objects.DataClasses.ComplexObject When an entity includes a complex type (such as the Address complex type crafted in the “Entity Data Model Designer” section on page 230 of Chapter 14, “Visualizing Data Models”), that type de- rives from the ComplexObject base class. System.Data.Objects.ObjectSet(Of TEntity) Entities—the table-style collection of individual entity instances—derive from this generic base class. ObjectSet implements the IEnumerable interface for a collection-like experience. System.Data.Objects.ObjectQuery(Of T) Although generated entity objects are not based on this class, it still plays a key role in Entity Framework data activities. Any time you query entity data—whether through an Entity SQL query, the LINQ tools discussed later in this book, or the query builder methods introduced in the second half of this chapter—the returned results exist as some form of ObjectQuery. It also serves as the base class for ObjectSet(Of TEntity). System.Data.Objects.ObjectContext This is the class-based embodiment of an en- tire conceptual model, also called the entity container. The generated entity container provides access to all entity and association instances within your application. You must create an instance of a derived ObjectContext to interact with Entity Framework data. Additional classes implement associations, association endpoints, and other class-based ex- pressions of conceptual model elements. The derived classes also draw on the storage and mapping layers to carry out the various data activities requested by your code. The following code, already introduced in an earlier chapter, shows some typical statements used to access external data through model-generated objects: Chapter 16 Understanding Entities Through Objects 269 C# // Always start by creating an object context. Create an instance of // either ObjectContext, or of the derived entity container class. using (SalesOrderEntities context = new SalesOrderEntities(GetConnectionString())) { // Option 1: Derived entity collections expose contained // entity sets directly. results = context.Customers; // Option 2: The CreateObjectSet method returns all entity // instances for the named entity type. results = context.CreateObjectSet<Customer>(); // Option 3: Run an Entity SQL query to retrieve some // or all entity instances. results = new ObjectQuery<Customer>(sqlText, context); // Option 4: Use query builder methods, shown later. // Option 5: Use LINQ, shown later. } Visual Basic ' Always start by creating an object context. Create an instance of ' either ObjectContext, or of the derived entity container class. Using context As New SalesOrderEntities(GetConnectionString()) ' Option 1: Derived entity collections expose contained ' entity sets directly. results = context.Customers ' Option 2: The CreateObjectSet method returns all entity ' instances for the named entity type. results = context.CreateObjectSet(Of Customer)() ' Option 3: Run an Entity SQL query to retrieve some ' or all entity instances. results = New ObjectQuery(Of Customer)(sqlText, context) ' Option 4: Use query builder methods, shown later. ' Option 5: Use LINQ, shown later. End Using 270 Microsoft ADO.NET 4 Step by Step Depending on how you configured your conceptual model, this code might not actually retrieve any data from the database because by default the Entity Framework defers data ac- cess until the data is needed. Therefore, in many cases, you must access individual entities or their properties to initiate a true database query. After you have a set of entity instances, you can scan through them as you do with any other collection. The entity properties of each instance method appear as standard .NET class properties, so you can access them from code just like any other strongly typed property. C# foreach (Customer oneCustomer in results) { SendInvoicesToCustomer(oneCustomer.ID, oneCustomer.FullName); } Visual Basic For Each oneCustomer As Customer In results SendInvoicesToCustomer(oneCustomer.ID, oneCustomer.FullName) Next oneCustomer Complex types use a multidotted property notation. C# VerifyPostalCode(oneCustomer.Address.PostalCode); Visual Basic VerifyPostalCode(oneCustomer.Address.PostalCode) This same syntax also works for content at the other end of a navigation property. C# // Assume that State is a navigation property. location = oneCustomer.Address.City + ", " + oneCustomer.Address.State.Abbreviation; Visual Basic ' Assume that State is a navigation property. location = oneCustomer.Address.City & ", " & oneCustomer.Address.State.Abbreviation Chapter 16 Understanding Entities Through Objects 271 Modifying Entity Data Through Objects Accessing data through properties is great, but if that is all the Entity Framework could do, it wouldn’t be a tremendous improvement over standard ADO.NET. Fortunately, the Entity Framework also supports data updates. Entities and properties you retrieve through the con- text are fully editable—assuming that the underlying database elements are editable. The entity container supports updates to existing entity properties, the addition of new en- tity instances, and the removal of existing entity instances. All changes propagate back to the database, and all take into account the constraints and business logic rules you impose on the conceptual layer, the storage layer, the mapping layer, and the external data store. Modifying existing properties is the easiest action to take. After retrieving an entity, you modify it by simply setting one of its properties to the new value. C# oneCustomer.AnnualFee += 50; Visual Basic oneCustomer.AnnualFee += 50 Just as with ADO.NET, you must take one additional step that is needed to accept all pend- ing changes. To accept changes in the Entity Framework, call the SaveChanges method of the active context object. This completes the update process and persists all changes to the underlying data source. C# context.SaveChanges(); Visual Basic context.SaveChanges() Adding new entities is a little more involved, but it parallels what you would normally do with a collection of objects in .NET. To add a new Customer entity to the model, and ultimately to the database table or tables that manage customer data, follow four simple steps: 1. Create a new instance of the Customer entity. 2. Fill in its properties. 3. Add the new entity instance to the context or the context’s exposed set of customers. 4. Call the context object’s SaveChanges method. 272 Microsoft ADO.NET 4 Step by Step Here’s an example that adds a new customer: C# using (SalesOrderEntities context = new SalesOrderEntities(connectionString)) { // Step 1: Create a new Customer instance. Customer oneCustomer = new Customer(); // Step 2: Fill in the properties. oneCustomer.FullName = "Fourth Coffee"; // and so on // Step 3: Add the Customer to the context. context.AddObject("Customers", oneCustomer); // or context.Customers.AddObject(oneCustomer); // Step 4: Confirm the change. context.SaveChanges(); } Visual Basic Using context As New SalesOrderEntities(connectionString) ' Step 1: Create a new Customer instance. Dim oneCustomer As New Customer ' Step 2: Fill in the properties. oneCustomer.FullName = "Fourth Coffee" ' and so on ' Step 3: Add the Customer to the context. context.AddObject("Customers", oneCustomer) ' or context.Customers.AddObject(oneCustomer) ' Step 4: Confirm the change. context.SaveChanges() End Using The ObjectContext.AddObject method accepts the name of the entity set (normally the plural name of the entity) and the new entity instance. Alternatively, you can call AddObject from the existing collection (as in context.Customers.AddObject), passing only the new entity in- stance as an argument. Chapter 16 Understanding Entities Through Objects 273 Note Each generated entity exposes two events for each core property: OnPropertyChanging and OnPropertyChanged, where the “Property” portion matches the associated property name. Use these events to add appropriate business logic to any entity modifications. Your code is responsible for supplying all required property values (those that don’t accept NULL values and that don’t have defaults). If neither the conceptual model nor the underlying database provides primary key values, your code must supply them as well. Note If you neglect to call SaveChanges, not only will the changes not be persisted to the data- base but you will also not receive any warning about the unsaved content. To remove an existing entity from the model, call the De leteObject method—the counterpart of AddObject—passing it the instance to be deleted. C# // Delete a Customer from the context. context.DeleteObject(oneCustomer); // or context.Customers.DeleteObject(oneCustomer); Visual Basic ' Delete a Customer from the context. context.DeleteObject(oneCustomer) ' or context.Customers.DeleteObject(oneCustomer) If an entity or one or more of its underlying database tables are configured to cascade de- letes, other related entities or data values can be removed in response to a DeleteObject call. Be sure to call SaveChanges after completing one or more entity adds, updates, or deletes. If saving your data modifications causes other data side effects (perhaps due to triggers at the database level), you can call the context object’s Refr esh method to force an eventual reload of any new or modified values. C# context.Refresh(RefreshMode.StoreWins); Visual Basic context.Refresh(RefreshMode.StoreWins) The Refresh method includes a RefreshMode parameter that tells the method how to deal with data conflicts between the data source and the local EF model’s content. Passing a 274 Microsoft ADO.NET 4 Step by Step value of RefreshMode.StoreWins will bring any modifications found in the data source into the local entity sets, overwriting any out-of-date information stored within the EF context. RefreshMode.ClientWins, the other available option, updates data in the data source to bring it in line with the model’s view of those associated data records. By default, the Entity Framework will build the appropriate INSERT, UPDATE, and DELETE statements needed by each entity as found in the storage layer, taking into account the data fields, the primary keys, and the relationships for each entity. You can override this behavior and supply your own table-specific modification functions in the mapping layer. These func- tions ultimately tie to stored procedures within the linked database. In the Entity Data Model Designer, use the Map Entity To Functions button on the Mapping Details panel to specify each stored procedure. The “Adding a Mapping Condition to an Entity” exercise on page 237 in Chapter 14 demonstrated this process. Modifying a Database Through Entity Objects: C# 1. Open the “Chapter 16 CSharp” project from the installed samples folder. The project includes Windows.Forms classes named CustomerEditor and CustomerDetail, which let a user modify records in the sample database’s Customer table. 2. Open the source code view for the CustomerEditor form. Locate the GetConnectionString function; this is a routine that uses a SqlConnectionStringBuilder to create a valid con- nection string to the sample database. It currently includes the following statements: sqlPortion.DataSource = @"(local)\SQLExpress"; sqlPortion.InitialCatalog = "StepSample"; sqlPortion.IntegratedSecurity = true; Adjust these statements as needed to provide access to your own test database. 3. Open the source code view for the CustomerDetail form. Locate the SaveFormData function. This routine updates an entity’s properties with data supplied by the user. Just after the “Update the individual fields” comment, add the following statements: toUpdate.FullName = CustomerName.Text.Trim(); if (Address1.Text.Trim().Length > 0) toUpdate.Address1 = Address1.Text.Trim(); else toUpdate.Address1 = null; if (Address2.Text.Trim().Length > 0) toUpdate.Address2 = Address2.Text.Trim(); else toUpdate.Address2 = null; Chapter 16 Understanding Entities Through Objects 275 if (CityName.Text.Trim().Length > 0) toUpdate.City = CityName.Text.Trim(); else toUpdate.City = null; if (ItemData.GetItemData(StateName.SelectedItem) != -1L) toUpdate.StateRegion = ItemData.GetItemData(StateName.SelectedItem); else toUpdate.StateRegion = null; if (PostalCode.Text.Trim().Length > 0) toUpdate.PostalCode = PostalCode.Text.Trim(); else toUpdate.PostalCode = null; if (PhoneNumber.Text.Trim().Length > 0) toUpdate.PhoneNumber = PhoneNumber.Text.Trim(); else toUpdate.PhoneNumber = null; if (WebSite.Text.Trim().Length > 0) toUpdate.WebSite = WebSite.Text.Trim(); else toUpdate.WebSite = null; toUpdate.AnnualFee = AnnualFee.Value; Most of the properties in the Customer entity are nullable, allowing even numeric prop- erties to be assigned a value of null. 4. Just after the “Update the database” comment, inside the try block, add the following statements: if (this.ActiveCustomer == null) { this.ActiveContext.Customers.AddObject(toUpdate); this.ActiveCustomer = toUpdate; } this.ActiveContext.SaveChanges(); return true; These lines perform the actual add or update of the Customer entity. The call to SaveChanges flushes all changes out to the database. 5. Run the program. When the list of customers appears, click Add or select a customer and click Edit. When the CustomerDetail form appears, add or update the individual field values. When you’re finished, click OK. If you added or modified a customer name, that change will be reflected in the list of customer names back on the CustomerEditor form. . context) ' Option 4: Use query builder methods, shown later. ' Option 5: Use LINQ, shown later. End Using 270 Microsoft ADO. NET 4 Step by Step Depending on how you configured your conceptual. method. 272 Microsoft ADO. NET 4 Step by Step Here’s an example that adds a new customer: C# using (SalesOrderEntities context = new SalesOrderEntities(connectionString)) { // Step 1: Create. “Property” portion matches the associated property name. Use these events to add appropriate business logic to any entity modifications. Your code is responsible for supplying all required property