Update docs and nuget package description

yv989c · yv989c · commit 80a9cffbe192 · 2022-01-03T22:58:48.000-05:00
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 </p>
 
 # QueryableValues [![CI/CD Workflow](https://github.com/yv989c/BlazarTech.QueryableValues/actions/workflows/ci-workflow.yml/badge.svg)](https://github.com/yv989c/BlazarTech.QueryableValues/actions/workflows/ci-workflow.yml)
-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]. 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.
 
 The supported types for `T` are:
 - Simple Type: [Byte], [Int16], [Int32], [Int64], [Decimal], [Single], [Double], [DateTime], [DateTimeOffset], [Guid], [Char], and [String].
@@ -22,7 +22,7 @@ It provides a solution to the following long standing [EF Core issue](https://gi
 ## Getting Started
 
 ### Installation
-QueryableValues is distributed as a [NuGet Package]. The major version number of this library is aligned with the version of [Entity Framework Core] by which it’s supported (e.g. If you are using EF Core 5, then you must use version 5 of QueryableValues).
+QueryableValues is distributed as a [NuGet Package]. The major version number of this library is aligned with the version of [Entity Framework Core] by which it's supported (e.g. If you are using EF Core 5, then you must use version 5 of QueryableValues).
 
 Please choose the appropriate command below to install it using the NuGet Package Manager Console window in Visual Studio:
 
@@ -144,8 +144,8 @@ var myQuery2 =
 #### Complex Type Example
 ```c#
 // Performance Tip:
-// If your IEnumerable<T> variable’s item type has many properties,
-// project only the ones you need to a new variable and use it in your query.
+// 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 = 
@@ -158,7 +158,7 @@ var myQuery =
     };
 ```
 **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.
+> :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.
 
 > :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.
 
@@ -180,9 +180,9 @@ var myQuery = dbContext.MyEntities
         i.PropC
     });
 ```
-The previous query will yield the expected results, but there’s a catch. If the sequence of values in our list *is different* on every execution, the underline SQL query will be built in a way that’s not optimal for SQL Server’s query engine. Wasting system resources like CPU, memory, IO, and potentially affecting other queries in the instance.
+The previous query will yield the expected results, but there's a catch. If the sequence of values in our list *is different* on every execution, the underline SQL query will be built in a way that's not optimal for SQL Server's query engine. Wasting system resources like CPU, memory, IO, and potentially affecting other queries in the instance.
 
-Let’s take a look at the following query and the SQL that is generated by the [SQL Server Database Provider] as of version 5.0.11 when the query is materialized:
+Let's take a look at the following query and the SQL that is generated by the [SQL Server Database Provider] as of version 5.0.11 when the query is materialized:
 
 ```c#
 var listOfValues = new List<int> { 1, 2, 3 };
@@ -207,20 +207,20 @@ WHERE [m].[MyEntityID] IN (1, 2, 3) OR ([m].[PropB] = @__p_1)',N'@__p_1 bigint',
 ```
 Here we can observe that the values in our list are being hardcoded as part of the SQL statement provided to [sp_executesql] as opposed to them being injected via a parameter, as is the case for our other variable holding the value 100.
 
-Now, let’s add another item to the list of values and execute the query again:
+Now, let's add another item to the list of values and execute the query again:
 ```tsql
 exec sp_executesql N'SELECT [m].[MyEntityID], [m].[PropA]
 FROM [dbo].[MyEntity] AS [m]
 WHERE [m].[MyEntityID] IN (1, 2, 3, 4) OR ([m].[PropB] = @__p_1)',N'@__p_1 bigint',@__p_1=100
 ```
-As we can see, a new SQL statement was generated just because we modified the list that’s being used in our `Where` predicate. This has the detrimental effect that a previously cached execution plan cannot be reused, forcing SQL Server’s query engine to compute a new [execution plan] *every time* it is provided with a SQL statement that it hasn’t seen before and increasing the likelihood of flushing other plans in the process.
+As we can see, a new SQL statement was generated just because we modified the list that's being used in our `Where` predicate. This has the detrimental effect that a previously cached execution plan cannot be reused, forcing SQL Server's query engine to compute a new [execution plan] *every time* it is provided with a SQL statement that it hasn't seen before and increasing the likelihood of flushing other plans in the process.
 
 ## Enter AsQueryableValues 🙌
 ![Parameterize All the Things](/docs/images/parameterize-all-the-things.jpg)
 
 This library provides you with the `AsQueryableValues` extension method made available on the [DbContext] class. It solves the problem explained above by allowing you to build a query that will generate a SQL statement for [sp_executesql] that will remain constant execution after execution, allowing SQL Server to do its best every time by using a previously cached [execution plan]. This will speed up your query on subsequent executions, and conserve system resources.
 
-Let’s take a look at the following query making use of this method, which is functionally equivalent to the previous example:
+Let's take a look at the following query making use of this method, which is functionally equivalent to the previous example:
 ```c#
 var myQuery = dbContext.MyEntities
     .Where(i =>
@@ -246,7 +246,7 @@ WHERE EXISTS (
     ) AS [q]
     WHERE [q].[V] = [m].[MyEntityID]) OR ([m].[PropB] = @__p_1)',N'@p0 xml,@__p_1 bigint',@p0=@p3,@__p_1=100
 ```
-Now, let’s add another item to the list of values and execute the query again:
+Now, let's add another item to the list of values and execute the query again:
 ```tsql
 declare @p3 xml
 set @p3=convert(xml,N'<R><V>1</V><V>2</V><V>3</V><V>4</V></R>')
@@ -262,19 +262,19 @@ WHERE EXISTS (
 Great! The SQL statement provided to [sp_executesql] remains constant. In this case SQL Server can reuse the [execution plan] from the previous execution.
 
 ## The Numbers 📊
-You don’t have to take my word for it! Let’s see a trace of what’s going on under the hood when both of these queries are executed multiple times, adding a new value to the list after each execution. First, five executions of the one making direct use of the [Contains][ContainsEnumerable] LINQ method (orange), and then five executions of the second one making use of the `AsQueryableValues` extension method on the [DbContext] (green):
+You don't have to take my word for it! Let's see a trace of what's going on under the hood when both of these queries are executed multiple times, adding a new value to the list after each execution. First, five executions of the one making direct use of the [Contains][ContainsEnumerable] LINQ method (orange), and then five executions of the second one making use of the `AsQueryableValues` extension method on the [DbContext] (green):
 
 ![Trace](/docs/images/as-queryable-trace.png)
 <sup>Queries executed against SQL Server 2017 Express (14.0.2037) running on a resource constrained laptop.</sup>
 
 As expected, none of the queries in the orange section hit the cache. On the other hand, after the first query in the green section, all the subsequent ones hit the cache and consumed fewer resources.
 
-Now, focus your attention to the first query of the green section. Here you can observe that there’s a cost associated with this technique, but this cost can be offset in the long run, especially when your queries are not trivial like the ones in these examples.
+Now, focus your attention to the first query of the green section. Here you can observe that there's a cost associated with this technique, but this cost can be offset in the long run, especially when your queries are not trivial like the ones in these examples.
 
 ## What Makes This Work? 🤓
-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].
+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].
 
-This is a technique that I have not seen being used by other popular libraries that aim to solve this problem. It is superior from a latency standpoint because it resolves the query with a single round trip to the database and most importantly, it preserves the query’s [execution plan] even when the content of the XML is changed.
+This is a technique that I have not seen being used by other popular libraries that aim to solve this problem. It is superior from a latency standpoint because it resolves the query with a single round trip to the database and most importantly, it preserves the query's [execution plan] even when the content of the XML is changed.
 
 ## One More Thing 👀
 The `AsQueryableValues` extension method allows you to treat a sequence of values as you normally would if these were another entity in your [DbContext]. The type returned by the extension is an [IQueryable\<T\>] that can be composed with other entities in your query.
diff --git a/docs/README.md b/docs/README.md
@@ -1,36 +1,36 @@
 # QueryableValues
 
-This library allows us to efficiently compose an [IEnumerable<T>] in our [Entity Framework Core] queries when using the [SQL Server Database Provider]. This is done by using the `AsQueryableValues` extension method that is made available on the [DbContext] class. Everything is evaluated on the server with a single roundtrip, 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]. 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.
 
 The supported types for `T` are:
-- Simple Type: [Int32], [Int64], [Decimal], [Double], [DateTime], [DateTimeOffset], [Guid], and [String].
+- 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.
+  - 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].
 
 For a detailed explanation, please continue reading [here][readme-background].
 
-## When Should I Use It?
-The `AsQueryableValues` extension method is intended for queries that are dependent on a *non-constant* sequence of external values. In this case, the underline SQL query will be efficient on subsequent executions.
+## 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.
+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.
 
 ## Getting Started
 
 ### Installation
-QueryableValues is distributed as a [NuGet Package]. The major version number of this library is aligned with the version of [Entity Framework Core] that's supported by it; for example, if you are using EF Core 5, then you must use version 5 of QueryableValues.
+QueryableValues is distributed as a [NuGet Package]. The major version number of this library is aligned with the version of [Entity Framework Core] by which it's supported (e.g. If you are using EF Core 5, then you must use version 5 of QueryableValues).
 
 Please choose the appropriate command below to install it using the NuGet Package Manager Console window in Visual Studio:
 
 EF Core | Command
 :---: | ---
-3.x | `Install-Package BlazarTech.QueryableValues.SqlServer -Version 3.2.0`
-5.x | `Install-Package BlazarTech.QueryableValues.SqlServer -Version 5.2.0`
-6.x | `Install-Package BlazarTech.QueryableValues.SqlServer -Version 6.2.0`
+3.x | `Install-Package BlazarTech.QueryableValues.SqlServer -Version 3.3.0`
+5.x | `Install-Package BlazarTech.QueryableValues.SqlServer -Version 5.3.0`
+6.x | `Install-Package BlazarTech.QueryableValues.SqlServer -Version 6.3.0`
 
 ### Configuration
-Look for the place in your code where you are setting up your [DbContext] and calling the [UseSqlServer] extension method, then use a lambda expression to access the `SqlServerDbContextOptionsBuilder` provided by it. It is on this builder that you must call the `UseQueryableValues` extension method, as shown in the following simplified examples:
+Look for the place in your code where you are setting up your [DbContext] and calling the [UseSqlServer] extension method, then use a lambda expression to access the `SqlServerDbContextOptionsBuilder` provided by it. It is on this builder that you must call the `UseQueryableValues` extension method as shown in the following simplified examples:
 
 When using the `OnConfiguring` method inside your [DbContext]:
 ```c#
@@ -71,13 +71,13 @@ public class Startup
 }
 ```
 
-### How Do I 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 in order for it to appear as a method of your [DbContext] instance:
+### 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:
 ```
 using BlazarTech.QueryableValues;
 ```
 
-Below you can find a few examples composing a query using the values provided by an [IEnumerable<T>].
+Below are a few examples composing a query using the values provided by an [IEnumerable<T>].
 
 #### Simple Type Examples
 Using the [Contains][ContainsQueryable] LINQ method:
@@ -138,10 +138,11 @@ var myQuery2 =
         i.PropA
     });
 ```
-#### Complex Type Examples
+#### Complex Type Example
 ```c#
-// If your IEnumerable<T> variable's item type is a complex type with many properties,
-// project only what you need to a new variable and use it in your query.
+// 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 = 
@@ -154,12 +155,12 @@ var myQuery =
     };
 ```
 **About Complex Types**
-> :warning: All the data provided by this type is transmitted to the server, therefore, ensure that it only contains the properties that you need for your query. Not following this recommendation will degrade the query's performance.
+> :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.
 
-> :warning: There is a limit of up to ten properties for any given simple type (e.g., cannot have more than ten [Int32] properties). Exceeding that limit will cause an exception and may also be a sign that you should rethink your strategy.
+> :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.
 
-## Do You Want to Know More? 📚
-Please take a look at the repository [here](https://github.com/yv989c/BlazarTech.QueryableValues).
+## Do You Want To Know More? 📚
+Please take a look at the [repository](https://github.com/yv989c/BlazarTech.QueryableValues).
 
 
 [Entity Framework Core]: https://docs.microsoft.com/en-us/ef/core/
@@ -176,11 +177,16 @@ Please take a look at the repository [here](https://github.com/yv989c/BlazarTech
 [NuGet Package]: https://www.nuget.org/packages/BlazarTech.QueryableValues.SqlServer/
 [readme-background]: https://github.com/yv989c/BlazarTech.QueryableValues#background-
 [execution plan]: https://docs.microsoft.com/en-us/sql/relational-databases/query-processing-architecture-guide?#execution-plan-caching-and-reuse
+[Boolean]: https://docs.microsoft.com/en-us/dotnet/api/system.boolean
+[Byte]: https://docs.microsoft.com/en-us/dotnet/api/system.byte
+[Int16]: https://docs.microsoft.com/en-us/dotnet/api/system.int16
 [Int32]: https://docs.microsoft.com/en-us/dotnet/api/system.int32
 [Int64]: https://docs.microsoft.com/en-us/dotnet/api/system.int64
 [Decimal]: https://docs.microsoft.com/en-us/dotnet/api/system.decimal
+[Single]: https://docs.microsoft.com/en-us/dotnet/api/system.single
 [Double]: https://docs.microsoft.com/en-us/dotnet/api/system.double
 [DateTime]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime
 [DateTimeOffset]: https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset
 [Guid]: https://docs.microsoft.com/en-us/dotnet/api/system.guid
+[Char]: https://docs.microsoft.com/en-us/dotnet/api/system.char
 [String]: https://docs.microsoft.com/en-us/dotnet/api/system.string
diff --git a/src/SharedProjectProperties.xml b/src/SharedProjectProperties.xml
