We’re happy to announce that ASP.NET Core OData 9 has been officially released and is available on NuGet:<\/p>\n
The major highlight of this release is the update of the OData .NET dependencies to the 8.x major version<\/a>.\nBy updating the dependencies, we’re able to take advantage of the improvements and new capabilities introduced in Microsoft.OData.Core 8.x<\/a> and Microsoft.OData.Edm 8.x<\/a> releases specifically.<\/p>\n The ASP.NET Core OData 9 release will only support .NET 8 or later.<\/p>\n The OData .NET 8 official release announcement<\/a> addresses the major changes introduced in that release. It’s advisable to go through the post to familiarize yourself with the changes.<\/p>\n In this post, we explore how some of those changes affect the ASP.NET Core OData library, and how to toggle the legacy behavior where possible.<\/p>\n In OData .NET 8, we introduced a new JSON writer that uses the .NET Utf8JsonWriter<\/a> behind the scenes to write request and response payloads. The new JSON writer is significantly faster and is the default writer in ASP.NET Core OData 9.<\/p>\n You might observe differences in character encoding on output payloads. We cover those differences in the sections below.<\/p>\n In its default configuration, the new JSON writer doesn’t encode a large subset of characters like the legacy (OData .NET 7) one did.<\/p>\n The legacy JSON writer encodes all characters with integer values less than 32 and greater than 127 by default – basically all non-ascii characters. This evaluates to around 65440 characters! It is possible to override the default configuration for the legacy JSON writer by passing The new JSON writer uses an underlying Below is an illustration – in form of code sample for an OData service, demonstrating how an output payload looks like when the new JSON writer is used:<\/p>\n You can query this service for order 1 using the Note<\/strong>: 5090 is a random port assigned by machine and would differ from one computer to the next.<\/p>\n Below is the result you would observe:<\/p>\n In the above case, the new JSON writer doesn’t encode the If it’s important in your scenario to retain the behaviour of the legacy JSON writer, you can do so by swapping out the new JSON writer with the legacy JSON writer using dependency injection. You can do this by modifying the Note<\/strong>: The Here’s how the response payload would look like if you queried for order 1 after the above change:<\/p>\n In the above case, the non-ascii characters are encoded.<\/p>\n The Here’s how the response payload would look like if you queried for order 1 after the above change:<\/p>\n The above response payload looks similar to the output from the legacy JSON writer.<\/p>\n However, it’s important to note that the To close the loop, here’s how you can configure your service to use the legacy JSON writer with the less strict encoding option:<\/p>\n The choice of The new JSON writer uses uppercase letters in the encoded output while the legacy JSON writer uses lowercase letters. Both outputs are legal, and clients should not have a problem deserializing either format.<\/p>\n Using the sample service from previous section with the new JSON writer configured, you can query for order 2 as follows:<\/p>\n Below is the result you would observe:<\/p>\n Note that the encoded values for the unicode characters are in uppercase.<\/p>\n If you query the same order 2 with the legacy JSON writer configured, here is how the response payload looks like:<\/p>\n If the described changes to character encoding are a deal breaker in your scenario, swap out the new JSON writer with the legacy JSON writer as illustrated.<\/p>\n We made significant changes to accommodate dependency injection restructure in OData .NET 8. We got rid of non-standard dependency injection artifacts ( In particular, the changes to the This offers the developer greater flexibility when manipulating those specific settings.<\/p>\n The A major goal for OData .NET 8 was to ensure that customers who migrated to the new version could output the same response payloads as they did in OData .NET 7. Where changes were made to better align with OData standard, a compatibility flag was added to make it possible to toggle the legacy behaviour.<\/p>\nCharacter encoding in request and response payloads<\/h2>\n
Subset of characters encoded<\/h3>\n
ODataStringEscapeOption.EscapeOnlyControls<\/code> option to the default JSON writer factory constructor<\/a>. With this alternative configuration, a much-reduced subset of characters is encoded.<\/p>\nUtf8JsonWriter<\/code> that is configured with the JavaScriptEncoder.UnsafeRelaxedJsonEscaping<\/code> encoder option by default. The resulting set of characters encoded is much smaller.<\/p>\n\/\/ Model\r\nnamespace Ver900Sample.Models\r\n{\r\n public class Order\r\n {\r\n public int Id { get; set; }\r\n public decimal Amount { get; set; }\r\n public string Note { get; set; }\r\n }\r\n}\r\n\r\n\/\/ Controller\r\nusing Microsoft.AspNetCore.OData.Query;\r\nusing Microsoft.AspNetCore.OData.Results;\r\nusing Microsoft.AspNetCore.OData.Routing.Controllers;\r\nusing Ver900Sample.Models;\r\n\r\nnamespace Ver900Sample.Controllers\r\n{\r\n public class OrdersController : ODataController\r\n {\r\n private static readonly List<Order> orders = new List<Order>\r\n {\r\n new Order { Id = 1, Amount = 130m, Note = \"a - z, \u03b1 - \u03a9\" },\r\n new Order { Id = 2, Amount = 170.50m, Note = \"\ud83d\ude00 \ud83d\udc02 \ud83d\udc15\" }\r\n };\r\n\r\n [EnableQuery]\r\n public SingleResult<Order> Get(int key)\r\n {\r\n return SingleResult.Create(orders.AsQueryable().Where(d => d.Id == key));\r\n }\r\n }\r\n}\r\n\r\n\/\/ Service configuration\r\nusing Ver900Sample.Models;\r\nusing Microsoft.AspNetCore.OData;\r\nusing Microsoft.OData.ModelBuilder;\r\n\r\nvar builder = WebApplication.CreateBuilder(args);\r\n\r\nvar modelBuilder = new ODataConventionModelBuilder();\r\nmodelBuilder.EntitySet<Order>(\"Orders\");\r\n\r\nbuilder.Services.AddControllers().AddOData(\r\n options => options.EnableQueryFeatures().AddRouteComponents(\r\n model: modelBuilder.GetEdmModel()));\r\n\r\nvar app = builder.Build();\r\n\r\napp.UseRouting();\r\napp.MapControllers();\r\n\r\napp.Run();<\/code><\/pre>\ncurl<\/code> tool – the browser may not be a good choice for this illustration since it will intelligently decode the encoded characters.<\/p>\ncurl http:\/\/localhost:5090\/Orders(1)<\/code><\/pre>\n{\r\n \"@odata.context\": \"http:\/\/localhost:5090\/$metadata#Orders\/$entity\",\r\n \"Id\": 1,\r\n \"Amount\": 130,\r\n \"Note\": \"a - z, \u03b1 - \u03a9\"\r\n}<\/code><\/pre>\n\u03b1<\/code> and \u03a9<\/code> non-ascii characters.<\/p>\nAddOData<\/code> method call from the above code snippet as follows:<\/p>\nbuilder.Services.AddControllers().AddOData(\r\n options => options.EnableQueryFeatures().AddRouteComponents(\r\n routePrefix: string.Empty,\r\n model: modelBuilder.GetEdmModel(),\r\n configureServices: (services) =>\r\n {\r\n services.AddScoped<Microsoft.OData.Json.IJsonWriterFactory>(\r\n sp => new Microsoft.OData.Json.ODataJsonWriterFactory());\r\n }));<\/code><\/pre>\nODataJsonWriterFactory<\/code> class is what was previously named DefaultJsonWriterFactory<\/code> in OData .NET 7. We felt that having “Default” in the name would perpetuate ambiguity since it’s not the default JSON writer factory in OData .NET 8.<\/p>\n{\r\n \"@odata.context\": \"http:\/\/localhost:5090\/$metadata#Orders\/$entity\",\r\n \"Id\": 1,\r\n \"Amount\": 130,\r\n \"Note\": \"a - z, \\u03b1 - \\u03a9\"\r\n}<\/code><\/pre>\nUtf8JsonWriter<\/code> also supports a stricter JavaScript encoder. You can configure your service to use that encoder as follows:<\/p>\nbuilder.Services.AddControllers().AddOData(\r\n options => options.EnableQueryFeatures().AddRouteComponents(\r\n routePrefix: string.Empty,\r\n model: modelBuilder.GetEdmModel(),\r\n configureServices: (services) =>\r\n {\r\n services.AddScoped<Microsoft.OData.Json.IJsonWriterFactory>(\r\n sp => new Microsoft.OData.Json.ODataUtf8JsonWriterFactory(\r\n System.Text.Encodings.Web.JavaScriptEncoder.Default));\r\n }));<\/code><\/pre>\n{\r\n \"@odata.context\": \"http:\/\/localhost:5090\/$metadata#Orders\/$entity\",\r\n \"Id\": 1,\r\n \"Amount\": 130,\r\n \"Note\": \"a - z, \\u03B1 - \\u03A9\"\r\n}<\/code><\/pre>\nUtf8JsonWriter<\/code> configured with the stricter JavaScript encoder is not a mirror of the legacy JSON writer in respect to the characters that get encoded.<\/p>\nbuilder.Services.AddControllers().AddOData(\r\n options => options.EnableQueryFeatures().AddRouteComponents(\r\n routePrefix: string.Empty,\r\n model: modelBuilder.GetEdmModel(),\r\n configureServices: (services) =>\r\n {\r\n services.AddScoped<Microsoft.OData.Json.IJsonWriterFactory>(\r\n sp => new Microsoft.OData.Json.ODataJsonWriterFactory(\r\n Microsoft.OData.Json.ODataStringEscapeOption.EscapeOnlyControls));\r\n }));<\/code><\/pre>\nJavaScriptEncoder.UnsafeRelaxedJsonEscaping<\/code> configuration option was informed by the fact that it’s the default option configured in ASP.NET Core 8.0.<\/p>\nUppercase letters for unicode code points<\/h3>\n
curl http:\/\/localhost:5090\/Orders(2)<\/code><\/pre>\n{\r\n \"@odata.context\": \"http:\/\/localhost:5090\/$metadata#Orders\/$entity\",\r\n \"Id\": 2,\r\n \"Amount\": 170.50,\r\n \"Note\": \"\\uD83D\\uDE00 \\uD83D\\uDC02 \\uD83D\\uDC15\"\r\n}<\/code><\/pre>\n{\r\n \"@odata.context\": \"http:\/\/localhost:5090\/$metadata#Orders\/$entity\",\r\n \"Id\": 2,\r\n \"Amount\": 170.50,\r\n \"Note\": \"\\ud83d\\ude00 \\ud83d\\udc02 \\ud83d\\udc15\"\r\n}<\/code><\/pre>\nChanges to injection of dependencies<\/h2>\n
IContainerBuilder<\/code> for instance) in favour of the .NET framework dependency injection abstractions.<\/p>\nAddODataDefaultServices<\/code> method in the OData core library makes it possible to configure ODataReaderSettings<\/code>, ODataMessageWriterSettings<\/code>, and ODataUriParserSettings<\/code> as follows:<\/p>\nbuilder.Services.AddControllers().AddOData(\r\n options => options.EnableQueryFeatures().AddRouteComponents(\r\n routePrefix: string.Empty,\r\n model: modelBuilder.GetEdmModel(),\r\n configureServices: (services) =>\r\n {\r\n services.AddDefaultODataServices(\r\n odataVersion: Microsoft.OData.ODataVersion.V4,\r\n configureReaderAction: (messageReaderSettings) =>\r\n {\r\n \/\/ Relevant changes to the ODataMessageReaderSettings instance here\r\n },\r\n configureWriterAction: (messageWriterSettings) =>\r\n {\r\n \/\/ Relevant changes to the ODataMessageWriterSettings instance here\r\n },\r\n configureUriParserAction: (uriParserSettings) =>\r\n {\r\n \/\/ \/\/ Relevant changes to the ODataUriParserSettings instance here\r\n });\r\n }));<\/code><\/pre>\nIServiceCollection<\/code> parameter also makes it straightforward to inject any desired dependencies:<\/p>\nbuilder.Services.AddControllers().AddOData(\r\n options => options.EnableQueryFeatures().AddRouteComponents(\r\n routePrefix: string.Empty,\r\n model: modelBuilder.GetEdmModel(),\r\n configureServices: (services) =>\r\n {\r\n services.AddSingleton<Microsoft.OData.ODataPayloadValueConverter>(\r\n sp => new CustomODataPayloadValueConverter());\r\n }));\r\n\r\n\/\/ ...\r\n\r\npublic class CustomODataPayloadValueConverter : Microsoft.OData.ODataPayloadValueConverter\r\n{\r\n public override object ConvertToPayloadValue(object value, IEdmTypeReference edmTypeReference)\r\n {\r\n if (edmTypeReference.PrimitiveKind() == EdmPrimitiveTypeKind.DateTimeOffset)\r\n {\r\n var dateTimeOffset = (DateTimeOffset)value;\r\n return dateTimeOffset.ToString(\"yyyy-MM-dd'T'HH:mm:ss.fffffffzzz\");\r\n }\r\n\r\n return base.ConvertToPayloadValue(value, edmTypeReference);\r\n }\r\n}<\/code><\/pre>\nBackward compatibility flags<\/h2>\n