v3.25.0

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Represents the **NuGet** versions.
 
+## v3.25.0
+- *Enhancement:* Added new `CoreEx.Data` project/package to encapsulate all generic data-related capabilities, specifically the new `QueryFilterParser` and `QueryOrderByParser` classes. These enable a limited, explicitly supported, dynamic capability to `$filter` and `$orderby` an underlying query _similar_ to _OData_. This is **not** intended to be a replacement for the full capabilities of OData, GraphQL, etc. but to offer basic dynamic flexibility where needed.
+  - Added `IQueryable<T>.Where()` and `IQueryable<T>.OrderBy` extension method that will use the aforementioned parsers configured within the new `QueryArgsConfig` and `QueryArgs` and apply leveraging `System.Linq.Dynamic.Core`.
+  - Updated `HttpRequestOptions` and `WebApiRequestOptions` to support `QueryArgs` (`$filter` and `$orderby` query string arguments) similar to the existing `PagingArgs`.
+  - Added `QueryAttribute` to enable _Swagger/Swashbuckle_ generated documentation.
+- *Fixed:* Fixed missing `IServiceCollection.AddCosmosDb` including corresponding `CosmosDbHealthCheck`.
+- *Fixed:* Added `JsonIgnore` to all interfaces that have a `CompositeKey` property as _not_ intended to be serialized by default.
+- *Fixed:* Fixed `ReferenceDataCollectionBase<TId, TRef, TSelf>` constructor which was hiding `sortOrder` and `codeComparer` parameters.
+
 ## v3.24.1
 - *Fixed*: `CosmosDb.SelectMultiSetWithResultAsync` updated to skip items that are not considered valid; ensures same outcome as if using a `CosmosDbModelQueryBase` with respect to filtering.
 

Common.targets

@@ -1,6 +1,6 @@
 <Project>
 	<PropertyGroup>
-		<Version>3.24.1</Version>
+		<Version>3.25.0</Version>
 		<LangVersion>preview</LangVersion>
 		<Authors>Avanade</Authors>
 		<Company>Avanade</Company>

CoreEx.sln

@@ -87,7 +87,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CoreEx.TestFunctionIso", "t
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CoreEx.Test2", "tests\CoreEx.Test2\CoreEx.Test2.csproj", "{910B5894-46BC-4427-95D6-2804F06458E3}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.Database.Postgres", "src\CoreEx.Database.Postgres\CoreEx.Database.Postgres.csproj", "{C042AC2A-415D-432E-83FA-B911FD9ED378}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CoreEx.Database.Postgres", "src\CoreEx.Database.Postgres\CoreEx.Database.Postgres.csproj", "{C042AC2A-415D-432E-83FA-B911FD9ED378}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CoreEx.Data", "src\CoreEx.Data\CoreEx.Data.csproj", "{B927138A-1DCA-4BA6-A9E5-E5DA6446DABC}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -215,6 +217,10 @@ Global
 		{C042AC2A-415D-432E-83FA-B911FD9ED378}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{C042AC2A-415D-432E-83FA-B911FD9ED378}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{C042AC2A-415D-432E-83FA-B911FD9ED378}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B927138A-1DCA-4BA6-A9E5-E5DA6446DABC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B927138A-1DCA-4BA6-A9E5-E5DA6446DABC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B927138A-1DCA-4BA6-A9E5-E5DA6446DABC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B927138A-1DCA-4BA6-A9E5-E5DA6446DABC}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -252,6 +258,7 @@ Global
 		{6F7B4F1E-3C3A-4CD7-A9BF-973A5053C1C8} = {3145DCB9-98FB-4519-BCC0-75A22A252EDC}
 		{910B5894-46BC-4427-95D6-2804F06458E3} = {3145DCB9-98FB-4519-BCC0-75A22A252EDC}
 		{C042AC2A-415D-432E-83FA-B911FD9ED378} = {4B6BC31E-93B1-42B0-AE09-AD85AC4DB657}
+		{B927138A-1DCA-4BA6-A9E5-E5DA6446DABC} = {4B6BC31E-93B1-42B0-AE09-AD85AC4DB657}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {8B4566D2-9B22-4E27-9654-402BDBA6C744}

README.md

@@ -25,6 +25,7 @@ Package | Status | Source & documentation
 `CoreEx.AutoMapper` | [![NuGet version](https://badge.fury.io/nu/CoreEx.AutoMapper.svg)](https://badge.fury.io/nu/CoreEx.AutoMapper) | [Link](./src/CoreEx.AutoMapper)
 `CoreEx.Azure` | [![NuGet version](https://badge.fury.io/nu/CoreEx.Azure.svg)](https://badge.fury.io/nu/CoreEx.Azure) | [Link](./src/CoreEx.Azure)
 `CoreEx.Cosmos` | [![NuGet version](https://badge.fury.io/nu/CoreEx.Cosmos.svg)](https://badge.fury.io/nu/CoreEx.Cosmos) | [Link](./src/CoreEx.Cosmos)
+`CoreEx.Data` | [![NuGet version](https://badge.fury.io/nu/CoreEx.Data.svg)](https://badge.fury.io/nu/CoreEx.Data) | [Link](./src/CoreEx.Data)
 `CoreEx.Database` | [![NuGet version](https://badge.fury.io/nu/CoreEx.Database.svg)](https://badge.fury.io/nu/CoreEx.Database) | [Link](./src/CoreEx.Database)
 `CoreEx.Database.MySql` | [![NuGet version](https://badge.fury.io/nu/CoreEx.Database.MySql.svg)](https://badge.fury.io/nu/CoreEx.Database.MySql) | [Link](./src/CoreEx.Database.MySql)
 `CoreEx.Database.Postgres` | [![NuGet version](https://badge.fury.io/nu/CoreEx.Database.Postgres.svg)](https://badge.fury.io/nu/CoreEx.Database.Postgres) | [Link](./src/CoreEx.Database.Postgres)

nuget-publish.ps1

@@ -53,6 +53,7 @@ param(
         "src\CoreEx.AutoMapper",
         "src\CoreEx.Azure",
         "src\CoreEx.Solace",
+        "src\CoreEx.Data",
         "src\CoreEx.Database",
         "src\CoreEx.Database.SqlServer",
         "src\CoreEx.Database.MySql",

samples/My.Hr/My.Hr.Api/Controllers/EmployeeController.cs

@@ -31,8 +31,9 @@ public Task<IActionResult> GetAsync(Guid id)
     [HttpGet("")]
     [ProducesResponseType(typeof(IEnumerable<Employee>), (int)HttpStatusCode.OK)]
     [Paging]
+    [Query]
     public Task<IActionResult> GetAllAsync()
-        => _webApi.GetAsync(Request, p => _service.GetAllAsync(p.RequestOptions.Paging));
+        => _webApi.GetAsync(Request, p => _service.GetAllAsync(p.RequestOptions.Query, p.RequestOptions.Paging));
 
     /// <summary>
     /// Creates a new <see cref="Employee"/>.

samples/My.Hr/My.Hr.Api/Controllers/ReferenceDataController.cs

@@ -37,6 +37,5 @@ public Task<IActionResult> GenderGetAll([FromQuery] IEnumerable<string>? codes =
 
     [HttpGet()]
     [ProducesResponseType(typeof(ReferenceDataMultiDictionary), (int)HttpStatusCode.OK)]
-    [ApiExplorerSettings(IgnoreApi = true)]
     public Task<IActionResult> GetNamed() => _webApi.GetAsync(Request, p => _orchestrator.GetNamedAsync(p.RequestOptions));
 }

samples/My.Hr/My.Hr.Api/My.Hr.Api.csproj

@@ -4,6 +4,7 @@
     <TargetFramework>net6.0</TargetFramework>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>preview</LangVersion>
   </PropertyGroup>
 
   <PropertyGroup>

samples/My.Hr/My.Hr.Api/Startup.cs

@@ -73,7 +73,8 @@ public void ConfigureServices(IServiceCollection services)
             var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
             options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
             options.OperationFilter<AcceptsBodyOperationFilter>();  // Needed to support AcceptsBodyAttribue where body parameter not explicitly defined.
-            options.OperationFilter<PagingOperationFilter>(PagingOperationFilterFields.TokenTake);  // Needed to support PagingAttribue where PagingArgs parameter not explicitly defined.
+            options.OperationFilter<PagingOperationFilter>(PagingOperationFilterFields.SkipTake);  // Needed to support PagingAttribute where PagingArgs parameter not explicitly defined.
+            options.OperationFilter<QueryOperationFilter>(QueryOperationFilterFields.FilterAndOrderby);  // Needed to support QueryAttribute where QueryArgs parameter not explicitly defined.
         });
     }
 

samples/My.Hr/My.Hr.Business/Models/UsState.cs

@@ -7,4 +7,4 @@ public class USState : ReferenceDataBaseEx<Guid, USState>
     public static implicit operator USState?(string? code) => ConvertFromCode(code);
 }
 
-public class USStateCollection : ReferenceDataCollectionBase<Guid, USState, USStateCollection> { }
+public class USStateCollection() : ReferenceDataCollectionBase<Guid, USState, USStateCollection>(ReferenceDataSortOrder.SortOrder) { }

samples/My.Hr/My.Hr.Business/My.Hr.Business.csproj

@@ -4,6 +4,7 @@
     <TargetFramework>net6.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <LangVersion>preview</LangVersion>
   </PropertyGroup>
 
   <ItemGroup>

samples/My.Hr/My.Hr.Business/Services/EmployeeService.cs

@@ -1,7 +1,25 @@
+using CoreEx.Data.Querying;
+
 namespace My.Hr.Business.Services;
 
 public class EmployeeService : IEmployeeService
 {
+    private static readonly QueryArgsConfig _queryConfig = QueryArgsConfig.Create()
+        .WithFilter(filter => filter
+            .AddField<string>("LastName", c => c.Operators(QueryFilterTokenKind.AllStringOperators).UseUpperCase())
+            .AddField<string>("FirstName", c => c.Operators(QueryFilterTokenKind.AllStringOperators).UseUpperCase())
+            .AddField<DateTime>("StartDate")
+            .AddField<DateTime>("TerminationDate")
+            .AddField<string>(nameof(Employee.Gender), c => c.WithValue(v =>
+            {
+                var g = Gender.ConvertFromCode(v);
+                return g is not null && g.IsValid ? g : throw new FormatException("Gender is invalid.");
+            })))
+        .WithOrderBy(orderBy => orderBy
+            .AddField("LastName")
+            .AddField("FirstName")
+            .WithDefault("LastName, FirstName"));
+
     private readonly HrDbContext _dbContext;
     private readonly IEventPublisher _publisher;
     private readonly HrSettings _settings;
@@ -16,8 +34,8 @@ public EmployeeService(HrDbContext dbContext, IEventPublisher publisher, HrSetti
     public async Task<Employee?> GetEmployeeAsync(Guid id) 
         => await _dbContext.Employees.FirstOrDefaultAsync(e => e.Id == id);
 
-    public Task<EmployeeCollectionResult> GetAllAsync(PagingArgs? paging) 
-        => _dbContext.Employees.OrderBy(x => x.LastName).ThenBy(x => x.FirstName).ToCollectionResultAsync<EmployeeCollectionResult, EmployeeCollection, Employee>(paging);
+    public Task<EmployeeCollectionResult> GetAllAsync(QueryArgs? query, PagingArgs? paging) 
+        => _dbContext.Employees.Where(_queryConfig, query).OrderBy(_queryConfig, query).ToCollectionResultAsync<EmployeeCollectionResult, EmployeeCollection, Employee>(paging);
 
     public async Task<Employee> AddEmployeeAsync(Employee employee)
     {

samples/My.Hr/My.Hr.Business/Services/EmployeeService2.cs

@@ -18,7 +18,7 @@ public EmployeeService2(IHrEfDb efDb, IEventPublisher publisher, HrSettings sett
 
     public Task<Employee?> GetEmployeeAsync(Guid id) => _efDb.Employees.GetAsync(id);
 
-    public Task<EmployeeCollectionResult> GetAllAsync(PagingArgs? paging) 
+    public Task<EmployeeCollectionResult> GetAllAsync(QueryArgs? query, PagingArgs? paging) 
         => _efDb.Employees.Query(q => q.OrderBy(x => x.LastName).ThenBy(x => x.FirstName)).WithPaging(paging).SelectResultAsync<EmployeeCollectionResult, EmployeeCollection>();
 
     public Task<Employee> AddEmployeeAsync(Employee employee) => _efDb.Employees.CreateAsync(employee);

samples/My.Hr/My.Hr.Business/Services/IEmployeeService.cs

@@ -4,7 +4,7 @@ public interface IEmployeeService
     {
         Task<Employee?> GetEmployeeAsync(Guid id);
 
-        Task<EmployeeCollectionResult> GetAllAsync(PagingArgs? paging);
+        Task<EmployeeCollectionResult> GetAllAsync(QueryArgs? query, PagingArgs? paging);
 
         Task<Employee> AddEmployeeAsync(Employee employee);
 

samples/My.Hr/My.Hr.Functions/Functions/EmployeeFunction.cs

@@ -44,7 +44,7 @@ public Task<IActionResult> GetAsync([HttpTrigger(AuthorizationLevel.Function, "g
     [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
     [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: MediaTypeNames.Application.Json, bodyType: typeof(List<Employee>), Description = "Employee records")]
     public Task<IActionResult> GetAllAsync([HttpTrigger(AuthorizationLevel.Function, "get", Route = "api/employees")] HttpRequest request)
-        => _webApi.GetAsync(request, p => _service.GetAllAsync(p.RequestOptions.Paging));
+        => _webApi.GetAsync(request, p => _service.GetAllAsync(p.RequestOptions.Query, p.RequestOptions.Paging));
 
     [FunctionName("Create")]
     [OpenApiOperation(operationId: "Create", tags: new[] { "employee" })]

samples/My.Hr/My.Hr.UnitTest/EmployeeControllerTest.cs

@@ -116,7 +116,7 @@ public void B110_GetAll_Paging()
             var x = TestSetUp.Extensions;
 
             var v = test.Controller<EmployeeController>()
-                .Run(c => c.GetAllAsync(), requestOptions: new HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2, true) })
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2, true)))
                 .AssertOK()
                 .GetValue<EmployeeCollectionResult>();
 
@@ -133,14 +133,44 @@ public void B120_GetAll_PagingAndIncludeFields()
             using var test = ApiTester.Create<Startup>();
 
             var v = test.Controller<EmployeeController>()
-                .Run(c => c.GetAllAsync(), requestOptions: new HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2) }.Include("lastname"))
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2)).Include("lastname"))
                 .AssertOK()
                 .AssertJson("[ { \"lastName\": \"Jones\" }, { \"lastName\": \"Smith\" } ]")
                 .GetValue<EmployeeCollectionResult>();
 
             Assert.That(v!.Paging!.TotalCount, Is.Null); // No count requested.
         }
 
+        [Test]
+        public void B120_GetAll_Filter_LastName()
+        {
+            using var test = ApiTester.Create<Startup>();
+
+            var v = test.Controller<EmployeeController>()
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create().Filter("startswith(lastname, 's')"))
+                .AssertOK()
+                .GetValue<EmployeeCollectionResult>();
+
+            Assert.That(v?.Items, Is.Not.Null);
+            Assert.That(v!.Items, Has.Count.EqualTo(2));
+            Assert.That(v.Items.Select(x => x.LastName).ToArray(), Is.EqualTo(new string[] { "Smith", "Smithers" }));
+        }
+
+        [Test]
+        public void B130_GetAll_Filter_StartDateAndGenders_OrderBy_FirstName()
+        {
+            using var test = ApiTester.Create<Startup>();
+
+            var v = test.Controller<EmployeeController>()
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create().Filter("startdate ge 2010-01-01 and gender in ('m','f')").OrderBy("lastname desc"))
+                .AssertOK()
+                .GetValue<EmployeeCollectionResult>();
+
+            Assert.That(v?.Items, Is.Not.Null);
+            Assert.That(v!.Items, Has.Count.EqualTo(2));
+            Assert.That(v.Items.Select(x => x.LastName).ToArray(), Is.EqualTo(new string[] { "Smith", "Browne" }));
+        }
+
         [Test]
         public void C100_Create_Error()
         {

samples/My.Hr/My.Hr.UnitTest/EmployeeControllerTest2.cs

@@ -104,7 +104,7 @@ public void B110_GetAll_Paging()
             using var test = ApiTester.Create<Startup>().ConfigureServices(sc => sc.ReplaceScoped<IEmployeeService, EmployeeService2>());
 
             var v = test.Controller<EmployeeController>()
-                .Run(c => c.GetAllAsync(), requestOptions: new HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2, true) })
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2, true)))
                 .AssertOK()
                 .GetValue<EmployeeCollectionResult>();
 
@@ -124,7 +124,7 @@ public void B120_GetAll_PagingAndIncludeFields()
             using var test = ApiTester.Create<Startup>().ConfigureServices(sc => sc.ReplaceScoped<IEmployeeService, EmployeeService2>());
 
             var v = test.Controller<EmployeeController>()
-                .Run(c => c.GetAllAsync(), requestOptions: new HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2) }.Include("lastname"))
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2)).Include("lastname"))
                 .AssertOK()
                 .AssertJson("[ { \"lastName\": \"Jones\" }, { \"lastName\": \"Smith\" } ]")
                 .GetValue<EmployeeCollectionResult>();

samples/My.Hr/My.Hr.UnitTest/EmployeeFunctionTest.cs

@@ -112,7 +112,7 @@ public void B110_GetAll_Paging()
             using var test = FunctionTester.Create<Startup>();
 
             var v = test.HttpTrigger<EmployeeFunction>()
-                .Run(f => f.GetAllAsync(test.CreateHttpRequest(HttpMethod.Get, "api/employees", new CoreEx.Http.HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2, true) })))
+                .Run(f => f.GetAllAsync(test.CreateHttpRequest(HttpMethod.Get, "api/employees", CoreEx.Http.HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2, true)))))
                 .AssertOK()
                 .GetValue<EmployeeCollectionResult>();
 
@@ -129,7 +129,7 @@ public void B120_GetAll_PagingAndIncludeFields()
             using var test = FunctionTester.Create<Startup>();
 
             var v = test.HttpTrigger<EmployeeFunction>()
-                .Run(f => f.GetAllAsync(test.CreateHttpRequest(HttpMethod.Get, "api/employees", new CoreEx.Http.HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2, false) }.Include("lastname"))))
+                .Run(f => f.GetAllAsync(test.CreateHttpRequest(HttpMethod.Get, "api/employees", CoreEx.Http.HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2, false)).Include("lastname"))))
                 .AssertOK()
                 .AssertJson("[ { \"lastName\": \"Jones\" }, { \"lastName\": \"Smith\" } ]")
                 .GetValue<EmployeeCollectionResult>();

samples/My.Hr/My.Hr.UnitTest/EmployeeResultControllerTest.cs

@@ -117,7 +117,7 @@ public void B110_GetAll_Paging()
             using var test = ApiTester.Create<Startup>();
 
             var v = test.Controller<EmployeeResultController>()
-                .Run(c => c.GetAllAsync(), requestOptions: new HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2, true) })
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2, true)))
                 .AssertOK()
                 .GetValue<EmployeeCollectionResult>();
 
@@ -137,7 +137,7 @@ public void B120_GetAll_PagingAndIncludeFields()
             using var test = ApiTester.Create<Startup>();
 
             var v = test.Controller<EmployeeResultController>()
-                .Run(c => c.GetAllAsync(), requestOptions: new HttpRequestOptions { Paging = PagingArgs.CreateSkipAndTake(1, 2) }.Include("lastname"))
+                .Run(c => c.GetAllAsync(), requestOptions: HttpRequestOptions.Create(PagingArgs.CreateSkipAndTake(1, 2)).Include("lastname"))
                 .AssertOK()
                 .AssertJson("[ { \"lastName\": \"Jones\" }, { \"lastName\": \"Smith\" } ]")
                 .GetValue<EmployeeCollectionResult>();

src/CoreEx.AspNetCore/WebApis/PagingOperationFilter.cs

@@ -9,7 +9,7 @@
 namespace CoreEx.AspNetCore.WebApis
 {
     /// <summary>
-    /// A <i>Swagger/Swashbuckle</i> <see cref="IOperationFilter"/> to add the <see cref="PagingArgs"/> paramaters from the specification of the <see cref="PagingAttribute"/>.
+    /// A <i>Swagger/Swashbuckle</i> <see cref="IOperationFilter"/> to add the <see cref="PagingArgs"/> parameters from the specification of the <see cref="PagingAttribute"/>.
     /// </summary>
     /// <remarks>The <see cref="PagingOperationFilter"/> must be added when registering services (DI) during application startup; example as follows:
     /// <code>
@@ -67,7 +67,7 @@ public void Apply(OpenApiOperation operation, OperationFilterContext context)
         /// <summary>
         /// Create the parameter definition.
         /// </summary>
-        private static OpenApiParameter CreateParameter(string name, string description, string typeName, string? format = null) => new()
+        internal static OpenApiParameter CreateParameter(string name, string description, string typeName, string? format = null) => new()
         {
             Name = name,
             Description = description,