Adapters

What Are Adapters?

Adapters are an OData controller dispatching mechanism that allows users to specify complex query strings with filters and field selections. Unlike normal OData controllers, adapters don't make use of the EF Core provider. Instead, adapters are backed by your custom code. Adapters transform the conditions specified in the OData query into a data structure that is similar to one that might be currently used when implementing search operations within your Synergy applications. Adapters currently have support for filters based on equality, range, in set, and parameters.

What Are Adapters For?

Adapters are the preferred mechanism for exposing custom Synergy code where the user may want to supply filter criteria, that needs to be applied at the database level. A good example would be if you have custom code that would be performance prohibitive to perform filtering actions after your code runs. OData is perfectly capable of applying transformations to the results of your custom code, but adapters allow you to filter down the results before they are handed back to OData.

Using Adapters

Adapters are defined the same way you would for sproc routing with one difference. Methods that you intend to have dispatched this way should have a single parameter with AdapterParameterAttribute applied. The type of the parameter should be a class comprised of public read/write properties, each with one of the adapter attributes applied, informing the system how to synthesize its value. Here is the list of supported adapter attributes:

• ParameterFieldAdapterAttribute - named parameter passed inside the parentheses inside the URI (may be optional)
• MatchFieldAdapterAttribute - inside the $filter clause, this can transform operations like field1 eq 'somevalue'
• RangeFieldAdapterAttribute - inside the $filter clause, this can transform operations that specify upper or lower bounds (or both) for a value using the 'gt', 'lt', 'gte', 'lte' operators
• OrFieldAdapterAttribute - inside the $filter clause, this can transform operations where there are a set of 'or equals' operations

In addition to the above changes that are made per method you want to expose, you will also need to enable the AdapterRoutingConvention using something like the following inside your Startup.dbl Configure method.

lambda EnableRouting(sp)
begin
    ;;Enable optional OData features

    ;;Enable $select expressions to select properties returned
    builder.Select()

    ;;Enable $filter expressions to filter rows returned
    builder.Filter()

    ;;Enable $orderby expressions to custom sort results
    builder.OrderBy()

    ;;Enable /$count endpoints
    builder.Count()

    ;;Enable $expand expressions to expand relations
    builder.Expand()

    ;;Specify the maximum rows that may be returned by $top expressions
    builder.MaxTop(100)

    data routeList = ODataRoutingConventions.CreateDefaultWithAttributeRouting("uri_base_name", builder)
    routeList.Insert(0, new AdapterRoutingConvention())
    mreturn routeList
end

lambda ConfigureRoute(containerBuilder)
begin
    ...
    containerBuilder.AddService<IEnumerable<IODataRoutingConvention>>(Microsoft.OData.ServiceLifetime.Singleton, EnableRouting)
end

builder.MapODataServiceRoute("uri_base_name", "uri_base_name", ConfigureRoute)

Alternatively, if you're using the project templates we provide along with the regen.bat, you can just un-comment the following line:

set ENABLE_ADAPTER_ROUTING=-define ENABLE_ADAPTER_ROUTING