ASP.NET Core OData Documentation

OData routing matches your Entity Data Model (Edm Model) to your ASP.NET Core controllers using one of two conventions:

1. Convention Routing (Default): Routes are discovered based on naming conventions. For example, an entity set named Customers expects a controller named CustomersController. If you rename the controller (e.g., to MyCustomersController), OData will no longer match the Customers entity set.
2. Attribute Routing: Routes are discovered based on attributes applied directly to the controller class or its methods.

By default, the project uses Convention Routing.

An Alternate Key is a secondary identifier for an entity that is distinct from its declared primary key. In ASP.NET Core OData 8.x, you can define these using vocabulary annotations in your metadata.

There are two ways to define them:

1. Recommended: Use the Org.OData.Core.V1.AlternateKey term.
2. Backward Compatible: Use the OData.Community.Keys.V1.AlternateKeys term.

To invoke an API using an alternate key, you must use the alternateKeyAlias=alternateKeyValue pattern, which is only supported when using attribute routing.

A Non-Edm model refers to a route that does not have an explicit Entity Data Model (EDM) configured. Even without an EDM, you can still perform OData queries such as $select and $top on these routes.

Example Request: http://localhost:5000/api/accounts?$select=Name&$top=3

Example Response:

[
    {
        "Name": "Warm"
    },
    {
        "Name": "Scorching"
    },
    {
        "Name": "Sweltering"
    }
]

Known Limitation: There are currently known issues when attempting complex property selection on Non-Edm models, such as selecting nested properties:

• ?$select=HomeAddress
• ?$select=HomeAddress($select=City)

Once the ASP.NET Core OData service is running, you can inspect the configured routing table by sending a GET request to the /$odata endpoint. This provides a visual or structured representation of the available OData routes in the application.

GET ~/$odata

In non-Edm OData scenarios, using the $select query parameter causes the response to return selected properties as keys within a dictionary. By default, these dictionary keys use the original C# property names (PascalCase) rather than the camelCase used in standard JSON responses.

To ensure that $select results use camelCase for property names, you must configure the DictionaryKeyPolicy for the JSON serializer in your ASP.NET Core service configuration.

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.DictionaryKeyPolicy = JsonNamingPolicy.CamelCase;
    })
    .AddOData(options => options.Select().Filter().OrderBy());

To add OData support to your ASP.NET Core project, install the Microsoft.AspNetCore.OData NuGet package using the .NET CLI.

dotnet add package Microsoft.AspNetCore.OData

To handle OData queries where the query options are passed in the request body instead of the URL, use the UseODataQueryRequest() extension method. This is useful for avoiding URL length limitations by appending /$query to the resource path and using the POST verb.

Important: This middleware must be added to the pipeline before app.UseRouting().

app.UseODataQueryRequest();

Alternatively, instead of using a controller, you can use the app.UseODataRouteDebug middleware in your ASP.NET Core application pipeline to retrieve similar debug information regarding your OData routing.

app.UseODataRouteDebug();

Composite alternate keys allow you to identify an entity using a combination of multiple properties. This is useful when a single property is not unique, but a set of properties is.

Example for a Person entity using a composite key of CountryOrRegion and Passport:

• Community Composite: ~/odata/People(c_or_r='USA',passport='9999')
• Core Composite: ~/odata/People(core_c_r='USA',core_passport='9999')

To enable debug routing that lists all available endpoints in your service, use the UseODataRouteDebug() extension method. This provides a /$odata endpoint for easy debugging.

Important: This middleware must be added to the pipeline before app.UseRouting().

app.UseODataRouteDebug();