Migrating OData V3 Services to OData V4 without Disrupting Existing Clients

Feng Xie

The migration from your existing OData V3 services to V4 can be challenging if there are some clients that cannot be easily upgraded, like the ones running on on-premises resources. The OData V3 services will need to be kept running until the old clients have been phased out, incurring maintenance overhead. OData team recently released an extension to overcome the challenge. This extension eases the transitioning by enabling OData V4 services to serve OData V3 requests. The advantage is that no changes are needed on the OData V3 clients while the OData V3 services are migrated to OData V4.

In this article, I am going to show you how to use the Migration extension.


It is assumed that you have migrated your OData V3 service to OData V4 and:

  • The service is built on ASP.NET Core 2.1+
  • The models remain unchanged including naming and name space
  • The requests and responses use JSON format

If a request is sent from the OData V3 client to the V4 service, the response will most likely be a 404 NotFound error because the service does not know how to route the request to the controller.

Adding Package Reference

Add a reference to the latest Microsoft.OData.Extensions.Migration package.

Image Migration reference

Configuring OData Migration Services

Add the OData Migration extension to services. It needs to be added after OData.

public static void ConfigureServices(IServiceCollection services)
    // your code here

    // AddOData must be called before AddODataMigration

    // your code here

Using OData Migration Middleware

Call UseODataMigration to enable the extension in the pipeline. It needs both the OData V3 and V4 models. The OData V3 model can be represented by either a Data.Edm.IEdmModel object or an EDMX string. The service will return the OData V3 formatted EDMX for the metadata calls.

Below is the sample code of calling UseODataMigration with an OData V3 EDMX string.

public static void Configure(IApplicationBuilder builder)
    // your code here

    // If using batching, you must call UseODataBatching before UseODataMigration

    string v3Edmx = /*your EDMX string*/
    builder.UseODataMigration(v3Edmx, v4model);

    // your code here


Now if you make a metadata call to the service:


The response should be the EDMX text for the OData V3 model:

<?xml version="1.0" encoding="iso-8859-1"?>
<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2009/11/edmx" Version="3.0">
  <edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:MaxDataServiceVersion="3.0" m:DataServiceVersion="3.0">
    <Schema xmlns="http://schemas.microsoft.com/ado/2009/11/edm" Namespace="Your.Namespace">
      <EntityContainer m:IsDefaultEntityContainer="true" Name="CommonContainer">
        <!-- Your entities here -->

The OData V4 service can respond to both OData V3 and V4 clients now.

URI Migration

Under the hood, the OData V3 URI is translated to the OData V4 format.

For example, a GUID value has different representation in OData V3 and V4. The following OData V3 URI:


will be translated into:


Request/Response Payload Migration

The extension is also able to deserialize an OData V3 request body and serialize the response body to the OData V3 format.

For example, a long value is serialized differently in OData V3 and V4. The client will send and receive a payload like

  "MyString": “John”
  "MyLong": "1000000000"

while the OData V4 service sees below internally:

  "MyString": "John",
  "MyLong": 1000000000

Once the OData V3 clients have been phased out simply remove the reference and the two lines of code for OData Migration.

Final Notes

More information on the OData Migration extension including architecture and limitations can be found here. The source code of the extension is published on GitHub.

If you have any questions, comments, concerns or if you are running into any issues using this extension feel free to reach out on this blog post or by email. We are more than happy to listen to your feedback and communicate your concerns.


Discussion is closed.

Feedback usabilla icon