Working with Multiple Versions of ADO.NET Data Services
Note
This topic describes new functionality in ADO.NET Data Services that is available as an update to the .NET Framework version 3.5 Service Pack 1. You can download and install the update from the Microsoft Download Center.
ADO.NET Data Services enables a data source to be accessed remotely by using standard Internet protocols over HTTP. As new versions of ADO.NET Data Services are released, client applications may not be using the same version of ADO.NET Data Services that is providing the data service. An older client application may access a data service provided by a new ADO.NET Data Services runtime, or a client application may be using a newer version of the ADO.NET Data Services client library than the data service that is being accessed.
Note
The version of ADO.NET Data Services that is installed by the update to the .NET Framework version 3.5 Service Pack 1 is the same version that is included with the .NET Framework 4. In the .NET Framework 4, ADO.NET Data Services is also renamed to be WCF Data Services.
ADO.NET Data Services includes support to handle such versioning scenarios in the Open Data Protocol (OData). There is also support for generating and using data model metadata to create client data service classes when the client uses a different version of ADO.NET Data Services than the data service uses.
Protocol Versions
ADO.NET Data Services uses the DataServiceVersion HTTP header to explicitly declare the version of the OData protocol that is being used in an individual request or response message. When a client application makes a request to a data service, the DataServiceVersion header in the request reflects the version of ADO.NET Data Services that the application requires to operate correctly.
When the DataServiceVersion header is not included, the version of the request is assumed to be 1.0.Requests to and responses from the server should use the highest possible value for the DataServiceVersion header.
In addition, requests to the data service may also include the MaxDataServiceVersion HTTP header, which tells the data service the maximum version of the OData protocol supported by the requesting client application. The client application should always send a value for the MaxDataServiceVersion header that reflects the highest version of functionality that it can handle. This provides the data service with the most flexibility when generating a response.
The data service can be configured to define the highest version of the OData protocol that will be used by the service, regardless of the version requested by the client. You can do this by specifying a DataServiceProtocolVersion value for the MaxProtocolVersion() property of the DataServiceBehavior used by the data service. For more information, see Configuring the Data Service (ADO.NET Data Services).
When an application uses the ADO.NET Data Services client libraries to access a data service, the libraries automatically set these headers to the correct values, depending on the version of ADO.NET Data Services and the features that are used in your application.
Metadata Versions
ADO.NET Data Services uses the conceptual schema definition language (CSDL) to define the data model that is used to expose data for REST-based access by client applications. This data model is returned by a request to the $metadata endpoint, such as the URI https://localhost:12345/Northwind.svc/$metadata. For more information, see Special Resource Paths (ADO.NET Data Services). The returned data model is enclosed in an Edmx element in the response. For more information, see the specification [MC-EDMX]: Entity Data Model for Data Services Packaging Format.
By default, ADO.NET Data Services uses version 1.1 of CSDL to represent a data model. This is always the case for data models that are based on either a reflection provider or a custom data service provider. However, when the data model is defined by using the Entity Framework, the version of CSDL returned is the same as the version that is used by the Entity Framework. The version of the CSDL is determined by the namespace of the Schema element. For more information, see the specification [MC-CSDL]: Conceptual Schema Definition File Format.
The DataServices element of the returned metadata also contains a DataServiceVersion attribute, which is the same value as the DataServiceVersion header in the response message. Client applications, such as the Add Service Reference dialog box in Visual Studio, use this information to generate client data service classes that work correctly with the version of ADO.NET Data Services that host the data service.
See Also
Other Resources
Data Services Providers (ADO.NET Data Services)