{"id":4992,"date":"2022-08-17T00:14:27","date_gmt":"2022-08-17T07:14:27","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/odata\/?p=4992"},"modified":"2022-08-18T21:35:56","modified_gmt":"2022-08-19T04:35:56","slug":"using-the-new-json-writer-in-odata","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/using-the-new-json-writer-in-odata\/","title":{"rendered":"Using the new JSON writer in OData"},"content":{"rendered":"

Microsoft.OData.Core<\/code> version 7.12.2 has introduced a new JSON writer that\u2019s based on .NET\u2019s Utf8JsonWriter<\/a>. The current JSON writer used in Microsoft.OData.Core<\/code>, internally called JsonWriter<\/code>, is a custom implementation that uses TextWriter<\/code><\/a> to write the JSON output to the destination stream. We decided to write a new implementation to take advantage of the performance optimizations in Utf8JsonWriter<\/code>.<\/p>\n

In order not to disrupt existing customers, people will have to explicitly \u201copt-in\u201d to using the new writer. Currently, ODataMessageWriter<\/code> allows you to override the default IJsonWriter<\/code> used for writing JSON output by providing a custom IJsonWriterFactory<\/code> to the dependency-injection container that\u2019s attached to the message instance<\/a> (IODataResponseMessage<\/code> or IODataRequestMessage<\/code>). However, the existing IJsonWriterFactory<\/code> is tightly coupled to TextWriter<\/code>. We introduced a new factory interface that allows writing directly to the output Stream<\/code> instead of TextWriter<\/code>. We call it IStreamBasedJsonWriterFactory<\/code>. The default implementation of this factory is called DefaultStreamBasedJsonWriter.<\/code> It creates an instance of the new JSON Writer, internally called ODataUtf8JsonWriter<\/code>. To opt-in to using the new writer, you need to add this factory as a service to the dependency-injection container. We\u2019ll demonstrate how to do that in OData Web API 7.x and OData Web API 8.x libraries and when using ODataMessageWriter<\/code> directly.<\/p>\n

OData Web API 8.x<\/h2>\n

You can use the new writer starting with Microsoft.AspNetCore.OData<\/code><\/a> 8.0.11. You can configure custom services when registering new OData route components using the AddRouteComponens<\/code> method. Here\u2019s an example:<\/p>\n

Add the following using statement to the Startup.cs<\/code> file, or the file where you configure application services:<\/p>\n

using Microsoft.OData.Json;<\/pre>\n
Then register the new factory inside the Startup.ConfigureServices<\/code> method or the method where you\u2019re configuring application services if not Startup.ConfigureServices<\/code>:<\/p>\n
services.AddControllers()\r\n    .AddOData(options =>\r\n    options.AddRouteCompontents(\u201codata\u201d, model, services =>\r\n    {\r\n        Services.AddSingleton<IStreamBasedJsonWriterFactory>(_ => DefaultStreamBasedJsonWriterFactory.Default);\r\n    });\r\n<\/pre>\n
OData Web API 7.x<\/h2>\n
This feature is available in Microsoft.AspNetCore.OData<\/code> 7.5.17. There are different methods to configure custom OData services depending on whether you\u2019re using endpoint routing or classic MVC routing.<\/p>\n
This feature was initially announced with Microsoft.AspNetCore.OData version 7.5.16. However, customers reported issues<\/a> with that release. As result, 7.5.16 has been unlisted on Nuget and 7.5.17 was released to address the issues.<\/div><\/p>\n
Endpoint routing<\/h2>\n
If you\u2019re using Endpoint routing, then you configure the OData route using endpoints.MapODataRoute<\/code> in the action passed to app.UseEndpoints<\/code> in Startup.Configure<\/code>. There\u2019s an overload of MapODataRoute<\/code> that allows you to configure custom OData services. We\u2019ll use this to inject the new factory class into the internal service container. We\u2019ll also need to manually register the default routing conventions since this overload of MapODataRoute<\/code> does not handle that automatically, otherwise routing will not work properly.<\/p>\n
Example:<\/p>\n
Ensure you have the following using statements to the Startup.cs<\/code> file<\/p>\n
using System.Collections.Generic;\r\nusing Microsoft.AspNet.OData.Routing.Conventions;\r\nusing Microsoft.OData;\r\nusing Microsoft.OData.Json;\r\n<\/pre>\n
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)\r\n{\r\n\r\n    IEdmModel model = GetEdmModel();\r\n\r\n    app.UseODataBatching();\r\n\r\n    app.UseRouting();\r\n\r\n    app.UseEndpoints(endpoints =>\r\n    {\r\n        endpoints.MapODataRoute(\r\n            \"odata\", \u201codata\u201d,\r\n            container =>\r\n            {\r\n                container.AddService(Microsoft.OData.ServiceLifetime.Singleton, sp => model);\r\n                container.AddService<IStreamBasedJsonWriterFactory>(Microsoft.OData.ServiceLifetime.Singleton, sp => DefaultStreamBasedJsonWriterFactory.Default);\r\n                container.AddService<IEnumerable<IODataRoutingConvention>>(Microsoft.OData.ServiceLifetime.Singleton,\r\n                    sp => ODataRoutingConventions.CreateDefaultWithAttributeRouting(\"nullPrefix\", endpoints.ServiceProvider));\r\n            });\r\n    });\r\n}\r\n<\/pre>\n
MVC routing<\/h2>\n
If you\u2019re using MVC routing, you can configure custom OData services inside the Startup.Configure<\/code> method by passing configuration action to the MapODataServiceRoute<\/code> method. Using this overload of MapODataServiceRoute<\/code> will also require you to manually register the default routing conventions, otherwise routing will not work properly.<\/p>\n
Add the following using statements to the Startup.cs<\/code> file.<\/p>\n
using System.Collections.Generic;\r\nusing Microsoft.AspNet.OData.Routing.Conventions;\r\nusing Microsoft.OData;\r\nusing Microsoft.OData.Json;\r\n<\/pre>\n
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)\r\n{\r\n    IEdmModel model = GetEdmModel();\r\n\r\n    app.UseMvc(builder =>\r\n    {\r\n        builder.Select().Expand().Filter().OrderBy().MaxTop(100).Count();\r\n\r\n        builder.MapODataServiceRoute(\"odata\", \"odata\", container =>\r\n        {\r\n            container.AddService(Microsoft.OData.ServiceLifetime.Singleton, sp => model)\r\n                .AddService<IStreamBasedJsonWriterFactory>(Microsoft.OData.ServiceLifetime.Singleton, sp => DefaultStreamBasedJsonWriterFactory.Default)\r\n                .AddService<IEnumerable<IODataRoutingConvention>>(Microsoft.OData.ServiceLifetime.Singleton, sp =>\r\n                    ODataRoutingConventions.CreateDefaultWithAttributeRouting(\"odata\", builder));\r\n        });\r\n    });\r\n}\r\n<\/pre>\n
 <\/p>\n
ODataMessageWriter<\/h2>\n
If you\u2019re using ODataMessageWriter directly from Microsot.OData.Core<\/code> to write JSON payloads, it takes a few extra steps to configure.<\/p>\n
To write a message, you need to provide an implementation of IODataResponseMessage<\/code> when writing a response and IODataRequestMessage<\/code> when writing a request body. Whatever I mention next about IODataResponseMessage<\/code> also applies to IODataRequestMessage<\/code>. To make your custom services accessible to the ODataMessageWriter<\/code>, your implementation of IODataResponseMessage<\/code> must also implement IContainerProvider<\/code>. This is a simple interface that exposes a Container<\/code> property of type IServiceProvider<\/code>. ODataMessageWriter<\/code> will use this property (if it has been defined on the message instance) to request services it needs, like an implementation of the IStreamBasedJsonWriterFactory<\/code>.<\/p>\n
For example, an IODataResponseMessage<\/code> implementation could look like<\/p>\n
class MyResponseMessage : IODataResponseMessage, IContainerProvider \r\n{ \r\n    \/\/\u2026 other methods omitted for brevity\r\n    IServiceProvider Container { get; init; };\r\n}\r\n<\/pre>\n
You must also implement IContainerBuilder<\/code>. This is a Microsoft.OData.Core<\/code> interface that provides an abstraction for service containers, without tying itself to any specific dependency injection library. If you don\u2019t already have an existing implementation in your code, you can copy or refer to the DefaultContainerBuilder<\/code><\/a> implementation in Microsoft.AspNetCore.OData<\/code>which is based on Microsoft.Extensions.DependencyInjection library. To learn more about dependency injection in the OData core library, visit this page<\/a>.<\/p>\n
Then use the following steps to configure the container builder.<\/p>\n
You will need the following using statements:<\/p>\n
using Microsoft.OData;\r\nusing Microsoft.OData.Json;\r\n<\/pre>\n
var containerBuilder = new DefaultContainerBuild();\r\ncontainerBuilder.AddDefaultODataServices(); \r\ncontainerBuilder.Services.Add<IStreamBasedJsonWriterFactory>(DefaultStreamBasedJsonWrtiterFactory.Default);\r\n<\/pre>\n
Then create the service provider:<\/p>\n
IServiceProvider services = containerBuilder.BuildContainer();<\/pre>\n
And here\u2019s how to set it on the response message when using ODataMessageWriter<\/code>:<\/p>\n
MyResponseMessage message = new MyResponseMessage(\u2026) { Container = services };\r\nODataMessageWriterSettings settings = \u2026;\r\nIEdmModel model = \u2026;\r\n\r\nODataMessageWriter writer = new ODataMessageWriter(message, settings, model);\r\nawait  writer.WriteStartAsync(new ODataResourceSet());\r\n<\/pre>\n
Performance<\/h2>\n
Based on some of our benchmarks<\/a>, ODataUtf8JsonWriter<\/code> is about 38% faster than the default JsonWriter<\/code> and uses less memory. It can increase the speed of the overall ODataMessageWriter<\/code> by about 5-7% and reduces its memory usage by 2.5% when using the synchronous API. When using the asynchronous API, it makes ODataMessageWriter<\/code> about 47% faster and reduces memory usage by almost 33%.<\/p>\n
Limitations and other considerations<\/h2>\n
Support for streaming writes<\/h2>\n
The default JsonWriter<\/code> implements the IJsonStreamWriter<\/code> interface. This interface allows you to pipe data directly from an input stream to the output destination. This may be useful when writing the contents of large binary or text file into the JSON output without reading everything in memory first. The new ODataUtf8JsonWriter<\/code> does not yet implement this interface, which means input from a stream will be buffered entirely in memory before being written out to the destination.<\/p>\n
Supported .NET versions<\/h2>\n
This feature is only available with Microsoft.OData.Core<\/code> on .NET Core 3.1 and above (i.e. .NET 6 etc.). It is not supported on Microsoft.OData.Core<\/code> versions running on .NET Framework.<\/p>\n
Choosing a JavaScriptEncoder<\/h2>\n
The DefaultStreamBasedJsonWriterFactory.Default<\/code> uses the default JavaScriptEncoder<\/code> used by Utf8JsonWriter<\/code> to encode and escape output text. The default encoder escapes control characters, non-ASCII characters and HTML-sensitive characters like \u2018<\u2019. This differs from OData\u2019s default behavior which does not escape HTML-sensitive characters.<\/p>\n
You can provide a different JavaScriptEncoder<\/code>. Instead of injecting DefaultStreamBasedJsonWriterFactory.Default<\/code>, you can create a new instance of the factory and pass the encoder to the constructor. The following snippet uses the JavaScriptEncoder.UnsafeRelaxedJsonEscaping<\/code> which does not escape HTML-sensitive characters. This is the default encoder used by ASP.NET Core.<\/p>\n
IStreamBasedJsonWriterFactory factory = new DefaultStreamBasedJsonWriterFactory(JavaScriptEncoder.UnsafeRelaxedJsonEscaping);<\/pre>\n
Note that there\u2019s no built-in JavaScriptEncoder<\/code> that exactly matches the escaping implementation of OData\u2019s default JsonWriter<\/code>. The raw output of the two writers will be different. But if the client is compliant, this should not be a problem. Nevertheless, this is something you should take into consideration before adopting the new writer. In general, you should not be highly dependent on a whether certain characters are escaped or not because the internal implementation may change from one version of .NET to another (See relevant discussions here<\/a> and here<\/a>).<\/p>\n
Conclusion<\/h2>\n
We have introduced the new ODataUtf8JsonWriter<\/code> that ships with Microsoft.OData.Core<\/code> 7.12.2 and showed how to configure OData serializers and writers to use it. This is part of a larger effort to make the core libraries more performant and efficient. We invite you to try out the new writer and share feedback with us. Let us know what you think, whether you observe any performance improvements (or regressions) and what other improvements we can make.<\/p>\n","protected":false},"excerpt":{"rendered":"
Microsoft.OData.Core version 7.12.2 has introduced a new JSON writer that\u2019s based on .NET\u2019s Utf8JsonWriter. The current JSON writer used in Microsoft.OData.Core, internally called JsonWriter, is a custom implementation that uses TextWriter to write the JSON output to the destination stream. We decided to write a new implementation to take advantage of the performance optimizations in […]<\/p>\n","protected":false},"author":20326,"featured_media":3253,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-4992","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-odata"],"acf":[],"blog_post_summary":"
Microsoft.OData.Core version 7.12.2 has introduced a new JSON writer that\u2019s based on .NET\u2019s Utf8JsonWriter. The current JSON writer used in Microsoft.OData.Core, internally called JsonWriter, is a custom implementation that uses TextWriter to write the JSON output to the destination stream. We decided to write a new implementation to take advantage of the performance optimizations in […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/4992","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/users\/20326"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/comments?post=4992"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/4992\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media\/3253"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media?parent=4992"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/categories?post=4992"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/tags?post=4992"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}