Add Open.Database.Extensions project and refactor code

- Updated solution file to include new project for Open.Database.Extensions with build configurations.
- Converted Param struct to readonly record struct in ExpressiveCommandBase.Param.cs for improved immutability.
- Modified AddParam methods in ExpressiveCommandBase.cs to support new Param structure and added overloads for direction.
- Changed versioning scheme in Directory.Build.props to use version prefix and suffix.
- Enhanced parameter handling in ExpressiveSqlCommand.cs to check for null values during parameter creation.
- Created Open.Database.Extensions.csproj to define project structure and dependencies.

Author: electricessence

Open.Database.Extensions.sln

@@ -24,6 +24,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Open.Database.Extensions.MSSqlClient", "Source\MSSqlClient\Open.Database.Extensions.MSSqlClient.csproj", "{B9245504-9E2F-417F-87AC-8950BFB4FD4E}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Open.Database.Extensions", "Source\Extensions\Open.Database.Extensions.csproj", "{446C228B-E12F-424D-AB46-B856422EBDAE}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -54,6 +56,10 @@ Global
 		{B9245504-9E2F-417F-87AC-8950BFB4FD4E}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B9245504-9E2F-417F-87AC-8950BFB4FD4E}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B9245504-9E2F-417F-87AC-8950BFB4FD4E}.Release|Any CPU.Build.0 = Release|Any CPU
+		{446C228B-E12F-424D-AB46-B856422EBDAE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{446C228B-E12F-424D-AB46-B856422EBDAE}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{446C228B-E12F-424D-AB46-B856422EBDAE}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{446C228B-E12F-424D-AB46-B856422EBDAE}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

Source/Core/ExpressiveCommandBase.Param.cs

@@ -11,58 +11,38 @@ public abstract partial class ExpressiveCommandBase<TConnection, TCommand, TRead
 	/// A struct that represents the param to be created when the command is executed.
 	/// TDbType facilitates the difference between DbType and SqlDbType.
 	/// </summary>
-	public struct Param : IEquatable<Param>
+	public readonly record struct Param : IEquatable<Param>
 
 	{
 		/// <summary>
-		/// The name of the param.
+		/// Constructs a <see cref="Param"/>.
 		/// </summary>
-		public string Name { get; set; }
+		public Param(string name, object? value, TDbType? type = null, ParameterDirection direction = ParameterDirection.Input)
+		{
+			Name = name;
+			Value = value;
+			Type = type;
+			Direction = direction;
+		}
 
 		/// <summary>
-		/// The value of the param.
+		/// The name of the param.
 		/// </summary>
-		public object Value { get; set; }
+		public string Name { get; }
 
 		/// <summary>
-		/// The DbType of the param.
+		/// The value of the param.
 		/// </summary>
-		public TDbType? Type { get; set; }
-
-		/// <inheritdoc />
-		public readonly bool Equals(Param other)
-			=> Name == other.Name
-			&& EqualityComparer<object>.Default.Equals(Value, other.Value)
-			&& EqualityComparer<TDbType?>.Default.Equals(Type, other.Type);
-
-		/// <inheritdoc />
-		public override readonly bool Equals(object? obj)
-			=> obj is Param o && Equals(o);
-
-		/// <inheritdoc />
-#if NETSTANDARD2_0
-		[SuppressMessage("Roslynator", "RCS1123:Add parentheses when necessary", Justification = "<Pending>")]
-		public override readonly int GetHashCode()
-		{
-			int hashCode = 1477810893;
-			hashCode = hashCode * -1521134295 + EqualityComparer<string>.Default.GetHashCode(Name);
-			hashCode = hashCode * -1521134295 + EqualityComparer<object>.Default.GetHashCode(Value);
-			hashCode = hashCode * -1521134295 + EqualityComparer<TDbType?>.Default.GetHashCode(Type);
-			return hashCode;
-		}
-#else
-		public override readonly int GetHashCode()
-			=> HashCode.Combine(Name, Value, Type);
-#endif
+		public object? Value { get; }
 
 		/// <summary>
-		/// Equality operator.
+		/// The DbType of the param.
 		/// </summary>
-		public static bool operator ==(Param left, Param right) => left.Equals(right);
+		public TDbType? Type { get; }
 
 		/// <summary>
-		/// Inequality operator.
+		/// The direction of the param.
 		/// </summary>
-		public static bool operator !=(Param left, Param right) => !left.Equals(right);
+		public ParameterDirection Direction { get; }
 	}
 }

Source/Core/ExpressiveCommandBase.cs

@@ -179,138 +179,115 @@ public TThis UseCancellationToken(CancellationToken token)
 	}
 
 	#region AddParam
+
 	/// <summary>
 	/// Adds a parameter to the params list.
 	/// </summary>
 	/// <param name="name">The name of the parameter.</param>
 	/// <param name="value">The value of the parameter.</param>
 	/// <param name="type">The database type of the parameter.</param>
+	/// <param name="direction">The direction of the parameter.</param>
 	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParam(string name, object value, TDbType type)
+	/// <exception cref="ArgumentNullException"><paramref name="name"/> is null.</exception>
+	/// <exception cref="ArgumentException"><paramref name="name"/> is blank.</exception>
+	public TThis AddParam(string name, object value, TDbType type, ParameterDirection direction = ParameterDirection.Input)
 	{
 		if (name is null) throw new ArgumentNullException(nameof(name));
-		else if (string.IsNullOrWhiteSpace(name))
+		if (string.IsNullOrWhiteSpace(name))
 			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
 		Contract.EndContractBlock();
 
-		Params.Add(new Param
-		{
-			Name = name,
-			Value = value,
-			Type = type
-		});
-
+		Params.Add(new(name, value, type, direction));
 		return (TThis)this;
 	}
 
-	/// <summary>
-	/// Adds a parameter to the params list.
-	/// </summary>
-	/// <param name="name">The name of the parameter.</param>
-	/// <param name="value">The value of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParam(string name, object value)
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParam(string name, object? value, ParameterDirection direction = ParameterDirection.Input)
 	{
 		if (name is null) throw new ArgumentNullException(nameof(name));
-		else if (string.IsNullOrWhiteSpace(name))
+		if (string.IsNullOrWhiteSpace(name))
 			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
 		Contract.EndContractBlock();
 
-		Params.Add(new Param
-		{
-			Name = name,
-			Value = value ?? DBNull.Value
-		});
-
+		Params.Add(new(name, value ?? DBNull.Value, null, direction));
 		return (TThis)this;
 	}
 
-	/// <summary>
-	/// Adds a parameter to the params list.
-	/// </summary>
-	/// <param name="name">The name of the parameter.</param>
-	/// <param name="value">The value of the parameter.</param>
-	/// <param name="type">The database type of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParam<T>(string name, T? value, TDbType type)
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParam<T>(string name, T? value, TDbType? type = null, ParameterDirection direction = ParameterDirection.Input)
 		where T : struct
 	{
 		if (name is null) throw new ArgumentNullException(nameof(name));
-		else if (string.IsNullOrWhiteSpace(name))
+		if (string.IsNullOrWhiteSpace(name))
 			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
 		Contract.EndContractBlock();
 
-		Params.Add(new Param
-		{
-			Name = name,
-			Type = type,
-			Value = value ?? (object)DBNull.Value
-		});
+		Params.Add(new(name, value ?? (object)DBNull.Value, type, direction));
+		return (TThis)this;
+	}
+
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParam(string name, string? value, TDbType? type = null, ParameterDirection direction = ParameterDirection.Input)
+	{
+		if (name is null) throw new ArgumentNullException(nameof(name));
+		if (string.IsNullOrWhiteSpace(name))
+			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
+		Contract.EndContractBlock();
 
+		Params.Add(new(name, value ?? (object)DBNull.Value, type, direction));
 		return (TThis)this;
 	}
 
-	/// <summary>
-	/// Adds a parameter to the params list.
-	/// </summary>
-	/// <param name="name">The name of the parameter.</param>
-	/// <param name="value">The value of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParam<T>(string name, T? value)
-		where T : struct
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParam(string name, TDbType type, ParameterDirection direction = ParameterDirection.Input)
 	{
 		if (name is null) throw new ArgumentNullException(nameof(name));
+		if (string.IsNullOrWhiteSpace(name))
+			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
 		Contract.EndContractBlock();
 
-		Params.Add(new Param
-		{
-			Name = name,
-			Value = value ?? (object)DBNull.Value
-		});
+		Params.Add(new (name, null, type, direction));
+		return (TThis)this;
+	}
+
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParam(string name, ParameterDirection direction = ParameterDirection.Input)
+	{
+		if (name is null) throw new ArgumentNullException(nameof(name));
+		if (string.IsNullOrWhiteSpace(name))
+			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
+		Contract.EndContractBlock();
 
+		Params.Add(new(name, null, null, direction));
 		return (TThis)this;
 	}
 
 	/// <summary>
-	/// Adds a parameter to the params list.
+	/// Adds a return parameter to the params list.
 	/// </summary>
-	/// <param name="name">The name of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParam(string name)
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddReturnParam(string name, TDbType type)
 	{
 		if (name is null) throw new ArgumentNullException(nameof(name));
-		else if (string.IsNullOrWhiteSpace(name))
+		if (string.IsNullOrWhiteSpace(name))
 			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
 		Contract.EndContractBlock();
 
-		Params.Add(new Param
-		{
-			Name = name
-		});
-
+		Params.Add(new(name, null, type, ParameterDirection.ReturnValue));
 		return (TThis)this;
 	}
 
-	/// <summary>
-	/// Conditionally adds a parameter to the params list.
-	/// </summary>
-	/// <param name="condition">The condition to add the param by.  Only adds if true.</param>
-	/// <param name="name">The name of the parameter.</param>
-	/// <param name="value">The value of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParamIf<T>(bool condition, string name, T? value)
-		where T : struct
-		=> condition ? AddParam(name, value) : (TThis)this;
+	/// <inheritdoc cref="AddReturnParam(string, TDbType)"/>
+	public TThis AddReturnParam(string name)
+	{
+		if (name is null) throw new ArgumentNullException(nameof(name));
+		if (string.IsNullOrWhiteSpace(name))
+			throw new ArgumentException("Parameter names cannot be empty or white space.", nameof(name));
+		Contract.EndContractBlock();
 
-	/// <summary>
-	/// Conditionally adds a parameter to the params list.
-	/// </summary>
-	/// <param name="condition">The condition to add the param by.  Only adds if true.</param>
-	/// <param name="name">The name of the parameter.</param>
-	/// <param name="value">The value of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParamIf(bool condition, string name, object value)
-		=> condition ? AddParam(name, value) : (TThis)this;
+		Params.Add(new(name, null, null, ParameterDirection.ReturnValue));
+		return (TThis)this;
+	}
 
 	/// <summary>
 	/// Conditionally adds a parameter to the params list.
@@ -319,30 +296,32 @@ public TThis AddParamIf(bool condition, string name, object value)
 	/// <param name="name">The name of the parameter.</param>
 	/// <param name="value">The value of the parameter.</param>
 	/// <param name="type">The database type of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParamIf(bool condition, string name, object value, TDbType type)
-		=> condition ? AddParam(name, value, type) : (TThis)this;
+	/// <param name="direction">The direction of the parameter.</param>
+	/// <inheritdoc cref="AddParam(string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParamIf(bool condition, string name, object value, TDbType type, ParameterDirection direction = ParameterDirection.Input)
+		=> condition ? AddParam(name, value, type, direction) : (TThis)this;
 
-	/// <summary>
-	/// Conditionally adds a parameter to the params list.
-	/// </summary>
-	/// <param name="condition">The condition to add the param by.  Only adds if true.</param>
-	/// <param name="name">The name of the parameter.</param>
-	/// <param name="value">The value of the parameter.</param>
-	/// <param name="type">The database type of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParamIf<T>(bool condition, string name, T? value, TDbType type)
+	/// <inheritdoc cref="AddParamIf(bool, string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParamIf<T>(bool condition, string name, T? value, ParameterDirection direction = ParameterDirection.Input)
 		where T : struct
-		=> condition ? AddParam(name, value, type) : (TThis)this;
+		=> condition ? AddParam(name, value, null, direction) : (TThis)this;
 
-	/// <summary>
-	/// Conditionally adds a parameter to the params list.
-	/// </summary>
-	/// <param name="condition">The condition to add the param by.  Only adds if true.</param>
-	/// <param name="name">The name of the parameter.</param>
-	/// <returns>This instance for use in method chaining.</returns>
-	public TThis AddParamIf(bool condition, string name)
-		=> condition ? AddParam(name) : (TThis)this;
+	/// <inheritdoc cref="AddParamIf(bool, string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParamIf(bool condition, string name, object? value, ParameterDirection direction = ParameterDirection.Input)
+		=> condition ? AddParam(name, value, direction) : (TThis)this;
+
+	/// <inheritdoc cref="AddParamIf(bool, string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParamIf<T>(bool condition, string name, T? value, TDbType? type, ParameterDirection direction = ParameterDirection.Input)
+		where T : struct
+		=> condition ? AddParam(name, value, type, direction) : (TThis)this;
+
+	/// <inheritdoc cref="AddParamIf(bool, string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParamIf(bool condition, string name, TDbType type, ParameterDirection direction = ParameterDirection.Input)
+		=> condition ? AddParam(name, type, direction) : (TThis)this;
+
+	/// <inheritdoc cref="AddParamIf(bool, string, object, TDbType, ParameterDirection)"/>
+	public TThis AddParamIf(bool condition, string name, ParameterDirection direction = ParameterDirection.Input)
+		=> condition ? AddParam(name, direction) : (TThis)this;
 
 	/// <summary>
 	/// Handles adding the list of parameters to a new command.

Source/Directory.Build.props

@@ -2,7 +2,9 @@
 
 	<PropertyGroup>
 		<RootNamespace>Open.Database.Extensions</RootNamespace>
-		<Version>9.0.0</Version>
+		
+		<VersionPrefix>9.0.1</VersionPrefix>
+		<VersionSuffix Condition="'$(Configuration)' == 'Debug'">debug</VersionSuffix>
 
 		<TargetFrameworks>netstandard2.0; netstandard2.1; net8.0; net9.0;</TargetFrameworks>
 		<LangVersion>latest</LangVersion>

Source/Extensions/Open.Database.Extensions.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+	<PropertyGroup>
+		<Description>
+			Useful set of utilities and abstractions for simplifying modern data-access operations and ensuring DI compatibility.
+			This is simply a meta-package that includes Open.Database.Extensions.Core.
+		</Description>
+		<PackageTags>ado;ado extensions;sql;connection factory;extensions;</PackageTags>
+	</PropertyGroup>
+
+	<ItemGroup>
+    <ProjectReference Include="..\Core\Open.Database.Extensions.Core.csproj" />
+  </ItemGroup>
+	
+</Project>

Source/MSSqlClient/ExpressiveSqlCommand.cs

@@ -71,10 +71,18 @@ protected override void AddParams(SqlCommand command)
 
 		foreach (Param p in Params)
 		{
-			SqlParameter np = command
-				.Parameters
-				.AddWithValue(p.Name, p.Value);
+			SqlParameter np;
+			if (p.Value is null)
+			{
+				np = command.CreateParameter();
+				np.ParameterName = p.Name;
+			}
+			else
+			{
+				np = command.Parameters.AddWithValue(p.Name, p.Value);
+			}
 
+			np.Direction = p.Direction;
 			if (p.Type.HasValue)
 				np.SqlDbType = p.Type.Value;
 		}