Share via

Upgrading WCF Data Services Projects to WCF Data Services 5.0

  • Article

Now that WCF Data Services 5.0 has been shipped with support for OData v3, it’s time to start updating existing applications to take advantage of some of the new features of OData v3. For a complete list of new OData v3 features that are supported in WCF Data Services 5.0, see the post WCF Data Services 5.0 RTM Release.

Note: If you do not need any of the new OData v3 functionalities, you don’t really need to upgrade to WCF Data Services 5.0. If you do upgrade, you can still take advantage of the OData v2 behaviors in WCF Data Services 5.0. For more information, see the section OData Protocol Versions in Data Service Versioning (WCF Data Services).

Side-by-Side Installation

This release installs side-by-side with the previous versions of WCF Data Services that are in the .NET Framework. This is achieved by renaming the WCF Data Services assemblies from System.Data.Services.*.dll to Microsoft.Data.Services.*.dll, which makes it easier to target the version of WCF Data Services without having to use the multi-targeting in Visual Studio (trust me this is a good thing). This new out-of-band version of WCF Data Services is installed in the program files directory rather than with the reference assemblies. This means that you can find the new assemblies in the following installation path on an x64 computer:

 %programfiles(x86)%\Microsoft WCF Data Services\5.0\bin

As you would expect, the WCF Data Services client and server libraries are in the .NETFramework subdirectory and the Silverlight client assemblies are in the SL directory (plus, the Silverlight assemblies have SL appended to the file name).

Common Upgrade Tasks

There are two things that you need to do before you can upgrade a Visual Studio project to use WCF Data Services 5.0 libraries.

  1. Install the new 5.0 release, which you can get from the Download Center page WCF Data Services 5.0 for OData v3.
  2. Remove any existing references to existing assemblies the name of which start with System.Data.Services.

At this point, you can upgrade either data service or client projects.

Upgrading a Data Service Project

Use the following procedure to upgrade an existing WCF Data Services instance to 5.0 and use OData v3 support:   

  1. Remove references to System.Data.Services.dll and System.Data.Services.Client.dll.

  2. Add a new reference to Microsoft.Data.Services.dll and Microsoft.Data.Services.Client.dll assemblies (found in the installation location described above).   

  3. Change the Factory attribute in the .svc file markup to:

     Factory="System.Data.Services.DataServiceHostFactory, 
Microsoft.Data.Services, Version=5.0.0.0, 
Culture=neutral, PublicKeyToken=31bf3856ad364e35"

  4. Change the value of DataServiceBehavior.MaxProtocolVersion to DataServiceProtocolVersion.V3.

 

Upgrading an OData Client Project

Really, the only way that I have found to be able to correctly upgrade an existing client application to use the WCF Data Services 5.0 version of the client libraries is as follows:

  1. Remove the existing references to System.Data.Services.Client.dll.
  2. Delete the existing service references to OData services.
  3. Re-add the service reference using the Add Service Reference dialog in Visual Studio.

 

Heads-up for JSON-based Applications

OData v3 introduces a change in the Accept header values used to request a JSON response from the data service. This change doesn’t technically break OData v2 clients because it requires that the data service use the OData v3. However, you may start to get HTTP 415 responses after you upgrade the client or service to OData v3 and request that the data service use the OData v3 protocol with the old application/json value. For a good, detailed explanation of the nuances of this, see the post What happened to application/json in WCF DS 5.0?

As you may recall from my earlier post Getting JSON Out of WCF Data Services, you have to do some extra work enable the data service to handle the $format=json query option. Remember that when upgrading such a data service to support OData v3, you must also change the JSON Accept header value inserted by your code to application/json;odata=verbose.

 

Cheers!

Glenn Gailey

Comments

  • Anonymous
    May 16, 2012
    One thing i observed is that we need to add the references for Microsoft.Data.Edm and Microsoft.Data.OData also to the host project if you are packaging the dll's with the deployment and not installing the WCFDataServices 5.0 in the server hosting the services

  • Anonymous
    November 20, 2012
    Isn't it better to specify just Factory="System.Data.Services.DataServiceHostFactory, Microsoft.Data.Services" because right now NuGet installs Microsoft.Data.Services.dll ver. 5.1.0.51106