Skip to content

v3.0.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 21 Jun 11:20
v3.0.0
eca3389

FlexQuery.NET v3.0.0 Release Notes

FlexQuery.NET v3.0.0 is a major release that introduces a modular, provider-agnostic architecture along with new first-party integrations for Dapper, AG Grid, and MiniOData.

This release focuses on decoupling the query engine from Entity Framework, improving extensibility, strengthening validation, and improving runtime performance through caching and parser optimizations.

Why v3.0?

Version 3.0 lays the foundation for a modular FlexQuery ecosystem.

Applications can now choose only the integrations they need while sharing a common query model across:

  • Entity Framework Core
  • Dapper
  • Raw SQL providers
  • AG Grid
  • OData-style clients

This reduces coupling and enables FlexQuery to support a broader range of application architectures.

Highlights

  • New Dapper and Raw SQL support through FlexQuery.NET.Dapper
  • Provider-agnostic query execution architecture
  • New AG Grid and MiniOData integrations
  • Improved caching and parser performance
  • Configurable validation behavior

📦 New Packages & Features

FlexQuery.NET.Dapper

A new SQL translation engine that enables FlexQuery to execute on Dapper or raw ADO.NET.

  • Dialect Translation: Introduces SqlTranslator with translation logic for SQL Server, SQLite, MySQL, and PostgreSQL.
  • Flat Projections: The FlatProjectionBuilder maps nested request structures to flat LEFT JOIN queries, supporting hierarchical row hydration.
  • Aggregations: The TranslateAggregates method maps query aggregations (count, sum, min, max, average) to corresponding SQL aggregation functions.
  • Parameterization: SQL generation uses SqlParameterContext to bind parameters, avoiding inline values.

FlexQuery.NET.AgGrid

A dedicated adapter that translates AG Grid server-side requests into FlexQuery query models.

Supported capabilities include:

  • Text, number, date, and set filters
  • Multi-condition AND/OR filter groups
  • Multi-column sorting
  • Pagination translation
  • Row grouping
  • Aggregate mapping through ValueCols
  • JSON payload parsing

This allows AG Grid applications to reuse FlexQuery's filtering, sorting, grouping, and aggregation pipeline without custom request translation code.

FlexQuery.NET.MiniOData

An optional compatibility layer for applications that expose OData-style query parameters.

Supported query options include:

  • $filter
  • $orderby
  • $select
  • $top
  • $skip
  • $expand
  • $count

Additional capabilities:

  • Nested path translation (address/city → address.city)
  • Case-insensitive parameter handling
  • Automatic paging translation from $top and $skip
  • Integration with FlexQuery validation and security rules

This allows existing OData-style clients to integrate with FlexQuery without requiring a full OData implementation.

⚡ Performance & Architecture

Performance Improvements

  • Improved query parsing and projection performance through internal caching optimizations.
  • Reduced reflection overhead during expression generation.
  • Improved cache isolation and memory predictability for long-running applications.
  • Replaced legacy unbounded caching strategies with bounded cache implementations.

Parser & Core Refactoring

The query parsing pipeline was decomposed into specialized parser components to improve maintainability, extensibility, and testability.

Examples include:

  • FilterParser
  • SortParser
  • SelectParser
  • JsonQueryParser

This replaces portions of the previous monolithic parser implementation with focused parser components.

Non-Strict Validation

  • Added StrictFieldValidation to BaseQueryExecutionOptions. Setting this to false instructs the engine to remove unauthorized fields or nested includes from the query instead of throwing a QueryValidationException, allowing execution to continue using only permitted members.

Package Migration

v3 introduces optional packages that can be installed independently.

Example

dotnet add package FlexQuery.NET.Dapper
dotnet add package FlexQuery.NET.AgGrid
dotnet add package FlexQuery.NET.MiniOData

Review your package references and install only the integrations required by your application.

Architecture Changes

Modular Package Ecosystem

FlexQuery.NET has been reorganized into focused packages that can evolve independently while sharing a common query abstraction layer.

Benefits include:

  • Reduced dependencies
  • Smaller deployment footprint
  • Easier integration with non-EF data providers
  • Improved maintainability and extensibility

🛠 Breaking Changes

Target Frameworks

  • Added: net10.0
  • Removed: net7.0 (EOL)
  • Supported: net6.0, net8.0, net10.0

API Deprecations and Removals

  • Request Models: QueryRequest and FlexQueryRequest have been removed after being deprecated in the v2.x release series.
  • FlexQueryParameters remains the supported request model and should be used for all new integrations.
  • AST Restructuring: Legacy parsers (DslParser, JqlParser) and their associated node types have been refactored and relocated to the Ast namespace.
  • Constant Typing: Magic strings used for error codes and operators have been replaced with strongly typed constants (ContextKeys, FilterOperators, QueryOptionKeys, ValidationErrorCodes).

📋 Migration Guide

If you are upgrading from v2.x to v3.0.0, please follow these steps:

  1. Update Target Frameworks: Ensure your consuming projects target .NET 6.0, .NET 8.0, or .NET 10.0.
  2. Migrate Request Models: QueryRequest and FlexQueryRequest were deprecated in v2.x and have been removed in v3.0. Replace any remaining usages with FlexQueryParameters.
  3. Update DI Registrations: FlexQuery no longer registers all adapters by default. You must explicitly install and register the packages you use using their respective extension methods (e.g., services.AddFlexQueryMiniOData()).
  4. Resolve Namespace Changes: If you wrote custom AST manipulations, update your using directives to reference the new FlexQuery.NET.Parsers.Dsl.Ast or FlexQuery.NET.Parsers.Jql.Ast namespaces.
  5. Update Constants: Replace string literals in validation checks or custom operators with the new constant classes (e.g., replace "eq" with FilterOperators.Equal).
Assets 11
Loading