When you use the WCF Data Services client library to consume an Open Data Protocol (OData) feed, the library translates the entries in the feed into instances of client data service classes. These data service classes are tracked by using the DataServiceContext to which the DataServiceQuery<TElement> belongs. The client tracks changes to entities that you report by using methods on DataServiceContext. These methods enable the client to track added and deleted entities and also changes that you make to property values or to relationships between entity instances. Those tracked changes are sent back to the data service as REST-based operations when you call the SaveChanges method.
When you use an instance of DataServiceCollection<T> to bind data to controls, changes made to data in the bound control are automatically reported to the DataServiceContext. For more information, see Binding Data to Controls.
Adding, Modifying, and Changing Entities
When you use the Add Service Reference dialog in Visual Studio to add a reference to an OData feed, the resulting client data service classes each have a static Create method that takes one parameter for each non-nullable entity property. You can use this method to create instances of entity type classes, as in the following example:
// Create the new product. Product newProduct = Product.CreateProduct(0, "White Tea - loose", false);
' Create the new product. Dim newProduct = _ Product.CreateProduct(0, "White Tea - loose", False)
To add an entity instance, call the appropriate AddTo method on the DataServiceContext class generated by the Add Service Reference dialog box, as in the following example:
// Add the new product to the Products entity set. context.AddToProducts(newProduct);
' Add the new product to the Products entity set. context.AddToProducts(newProduct)
This adds the object to the context and into the correct entity set. You can also call AddObject, but you must instead supply the entity set name. If the added entity has one or more relationships to other entities, you can either use the AddRelatedObject method or use one of the previous methods and also explicitly define those links. These operations are discussed later in this topic.
To modify an existing entity instance, first query for that entity, make the desired changes to its properties, and then call the UpdateObject method on the DataServiceContext to indicate to the client library that it needs to send an update for that object, as shown in the following example:
// Mark the customer as updated. context.UpdateObject(customerToChange);
' Mark the customer as updated. context.UpdateObject(customerToChange)
// Mark the product for deletion. context.DeleteObject(deletedProduct);
' Mark the product for deletion. context.DeleteObject(deletedProduct)
For more information, see How to: Add, Modify, and Delete Entities.
The client library enables you to save updates that you made to an entity without first executing a query to load the entity into the DataServiceContext. Use the AttachTo method to attach an existing object to a specific entity set in the DataServiceContext. You can then modify the object and save the changes to the data service. In the following example, a customer object that has been changed is attached to the context and then UpdateObject is called to mark the attached object as Modified before SaveChanges is called:
// Attach the existing customer to the context and mark it as updated. context.AttachTo("Customers", customer); context.UpdateObject(customer); // Send updates to the data service. context.SaveChanges();
' Attach the existing customer to the context and mark it as updated. context.AttachTo("Customers", customer) context.UpdateObject(customer) ' Send updates to the data service. context.SaveChanges()
The following considerations apply when attaching objects:
An object is attached in the Unchanged state.
When an object is attached, objects that are related to the attached object are not also attached.
An object cannot be attached if the entity is already being tracked by the context.
The AttachTo(String, Object, String) method overload that takes an
etagparameter is used when you attach an entity object that was received along with an eTag value. This eTag value is then used to check for concurrency when changes to the attached object are saved.
For more information, see How to: Attach an Existing Entity to the DataServiceContext.
Creating and Modifying Relationship Links
When you add a new entity by using either the AddObject method or the appropriate AddTo method of the DataServiceContext class that the Add Service Reference dialog generates, any relationships between the new entity and related entities are not automatically defined.
You can create and change relationships between entity instances and have the client library reflect those changes in the data service. Relationships between entities are defined as associations in the model, and the DataServiceContext tracks each relationship as a link object in the context. WCF Data Services provides the following methods on the DataServiceContext class to create, modify, and delete these links:
|AddRelatedObject||Creates a new link between two related entity objects. Calling this method is equivalent to calling AddObject and AddLink to both create the new object and define the relationship to an existing object.|
|AddLink||Creates a new link between two related entity objects.|
|SetLink||Updates an existing link between two related entity objects. SetLink is also used to delete links with a cardinality of zero-or-one-to-one (
|DeleteLink||Marks a link that the context is tracking for deletion when the SaveChanges method is called. Use this method when you delete a related object or change a relationship by first deleting the link to an existing object and then adding a link to the new related object.|
|AttachLink||Notifies the context of an existing link between two entity objects. The context assumes that this relationship already exists in the data service and does not try to create the link when you call the SaveChanges method. Use this method when you attach objects to a context and need to also attach the link between the two. If you are defining a new relationship, you should instead use AddLink.|
|DetachLink||Stops tracking the specified link in the context. This method is used to delete one-to-many (
The following example shows how to use the AddRelatedObject method to add a new
Order_Detail that is related to an existing
Orders entity. Because the new
Order_Details object is now tracked by the DataServiceContext, the relationship of the added
Order_Details object to the existing
Products entity is defined by calling the AddLink method:
// Add the new item with a link to the related order. context.AddRelatedObject(order, "Order_Details", newItem);
' Add the new item with a link to the related order. context.AddRelatedObject(order, "Order_Details", newItem)
While the AddLink method defines links that must be created in the data service, to have these links reflected in the objects that are in the context, you must also set the navigation properties on the objects themselves. In the previous example, you should set the navigation properties as follows:
// Add the new order detail to the collection, and // set the reference to the product. order.Order_Details.Add(newItem); newItem.Order = order; newItem.Product = selectedProduct;
' Add the new order detail to the collection, and ' set the reference to the product. order.Order_Details.Add(newItem) newItem.Order = order newItem.Product = selectedProduct
For more information, see How to: Define Entity Relationships.
Changes are tracked in the DataServiceContext instance but not sent to the server immediately. After you are finished with the required changes for a specified activity, call SaveChanges to submit all the changes to the data service. For more information, see Managing the Data Service Context. You can also save changes asynchronously by using the BeginSaveChanges and EndSaveChanges methods. For more information, see Asynchronous Operations.