{"id":5189,"date":"2023-03-09T15:49:39","date_gmt":"2023-03-09T22:49:39","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/odata\/?p=5189"},"modified":"2024-10-01T12:06:18","modified_gmt":"2024-10-01T19:06:18","slug":"customize-odata-payload-serialization-format-within-asp-net-core-odata","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/customize-odata-payload-serialization-format-within-asp-net-core-odata\/","title":{"rendered":"Customize OData payload serialization format within ASP.NET Core OData"},"content":{"rendered":"

Introduction<\/h2>\n

JSON (aka, JavaScript Object Notation), a standard text-based format for representing structured data based on JavaScript object syntax, is the default representation\u00a0for the OData requests and responses payload, see OData JSON format here<\/a>. It\u2019s a very popular format and widely used in most scenarios. However, there are customers who want to build services following OData conventions and want to get OData payload using formats other than JSON, such as CSV (aka, Comma Separated Value) format, or YAML (aka, YAML Ain’t Markup Language) format, etc.<\/p>\n

OData .NET libraries are designed to empower customers to customize\/extend other payload formats besides JSON. There\u2019s a post here<\/a> mentioning a way to customize CSV format using an old version of OData APIs. In this post, I\u2019d like to guide you through the steps about how to customize\/extend OData payload serialization formats with ASP.NET Core OData 8.x version. I mainly use CSV to introduce the detail customization process, but you can follow the same pattern to implement any other payload format in your OData service, for example, YAML.<\/p>\n

Let\u2019s get started by overviewing the OData payload serialization\/writing process within ASP.NET Core OData.<\/p>\n

OData Payload Serialization Overview<\/h2>\n

Below is a simple picture describing the components used to serialize OData payload within ASP.NET Core OData 8.<\/p>\n

\"Diagram<\/p>\n

Where ODataOutputFormatter<\/strong> is the formatter to serialize the OData payload into the response body. It creates ODataMessageWriter<\/strong> using the ODataMessageWriterSettings<\/strong> from the service container and a response message. ODataMessageWriter<\/strong> would internally delegate ODataMediaTypeResolver <\/strong>from the service container also to figure out the proper payload format (aka, ODataFormat<\/strong>), which in turn creates the corresponding output context (aka, ODataOutputContext<\/strong>), finally, the output context creates the ODataWriter<\/strong> to perform output writing. The serializers, such as ODataResourceSerializer<\/strong>, use the ODataWriter<\/strong> to write the resources, properties, nested properties, etc.<\/p>\n

ODataMediaTypeResolver<\/strong>, ODataFormat<\/strong>, ODataOutputContext,<\/strong> and ODataWriter<\/strong> are key components that we should implement by ourselves to customize the payload format. I will use a sample application in the following sections to share a demo about how to customize them to get the CSV format payload.<\/p>\n

Prerequisites<\/h2>\n

Let\u2019s start to create an ASP.NET Core Web API application named \u2018ODataCustomizePayloadFormat\u2019<\/em><\/strong> with\u00a0Microsoft.AspNetCore.OData<\/a>\u00a0(version-8.0.12) installed. You can follow up on my previous posts to build the project.<\/p>\n

Within this application, I have two types of entities:<\/p>\n

    \n
  1. Book<\/strong>: only contains primitive type properties<\/li>\n
  2. Customer<\/strong>: contains properties of primitive, enum, complex type and collection of them<\/li>\n<\/ol>\n

    I have the corresponding controllers for both entity types and keep them as simple as possible, for example:<\/p>\n

    public class BooksController : ControllerBase\r\n{\r\n    private static IList<Book> _books = GetBooks();\r\n\r\n    [HttpGet]\r\n    [EnableQuery]\r\n    public IActionResult Get()\r\n    {\r\n        return Ok(_books);\r\n    }\r\n\r\n    [HttpGet]\r\n    [EnableQuery]\r\n    public Book Get(int key)\r\n    {\r\n        Book b = _books.FirstOrDefault(c => c.Id == key);\r\n        return b;\r\n    }\r\n\r\n    \/\/ ......\r\n}\r\n<\/pre>\n
    I’m omitting other codes (such as Edm model builder, etc) from the post. Please refer to the sample here<\/a> for details.<\/p>\n
    Implement CSV Format<\/h2>\n
    In order to support the CSV format, we need to create the following four classes derived from the classes listed in the above overview section, respectively.<\/p>\n
      \n
    1. public class CsvMediaTypeResolver : ODataMediaTypeResolver<\/code>This class is used to build a mapping between the media type and an OData format. For example, it builds a mapping between text\/csv<\/strong> media type and CsvFormat<\/strong>.<\/li>\n
    2. public class CsvFormat : ODataFormat<\/code>This class is used to create the output context for writing and the input context for reading. In this post, I only cover the writing context.<\/li>\n
    3. public class CsvOutputContext : ODataOutputContext<\/code>This class is used to create the CsvWriter, it acts as a bridge between ODataMessageWriter<\/strong> and the specific OData writer.<\/li>\n
    4. public class CsvWriter : ODataWriter<\/code>This class is used to perform the ‘real’ writing process.<\/li>\n<\/ol>\n
      Let\u2019s implement them one by one in detail.<\/p>\n
      CsvMediaTypeResolver<\/h2>\n
      OData media type resolving is designed to get an ODataFormat<\/strong> based on the request metadata, such as Content-Type header, Accept header, etc. The resolving process depends on an ODataMediaTypeResolver<\/strong> which is registered as a service in the dependency injection service container. OData reader and writer would first call the GetMediaTypeFormats<\/em> method as below from this service to get a list of supported ODataMediaTypeFormat<\/strong> based on the given ODataPayloadKind<\/strong>, then resolve media type information from request message to get the best matched ODataFormat<\/strong>.<\/p>\n
      public class ODataMediaTypeResolver\r\n{\r\n    public virtual IEnumerable<ODataMediaTypeFormat> GetMediaTypeFormats(ODataPayloadKind payloadKind)\r\n    { ......}\r\n}\r\n<\/pre>\n
      The default implementation of ODataMediaTypeResolver<\/strong> would return JSON format for data requests and XML format for metadata requests. To make media type resolver understand text\/csv<\/strong> media type and return the corresponding CsvFormat<\/strong>, we can derive from ODataMediaTypeResolver<\/strong> and override GetMediaTypeFormats<\/em> to inject our own behavior. Here\u2019s the sample implementation:<\/p>\n
      public class CsvMediaTypeResolver : ODataMediaTypeResolver\r\n{\r\n    private readonly ODataMediaTypeFormat[] _mediaTypeFormats =\r\n    {\r\n        new ODataMediaTypeFormat(new ODataMediaType(\"text\", \"csv\"), new CsvFormat()),\r\n    };\r\n\r\n    public override IEnumerable<ODataMediaTypeFormat> GetMediaTypeFormats(ODataPayloadKind payloadKind)\r\n    {\r\n        if (payloadKind == ODataPayloadKind.Resource || payloadKind == ODataPayloadKind.ResourceSet)\r\n        {\r\n            return _mediaTypeFormats.Concat(base.GetMediaTypeFormats(payloadKind));\r\n        }\r\n\r\n        return base.GetMediaTypeFormats(payloadKind);\r\n    }\r\n}\r\n<\/pre>\n
      Where, I have a private field to hold a mapping between media type text\/csv<\/strong> and an instance of CsvFormat<\/strong>, which is inserted into the list of ODataMediaTypeFormat<\/strong> in the overridden method GetMediaTypeFormats<\/em>.<\/p>\n
      We should register the new media type resolver into the service container. I will share it in the following section.<\/p>\n
      CsvFormat<\/h2>\n
      As mentioned above, we need an ODataFormat<\/strong> in the CsvMeiaTypeResolver<\/strong> to create the output context for writing and the input context for reading. ODataFormat<\/strong> is defined as an abstract class as below, so we should implement it.<\/p>\n
      public abstract class ODataFormat\r\n{}\r\n<\/pre>\n
      Below is the CsvFormat<\/strong> implementation:<\/p>\n
      public class CsvFormat : ODataFormat\r\n{\r\n    public override Task<ODataOutputContext> CreateOutputContextAsync(\r\n        ODataMessageInfo messageInfo, ODataMessageWriterSettings messageWriterSettings)\r\n    {\r\n        return Task.FromResult<ODataOutputContext>(\r\n            new CsvOutputContext(this, messageWriterSettings, messageInfo));\r\n    }\r\n\r\n    \/\/ \u2026\u2026\r\n    \/\/ We don't need other overrides for writing, just throw NotImplementedException<\/strong> and omit them here\u2026\r\n\r\n}\r\n<\/pre>\n
      In this post, we only need to implement the CreateOutputContextAsync<\/em> method in CsvFormat<\/strong> to return a CsvOutputContext<\/strong>. For other overrides, let\u2019s simply throw NotImplementedException<\/strong> exceptions since we don\u2019t use them.<\/p>\n
      CsvOutputContext<\/h2>\n
      As mentioned, output context acts as a bridge between ODataMessageWriter<\/strong> and the specific ODataWriter<\/strong>. ODataOutputContext<\/strong> is also defined as an abstract class, so we should implement it by ourselves. Here\u2019s the CsvOutputContext<\/strong> implementation:<\/p>\n
      public class CsvOutputContext : ODataOutputContext\r\n{\r\n    private Stream stream;\r\n\r\n    public CsvOutputContext(ODataFormat format, ODataMessageWriterSettings settings, ODataMessageInfo messageInfo)\r\n        : base(format, messageInfo, settings)\r\n    {\r\n        stream = messageInfo.MessageStream;\r\n        Writer = new StreamWriter(stream);\r\n    }\r\n\r\n    public TextWriter Writer { get; private set; }\r\n\r\n    public override Task<ODataWriter> CreateODataResourceSetWriterAsync(IEdmEntitySetBase entitySet, IEdmStructuredType resourceType)\r\n        => Task.FromResult<ODataWriter>(new CsvWriter(this, resourceType));\r\n\r\n    public override Task<ODataWriter> CreateODataResourceWriterAsync(IEdmNavigationSource navigationSource, IEdmStructuredType resourceType)\r\n        => Task.FromResult<ODataWriter>(new CsvWriter(this, resourceType));\r\n\r\n    public void Flush() => stream.Flush();\r\n\r\n    protected override void Dispose(bool disposing)\r\n    {\r\n        \/\/ ...... Omits the disposing codes\r\n    }\r\n}\r\n<\/pre>\n
      The implementation is simple. In the constructor, I create a StreamWriter<\/strong> to wrap the writing stream. Within the class, we only override the needed methods to create a writer for a resource set and a single resource. Be noted<\/strong>, to dispose the stream and the writer in the Dispose(bool) is important otherwise the content may be truncated, or no content is return at all. Thanks sifernan@microsoft.com<\/a><\/p>\n
      CsvWriter<\/h2>\n
      CsvOutputContext<\/strong> is responsible for returning the OData writer to finish the \u2018real\u2019 writing operations. CsvWriter<\/strong> is such a class used to finish the CSV format writing. It is a class derived from abstract class ODataWriter<\/strong>, typically we should override the following four virtual methods to finish the resource set or resource writing:<\/p>\n
      public class CsvWriter : ODataWriter\r\n{\r\n    public override Task WriteStartAsync(ODataResourceSet resourceSet)\r\n    { }\r\n\r\n    public override Task WriteStartAsync(ODataResource resource)\r\n    { }\r\n\r\n    public override Task WriteStartAsync(ODataNestedResourceInfo nestedResourceInfo)\r\n    { }\r\n\r\n    public override Task WriteEndAsync()\r\n    { }\r\n}\r\n<\/pre>\n
      Be noted<\/strong>, I use WriteEndAsync<\/em> in the above class for consistency. Actually, I override the abstract method WriteEnd<\/em>() in my sample, not the WriteEndAsync<\/em>(), since WriteEndAsync() in the base class calls WriteEnd<\/em>() directly.<\/p>\n
      It could be a little bit hard to understand the writing flow, for example, which method is called first, which is next, etc. Let me use the following example to illustrate it.<\/p>\n
      Supposed I want to write and get the below-left payload, I need a couple of OData objects (for example, ODataResoruceSet<\/strong>, ODataResource<\/strong>, etc) to call WriteStartAsync<\/em> method. In the below-right picture, I list all OData objects related. The top level is an ODataResourceSet<\/strong>, it\u2019s a collection of ODataResource<\/strong>, each ODataResource<\/strong> contains properties, and may contain a collection of ODataNestedResourceInfo<\/strong>.<\/p>\n
      <\/p>\n
      Here\u2019s the simplified writing process for the above OData payload:<\/p>\n
      \"Text,<\/p>\n
      Where you can see that for each OData object, a WriteStartAsync<\/em> is called first, then a WriteEndAsync<\/em> is called at the end. We can embed more writing processes within it, and each writing process also starts calling WriteStartAsync<\/em>, ends calling WriteEndAsync<\/em>.<\/p>\n
      The implementation of CsvWriter<\/strong> depends on your requirement. You can refer to this post<\/a> for a simple scenario, or you can refer to my implementation here<\/a> for a little bit complex scenario, in which I have codes to write the nested properties.<\/p>\n
      Register CSV format<\/h2>\n
      In the old version, we must register the CsvMediaTypeResolver<\/strong> on MessageWriterSettings<\/strong>. With ASP.NET Core OData 8.x version, it\u2019s easy to inject the CsvMediaTypeResolver<\/strong> into the service container through dependency injection as below.<\/p>\n
      builder.Services.AddControllers().\r\n    AddOData(opt =>\r\n        opt.EnableQueryFeatures()\r\n        .AddRouteComponents(\"odata\", EdmModelBuilder.GetEdmModel(),\r\n            service => service.AddSingleton<ODataMediaTypeResolver>(sp => new CsvMediaTypeResolver())));\r\n<\/pre>\n
      Besides, we should let the existing OData formatter understand the new “text\/csv<\/strong>” media type. We can achieve it using following codes:<\/p>\n
      builder.Services.AddControllers(opt =>\r\n{\r\n    var odataFormatter = opt.OutputFormatters.OfType<ODataOutputFormatter>().First();\r\n    odataFormatter.SupportedMediaTypes.Add(\"text\/csv\");\r\n});\r\n<\/pre>\n
      Test<\/h2>\n
      We finished all implementations. Let\u2019s run and test it.<\/p>\n
      First, we send the \u201cGET http:\/\/localhost:5296\/odata\/books<\/a>\u201d request without any other header settings. You can get the default JSON-formatted OData payload as:<\/p>\n
      \"Text<\/p>\n
      Resend the request \u201cGET http:\/\/localhost:5296\/odata\/books<\/a>\u201d again with request header Accept=text\/csv<\/strong>, we can get the OData CSV-formatted response payload as:<\/p>\n
      <\/p>\n
      It also works with the OData query options such as:<\/p>\n
      \"Graphical<\/p>\n
      My CsvWriter<\/strong> implementation supports writing the nested resource (complex or collection of the complex). For simplicity, I write the nested single-value resource as “{propertyName=PropertyValue,\u2026}”<\/em>, and collection-valued nested resource as “[{nested resource},{\u2026},\u2026]”. <\/em>You can change it to get any format for the nested resource.<\/p>\n
      Send the request \u201cGET <\/a>http:\/\/localhost:5296\/odata\/customers<\/a>\u201d with request header \u201cAccept=text\/csv<\/strong>\u201d, we can get a little complex CSV-formatted OData payload.<\/p>\n
      \"Graphical<\/p>\n
      It also supports querying the simple property and writing it as a CSV.<\/p>\n
      \"Graphical<\/p>\n
      Again, we can also query the CSV-formatted collection complex property such as:<\/p>\n
      \"Graphical<\/p>\n
      Yaml format<\/h2>\n
      It\u2019s easy to repeat the same process to customize the OData serialization payload to another format, for example, YAML. What we need is:<\/p>\n