Updating the Data Service (WCF Data Services)

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 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.

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 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:

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).

See Also

Concepts

Querying the Data Service (WCF Data Services)
Asynchronous Operations (WCF Data Services)
Batching Operations (WCF Data Services)
Object Materialization (WCF Data Services)
Managing the Data Service Context (WCF Data Services)

Other Resources

WCF Data Services Client Library