Updating the Data Service (WCF Data Services)

Article
05/23/2013

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.

Note

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 (WCF Data Services).

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.
Dim newProduct = _
    Product.CreateProduct(0, "White Tea - loose", False)

// Create the new product.
Product 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);

To delete an entity instance, call the DeleteObject method on the DataServiceContext, as shown in the following example:

' 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 (WCF Data Services).

Attaching 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 etag parameter 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 (WCF Data Services).

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:

Method	Description
AddRelatedObject	Creates a new link between two related entity objects. Calling this method is equivalent to calling AddObject(String, Object) and AddLink(Object, String, Object) 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(Object, String, Object) is also used to delete links with a cardinality of zero-or-one-to-one (0..1:1) and one-to-one (1:1). You can do this by setting the related object to null.
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 (:) relationships. For relationship links with a cardinality of one, you must instead use SetLink(Object, String, Object).

Note

Most data service providers, including the Entity Framework provider, treat relationships between entities in the data model as bi-directional. For example, the association between Customers and Orders entities represents both a relationship between a customer and one or more orders and also a relationship between an order and the customer to which it belongs. If the data service provider does not create both directions of a new relationship, you may need to also call the SetLink(Object, String, Object) method along with AddLink(Object, String, Object) to define both directions of the relationship.

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 (WCF Data Services).

Saving Changes

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 (WCF Data Services). You can also save changes asynchronously by using the BeginSaveChanges and EndSaveChanges methods. For more information, see Asynchronous Operations (WCF Data Services).

Share via

Updating the Data Service (WCF Data Services)

Adding, Modifying, and Changing Entities

Attaching Entities

Creating and Modifying Relationship Links

Saving Changes

See Also

Concepts

Other Resources

Additional resources