Condividi tramite

Updating the Data Service (WCF Data Services)

  • Articolo

Important

WCF Data Services has been deprecated and will no longer be available for download from the Microsoft Download Center. WCF Data Services supported earlier versions of the Microsoft OData (V1-V3) protocol only and has not been under active development. OData V1-V3 has been superseded by OData V4, which is an industry standard published by OASIS and ratified by ISO. OData V4 is supported through the OData V4 compliant core libraries available at Microsoft.OData.Core. Support documentation is available at OData.Net, and the OData V4 service libraries are available at Microsoft.AspNetCore.OData.

RESTier is the successor to WCF Data Services. RESTier helps you bootstrap a standardized, queryable, HTTP-based REST interface in minutes. Like WCF Data Services before it, Restier provides simple and straightforward ways to shape queries and intercept submissions before and after they hit the database. And like Web API + OData, you still have the flexibility to add your own custom queries and actions with techniques you're already familiar with.

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.

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)

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.

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.

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

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.

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

See also