Share via


Using a Data Service in a Client Application (WCF Data Services)

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.

You can access a service that exposes an Open Data Protocol (OData) feed by supplying a URI to a Web browser. The URI provides the address of a resource, and request messages are sent to these addresses to access or change the underlying data that the resource represents. The browser issues an HTTP GET command and returns the requested resource as an OData feed. For more information, see Accessing the Service from a Web Browser.

Although a Web browser may be useful for testing that an OData service returns the expected data, production OData services that enable you to also create, update, and delete data are generally accessed by application code or scripting languages in a Web page. This topic provides an overview of how to access OData feeds from a client application.

Accessing and Changing Data Using REST Semantics

OData helps guarantee interoperability between services that expose OData feeds and applications that consume OData feeds. Applications access and change data in an OData-based service by sending request messages of a specific HTTP action and with a URI that addresses an entity resource against which the action should be performed. When entity data must be supplied, it is supplied as a specifically encoded payload in the body of the message.

HTTP Actions

OData supports the following HTTP actions to perform create, read, update, and delete operations on the entity data that the addressed resource represents:

  • HTTP GET - This is the default action when a resource is accessed from a browser. No payload is supplied in the request message, and a response method with a payload that contains the requested data is returned.

  • HTTP POST - Inserts new entity data into the supplied resource. Data to be inserted is supplied in the payload of the request message. The payload of the response message contains the data for the newly created entity. This includes any autogenerated key values. The header also contains the URI that addresses the new entity resource.

  • HTTP DELETE - Deletes the entity data that the specified resource represents. A payload is not present in the request or response messages.

  • HTTP PUT - Replaces existing entity data at the requested resource with new data that is supplied in the payload of the request message.

  • HTTP MERGE - Because of inefficiencies in executing a delete followed by an insert in the data source just to change entity data, OData introduces a new HTTP MERGE action. The payload of the request message contains the properties that must be changed on the addressed entity resource. Because HTTP MERGE is not defined in the HTTP specification, it may require additional processing to route a HTTP MERGE request through non-OData aware servers.

For more information, see OData: Operations.

Payload Formats

For an HTTP PUT, HTTP POST, or HTTP MERGE request, the payload of a request message contains the entity data that you send to the data service. The contents of the payload depend on the data format of the message. The HTTP responses to all actions except DELETE also contain such a payload. OData supports the following payload formats for accessing and changing data with the service:

  • Atom - An XML-based message encoding that is defined by OData as an extension to the Atom Publishing Protocol (AtomPub) to enable data exchange over HTTP for Web feeds, podcasts, wikis, and XML-based Internet functionality. For more information, see OData: Atom Format.

  • JSON - JavaScript Object Notation (JSON) is a lightweight data interchange format that is based on a subset of the JavaScript Programming Language. For more information, see OData: JSON Format.

The message format of the payload is requested in the header of the HTTP request message. For more information, see OData: Operations.

Accessing and Changing Data Using Client Libraries

WCF Data Services includes client libraries that enable you to more easily consume an OData feed from .NET Framework and Silverlight-based client applications. These libraries simplify sending and receiving HTTP messages. They also translate the message payload into CLR objects that represent entity data. The client libraries feature the two core classes DataServiceContext and DataServiceQuery<TElement>. These classes enable you to query a data service and then work with the returned entity data as CLR objects. For more information, see WCF Data Services Client Library and WCF Data Services (Silverlight).

You can use the Add Service Reference dialog in Visual Studio to add a reference to a data service. This tool requests the service metadata from a referenced data service and generates the DataServiceContext that represents a data service, as well as generates the client data service classes that represent entities. For more information, see Generating the Data Service Client Library.

There are programming libraries available that you can use to consume an OData feed in other kinds of client applications. For more information on OData SDK, see OData SDK - Sample Code.

See also