Working with Multiple Versions of ADO.NET Data Services

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.

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)

Defining a Data Service (ADO.NET Data Services)

Open Data Protocol (OData)