Merge pull request #32 from yv989c/feature/order-guarantees

Feature/order guarantees

Author: yv989c

README.md

@@ -10,25 +10,20 @@
 
 > 🤔💭 TLDR; By using QueryableValues, you can incorporate in-memory collections into your EF queries with outstanding performance and flexibility.
 
-This library allows you to efficiently compose an [IEnumerable<T>] in your [Entity Framework Core] queries when using the [SQL Server Database Provider]. This is accomplished by using the `AsQueryableValues` extension method available on the [DbContext] class. Everything is evaluated on the server with a single round trip, in a way that preserves the query's [execution plan], even when the values behind the [IEnumerable<T>] are changed on subsequent executions.
+This library allows you to efficiently compose an [IEnumerable<T>] in your [Entity Framework Core] queries when using the [SQL Server Database Provider]. You can accomplish this by using the `AsQueryableValues` extension method that's available on the [DbContext] class. The query is processed in a single round trip to the server, in a way that preserves its [execution plan], even when the values within the [IEnumerable<T>] are changed on subsequent executions.
 
-The supported types for `T` are:
-- Simple Type: [Byte], [Int16], [Int32], [Int64], [Decimal], [Single], [Double], [DateTime], [DateTimeOffset], [Guid], [Char], and [String].
-- Complex Type:
-  - Can be an anonymous type.
-  - Can be a user-defined class or struct with read/write properties and a public constructor.
-  - Must have one or more simple type properties, including [Boolean].
+**Highlights**
+- ✨ Enables the composition of in-memory data within your queries, utilizing both simple and complex types.
+- 👌 Works with all versions of SQL Server supported by [Entity Framework Core].
+- ⚡ Automatically uses the most efficient strategy compatible with your SQL Server instance and configuration.
+- ✅ Boasts over 140 tests for reliability and compatibility, giving you added confidence.
 
 For a detailed explanation of the problem solved by QueryableValues, please continue reading [here][readme-background].
 
-> ✅ QueryableValues boasts over 120 integration tests that are executed on every supported version of EF. These tests ensure reliability and compatibility, giving you added confidence.
-
 > 💡 Still on Entity Framework 6 (non-core)? Then [QueryableValues `EF6 Edition`](https://github.com/yv989c/BlazarTech.QueryableValues.EF6) is what you need.
 
 ## When Should You Use It?
-The `AsQueryableValues` extension method is intended for queries that are dependent upon a *non-constant* sequence of external values. In such cases, the underlying SQL query will be efficient on subsequent executions.
-
-It provides a solution to the following long standing [EF Core issue](https://github.com/dotnet/efcore/issues/13617) and enables other currently unsupported scenarios; like the ability to efficiently create joins with in-memory data.
+The `AsQueryableValues` extension method is intended for queries that are dependent upon a *non-constant* sequence of external values. It provides a solution to the following [EF Core issue](https://github.com/dotnet/efcore/issues/13617) and enables other currently unsupported scenarios; like the ability to efficiently create joins with in-memory data.
 
 ## Your Support is Appreciated!
 If you feel that this solution has provided you some value, please consider [buying me a ☕][BuyMeACoffee].
@@ -83,7 +78,7 @@ public class Startup
     }
 }
 ```
-> 💡 Pro-tip: `UseQueryableValues` offers an optional `options` delegate for additional configurations.
+> 💡 `UseQueryableValues` offers an optional `options` delegate for additional configurations.
 
 ## How Do You Use It?
 The `AsQueryableValues` extension method is provided by the `BlazarTech.QueryableValues` namespace; therefore, you must add the following `using` directive to your source code file for it to appear as a method of your [DbContext] instance:
@@ -96,6 +91,9 @@ using BlazarTech.QueryableValues;
 Below are a few examples composing a query using the values provided by an [IEnumerable<T>].
 
 ### Simple Type Examples
+
+> 💡 Supports [Byte], [Int16], [Int32], [Int64], [Decimal], [Single], [Double], [DateTime], [DateTimeOffset], [Guid], [Char], and [String].
+
 Using the [Contains][ContainsQueryable] LINQ method:
 
 ```c#
@@ -155,13 +153,30 @@ var myQuery2 =
     };
 ```
 ### Complex Type Example
+
+> 💡 Must be an anonymous or user-defined type with one or more simple type properties, including [Boolean].
+
 ```c#
 // Performance Tip:
 // If your IEnumerable<T> item type (T) has many properties, project only 
 // the ones you need to a new variable and use it in your query.
 var projectedItems = items.Select(i => new { i.CategoryId, i.ColorName });
 
-var myQuery = 
+// Example #1 (LINQ method syntax)
+var myQuery1 = dbContext.Product
+    .Join(
+        dbContext.AsQueryableValues(projectedItems),
+        p => new { p.CategoryId, p.ColorName },
+        pi => new { pi.CategoryId, pi.ColorName },
+        (p, pi) => new
+        {
+            p.ProductId,
+            p.Description
+        }
+    );
+
+// Example #2 (LINQ query syntax)
+var myQuery2 = 
     from p in dbContext.Product
     join pi in dbContext.AsQueryableValues(projectedItems) on new { p.CategoryId, p.ColorName } equals new { pi.CategoryId, pi.ColorName }
     select new
@@ -170,10 +185,11 @@ var myQuery =
         p.Description
     };
 ```
+
 **About Complex Types**
-> :warning: All the data provided by this type is transmitted to the server; therefore, ensure that it only contains the properties you need for your query. Not following this recommendation will degrade the query's performance.
+> ⚠️ All the data provided by this type is transmitted to the server; therefore, ensure that it only contains the properties you need for your query. Not following this recommendation will degrade the query's performance.
 
-> :warning: There is a limit of up to 10 properties for any given simple type (e.g. cannot have more than 10 [Int32] properties). Exceeding that limit will cause an exception and may also suggest that you should rethink your strategy.
+> ⚠️ There is a limit of up to 10 properties for any given simple type (e.g. cannot have more than 10 [Int32] properties). Exceeding that limit will cause an exception and may also suggest that you should rethink your strategy.
 
 # Benchmarks
 The following [benchmarks] consist of simple EF Core queries that have a dependency on a random sequence of [Int32], [Guid], and [String] values via the `Contains` LINQ method. It shows the performance differences between not using and using QueryableValues. In practice, the benefits of using QueryableValues are more dramatic on complex EF Core queries and busy environments.
@@ -404,7 +420,7 @@ Now, focus your attention to the first query of the green section. Here you can
 
 ## What Makes This Work? 🤓
 
-> 🎉 QueryableValues now supports JSON serialization, which improves its performance compared to using XML. By default, QueryableValues will attempt to use JSON if it is supported.
+> 🎉 QueryableValues now supports JSON serialization, which improves its performance compared to using XML. By default, QueryableValues will attempt to use JSON if it is supported by your SQL Server instance and database configuration.
 
 QueryableValues makes use of the XML parsing capabilities in SQL Server, which are available in all the supported versions of SQL Server to date. The provided sequence of values are serialized as XML and embedded in the underlying SQL query using a native XML parameter, then it uses SQL Server's XML type methods to project the query in a way that can be mapped by [Entity Framework Core].
 

Version.xml

@@ -1,8 +1,8 @@
 <Project>
 	<PropertyGroup>
-		<VersionEFCore3>3.7.0</VersionEFCore3>
-		<VersionEFCore5>5.7.0</VersionEFCore5>
-		<VersionEFCore6>6.7.0</VersionEFCore6>
-		<VersionEFCore7>7.2.0</VersionEFCore7>
+		<VersionEFCore3>3.8.0</VersionEFCore3>
+		<VersionEFCore5>5.8.0</VersionEFCore5>
+		<VersionEFCore6>6.8.0</VersionEFCore6>
+		<VersionEFCore7>7.3.0</VersionEFCore7>
 	</PropertyGroup>
 </Project>

docs/README.md

@@ -6,25 +6,20 @@
 
 > 🤔💭 TLDR; By using QueryableValues, you can incorporate in-memory collections into your EF queries with outstanding performance and flexibility.
 
-This library allows you to efficiently compose an [IEnumerable<T>] in your [Entity Framework Core] queries when using the [SQL Server Database Provider]. This is accomplished by using the `AsQueryableValues` extension method available on the [DbContext] class. Everything is evaluated on the server with a single round trip, in a way that preserves the query's [execution plan], even when the values behind the [IEnumerable<T>] are changed on subsequent executions.
+This library allows you to efficiently compose an [IEnumerable<T>] in your [Entity Framework Core] queries when using the [SQL Server Database Provider]. You can accomplish this by using the `AsQueryableValues` extension method that's available on the [DbContext] class. The query is processed in a single round trip to the server, in a way that preserves its [execution plan], even when the values within the [IEnumerable<T>] are changed on subsequent executions.
 
-The supported types for `T` are:
-- Simple Type: [Byte], [Int16], [Int32], [Int64], [Decimal], [Single], [Double], [DateTime], [DateTimeOffset], [Guid], [Char], and [String].
-- Complex Type:
-  - Can be an anonymous type.
-  - Can be a user-defined class or struct with read/write properties and a public constructor.
-  - Must have one or more simple type properties, including [Boolean].
+**Highlights**
+- ✨ Enables the composition of in-memory data within your queries, utilizing both simple and complex types.
+- 👌 Works with all versions of SQL Server supported by [Entity Framework Core].
+- ⚡ Automatically uses the most efficient strategy compatible with your SQL Server instance and configuration.
+- ✅ Boasts over 140 tests for reliability and compatibility, giving you added confidence.
 
 For a detailed explanation of the problem solved by QueryableValues, please continue reading [here][readme-background].
 
-> ✅ QueryableValues boasts over 120 integration tests that are executed on every supported version of EF. These tests ensure reliability and compatibility, giving you added confidence.
-
 > 💡 Still on Entity Framework 6 (non-core)? Then [QueryableValues `EF6 Edition`](https://github.com/yv989c/BlazarTech.QueryableValues.EF6) is what you need.
 
 ## When Should You Use It?
-The `AsQueryableValues` extension method is intended for queries that are dependent upon a *non-constant* sequence of external values. In such cases, the underlying SQL query will be efficient on subsequent executions.
-
-It provides a solution to the following long standing [EF Core issue](https://github.com/dotnet/efcore/issues/13617) and enables other currently unsupported scenarios; like the ability to efficiently create joins with in-memory data.
+The `AsQueryableValues` extension method is intended for queries that are dependent upon a *non-constant* sequence of external values. It provides a solution to the following [EF Core issue](https://github.com/dotnet/efcore/issues/13617) and enables other currently unsupported scenarios; like the ability to efficiently create joins with in-memory data.
 
 ## Your Support is Appreciated!
 If you feel that this solution has provided you some value, please consider [buying me a ☕][BuyMeACoffee].
@@ -79,7 +74,7 @@ public class Startup
     }
 }
 ```
-> 💡 Pro-tip: `UseQueryableValues` offers an optional `options` delegate for additional configurations.
+> 💡 `UseQueryableValues` offers an optional `options` delegate for additional configurations.
 
 ## How Do You Use It?
 The `AsQueryableValues` extension method is provided by the `BlazarTech.QueryableValues` namespace; therefore, you must add the following `using` directive to your source code file for it to appear as a method of your [DbContext] instance:
@@ -92,6 +87,9 @@ using BlazarTech.QueryableValues;
 Below are a few examples composing a query using the values provided by an [IEnumerable<T>].
 
 ### Simple Type Examples
+
+> 💡 Supports [Byte], [Int16], [Int32], [Int64], [Decimal], [Single], [Double], [DateTime], [DateTimeOffset], [Guid], [Char], and [String].
+
 Using the [Contains][ContainsQueryable] LINQ method:
 
 ```c#
@@ -151,13 +149,30 @@ var myQuery2 =
     };
 ```
 ### Complex Type Example
+
+> 💡 Must be an anonymous or user-defined type with one or more simple type properties, including [Boolean].
+
 ```c#
 // Performance Tip:
 // If your IEnumerable<T> item type (T) has many properties, project only 
 // the ones you need to a new variable and use it in your query.
 var projectedItems = items.Select(i => new { i.CategoryId, i.ColorName });
 
-var myQuery = 
+// Example #1 (LINQ method syntax)
+var myQuery1 = dbContext.Product
+    .Join(
+        dbContext.AsQueryableValues(projectedItems),
+        p => new { p.CategoryId, p.ColorName },
+        pi => new { pi.CategoryId, pi.ColorName },
+        (p, pi) => new
+        {
+            p.ProductId,
+            p.Description
+        }
+    );
+
+// Example #2 (LINQ query syntax)
+var myQuery2 = 
     from p in dbContext.Product
     join pi in dbContext.AsQueryableValues(projectedItems) on new { p.CategoryId, p.ColorName } equals new { pi.CategoryId, pi.ColorName }
     select new
@@ -166,10 +181,11 @@ var myQuery =
         p.Description
     };
 ```
+
 **About Complex Types**
-> :warning: All the data provided by this type is transmitted to the server; therefore, ensure that it only contains the properties you need for your query. Not following this recommendation will degrade the query's performance.
+> ⚠️ All the data provided by this type is transmitted to the server; therefore, ensure that it only contains the properties you need for your query. Not following this recommendation will degrade the query's performance.
 
-> :warning: There is a limit of up to 10 properties for any given simple type (e.g. cannot have more than 10 [Int32] properties). Exceeding that limit will cause an exception and may also suggest that you should rethink your strategy.
+> ⚠️ There is a limit of up to 10 properties for any given simple type (e.g. cannot have more than 10 [Int32] properties). Exceeding that limit will cause an exception and may also suggest that you should rethink your strategy.
 
 ## Do You Want To Know More? 📚
 Please take a look at the [repository][Repository].

src/QueryableValues.SqlServer.EFCore7/QueryableValues.SqlServer.EFCore7.csproj

@@ -10,6 +10,6 @@
 	</PropertyGroup>
 
 	<ItemGroup>
-		<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="[7.0,8.0)" />
+		<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="[7.0,)" />
 	</ItemGroup>
 </Project>