What’s New in ASP.NET Web API 2.2 for OData v4.0

New features

1. Protocol and format changes from V3 to V4.

2. OData attribute routing: This release allows you to define the routes in your controllers and actions using attributes.

3. Support for functions: This release allows you to define functions in your OData model and bind them to actions in your controller that implement them.

4. Model aliasing: This release allows to change the names of the types and properties in your OData model to be different than the ones in your CLR types.

5. Support for limiting allowed queries: This feature release the service to define limitations on the properties of the model that can be filtered, sorted, expanded or navigated across.

6. Support for ETags: This release allows to generate an @odata.etag annotation based on some properties of the entity that can be used in IfMatch and IfNoneMatch headers in following requests.

7. Support for Enums: Improved our support for Enums and now we support them as OData enumerations.

8. Support for $format: Added support for $format, so clients are able to specify the desired format of the response in the URL.

Where to get it

It is now available at ASP.NET Web API 2.2 for OData v4.0 on MyGet. We recommend version v5.2.0-alpha1-140307 as a good place to start kicking the tires or go ahead and try the latest greatest. Please refer to the instructions on how to use nightly builds on our CodePlex site.

Sample codes

We have provided a comprehensive list of OData v4.0 service samples to accelerate your own v4.0 service implementation. They are available at https://aspnet.codeplex.com/SourceControl/latest#Samples/WebApi/OData/v4/

Tutorial Blog

http://blogs.msdn.com/b/webdev/archive/2014/03/13/getting-started-with-asp-net-web-api-2-2-for-odata-v4-0.aspx

T4 Template to Support V4 OData Spec

New Features

1. OData 4.0 Spec:  This release is able to generate C# and VB .NET client-side proxy classes to consume a OData V4 service.

2. Enum Support:  This release supports generating the codes of enum values and properties for OData Client library.

3. Singleton Support:  This release supports generating the codes of singleton values. You could now compose a LINQ query using singletons values.

Platform

We support the Professional, Premium, and Ultimate versions of Visual Studio 2010, 2012, 2013.

Where to get it

http://visualstudiogallery.msdn.microsoft.com/9b786c0e-79d1-4a50-89a5-125e57475937

Blog and Tutorial

http://blogs.msdn.com/b/odatateam/archive/2014/03/11/how-to-use-odata-client-code-generator-to-generate-client-side-proxy-class.aspx

Call to Action

If you has an existing OData service or is considering adding an OData service or migrating your V3 service to V4, now is an excellent time to engage with us.

In current WebApi impl you will be using an ODataMobuilder or ODataConventionModelBuilder to setup your model for oData feed. ODataConventionModelBuilder is the preferred way as it’d automatically map CLR classes to an EDM model based on a set of predefined Conventions.

For example you have class product and will be writing below code to setup your product model: 

public class Product
{
        public int ID { get; set; }

        public string Name { get; set; }

        public DateTime? ReleaseDate { get; set; }

        public DateTime? SupportedUntil { get; set; }

        public virtual ProductFamily Family { get; set; }
}
ODataConventionModelBuilder builder = new ODataConventionModelBuilder();
builder.EntitySet<Product>("Products");  

The problem with both current model builder that is that it requires a strong CLR type (Product in above code snippet) for each and every EDM type that the service is exposing. The mapping between the CLR type and the EDM type is one-to-one and not configurable.

To address that we introduced a set of new interfaces and classes that will be discussed below to support building entity object without backing CLR type. This is quite handy in the scenarios where the model is built in runtime. For example your data model will be matching a database schedule that is only discoverable when you load it, and all the payload is from the tables in that database.

Typeless Impl Internals

There are 4 key interfaces defined to enable the typeless feature. IEdmObject, IEdmStructuredObject, IEdmEntityObject and IEdmComplexObject. See below diagram for their inheritance relationship.

public interface IEdmObject
{
        IEdmTypeReference GetEdmType();
}
public interface IEdmStructuredObject : IEdmObject
{
        bool TryGetPropertyValue(string propertyName, out object value);
}

The classes EdmEntityObject, EdmComplexObject, EdmEntityCollectionObject, EdmComplexCollectionObject are created to impl above interfaces to model a typeless object system. 
public class EdmEntityObject : EdmStructuredObject, IEdmEntityObject
{… …}

public abstract class EdmStructuredObject : Delta, IEdmStructuredObject
{… …}

(Delta inheritance enables the EdmEntityObject the ability to track a set of changes for an entity object, you will be using that in a patch scenario)

Let’s take a look at the default implementation of the function TryGetPropertyValue/TrySetPropertyValue for EdmEntityObject and EdmStructuredObject

public override bool TryGetPropertyValue(string name, out object value)
{
    IEdmProperty property = _actualEdmType.FindProperty(name);
    if (property != null)
    {
        if (_container.ContainsKey(name))
        {
            value = _container[name];
            return true;
        }
        else
        {
            value = GetDefaultValue(property.Type);
            // store the default value (but don't update the list of 'set properties').
            _container[name] = value;
            return true;
        }
    }
    else
    {
        value = null;
        return false;
    }
}

 The code itself is pretty straightforward in that

1) It uses actualEdmType to record the type info for a property.

2) A Dictionary container is used to record the actual property value.

3) The class also provides many other helper functions, for example to locate a property by type and etc.

Lets create an example to learn how to setup and use a model without strong CLR type in ASP.NET Web API. To put the example as simple as possible. Let’s assume:

1) You already loaded the scheme from any sql connection and knew type info of the column properties.

2) There are only 2 associated tables in the DB. Product table and category table in a one to many relationship, which means a product can only have 0 to 1 category and a category can have multiple products in it.

 Create the Model

First we need to setup the EDM model for product and category and their associations.

        private static IEdmModel GetEdmModel()
        {
            EdmModel model = new EdmModel();

            // create & add entity type to the model.
            EdmEntityType product = new EdmEntityType("Org.Microsoft", "Product");
            product.AddStructuralProperty("Name", EdmPrimitiveTypeKind.String);
            product.AddStructuralProperty("Price", EdmPrimitiveTypeKind.Double);
            var key = product.AddStructuralProperty("ID", EdmPrimitiveTypeKind.Int32);
            product.AddKeys(key);
            model.AddElement(product);

            EdmEntityType category = new EdmEntityType("Org.Microsoft", "Category");
            category.AddStructuralProperty("Name", EdmPrimitiveTypeKind.String);
            var key1 = category.AddStructuralProperty("ID", EdmPrimitiveTypeKind.Int32);
            category.AddKeys(key1);
            model.AddElement(category);

            // setup navigations

            EdmNavigationPropertyInfo infoFrom = new EdmNavigationPropertyInfo();
            infoFrom.Name = "Product";
            infoFrom.TargetMultiplicity = EdmMultiplicity.Many;
            infoFrom.Target = product as IEdmEntityType;

            EdmNavigationPropertyInfo infoTo = new EdmNavigationPropertyInfo();
            infoFrom.Name = "Category";
            infoFrom.TargetMultiplicity = EdmMultiplicity.One;
            infoFrom.Target = category as IEdmEntityType;

            EdmNavigationProperty productCategory = product.AddBidirectionalNavigation(infoFrom, infoTo);

            // create & add entity container to the model.
            EdmEntityContainer container = new EdmEntityContainer("Org.Microsoft", "ProductsService");
            model.AddElement(container);
            model.SetIsDefaultEntityContainer(container, isDefaultContainer: true); // set this as the default container for smaller json light links.

            // create & add entity set 'Products'.
            EdmEntitySet Products = container.AddEntitySet("Products", product);
            EdmEntitySet Categories = container.AddEntitySet("Caegories", category);
            Products.AddNavigationTarget(productCategory, Categories);
            return model;
        }

Add a Simple Controller

Again for simplicity reason let’s build a controller that maps every request to a SimpleController.

public string SelectController(ODataPath odataPath, HttpRequestMessage request)
{
    Console.WriteLine(odataPath.PathTemplate);
    ODataPathSegment firstSegment = odataPath.Segments.FirstOrDefault();

    if (firstSegment != null && firstSegment is EntitySetPathSegment)
    {
        return "Simple";
    }

    return null;
}

Response Handler

Lets built 3 handlers to impl 3 scenarios

1) Get product by ID. By sending GET request http://localhost/odata/Products

public EdmEntityObjectCollection Get()
{
            ODataPath path = Request.GetODataPath();
            IEdmType edmType = path.EdmType;
            Contract.Assert(edmType.TypeKind == EdmTypeKind.Collection, "we are serving get {entityset}");

            IEdmEntityTypeReference entityType = (edmType as IEdmCollectionType).ElementType.AsEntity();

            var collectionProduct = new EdmEntityObjectCollection(new EdmCollectionTypeReference(edmType as IEdmCollectionType, isNullable: false));

            var entityProduct = new EdmEntityObject(entityType);
            entityProduct.TrySetPropertyValue("Name", "Microsoft Windows");
            entityProduct.TrySetPropertyValue("Price", 99.99);
            entityProduct.TrySetPropertyValue("ID", 12345);

            var entityCategory = new EdmEntityObject(entityType);
            entityCategory.TrySetPropertyValue("Name", "Category 1");
            entityCategory.TrySetPropertyValue("ID", 10000);

            entityProduct.TrySetPropertyValue("Category", entityCategory);
            collectionProduct.Add(entityProduct);
            return collectionProduct;
}

2) Get the category of given product by sending GET request http://localhost/odata/Products(12345)/Category

public IEdmEntityObject GetCategory(string key)
{
    ODataPath path = Request.GetODataPath();
    IEdmEntityType entityType = path.EdmType as IEdmEntityType;

    var entity = new EdmEntityObject(entityType);
    entity.TrySetPropertyValue("Name", "Category 1");
    entity.TrySetPropertyValue("ID", 10000);
    return entity;
}

The key to compose the payload is to create EdmEntityObject and populate the properties by using TrySetPropertyValue() interface.

3) Post a new product entity to the control by sending

On the client side we do:

 var request = new HttpRequestMessage(HttpMethod.Post, "http://localhost/odata/Products");

request.Content = new StringContent("{ 'Name': 'leo', Price : 1.99, ID: 12345}", Encoding.Default, "application/json");
PrintResponse(client.SendAsync(request).Result);

In the post handler we do to deserialize an IdmEntityObject

public HttpResponseMessage Post(IEdmEntityObject entity)
{
    ODataPath path = Request.GetODataPath();
    IEdmType edmType = path.EdmType;
    Contract.Assert(edmType.TypeKind == EdmTypeKind.Collection, "we are serving POST {entityset}");

    IEdmEntityTypeReference entityType = (edmType as IEdmCollectionType).ElementType.AsEntity();

    // do something with the entity object here.

    return Request.CreateResponse(HttpStatusCode.Created, entity);
 }

Summary

The new feature of the IEdmEntityObject that ships in oData version 5.0 adds support for creating an entity model object without strong CLR type backing. This provides better integration ability with your existing data model regardless your data type and source.

oData and JSON Format

The Open Data Protocol (OData) is a data access protocol built on core protocols like HTTP and commonly accepted methodologies like REST for the web. OData provides a uniform way to query and manipulate data sets through CRUD operations (create, read, update, and delete).

JSON is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. JSON is a text format that is completely language independent. JSON is built on a collection of name/value pairs realized in most modern languages.

OData’s JSON format extends JSON by defining a set of canonical annotations for control information such as ids, types, and links, and custom annotations MAY be used to add domain-specific information to the payload.

A key feature of OData’s JSON format is to allow omitting predictable parts of the wire format from the actual payload. Expressions are used to compute missing links, type information, and other control data on client side. Annotations are used in JSON to capture control information that cannot be predicted (e.g., the next link of a collection of entities) as well as a mechanism to provide values where a computed value would be wrong (e.g., if the media read link of one particular entity does not follow the standard URL conventions).

Computing values from metadata expressions on client side could be very expense. To accommodate for this the Accept header allows the client to control the amount of control information added to the response.

This doc is aiming to provide a quick overview of what’s the JSON payload would be look like in various typical scenarios.

We use the Northwind database as the SQL sample database in all our JSON examples. Northwind is a fictitious company that imports and exports foods globally. The Northwind sample database provides a good database structure for our JSON experiment.

Please see http://msdn.microsoft.com/en-us/library/ms227484(v=vs.80).aspx to get instructions of how to setup the database with your sqlserver

The following database diagram illustrates the Northwind database structure:

This section provides JSON samples of response payloads for the payload kinds supported in OData. The samples are based on a northwind domain.

Read an EntitySet

http://services.odata.org/V3/OData/OData.svc/Products?$format=json

{
   "odata.metadata":"http://services.odata.org/V3/OData/OData.svc/$metadata#Products",
   "value":[
      {
         "ID":0,
         "Name":"Bread",
         "Description":"Whole grain bread",
         "ReleaseDate":"1992-01-01T00:00:00",
         "DiscontinuedDate":null,
         "Rating":4,
         "Price":"2.5"
      },
      {
         "ID":1,
         "Name":"Milk",
         "Description":"Low fat milk",
         "ReleaseDate":"1995-10-01T00:00:00",
         "DiscontinuedDate":null,
         "Rating":3,
         "Price":"3.5"
      },
      {
         "ID":2,
         "Name":"Vint soda",
         "Description":"Americana Variety - Mix of 6 flavors",
         "ReleaseDate":"2000-10-01T00:00:00",
         "DiscontinuedDate":null,
         "Rating":3,
         "Price":"20.9"
      },
   …
   ]
}

Read an Entity

http://services.odata.org/V3/OData/OData.svc/Products(2)?$format=json

{
   "odata.metadata":"http://services.odata.org/V3/OData/OData.svc/$metadata#Products/@Element",
   "ID":2,
   "Name":"Vint soda",
   "Description":"Americana Variety - Mix of 6 flavors",
   "ReleaseDate":"2000-10-01T00:00:00",
   "DiscontinuedDate":null,
   "Rating":3,
   "Price":"20.9"
}

Read Property

http://services.odata.org/V3/OData/OData.svc/Products(2)/Description?$format=json

{
   "odata.metadata":"http://services.odata.org/V3/OData/OData.svc/$metadata#Edm.String",
   "value":"Americana Variety - Mix of 6 flavors"
}

http://odataservices.azurewebsites.net/OData/OData.svc/Products(0)/Name?$format=application/json

{
   "odata.metadata":"http://odataservices.azurewebsites.net/OData/OData.svc/$metadata#Edm.String",
   "value":"Bread"
}

Remove an Entity

DELETE http://services.odata.org/V3/(S(ettihtez1pypsghekhjamb1u))/OData/OData.svc/Products(200) HTTP/1.1

DataServiceVersion: 1.0;NetFx

MaxDataServiceVersion: 3.0;NetFx

Accept: application/json;odata=minimalmetadata

Accept-Charset: UTF-8

User-Agent: Microsoft ADO.NET Data Services

Host: services.odata.org

Create an Entry

POST http://services.odata.org/v3/(S(ettihtez1pypsghekhjamb1u))/odata/odata.svc/Products HTTP/1.1

DataServiceVersion: 3.0;NetFx

MaxDataServiceVersion: 3.0;NetFx

Content-Type: application/json;odata=minimalmetadata

Accept: application/json;odata=minimalmetadata

Accept-Charset: UTF-8

User-Agent: Microsoft ADO.NET Data Services

Host: services.odata.org

Content-Length: 180

Expect: 100-continue

Update an Entry with PATCH and PUT

PATCH

Services SHOULD support PATCH as the preferred means of updating an entity. PATCH provides more resiliency between clients and services by directly modifying only those values specified by the client.

PATCH http://services.odata.org/V3/(S(ettihtez1pypsghekhjamb1u))/OData/OData.svc/Products(200) HTTP/1.1

DataServiceVersion: 3.0;NetFx

MaxDataServiceVersion: 3.0;NetFx

Content-Type: application/json;odata=minimalmetadata

Accept: application/json;odata=minimalmetadata

Accept-Charset: UTF-8

User-Agent: Microsoft ADO.NET Data Services

Host: services.odata.org

Content-Length: 180

Expect: 100-continue

PUT

Services MAY additionally support PUT, but should be aware of the potential for data-loss in round-tripping properties that the client may not know about in advance, such as open or added properties, or properties not specified in metadata. Services that support PUT MUST replace all values of structural properties with those specified in the request body

PUT http://services.odata.org/V3/(S(ettihtez1pypsghekhjamb1u))/OData/OData.svc/Products(200) HTTP/1.1

DataServiceVersion: 3.0;NetFx

MaxDataServiceVersion: 3.0;NetFx

Content-Type: application/json;odata=minimalmetadata

Accept: application/json;odata=minimalmetadata

Accept-Charset: UTF-8

User-Agent: Microsoft ADO.NET Data Services

Host: services.odata.org

Content-Length: 180

Expect: 100-continue

Read Complex Type

http://services.odata.org/V3/OData/OData.svc/Suppliers(1)/Address?$format=json

{
   "odata.metadata":"http://services.odata.org/V3/OData/OData.svc/$metadata#ODataDemo.Address",
   "Street":"NE 40th",
   "City":"Redmond",
   "State":"WA",
   "ZipCode":"98052",
   "Country":"USA"
}

Read Entry with expanded navigation links

http://odataservices.azurewebsites.net/OData/OData.svc/Products(0)/Category?$expand=ID&$format=json

{
   "odata.metadata":"http://odataservices.azurewebsites.net/OData/OData.svc/$metadata#Categories/@Element",
   "ID":0,
   "Name":"Food"
}

Read Service document

http://odataservices.azurewebsites.net/OData/OData.svc/?$format=json

{
   "odata.metadata":"http://odataservices.azurewebsites.net/OData/OData.svc/$metadata",
   "value":[
      {
         "name":"Products",
         "url":"Products"
      },
      {
         "name":"Advertisements",
         "url":"Advertisements"
      },
      {
         "name":"Categories",
         "url":"Categories"
      },
      {
         "name":"Suppliers",
         "url":"Suppliers"
      }
   ]

Read an EntitySet with full metadata

http://services.odata.org/V3/OData/OData.svc/Products?$format=application/json;odata=fullmetadata

{
   "odata.metadata":"http://services.odata.org/V3/OData/OData.svc/$metadata#Products",
   "value":[
      {
         "odata.type":"ODataDemo.Product",
         "odata.id":"http://services.odata.org/V3/OData/OData.svc/Products(0)",
         "odata.editLink":"Products(0)",
         "Category@odata.navigationLinkUrl":"Products(0)/Category",
         "Category@odata.associationLinkUrl":"Products(0)/$links/Category",
         "Supplier@odata.navigationLinkUrl":"Products(0)/Supplier",
         "Supplier@odata.associationLinkUrl":"Products(0)/$links/Supplier",
         "ID":0,
         "Name":"Bread",
         "Description":"Whole grain bread",
         "ReleaseDate@odata.type":"Edm.DateTime",
         "ReleaseDate":"1992-01-01T00:00:00",
         "DiscontinuedDate":null,
         "Rating":4,
         "Price@odata.type":"Edm.Decimal",
         "Price":"2.5"
      },
      {
         "odata.type":"ODataDemo.Product",
         "odata.id":"http://services.odata.org/V3/OData/OData.svc/Products(1)",
         "odata.editLink":"Products(1)",
         "Category@odata.navigationLinkUrl":"Products(1)/Category",
         "Category@odata.associationLinkUrl":"Products(1)/$links/Category",
         "Supplier@odata.navigationLinkUrl":"Products(1)/Supplier",
         "Supplier@odata.associationLinkUrl":"Products(1)/$links/Supplier",
         "ID":1,
         "Name":"Milk",
         "Description":"Low fat milk",
         "ReleaseDate@odata.type":"Edm.DateTime",
         "ReleaseDate":"1995-10-01T00:00:00",
         "DiscontinuedDate":null,
         "Rating":3,
         "Price@odata.type":"Edm.Decimal",
         "Price":"3.5"
      },
      ]
}

Read an Entity with full metadata

http://services.odata.org/V3/OData/OData.svc/Products(2)?$format=application/json;odata=fullmetadata

{
   "odata.metadata":"http://services.odata.org/V3/OData/OData.svc/$metadata#Products/@Element",
   "odata.type":"ODataDemo.Product",
   "odata.id":"http://services.odata.org/V3/OData/OData.svc/Products(2)",
   "odata.editLink":"Products(2)",
   "Category@odata.navigationLinkUrl":"Products(2)/Category",
   "Category@odata.associationLinkUrl":"Products(2)/$links/Category",
   "Supplier@odata.navigationLinkUrl":"Products(2)/Supplier",
   "Supplier@odata.associationLinkUrl":"Products(2)/$links/Supplier",
   "ID":2,
   "Name":"Vint soda",
   "Description":"Americana Variety - Mix of 6 flavors",
   "ReleaseDate@odata.type":"Edm.DateTime",
   "ReleaseDate":"2000-10-01T00:00:00",
   "DiscontinuedDate":null,
   "Rating":3,
   "Price@odata.type":"Edm.Decimal",
   "Price":"20.9"
}

Read Entry with expanded navigation links with full metadata

http://odataservices.azurewebsites.net/OData/OData.svc/Products(0)/Category?$expand=ID&$format=application/json;odata=fullmetadata

{
   "odata.metadata":"http://odataservices.azurewebsites.net/OData/OData.svc/$metadata#Categories/@Element",
   "odata.type":"ODataDemo.Category",
   "odata.id":"http://odataservices.azurewebsites.net/OData/OData.svc/Categories(0)",
   "odata.editLink":"Categories(0)",
   "Products@odata.navigationLinkUrl":"Categories(0)/Products",
   "Products@odata.associationLinkUrl":"Categories(0)/$links/Products",
   "ID":0,
   "Name":"Food"
}