{"id":2740,"date":"2015-01-05T18:06:00","date_gmt":"2015-01-05T18:06:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/odatateam\/2015\/01\/05\/tutorial-sample-odatalib-custom-payload-format\/"},"modified":"2024-02-16T15:06:04","modified_gmt":"2024-02-16T22:06:04","slug":"tutorial-sample-odatalib-custom-payload-format","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/tutorial-sample-odatalib-custom-payload-format\/","title":{"rendered":"[Tutorial & Sample] ODataLib Custom Payload Format"},"content":{"rendered":"

This post is to guide you through the custom payload format support in ODataLib, which was introduced in ODataLib 6.9.0 release.<\/span><\/span><\/p>\n

All the sample codes in this post have been put to ODataSamples project<\/a>, you can check it out under ScenariosCustomFormat folder.<\/span><\/span><\/p>\n

Background<\/span><\/span><\/h2>\n

The OData specification defined several payload formats for data exchange. ODataLib has got built-in support for the JSON format(see OData JSON Format spec<\/a>). But there are cases when someone tries to build up a RESTful service following OData conventions, and also wants to use a custom payload format other than JSON. For example, assuming we have an existing service that uses a custom data format understood by existing clients.\u00a0 If we change the service to OData, we may prefer to keep the current data format, so that while taking advantage of OData features, existing clients could still consume the data returned by the service, or generate request that the service could read.<\/span><\/span><\/p>\n

The OData library was designed to support various payload formats, however, some of those read\/write APIs were not publicly visible. In 6.9.0 release, we changed some of those APIs to be public, so that users are able to write out payloads with custom format.<\/span><\/span><\/p>\n

In the following section, we\u2019ll first start by looking at the overall architecture of ODataLib\u2019s reader\/writer component and the media type resolving process. Then I will give a demo on how to write a custom payload extension for CSV (comma separated value) format.<\/span><\/span><\/p>\n

Reader\/Writer Overview<\/span><\/span><\/h2>\n

Here is a figure to describe the main classes used by ODataLib\u2019s reader and writer component. <\/span><\/span><\/p>\n

\"\"<\/a><\/p>\n

[click to enlarge]<\/p>\n

As you can see, the ODataLib\u2019s reader and writer share similar structure. The main entry point classes are ODataMessageReader and ODataMessageWriter. They both take a message and a setting class as input. Then when user calls some read\/write APIs, ODataMessageReader\/ODataMessageWriter would internally figure out the proper payload format to use, then perform corresponding input\/output actions using that format.<\/span><\/span><\/p>\n

Let\u2019s take a look at what happens when user tries to write an entry in response payload:<\/span><\/span><\/p>\n

    \n
  1. User prepares an OData response message, sets the header information, and then creates an ODataMessageWriter;<\/span><\/span><\/li>\n
  2. User calls CreateODataEntryWriter method on ODataMessageWriter, and gets a format specific ODataWriter;<\/span><\/span><\/li>\n
  3. User calls writing actions on the ODataWriter, such as StartEntry, EndEntry, etc.<\/span><\/span><\/li>\n<\/ol>\n

    In step 2, when creating the format specific ODataWriter, ODataMessageWriter would at first figure out what the payload format to use, we call this media type resolving. After that, an ODataFormat instance is present. Later on the ODataMessageWriter calls the CreateOutputContext method on ODataFormat to get the format specific output context, then calls the corresponding method on the context (CreateEntryWriter in this case).<\/span><\/span><\/p>\n

    Media Type Resolving<\/span><\/span><\/h2>\n

    For media type resolving, the input is the content-type header from ODataMessage, or instructions from settings (for writing only), and the output is an ODataFormat class. The ODataFormat represents the actual payload format, and it is the key point for decoupling various formats with reader\/writer APIs. Besides, we have ODataMediaType class which represents a certain kind of media type. Also, we have got ODataMediaTypeFormat that gets one ODataFormat bound to an ODataMediaType. At last, we provide MediaTypeResolver class responsible for choosing correct media types.<\/span><\/span><\/p>\n

    MediaTypeResolver class contains following method:<\/span><\/span><\/p>\n

    public virtual IEnumerable<ODataMediaTypeFormat> GetMediaTypeFormats(ODataPayloadKind payloadKind)<\/strong><\/p>\n

    This API should give out which media types are available for given payload kind. Internally, ODataLib\u2019s reader and writer would first call this method for certain payload kind to get a list of supported ODataMediaTypeFormat, then it would choose the best match based on media type information from request message.<\/span><\/span><\/p>\n

    In general, the default implementation of MediaTypeResolver would return JSON format for data request, and XML format for metadata request. Derived classes could choose to override this method to have their own behavior. Thus users could provide a custom media payload format by overriding it and returning the expected ODataMeidaFormat. We\u2019ll demo how to write a custom MediaTypeResolver in following section.<\/span><\/span><\/p>\n

    Implementing a CSV Format extension<\/span><\/span><\/h2>\n

    Here we\u2019ll have a demo on how to implement an extension that supports writing out CSV format payload. Our goal is to support writing an ODataEntry as a CSV format, every property appear to be in a single column. Please make sure your project have installed\u00a0Microsoft.OData.Core 6.9.0<\/a> package from NuGet gallery before getting started.<\/span><\/span><\/p>\n

    At first, we will implement the class CsvWriter and CsvOutputContext.<\/span><\/span><\/p>\n