services.AddControllers()\r\n .AddOData(opt => opt.AddRouteComponents(\"v{version}\", edmModel));\r\n<\/pre>\nBased on this configuration, it supports API versioning using URL segment as:<\/p>\n
- \n
- http:\/\/localhost:5000\/v1.0<\/strong>\/Customers<\/li>\n
- http:\/\/localhost:5000\/v2.0<\/strong>\/Customers<\/li>\n<\/ul>\n
ASP.NET Core OData 8 doesn’t have the built-in API versioning based on query string and request header. However, it’s easy to extend the package to achieve these two API versionings. This post will create the extensions to build the query string API versioning with ASP.NET Core OData 8.x and share with you the ideas of how easy to extend ASP.NET Core OData 8. The same way also applies to the request header.<\/p>\n
Let’s get started.<\/p>\n
Scenarios<\/h2>\n
We want to build an API which can return the different version of Customers<\/strong> data based on api-version<\/strong> query string using the same<\/strong> request URL, for example:<\/p>\n
- \n
- http:\/\/localhost:5000\/Customers?api-version=1.0<\/a> returns “Customers<\/strong>” for version 1.0<\/li>\n
- http:\/\/localhost:5000\/Customers?api-version=2.0<\/a> returns “Customers<\/strong>” for version 2.0<\/li>\n
- http:\/\/localhost:5000\/Customers?api-version=3.0<\/a> returns “Version 3.0 NotSupported exception<\/strong>“.<\/li>\n<\/ul>\n
Be noted<\/strong>, v1 and v2 use the same HTTP request path.<\/p>\n
Prerequisites<\/h2>\n
Let us create an ASP.NET Core Application called “ODataApiVersion<\/strong>” using Visual Studio 2019. You can follow up any guide or refer to ASP.NET Core OData 8.0 Preview for .NET 5<\/a> to create this application.<\/p>\n
We install the following nuget packages:<\/p>\n
- \n
- Microsoft.AspNetCore.OData -version 8.0.1<\/li>\n
- Microsoft.AspNetCore.Mvc.Versioning -version 5.0<\/li>\n<\/ul>\n
CLR Model<\/h2>\n
Once the application is created, let\u2019s create a folder named “Models” in the solution explorer. In this folder, let’s create the following three C# classes for our CLR model:<\/p>\n
Namespace ODataApiVersion.Models\r\n{\r\n public abstract class CustomerBase\r\n {\r\n public int Id { get; set; }\r\n public string ApiVersion { get; set; }\r\n }\r\n}\r\n\r\nNamespace ODataApiVersion.Models.v1<\/strong>\r\n{\r\n public class Customer : CustomerBase\r\n {\r\n public string Name { get; set; }\r\n public string PhoneNumber { get; set; }\r\n }\r\n}\r\n\r\nNamespace ODataApiVersion.Models.v2<\/strong>\r\n{\r\n public class Customer : CustomerBase\r\n {\r\n public string FirstName { get; set; }\r\n public string LastName { get; set; }\r\n public string Email { get; set; }\r\n }\r\n}\r\n<\/pre>\nBe noted<\/strong>: the two concrete classes have the same name “Customer<\/strong>” but in different namespace.<\/p>\n
Edm Model provider<\/h2>\n
We need an Edm model provider to provide the Edm model based on the API version.<\/p>\n
Let’s create the following interface and use it as a service in the dependency injection:<\/p>\n
public interface IODataModelProvider\r\n{\r\n IEdmModel GetEdmModel(string apiVersion);\r\n}\r\n<\/pre>\nWe create a default implementation for the model provider interface as<\/p>\n
public class MyODataModelProvider : IODataModelProvider\r\n{\r\n private IDictionary<string, IEdmModel> _cached = new Dictionary<string, IEdmModel>();\r\n public IEdmModel GetEdmModel(string apiVersion)\r\n {\r\n if (_cached.TryGetValue(apiVersion, out IEdmModel model))\r\n {\r\n return model;\r\n }\r\n\r\n model = BuildEdmModel(apiVersion);\r\n _cached[apiVersion] = model;\r\n return model;\r\n }\r\n\r\n private static IEdmModel BuildEdmModel(string version)\r\n {\r\n switch (version)\r\n {\r\n case \"1.0\": return BuildV1Model();\r\n case \"2.0\": return BuildV2Model();\r\n }\r\n\r\n throw new NotSupportedException($\"The input version '{version}' is not supported!\");\r\n }\r\n\r\n private static IEdmModel BuildV1Model()\r\n {\r\n var builder = new ODataConventionModelBuilder();\r\n builder.EntitySet<Models.v1.Customer>(\"Customers\");\r\n return builder.GetEdmModel();\r\n }\r\n\r\n private static IEdmModel BuildV2Model()\r\n {\r\n var builder = new ODataConventionModelBuilder();\r\n builder.EntitySet<Models.v2.Customer>(\"Customers\");\r\n return builder.GetEdmModel();\r\n }\r\n}\r\n<\/pre>\nBe noted<\/strong>: v1 and v2 Edm model have the same entity set named “Customers<\/strong>“.<\/p>\n
CustomersController<\/h2>\n
We need two controllers to handle the same request for different API versions. In the “Controllers” folder, add two controllers using the same name “CustomersController<\/strong>” but different namespace.<\/p>\n
namespace ODataApiVersion.Controllers.v1<\/strong>\r\n{\r\n [ApiVersion(\"1.0\")]\r\n public class CustomersController : ODataController\r\n {\r\n private Customer[] customers = new Customer[]\r\n {\r\n \/\/ ...... Omit the codes, you can find them from the project\r\n };\r\n\r\n [EnableQuery]\r\n public IActionResult Get()\r\n {\r\n return Ok(customers);\r\n }\r\n\r\n [EnableQuery]\r\n public IActionResult Get(int key)\r\n {\r\n var customer = customers.FirstOrDefault(c => c.Id == key);\r\n if (customer == null)\r\n {\r\n return NotFound($\"Cannot find customer with Id={key}.\");\r\n }\r\n\r\n return Ok(customer);\r\n\r\n }\r\n }\r\n}\r\n\r\nnamespace ODataApiVersion.Controllers.v2<\/strong>\r\n{\r\n [ApiVersion(\"2.0\")]\r\n public class CustomersController : ODataController\r\n {\r\n private Customer[] _customers = new Customer[]\r\n {\r\n \/\/ ...... Omit the codes, you can find them from the project\r\n };\r\n\r\n [EnableQuery]\r\n public IActionResult Get()\r\n {\r\n return Ok(customers);\r\n }\r\n\r\n [EnableQuery]\r\n public IActionResult Get(int key)\r\n {\r\n \/\/ ...... Omit the codes, you can find them from the project\r\n }\r\n }\r\n}\r\n<\/pre>\nBe noted<\/strong>: Each controller has [ApiVersionAttribute<\/strong>] decorated using different version string.<\/p>\n
Construct the routing template<\/h2>\n
We need to build the routing template for the action in the controller, which is used to match the coming request. The built-in OData routing convention cannot meet this requirement. So, we have to build the routing template using an IApplicationModelProvider <\/strong>.<\/p>\n
public class MyODataRoutingApplicationModelProvider : IApplicationModelProvider\r\n{\r\n public int Order => 90;\r\n public void OnProvidersExecuted(ApplicationModelProviderContext context)\r\n {\r\n IEdmModel model = EdmCoreModel.Instance; \/\/ just for place holder\r\n string prefix = string.Empty;\r\n foreach (var controllerModel in context.Result.Controllers)\r\n {\r\n \/\/ CustomersController\r\n if (controllerModel.ControllerName == \"Customers\")\r\n {\r\n ProcessCustomersController(prefix, model, controllerModel);\r\n continue;\r\n }\r\n\r\n \/\/ MetadataController\r\n if (controllerModel.ControllerName == \"Metadata\")\r\n {\r\n ProcessMetadata(prefix, model, controllerModel);\r\n continue;\r\n }\r\n }\r\n }\r\n\r\n public void OnProvidersExecuting(ApplicationModelProviderContext context)\r\n {}\r\n\r\n private static void ProcessCustomersController(string prefix, IEdmModel model, ControllerModel controllerModel)\r\n {\r\n foreach (var actionModel in controllerModel.Actions)\r\n {\r\n \/\/ For simplicity, only check the parameter count\r\n if (actionModel.ActionName == \"Get\")\r\n {\r\n if (actionModel.Parameters.Count == 0)\r\n {\r\n ODataPathTemplate path = new ODataPathTemplate(new EntitySetCustomersSegment());\r\n actionModel.AddSelector(\"get\", prefix, model, path);\r\n }\r\n else\r\n {\r\n ODataPathTemplate path = new ODataPathTemplate(\r\n new EntitySetCustomersSegment(),\r\n new EntitySetWithKeySegment());\r\n actionModel.AddSelector(\"get\", prefix, model, path);\r\n }\r\n }\r\n }\r\n }\r\n\r\n private static void ProcessMetadata(string prefix, IEdmModel model, ControllerModel controllerModel)\r\n {\r\n \/\/ ...... Omit the codes, you can find them from the project\r\n }\r\n}\r\n<\/pre>\nBe noted<\/strong>: the above codes handle the actions on:<\/p>\n
- \n
- v1.CustomersController<\/strong><\/li>\n
- v2.CustomersController<\/strong><\/li>\n
- MetadataController<\/strong><\/li>\n<\/ul>\n
Besides, EntitySetCustomersSegment<\/strong> has the following codes:<\/p>\n
public class EntitySetCustomersSegment : ODataSegmentTemplate\r\n{\r\n public override IEnumerable<string> GetTemplates(ODataRouteOptions options)\r\n {\r\n yield return \"\/Customers\";\r\n }\r\n\r\n public override bool TryTranslate(ODataTemplateTranslateContext context)\r\n {\r\n \/\/ Support case-insenstivie\r\n var edmEntitySet = context.Model.EntityContainer.EntitySets()\r\n .FirstOrDefault(e => string.Equals(\"Customers\", e.Name, StringComparison.OrdinalIgnoreCase));\r\n\r\n if (edmEntitySet != null)\r\n {\r\n EntitySetSegment segment = new EntitySetSegment(edmEntitySet);\r\n context.Segments.Add(segment);\r\n return true;\r\n }\r\n\r\n return false;\r\n }\r\n}\r\n<\/pre>\nAnd EntitySetWithKeySegment<\/strong> has the following codes:<\/p>\n
public class EntitySetWithKeySegment : ODataSegmentTemplate\r\n{\r\n public override IEnumerable<string> GetTemplates(ODataRouteOptions options)\r\n {\r\n yield return \"\/{key}\";\r\n \/\/ yield return \"({key})\"; enable it if you want to support key in parenthesis\r\n }\r\n\r\n public override bool TryTranslate(ODataTemplateTranslateContext context)\r\n {\r\n \/\/ ...... Omit the codes, you can find them from the project\r\n }\r\n}\r\n<\/pre>\nRouting matcher policy<\/h2>\n
We need a routing matcher policy to select the best endpoint. Here’s our implementation<\/p>\n
internal class MyODataRoutingMatcherPolicy : MatcherPolicy, IEndpointSelectorPolicy\r\n{\r\n private readonly IODataTemplateTranslator _translator;\r\n private readonly IODataModelProvider _provider;\r\n private readonly ODataOptions _options;\r\n\r\n public MyODataRoutingMatcherPolicy(IODataTemplateTranslator translator,\r\n IODataModelProvider provider,\r\n IOptions<ODataOptions> options)\r\n {\r\n _translator = translator;\r\n _provider = provider;\r\n _options = options.Value;\r\n }\r\n\r\n public override int Order => 900 - 1; \/\/ minus 1 to make sure it's running before built-in OData matcher policy\r\n\r\n public bool AppliesToEndpoints(IReadOnlyList<Endpoint> endpoints)\r\n {\r\n return endpoints.Any(e => e.Metadata.OfType<ODataRoutingMetadata>().FirstOrDefault() != null);\r\n }\r\n\r\n public Task ApplyAsync(HttpContext httpContext, CandidateSet candidates)\r\n {\r\n \/\/ ...... omit some checking codes\r\n\r\n for (var i = 0; i < candidates.Count; i++)\r\n {\r\n ref CandidateState candidate = ref candidates[i];\r\n if (!candidates.IsValidCandidate(i))\r\n {\r\n continue;\r\n }\r\n\r\n IODataRoutingMetadata metadata = candidate.Endpoint.Metadata.OfType<IODataRoutingMetadata>().FirstOrDefault();\r\n if (metadata == null)\r\n {\r\n continue;\r\n }\r\n\r\n \/\/ Get api-version query from HttpRequest?\r\n QueryStringApiVersionReader reader = new QueryStringApiVersionReader(\"api-version\");\r\n string apiVersionStr = reader.Read(httpContext.Request);\r\n if (apiVersionStr == null)\r\n {\r\n candidates.SetValidity(i, false);\r\n continue;\r\n }\r\n\r\n ApiVersion apiVersion = ApiVersion.Parse(apiVersionStr);\r\n IEdmModel model = GetEdmModel(apiVersion);\r\n if (model == null)\r\n {\r\n candidates.SetValidity(i, false);\r\n continue;\r\n }\r\n\r\n if (!IsApiVersionMatch(candidate.Endpoint.Metadata, apiVersion))\r\n {\r\n candidates.SetValidity(i, false);\r\n continue;\r\n }\r\n\r\n ODataTemplateTranslateContext translatorContext\r\n = new ODataTemplateTranslateContext(httpContext, candidate.Endpoint, candidate.Values, model);\r\n\r\n try\r\n {\r\n ODataPath odataPath = _translator.Translate(metadata.Template, translatorContext);\r\n if (odataPath != null)\r\n {\r\n odataFeature.RoutePrefix = metadata.Prefix;\r\n odataFeature.Model = model;\r\n odataFeature.Path = odataPath;\r\n\r\n ODataOptions options = new ODataOptions();\r\n UpdateQuerySetting(options);\r\n options.AddRouteComponents(model);\r\n odataFeature.Services = options.GetRouteServices(string.Empty);\r\n\r\n MergeRouteValues(translatorContext.UpdatedValues, candidate.Values);\r\n }\r\n else\r\n {\r\n candidates.SetValidity(i, false);\r\n }\r\n }\r\n catch\r\n {\r\n candidates.SetValidity(i, false);\r\n }\r\n }\r\n\r\n return Task.CompletedTask;\r\n }\r\n\r\n private void UpdateQuerySetting(ODataOptions options)\r\n {\r\n \/\/ ...... omit the setting copy codes\r\n }\r\n\r\n private static void MergeRouteValues(RouteValueDictionary updates, RouteValueDictionary source)\r\n {\r\n foreach (var data in updates)\r\n {\r\n source[data.Key] = data.Value;\r\n }\r\n }\r\n\r\n private IEdmModel GetEdmModel(ApiVersion apiVersion)\r\n {\r\n return _provider.GetEdmModel(apiVersion.ToString());\r\n }\r\n\r\n private static bool IsApiVersionMatch(EndpointMetadataCollection metadata, ApiVersion apiVersion)\r\n {\r\n var apiVersions = metadata.OfType<ApiVersionAttribute>().ToArray();\r\n if (apiVersions.Length == 0)\r\n {\r\n \/\/ If no [ApiVersion] on the controller,\r\n \/\/ Let's simply return true, it means it can work the input version or any version.\r\n return true;\r\n }\r\n\r\n foreach (var item in apiVersions)\r\n {\r\n if (item.Versions.Contains(apiVersion))\r\n {\r\n return true;\r\n }\r\n }\r\n\r\n return false;\r\n }\r\n}\r\n<\/pre>\nBe noted<\/strong>: The order value is “900 – 1” to make sure this policy is applied before the built-in OData routing match policy.<\/p>\n
Config the services<\/h2>\n
Now, let\u2019s configure the above extensions as services into the service collection in the Startup<\/strong> class as below:<\/p>\n
public void ConfigureServices(IServiceCollection services)\r\n{\r\n services.AddControllers().AddOData();\r\n services.TryAddSingleton<IODataModelProvider, MyODataModelProvider>();\r\n services.TryAddEnumerable(\r\n ServiceDescriptor.Transient<IApplicationModelProvider, MyODataRoutingApplicationModelProvider>());\r\n services.TryAddEnumerable(ServiceDescriptor.Singleton<MatcherPolicy, MyODataRoutingMatcherPolicy>());\r\n}\r\n\r\npublic void Configure(IApplicationBuilder app, IWebHostEnvironment env)\r\n{\r\n \/\/ ......\r\n app.UseODataRouteDebug();\r\n\r\n app.UseRouting();\r\n \/\/ ......\r\n}\r\n<\/pre>\nRouting Debug<\/h2>\n
You may noticed we call app.UseODataRouteDebug()<\/strong> in Configure(…)<\/strong> method. This function enables \/$odata<\/strong> middleware. Run the application and send http:\/\/localhost:5000\/$odata<\/a> in any internet browser, you can get the following html page:<\/p>\n
![\"Image](\"https:\/\/devblogs.microsoft.com\/odata\/wp-content\/uploads\/sites\/23\/2021\/07\/dollarOData.png\")
<\/p>\nThis HTML page gives you a whole routing template picture. You can see we have the same routing templates for different actions. For example, Get(int key)<\/strong> action in v1.CustomersController<\/strong> and v2.CustomersController<\/strong> have the same routing template as ~\/Customers\/{key}<\/strong>.<\/p>\n
Run and test the functionalities<\/h2>\n
Now, we can run and test the API versioning functionalities.<\/p>\n
Query metadata<\/h2>\n
As mentioned, we have the codes in MyODataRoutingApplicationModelProvider<\/strong> to process the MetadataController<\/strong>, it supports the metadata versioning.<\/p>\n
Send Http request http:\/\/localhost:5000\/$metadata?api-version=1.0<\/a>, you can get:<\/p>\n
- v2.CustomersController<\/strong><\/li>\n
- v1.CustomersController<\/strong><\/li>\n
- http:\/\/localhost:5000\/Customers?api-version=2.0<\/a> returns “Customers<\/strong>” for version 2.0<\/li>\n
- http:\/\/localhost:5000\/v2.0<\/strong>\/Customers<\/li>\n<\/ul>\n