Add MSSqlClient project and enhance documentation

- Updated solution file to include `Open.Database.Extensions.MSSqlClient` and `Source\Directory.Build.props`.
- Expanded `README.md` with a new "Principles" section and updated "Features" and "8.0 Release Notes".
- Added XML documentation comments to constructors in `ExpressiveCommand`, `ExpressiveCommandBase`, `ExpressiveDbCommand`, and `ExpressiveDbCommandBase` for improved clarity.
- Refactored connection management methods in `ConnectionProvider.Command.cs` to utilize the new `AsPool` method.
- Enhanced `Retrieve.cs` with a `SuppressMessage` attribute and improved handling of cancellation tokens in asynchronous methods.
- Added `using System.Data.Common` directive in `IDbConnectionFactory.cs` for better clarity.
- Updated `DbConnectionFactoryExtensions` to include new overloads for the `AsPool` method, enhancing flexibility in connection management.

Author: electricessence

Open.Database.Extensions.sln

@@ -19,6 +19,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 	ProjectSection(SolutionItems) = preProject
 		.editorconfig = .editorconfig
 		Source\Directory.Build.props = Source\Directory.Build.props
+		README.md = README.md
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Open.Database.Extensions.MSSqlClient", "Source\MSSqlClient\Open.Database.Extensions.MSSqlClient.csproj", "{B9245504-9E2F-417F-87AC-8950BFB4FD4E}"

README.md

@@ -4,24 +4,30 @@
 
 Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.
 
-## Connection Factories
+## Principles
+
+- Minimize connection open time.
+- Deferred/lazy transformation.
+- Optimize for specific use cases.
+- Minimize boilerplate code.
+
+## Features
+- Provides a fluent interface for database operations.
+- Supports dependency injection for connection factories.
+- Support both synchronous and asynchronous operations.
+- Provides expressive commands for executing SQL queries and stored procedures.
+
+### Connection Factories
 
 Connection factories facilitate creation and disposal of connections without the concern of a connection reference or need for awareness of a connection string.
 A `SqlConnectionFactory` is provided and can be overridden to provide more specific dependency injection configurations.
 
-## Expressive Commands
+### Expressive Commands
 
 The provided expressive command classes allow for an expressive means to append parameters and execute the results without lengthy complicated setup.
 
 Extensions are provided to create commands from connection factories.
 
-## 8.0 Release Notes
-
-  - All `.ConfigureAwait(true)` are now `.ConfigureAwait(false)` as they should be.  The caller will need to `.ConfigureAwait(true)` if they need to resume on the calling context.
-  - Added `Open.Database.Extensions.MSSqlClient` for `Microsoft.Data.SqlClient` support.
-  - .NET 8.0 added to targets to ensure potential compliation and performance improvements are available.
-  - Improved nullable integrity.
-
 ### Example
 
 ```cs
@@ -127,3 +133,10 @@ public static bool TryTransaction()
             .ExecuteScalar<bool>();
     }));
 ```
+
+## 8.0 Release Notes
+
+  - All `.ConfigureAwait(true)` are now `.ConfigureAwait(false)` as they should be.  The caller will need to `.ConfigureAwait(true)` if they need to resume on the calling context.
+  - Added `Open.Database.Extensions.MSSqlClient` for `Microsoft.Data.SqlClient` support.
+  - .NET 8.0 added to targets to ensure potential compliation and performance improvements are available.
+  - Improved nullable integrity.

Source/Core/ExpressiveCommand.cs

@@ -27,6 +27,17 @@ public ExpressiveCommand(
 	{
 	}
 
+	/// <summary>Constructs a <see cref="ExpressiveCommand"/>.</summary>
+	/// <inheritdoc cref="ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.ExpressiveCommandBase(IDbConnectionFactory{TConnection}, CommandType, string, IEnumerable{ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.Param}?)" />
+	public ExpressiveCommand(
+		Func<IDbConnection> connFactory,
+		CommandType type,
+		string command,
+		IEnumerable<Param>? @params = null)
+		: base(connFactory, type, command, @params)
+	{
+	}
+
 	/// <summary>Constructs a <see cref="ExpressiveCommand"/>.</summary>
 	/// <inheritdoc cref="ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.ExpressiveCommandBase(TConnection, IDbTransaction?, CommandType, string, IEnumerable{ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.Param}?)" />
 	public ExpressiveCommand(

Source/Core/ExpressiveCommandBase.cs

@@ -71,6 +71,16 @@ protected ExpressiveCommandBase(
 	{
 	}
 
+	/// <inheritdoc cref="ExpressiveCommandBase(IDbConnectionFactory{TConnection}, CommandType, string, IEnumerable{Param}?)"/>
+	protected ExpressiveCommandBase(
+		Func<TConnection> connFactory,
+		CommandType type,
+		string command,
+		IEnumerable<Param>? @params)
+		: this((connFactory ?? throw new ArgumentNullException(nameof(connFactory))).AsPool(), type, command, @params)
+	{
+	}
+
 	/// <summary>Constructs a <see cref="ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}"/>.</summary>
 	/// <param name="connection">The connection to execute the command on.</param>
 	/// <param name="transaction">The optional transaction to execute the command on.</param>

Source/Core/ExpressiveDbCommand.cs

@@ -27,6 +27,16 @@ public ExpressiveDbCommand(
 	{
 	}
 
+	/// <inheritdoc cref="ExpressiveDbCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.ExpressiveDbCommandBase(IDbConnectionFactory{TConnection}, CommandType, string, IEnumerable{ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.Param}?)"/>
+	public ExpressiveDbCommand(
+		Func<DbConnection> connFactory,
+		CommandType type,
+		string command,
+		IEnumerable<Param>? @params = null)
+	: base(connFactory.AsPool(), type, command, @params)
+	{
+	}
+
 	/// <summary>Constructs a <see cref="ExpressiveDbCommand"/>.</summary>
 	/// <inheritdoc />
 	public ExpressiveDbCommand(

Source/Core/ExpressiveDbCommandBase.cs

@@ -45,6 +45,16 @@ protected ExpressiveDbCommandBase(
 	{
 	}
 
+	/// <inheritdoc cref="ExpressiveDbCommandBase(IDbConnectionFactory{TConnection}, CommandType, string, IEnumerable{ExpressiveCommandBase{TConnection, TCommand, TReader, TDbType, TThis}.Param}?)"/>
+	protected ExpressiveDbCommandBase(
+		Func<TConnection> connFactory,
+		CommandType type,
+		string command,
+		IEnumerable<Param>? @params = null)
+		: base(connFactory, type, command, @params)
+	{
+	}
+
 	/// <summary>Constructs a an expressive command.</summary>
 	/// <param name="connection">The connection to execute the command on.</param>
 	/// <param name="transaction">The optional transaction to execute the command on.</param>

Source/Core/Extensions/ConnectionProvider.Command.cs

@@ -192,7 +192,7 @@ public static ExpressiveCommand Command(
 		this Func<IDbConnection> connectionSource,
 		string command,
 		CommandType type = CommandType.Text)
-		=> Command(DbConnectionFactory.Create(connectionSource), command, type);
+		=> Command(connectionSource.AsPool(), command, type);
 
 	/// <summary>
 	/// Creates an <see cref="ExpressiveCommand"/> with command type set to <see cref="CommandType.StoredProcedure"/> for subsequent configuration and execution.
@@ -216,7 +216,7 @@ public static ExpressiveDbCommand Command<TConnection>(
 		string command,
 		CommandType type = CommandType.Text)
 		where TConnection : DbConnection
-		=> Command(DbConnectionFactory.Create(connectionSource), command, type);
+		=> Command(connectionSource.AsPool(), command, type);
 
 	/// <summary>
 	/// Creates an <see cref="ExpressiveDbCommand"/> with command type set to <see cref="CommandType.StoredProcedure"/> for subsequent configuration and execution.
@@ -228,5 +228,5 @@ public static ExpressiveDbCommand StoredProcedure<TConnection>(
 		this Func<TConnection> connectionSource,
 		string procedureName)
 		where TConnection : DbConnection
-		=> StoredProcedure(DbConnectionFactory.Create(connectionSource), procedureName);
+		=> StoredProcedure(connectionSource.AsPool(), procedureName);
 }

Source/Core/Extensions/Retrieve.cs

@@ -1,6 +1,7 @@
 
 namespace Open.Database.Extensions;
 
+[SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Internal function that requires a cancellation token.")]
 public static partial class CoreExtensions
 {
 	internal static QueryResultQueue<object[]> RetrieveInternal(
@@ -141,12 +142,9 @@ public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 		CancellationToken cancellationToken)
 		=> RetrieveAsync(reader, true, cancellationToken);
 
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Internal function that requires a cancellation token.")]
 	static ValueTask<QueryResultQueue<object[]>> RetrieveAsyncInternal(DbDataReader reader, CancellationToken cancellationToken, IEnumerable<int> ordinals, IEnumerable<string>? columnNames = null, bool readStarted = false, bool useReadAsync = true)
 		=> RetrieveAsyncInternal(null, reader, cancellationToken, ordinals, columnNames, readStarted, useReadAsync)!;
 
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Internal function that requires a cancellation token.")]
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Style", "IDE0046:Convert to conditional expression", Justification = "<Pending>")]
 	static async ValueTask<QueryResultQueue<object[]>> RetrieveAsyncInternal(ArrayPool<object>? arrayPool, DbDataReader reader, CancellationToken cancellationToken, IEnumerable<int> ordinals, IEnumerable<string>? columnNames = null, bool readStarted = false, bool useReadAsync = true)
 	{
 		if (reader is null) throw new ArgumentNullException(nameof(reader));
@@ -237,7 +235,6 @@ public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 	/// <param name="n">The first ordinal to include in the request to the reader for each record.</param>
 	/// <param name="others">The remaining ordinals to request from the reader for each record.</param>
 	/// <inheritdoc cref="RetrieveAsync(DbDataReader, IEnumerable{int}, bool, CancellationToken)" />
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Method takes params and cannot have a the cancellation token last.")]
 	public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 		this DbDataReader reader,
 		CancellationToken cancellationToken,
@@ -295,7 +292,6 @@ public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 	/// <param name="c">The first column name to include in the request to the reader for each record.</param>
 	/// <param name="others">The remaining column names to request from the reader for each record.</param>
 	/// <inheritdoc cref="RetrieveAsync(DbDataReader, IEnumerable{string}, bool, bool, CancellationToken)"/>
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Method takes params and cannot have a the cancellation token last.")]
 	public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 		this DbDataReader reader,
 		CancellationToken cancellationToken,
@@ -322,7 +318,6 @@ public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 		CancellationToken cancellationToken)
 		=> RetrieveAsync(command, true, cancellationToken);
 
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Internal function that requires a cancellation token.")]
 	static ValueTask<QueryResultQueue<object[]>> RetrieveAsyncInternal(
 		DbCommand command,
 		CancellationToken cancellationToken,
@@ -362,7 +357,6 @@ public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 	/// <param name="n">The first ordinal to include in the request to the reader for each record.</param>
 	/// <param name="others">The remaining ordinals to request from the reader for each record.</param>
 	/// <inheritdoc cref="RetrieveAsync(DbCommand, IEnumerable{string}, bool, bool, CancellationToken)"/>
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Method takes params and cannot have a the cancellation token last.")]
 	public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 		this DbCommand command,
 		CancellationToken cancellationToken,
@@ -411,7 +405,6 @@ public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 	/// <param name="columnName">The first column name to include in the request to the reader for each record.</param>
 	/// <param name="otherColumnNames">The remaining column names to request from the reader for each record.</param>
 	/// <inheritdoc cref="RetrieveAsync(DbCommand, IEnumerable{string}, bool, bool, CancellationToken)"/>
-	[System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1068:CancellationToken parameters must come last", Justification = "Method takes params and cannot have a the cancellation token last.")]
 	public static ValueTask<QueryResultQueue<object[]>> RetrieveAsync(
 		this DbCommand command,
 		CancellationToken cancellationToken,

Source/Core/Extensions/_.cs

@@ -45,7 +45,6 @@ internal static IEnumerable<T> Concat<T>(T first, ICollection<T> remaining)
 	public static Span<object?> CopyToDBNullAsNull(this Span<object?> values, Span<object?> target)
 		=> CopyToDBNullAsNull((ReadOnlySpan<object?>)values, target);
 
-
 	/// <inheritdoc cref="CopyToDBNullAsNull(ReadOnlySpan{object?}, Span{object?})"/>
 	public static Span<object?> CopyToDBNullAsNull(this ReadOnlySpan<object?> values, Memory<object?> target)
 		=> CopyToDBNullAsNull(values, target.Span);

Source/Core/IDbConnectionFactory.cs

@@ -1,4 +1,6 @@
-namespace Open.Database.Extensions;
+using System.Data.Common;
+
+namespace Open.Database.Extensions;
 
 /// <summary>
 /// Common interface for creating a connection.  Can easily be used with dependency injection.
@@ -77,6 +79,10 @@ public void Give(IDbConnection connection)
 	public static ConnectionFactoryToPoolAdapter AsPool(this IDbConnectionFactory connectionFactory)
 		=> new (connectionFactory);
 
+	/// <inheritdoc cref="AsPool(IDbConnectionFactory)"/>
+	public static ConnectionFactoryToPoolAdapter AsPool(this Func<IDbConnection> connectionFactory)
+		=> new(connectionFactory);
+
 	/// <summary>
 	/// Provides a connection pool that simply creates from a connection factory and disposes when returned.
 	/// </summary>
@@ -86,6 +92,11 @@ public static ConnectionFactoryToPoolAdapter<TConnection> AsPool<TConnection>(th
 		where TConnection : IDbConnection
 		=> new (connectionFactory);
 
+	/// <inheritdoc cref="AsPool{TConnection}(IDbConnectionFactory{TConnection})"/>
+	public static ConnectionFactoryToPoolAdapter<TConnection> AsPool<TConnection>(this Func<TConnection> connectionFactory)
+		where TConnection : IDbConnection
+		=> new(connectionFactory);
+
 	/// <summary>
 	/// Coerces a non-generic connection factory to a generic one.
 	/// </summary>