misc updates

Author: pwelter34

src/FluentCommand.Csv/CsvCommandExtensions.cs

@@ -1,12 +1,11 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFrameworks>netstandard2.0;net8.0;net9.0</TargetFrameworks>
+    <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
     <RootNamespace>FluentCommand</RootNamespace>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="CsvHelper" Version="33.1.0" />
     <PackageReference Include="Microsoft.IO.RecyclableMemoryStream" Version="3.0.1" />
   </ItemGroup>
 

src/FluentCommand.Csv/FluentCommand.Csv.csproj

@@ -9,7 +9,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="MicroSoft.Data.SqlClient" Version="6.0.1" />
+    <PackageReference Include="MicroSoft.Data.SqlClient" Version="6.0.2" />
   </ItemGroup>
 
 </Project>

src/FluentCommand.SqlServer/FluentCommand.SqlServer.csproj

@@ -3,12 +3,26 @@
 namespace FluentCommand.Attributes;
 
 /// <summary>
-/// Source generate a data reader for the specified type
+/// Specifies that a source generator should create a data reader for the given type.
 /// </summary>
-/// <param name="type">The type to generate a data reader for</param>
+/// <remarks>
+/// Apply this attribute to an assembly, class, interface, or module to indicate that a data reader should be generated
+/// for the specified <see cref="Type"/>. This is typically used in conjunction with source generators.
+/// </remarks>
+/// <example>
+/// <code>
+/// [assembly: GenerateReader(typeof(Product))]
+/// </code>
+/// </example>
+/// <param name="type">
+/// The <see cref="Type"/> for which to generate a data reader. Must not be <c>null</c>.
+/// </param>
 [Conditional("FLUENTCOMMAND_GENERATOR")]
 [AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Class | AttributeTargets.Interface | AttributeTargets.Module, AllowMultiple = true)]
 public class GenerateReaderAttribute(Type type) : Attribute
 {
+    /// <summary>
+    /// Gets the type for which the data reader will be generated.
+    /// </summary>
     public Type Type { get; } = type ?? throw new ArgumentNullException(nameof(type));
 }

src/FluentCommand/Attributes/GenerateReaderAttribute.cs

@@ -5,12 +5,15 @@ namespace FluentCommand;
 /// <summary>
 /// A structure to hold concurrency token
 /// </summary>
+/// <remarks>
+/// This structure is commonly used to represent SQL Server <c>rowversion</c> (also known as <c>timestamp</c>) columns for optimistic concurrency control.
+/// </remarks>
 public readonly struct ConcurrencyToken : IEquatable<ConcurrencyToken>
 {
     /// <summary>
     /// The default empty token
     /// </summary>
-    public static readonly ConcurrencyToken None = new(Array.Empty<byte>());
+    public static readonly ConcurrencyToken None = new([]);
 
     /// <summary>
     /// Gets the underlying value of the token.
@@ -26,7 +29,7 @@ namespace FluentCommand;
     /// <param name="value">The value.</param>
     public ConcurrencyToken(byte[] value)
     {
-        Value = value ?? Array.Empty<byte>();
+        Value = value ?? [];
     }
 
     /// <summary>
@@ -36,12 +39,30 @@ public ConcurrencyToken(byte[] value)
     public ConcurrencyToken(string value)
     {
 #if NET5_0_OR_GREATER
-        Value = string.IsNullOrEmpty(value) ? Array.Empty<byte>() : Convert.FromHexString(value);
+        Value = string.IsNullOrEmpty(value) ? [] : Convert.FromHexString(value);
 #else
-        Value = string.IsNullOrEmpty(value) ? Array.Empty<byte>() : FromHexString(value);
+        Value = string.IsNullOrEmpty(value) ? [] : FromHexString(value);
 #endif
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConcurrencyToken"/> struct from a <see cref="long"/> value.
+    /// </summary>
+    /// <param name="value">The long value.</param>
+    public ConcurrencyToken(long value)
+    {
+        Value = BitConverter.GetBytes(value);
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConcurrencyToken"/> struct from a <see cref="ulong"/> value.
+    /// </summary>
+    /// <param name="value">The ulong value.</param>
+    public ConcurrencyToken(ulong value)
+    {
+        Value = BitConverter.GetBytes(value);
+    }
+
     /// <inheritdoc />
     public override string ToString()
     {
@@ -70,6 +91,7 @@ public override int GetHashCode()
         return Value.GetHashCode();
     }
 
+
     /// <summary>
     /// Performs an implicit conversion from <see cref="ConcurrencyToken"/> to byte array.
     /// </summary>
@@ -88,6 +110,45 @@ public override int GetHashCode()
     /// </returns>
     public static implicit operator string(ConcurrencyToken token) => token.ToString();
 
+    /// <summary>
+    /// Performs an implicit conversion from <see cref="ConcurrencyToken"/> to <see cref="long"/>.
+    /// </summary>
+    /// <param name="token">The concurrency token.</param>
+    /// <returns>
+    /// The result of the conversion.
+    /// </returns>
+    public static implicit operator long(ConcurrencyToken token)
+    {
+        if (token.Value == null || token.Value.Length == 0)
+            return 0L;
+
+        if (token.Value.Length < sizeof(long))
+            throw new InvalidCastException("The token value is too short to convert to a long.");
+
+        // Use little-endian to match BitConverter default
+        return BitConverter.ToInt64(token.Value, 0);
+    }
+
+    /// <summary>
+    /// Performs an implicit conversion from <see cref="ConcurrencyToken"/> to <see cref="ulong"/>.
+    /// </summary>
+    /// <param name="token">The concurrency token.</param>
+    /// <returns>
+    /// The result of the conversion.
+    /// </returns>
+    public static implicit operator ulong(ConcurrencyToken token)
+    {
+        if (token.Value == null || token.Value.Length == 0)
+            return 0UL;
+
+        if (token.Value.Length < sizeof(ulong))
+            throw new InvalidCastException("The token value is too short to convert to a ulong.");
+
+        // Use little-endian to match BitConverter default
+        return BitConverter.ToUInt64(token.Value, 0);
+    }
+
+
     /// <summary>
     /// Performs an implicit conversion from byte array to <see cref="ConcurrencyToken"/>.
     /// </summary>
@@ -106,6 +167,53 @@ public override int GetHashCode()
     /// </returns>
     public static implicit operator ConcurrencyToken(string token) => new(token);
 
+    /// <summary>
+    /// Performs an implicit conversion from <see cref="long"/> to <see cref="ConcurrencyToken"/>.
+    /// </summary>
+    /// <param name="value">The long value.</param>
+    /// <returns>
+    /// The result of the conversion.
+    /// </returns>
+    public static implicit operator ConcurrencyToken(long value)
+    {
+        var bytes = BitConverter.GetBytes(value);
+        return new ConcurrencyToken(bytes);
+    }
+
+    /// <summary>
+    /// Performs an implicit conversion from <see cref="ulong"/> to <see cref="ConcurrencyToken"/>.
+    /// </summary>
+    /// <param name="value">The ulong value.</param>
+    /// <returns>
+    /// The result of the conversion.
+    /// </returns>
+    public static implicit operator ConcurrencyToken(ulong value)
+    {
+        var bytes = BitConverter.GetBytes(value);
+        return new ConcurrencyToken(bytes);
+    }
+
+
+    /// <summary>
+    /// Determines whether two <see cref="ConcurrencyToken"/> instances are equal.
+    /// </summary>
+    /// <param name="left">The first <see cref="ConcurrencyToken"/> to compare.</param>
+    /// <param name="right">The second <see cref="ConcurrencyToken"/> to compare.</param>
+    /// <returns>
+    /// <see langword="true"/> if the two <see cref="ConcurrencyToken"/> instances are equal; otherwise, <see langword="false"/>.
+    /// </returns>
+    public static bool operator ==(ConcurrencyToken left, ConcurrencyToken right) => left.Equals(right);
+
+    /// <summary>
+    /// Determines whether two <see cref="ConcurrencyToken"/> instances are not equal.
+    /// </summary>
+    /// <param name="left">The first <see cref="ConcurrencyToken"/> to compare.</param>
+    /// <param name="right">The second <see cref="ConcurrencyToken"/> to compare.</param>
+    /// <returns>
+    /// <see langword="true"/> if the two <see cref="ConcurrencyToken"/> instances are not equal; otherwise, <see langword="false"/>.
+    /// </returns>
+    public static bool operator !=(ConcurrencyToken left, ConcurrencyToken right) => !(left == right);
+
 
 #if NETSTANDARD2_0
     private static string ToHexString(byte[] bytes)

src/FluentCommand/ConcurrencyToken.cs

@@ -1,7 +1,7 @@
 namespace FluentCommand;
 
 /// <summary>
-/// A base class that implements <see cref="IDisposable"/>
+/// Provides a base implementation of the <see cref="IDisposable"/> pattern, including support for asynchronous disposal on supported platforms.
 /// </summary>
 public abstract class DisposableBase
     : IDisposable
@@ -12,7 +12,7 @@ public abstract class DisposableBase
     private int _disposeState;
 
     /// <summary>
-    /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+    /// Releases all resources used by the current instance of the <see cref="DisposableBase"/> class.
     /// </summary>
     public void Dispose()
     {
@@ -21,9 +21,11 @@ public void Dispose()
     }
 
     /// <summary>
-    /// Releases unmanaged and - optionally - managed resources
+    /// Releases the unmanaged resources used by the object and, optionally, releases the managed resources.
     /// </summary>
-    /// <param name="disposing"><c>true</c> to release both managed and unmanaged resources; <c>false</c> to release only unmanaged resources.</param>
+    /// <param name="disposing">
+    /// <c>true</c> to release both managed and unmanaged resources; <c>false</c> to release only unmanaged resources.
+    /// </param>
     protected void Dispose(bool disposing)
     {
         // set state to disposing
@@ -40,7 +42,7 @@ protected void Dispose(bool disposing)
     }
 
     /// <summary>
-    /// Throws <see cref="ObjectDisposedException"/> if this instance is disposed.
+    /// Throws an <see cref="ObjectDisposedException"/> if this instance has already been disposed.
     /// </summary>
     protected void AssertDisposed()
     {
@@ -49,27 +51,27 @@ protected void AssertDisposed()
     }
 
     /// <summary>
-    /// Get the disposed state of the object.
+    /// Gets a value indicating whether this instance has been disposed.
     /// </summary>
     protected bool IsDisposed => _disposeState != 0;
 
     /// <summary>
-    /// Disposes the managed resources.
+    /// Releases managed resources. Override this method to dispose managed resources in derived classes.
     /// </summary>
     protected virtual void DisposeManagedResources()
     { }
 
     /// <summary>
-    /// Disposes the unmanaged resources.
+    /// Releases unmanaged resources. Override this method to dispose unmanaged resources in derived classes.
     /// </summary>
     protected virtual void DisposeUnmanagedResources()
     { }
 
 #if NETCOREAPP3_0_OR_GREATER
     /// <summary>
-    /// Disposes the asynchronous.
+    /// Asynchronously releases all resources used by the current instance of the <see cref="DisposableBase"/> class.
     /// </summary>
-    /// <returns></returns>
+    /// <returns>A <see cref="ValueTask"/> that represents the asynchronous dispose operation.</returns>
     public async ValueTask DisposeAsync()
     {
         // set state to disposing
@@ -80,20 +82,23 @@ public async ValueTask DisposeAsync()
 
         // set state to disposed
         Interlocked.Exchange(ref _disposeState, 2);
+
+        GC.SuppressFinalize(this);
     }
 
     /// <summary>
-    /// Disposes the managed resources.
+    /// Asynchronously releases managed resources. Override this method to asynchronously dispose managed resources in derived classes.
     /// </summary>
+    /// <returns>A <see cref="ValueTask"/> that represents the asynchronous dispose operation.</returns>
     protected virtual ValueTask DisposeResourcesAsync()
     {
         return ValueTask.CompletedTask;
     }
 #endif
 
     /// <summary>
-    /// Releases unmanaged resources and performs other cleanup operations before the
-    /// <see cref="DisposableBase"/> is reclaimed by garbage collection.
+    /// Finalizes an instance of the <see cref="DisposableBase"/> class.
+    /// Releases unmanaged resources and performs other cleanup operations before the object is reclaimed by garbage collection.
     /// </summary>
     ~DisposableBase()
     {

src/FluentCommand/DisposableBase.cs

@@ -1,7 +1,3 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-
 namespace FluentCommand.Extensions;
 
 /// <summary>
@@ -10,15 +6,15 @@ namespace FluentCommand.Extensions;
 public static class CollectionExtensions
 {
     /// <summary>
-    /// Gets the first element from the <paramref name="source"/> that passes the test specified by <paramref name="predicate" />; 
+    /// Gets the first element from the <paramref name="source"/> that passes the test specified by <paramref name="predicate" />;
     /// otherwise the <paramref name="valueFactory"/> is called and the result is added to the source.
     /// </summary>
     /// <typeparam name="T">The type of the elements of <paramref name="source" />.</typeparam>
     /// <param name="source">An <see cref="T:System.Collections.Generic.ICollection`1" /> to get or add an element from.</param>
     /// <param name="predicate">A function to test each element for a condition.</param>
     /// <param name="valueFactory">The function used to generate a value when not found in the collection.</param>
     /// <returns>
-    /// The value from <paramref name="valueFactory"/> if <paramref name="source" /> is empty or if no element passes the test specified by <paramref name="predicate" />; 
+    /// The value from <paramref name="valueFactory"/> if <paramref name="source" /> is empty or if no element passes the test specified by <paramref name="predicate" />;
     /// otherwise, the first element in <paramref name="source" /> that passes the test specified by <paramref name="predicate" />.
     /// </returns>
     public static T FirstOrAdd<T>(this ICollection<T> source, Func<T, bool> predicate, Func<T> valueFactory)

src/FluentCommand/Extensions/CollectionExtensions.cs

@@ -1,20 +1,28 @@
-using System.Collections.Generic;
 using System.Data;
 
 namespace FluentCommand.Extensions;
 
 /// <summary>
-/// Extension method for <see cref="DataTable"/>
+/// Provides extension methods for the <see cref="DataTable"/> class.
 /// </summary>
 public static class DataTableExtensions
 {
     /// <summary>
-    /// Converts the IEnumerable to a <see cref="DataTable" />.
+    /// Converts an <see cref="IEnumerable{T}"/> to a <see cref="DataTable"/> instance.
     /// </summary>
-    /// <typeparam name="T">The type of the source data</typeparam>
-    /// <param name="source">The source to convert.</param>
-    /// <param name="ignoreNames">The ignored property names.</param>
-    /// <returns>A <see cref="DataTable"/> from the specified source.</returns>
+    /// <typeparam name="T">The type of the elements in the source collection.</typeparam>
+    /// <param name="source">The collection of objects to convert to a <see cref="DataTable"/>.</param>
+    /// <param name="ignoreNames">
+    /// An optional collection of property names to ignore when creating columns in the <see cref="DataTable"/>.
+    /// If <c>null</c>, all public properties are included.
+    /// </param>
+    /// <returns>
+    /// A <see cref="DataTable"/> populated with the data from the <paramref name="source"/> collection,
+    /// or <c>null</c> if <paramref name="source"/> is <c>null</c>.
+    /// </returns>
+    /// <remarks>
+    /// This method uses <see cref="ListDataReader{T}"/> to read the data from the source collection and load it into a <see cref="DataTable"/>.
+    /// </remarks>
     public static DataTable ToDataTable<T>(this IEnumerable<T> source, IEnumerable<string> ignoreNames = null)
         where T : class
     {