{"id":4703,"date":"2021-08-23T12:10:46","date_gmt":"2021-08-23T19:10:46","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/odata\/?p=4703"},"modified":"2021-08-23T12:12:12","modified_gmt":"2021-08-23T19:12:12","slug":"build-formatter-extensions-in-asp-net-core-odata-8-and-hooks-in-odataconnectedservice","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/build-formatter-extensions-in-asp-net-core-odata-8-and-hooks-in-odataconnectedservice\/","title":{"rendered":"Build formatter extensions in ASP.NET Core OData 8 and hooks in ODataConnectedService"},"content":{"rendered":"

Introduction<\/h2>\n

In this post, I will create formatter extensions in an OData web service and request\/response hooks in an OData client application to generate\/consume ETag control information. ETag (aka entity tag), one of OData control information that may be applied to an entity or collection in response, can be used in a subsequent request to avoid overwriting if the entity or collection’s value has been changed by other requests.<\/p>\n

ETag value normally can be generated using concurrency properties automatically in OData, however, I\u2019d like to use this post to share with you the ideas of how to extend serialization and deserialization in ASP.NET Core OData 8 and how to use request\/response hook in OData Connected Service to customize the ETag functionality.<\/p>\n

Let\u2019s get started.<\/p>\n

Scenarios & Prerequisites<\/h2>\n

I want to generate\/consume the ETag control information (aka odata.etag<\/a>) using a hidden property on the service side, meanwhile, to generate\/consume the ETag using an extra property at the client side.<\/p>\n

So, let\u2019s create a blank solution named ODataETagExtensions<\/strong>, in which I create an ASP.NET Core Application called ODataETagWebApi<\/strong>, and a console application named ODataETagClient<\/strong>. I install the \u201cMicrosoft.AspNetCore.OData -version 8.0.1\u201d nuget package to ODataETagWebApi<\/strong>.<\/p>\n

I use ODataConnectedService<\/a> in the console application ODataETagClient<\/strong>\u00a0to consume the ETag from the service. If you haven\u2019t installed ODataConnectedService, go to [Extensions]\ud83e\udc7a[Manage Extensions] menu from Visual studio, search and install OData Connected Service<\/em>. You might need to close the VS to let the installation finish.<\/p>\n

\"Graphical<\/p>\n

Build the model with hidden ETag property<\/h2>\n

In ODataETagWebApi, <\/strong>I create a simple C# class as our schema model as:<\/p>\n

\/\/ Customer.cs\r\npublic class Customer\r\n{\r\n    public int Id { get; set; }\r\n\r\n    public string Name { get; set; }\r\n\r\n    public Guid Label { get; set; }\r\n}\r\n<\/pre>\n
Where, “Label”<\/em> is the property containing ETag info but not included in the schema. So, when building the Edm model, let\u2019s ignore this property as:<\/p>\n
private static IEdmModel GetEdmModel()\r\n{\r\n    var builder = new ODataConventionModelBuilder();\r\n\r\n    builder.EntitySet<Customer>(\"Customers\").EntityType.Ignore(c => c.Label);\r\n\r\n    return builder.GetEdmModel();\r\n}\r\n<\/pre>\n
Here\u2019s a part of the schema:<\/p>\n
<EntityType\u00a0Name=\"Customer\">\r\n  <Key>\r\n    <PropertyRef\u00a0Name=\"Id\"\/>\r\n  <\/Key>\r\n  <Property\u00a0Name=\"Id\"\u00a0Type=\"Edm.Int32\"\u00a0Nullable=\"false\"\/>\r\n  <Property\u00a0Name=\"Name\"\u00a0Type=\"Edm.String\"\/>\r\n<\/EntityType>\r\n<\/pre>\n
Build controller<\/h2>\n
I create the following CustomersController <\/strong>to handle the request. For simplicity, I use memory data for customers:<\/p>\n
public class CustomersController : ControllerBase\r\n{\r\n    private static IList<Customer> Customers = new List<Customer>\r\n    {\r\n        new Customer { Id = 1, Name = \"Freezing\", Label = new Guid(\"81B06CD0-3B66-4447-B193-94B11328A762\") },\r\n        new Customer { Id = 2, Name = \"Bracing\", Label = new Guid(\"629C11E1-1918-4978-AFE0-F90BA6A452C6\") },\r\n        new Customer { Id = 3, Name = \"Chilly\", Label = new Guid(\"CA02BF9C-8364-4320-B74F-CB8956C9A502\") },\r\n    };\r\n\r\n    [HttpGet]\r\n    [EnableQuery]\r\n    public IActionResult Get()\r\n    {\r\n        return Ok(Customers);\r\n    }\r\n\r\n    [HttpGet]\r\n    [EnableQuery]\r\n    public IActionResult Get(int key)\r\n    {\r\n        Customer c = Customers.FirstOrDefault(c => c.Id == key);\r\n        if (c == null)\r\n        {\r\n            return NotFound($\"Cannot find customer with Id={key}\");\r\n        }\r\n\r\n        return Ok(c);\r\n    }\r\n}\r\n<\/pre>\n
Config and test service<\/h2>\n
In the startup.cs<\/em>, let\u2019s configure OData as:<\/p>\n
public void ConfigureServices(IServiceCollection services)\r\n{\r\n    services.AddControllers()\r\n        .AddOData(opt => opt.AddRouteComponents(\"odata\", GetEdmModel));\r\n}\r\n<\/pre>\n
Now, let\u2019s build, run ODataETagWebApi,<\/strong> and query `http:\/\/localhost:5000\/odata\/customers`<\/a>, we can get the following:<\/p>\n
{\r\n  \"@odata.context\":\"http:\/\/localhost:5000\/odata\/$metadata#Customers\",\r\n  \"value\":[\r\n    {\r\n      \"Id\":1,\r\n      \"Name\":\"Freezing\"\r\n    },\r\n    ......\r\n    {\r\n      \"Id\":5,\r\n      \"Name\":\"Mild\"\r\n    }\r\n  ]\r\n}\r\n<\/pre>\n
Customize serializer to return ETtag from service<\/h2>\n
From the above Customers<\/em> query, you can find that each customer doesn\u2019t have \u201cLabel<\/em>\u201d property, neither odata.etag<\/em> property. In order to generate \u201codata.etag<\/em>\u201d using the “Label”<\/em> property, we can customize the resource serializer to generate it.<\/p>\n
I customize the serializer by deriving from ODataResourceSerializer<\/strong>. Below is my implementation:<\/p>\n
public class ETagResourceSerializer : ODataResourceSerializer\r\n{\r\n    public ETagResourceSerializer(IODataSerializerProvider serializerProvider)\r\n        : base(serializerProvider)\r\n    { }\r\n\r\n    public override ODataResource CreateResource(SelectExpandNode selectExpandNode, ResourceContext resourceContext)\r\n    {\r\n        ODataResource resource = base.CreateResource(selectExpandNode, resourceContext);\r\n\r\n        if (resource.ETag == null && resourceContext.ResourceInstance is Customer c)\r\n        {\r\n            resource.ETag = EncodeETag(c.Label);\r\n        }\r\n\r\n        return resource;\r\n    }\r\n\r\n    private static string EncodeETag(Guid guide)\r\n    {\r\n        byte[] bytes = Encoding.UTF8.GetBytes(guid.ToString());\r\n        return Convert.ToBase64String(bytes);\r\n    }\r\n}\r\n<\/pre>\n
I create the following serializer provider to inject the ETagResourceSerialize<\/strong>. Here\u2019s my implementation:<\/p>\n
public class ETagSerializerProvider : ODataSerializerProvider\r\n{\r\n    public ETagSerializerProvider(IServiceProvider serviceProvider)\r\n        : base(serviceProvider)\r\n    { }\r\n\r\n    public override IODataEdmTypeSerializer GetEdmTypeSerializer(IEdmTypeReference edmType)\r\n    {\r\n        if (edmType.IsEntity() || edmType.IsComplex())\r\n        {\r\n            return new ETagResourceSerializer(this);\r\n        }\r\n\r\n        return base.GetEdmTypeSerializer(edmType);\r\n    }\r\n}\r\n<\/pre>\n
Let\u2019s update Startup.cs<\/em> by injecting the serializer provider into service collection:<\/p>\n
public void ConfigureServices(IServiceCollection services)\r\n{\r\n    services.AddControllers()\r\n        .AddOData(opt => opt.AddRouteComponents(\"odata\", GetEdmModel(),\r\n            builder => builder.AddSingleton<IODataSerializerProvider, ETagSerializerProvider>()));\r\n}\r\n<\/pre>\n
Now, build, run ODataETagWebApi<\/strong> and query request: http:\/\/localhost:5000\/odata\/customers\/1<\/a><\/p>\n
We can get the following response:<\/p>\n
{\r\n  \"@odata.context\":\u00a0\"http:\/\/localhost:5000\/odata\/$metadata#Customers\/$entity\",\r\n  \"@odata.etag\":\u00a0\"ODFiMDZjZDAtM2I2Ni00NDQ3LWIxOTMtOTRiMTEzMjhhNzYy\",\r\n  \"Id\":\u00a01,\r\n  \"Name\":\u00a0\"Freezing\"\r\n}\r\n<\/pre>\n
Consume ETag at OData client<\/h2>\n
Let\u2019s use ODataConnectedService to config the ODataETagClient <\/strong>project. First, Let\u2019s run the service ODataETagWebApi<\/strong> without debug. Once the service is running, right click ODataETagClient<\/strong> project from Solution Explorer in VS. Select [Add] \ud83e\udc7a [Connected Service] menu from the Pop-up menu. In the dialog, select OData Connected Service. In the Configure endpoint <\/em>dialog below, input the Uri in the Address <\/strong>input box (be sure to use your service URI if different):<\/p>\n
<\/p>\n
Click next <\/strong>button and go to Schema Types<\/em> page to make sure we have the schema loaded.<\/p>\n
<\/p>\n
The above picture shows that OData connected service correctly retrieves the schema type from our service.<\/p>\n
Let\u2019s skip other configurations and click the Finish <\/strong>button to let the connected service generate the proxy classes.<\/p>\n
Now, let\u2019s change Program.cs <\/em>in the ODataETagClient<\/strong> using the following codes:<\/p>\n
class Program\r\n{\r\n    async static Task Main(string[] args)\r\n    {\r\n        await ListCustomers();\r\n    }\r\n\r\n    async static Task ListCustomers()\r\n    {\r\n        Console.WriteLine(\"List Customers: \");\r\n        Container context = GetContext();\r\n        IEnumerable<Customer> customers = await context.Customers.ExecuteAsync();\r\n        foreach (var customer in customers)\r\n        {\r\n            Console.WriteLine(\" {0}) Name={1}\", customer.Id, customer.Name);\r\n        }\r\n\r\n        Console.WriteLine();\r\n    }\r\n\r\n    private static Container GetContext()\r\n    {\r\n        var serviceRoot = \"http:\/\/localhost:5000\/odata\/\";\r\n        var context = new Container(new Uri(serviceRoot));\r\n        return context;\r\n    }\r\n}\r\n<\/pre>\n
To test, set ODataETagClient<\/strong> as startup project by right click ODataETagClient<\/strong> project in the solution explorer. Please make sure ODataETagWebApi<\/strong> is running, then [Ctrl+F5] to run ODataETagClient<\/strong>, we can get:<\/p>\n
<\/p>\n
You can find OData connected service generates a proxy class named Customer<\/strong>, but it only has Id <\/strong>and Name <\/strong>properties.<\/p>\n
To use Label<\/em>, let\u2019s add a new C# file \u201cCustomer.cs\u201d into ODataETagClient<\/strong> project, add the following:<\/p>\n
\/\/ Customers.cs\r\npublic partial class Customer\r\n{\r\n    public Guid Label { get; set; }\r\n}\r\n<\/pre>\n
Change \u201cListCustomers()<\/strong>\u201d in the program.cs<\/em> class:<\/p>\n
async static Task ListCustomers()\r\n{\r\n    \/\/ omit codes\r\n\r\n    foreach (var customer in customers)\r\n    {\r\n        Console.WriteLine(\" {0}) Name={1,-10}Label={2}\", customer.Id, customer.Name + \",\", customer.Label);\r\n    }\r\n\r\n    \/\/ omit codes\r\n}\r\n<\/pre>\n
Run the console application again, we can get an empty Guid Label.<\/p>\n
<\/p>\n
Now, let\u2019s retrieve the Label <\/em>from ETag. In order to retrieve the value, we can use OData client hook. OData client provides several ways to allow developers to hook into the client request and response. In the current scenario, we can use OnEntityMaterialized<\/strong> from response pipeline configuration. For other hooks, please refer to here.<\/a><\/p>\n
OnEntityMaterialized<\/strong> response hook uses MaterializedEntityArgs<\/strong> as:<\/p>\n
public sealed class MaterializedEntityArgs\r\n{\r\n    public MaterializedEntityArgs(ODataResource entry, object entity);\r\n    public ODataResource Entry { get; }\r\n    public object Entity { get; }\r\n}\r\n<\/pre>\n
Where,<\/p>\n