update docs

docs/docfx.json

@@ -4,9 +4,9 @@
       "src": [
         {
           "files": [
-            "src/FluentCommand/bin/Release/net7.0/FluentCommand.dll",
-            "src/FluentCommand.SqlServer/bin/Release/net7.0/FluentCommand.SqlServer.dll",
-            "src/FluentCommand.Json/bin/Release/net7.0/FluentCommand.Json.dll"
+            "src/FluentCommand/bin/Release/net8.0/FluentCommand.dll",
+            "src/FluentCommand.SqlServer/bin/Release/net8.0/FluentCommand.SqlServer.dll",
+            "src/FluentCommand.Json/bin/Release/net8.0/FluentCommand.Json.dll"
           ],
           "src": "../"
         }
@@ -44,7 +44,7 @@
     "globalMetadata": {
       "_appTitle": "FluentCommand",
       "_appName": "FluentCommand",
-      "_appFooter": "Copyright © 2023 LoreSoft",
+      "_appFooter": "Copyright © 2024 LoreSoft",
       "_appLogoPath": "assets/logo.png",
       "_appFaviconPath": "assets/logo.png",
       "_enableSearch": true

docs/guide/cache.md

@@ -0,0 +1 @@
+# Caching

docs/guide/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Configuration for SQL Server
+## Configuration for SQL Server
 
 ```csharp
 var dataConfiguration  = new DataConfiguration(
@@ -9,7 +9,7 @@ var dataConfiguration  = new DataConfiguration(
 );
 ```
 
-Configure data logger
+## Configure data logger
 
 ```csharp
 var dataLogger = new DataQueryLogger(Output.WriteLine);
@@ -20,7 +20,7 @@ var dataConfiguration  = new DataConfiguration(
 );
 ```
 
-Register with dependency injection
+## Register with dependency injection
 
 ```csharp
 services.AddFluentCommand(builder => builder
@@ -29,7 +29,7 @@ services.AddFluentCommand(builder => builder
 );
 ```
 
-Register using a connection name from the appsettings.json
+## Register using a connection name from the appsettings.json
 
 ```csharp
 services.AddFluentCommand(builder => builder
@@ -46,7 +46,7 @@ services.AddFluentCommand(builder => builder
 }
 ```
 
-Register for PostgreSQL
+## Register for PostgreSQL
 
 ```csharp
 services.AddFluentCommand(builder => builder

docs/guide/generation.md

@@ -0,0 +1,39 @@
+# Source Generator
+
+The project supports generating a DbDataReader from a class via an attribute.  Add the `TableAttribute` to a class to generate the needed extension methods.
+
+```c#
+[Table("Status", Schema = "dbo")]
+public class Status
+{
+    public int Id { get; set; }
+    public string Name { get; set; }
+    public string Description { get; set; }
+    public int DisplayOrder { get; set; }
+    public bool IsActive { get; set; }
+    public DateTimeOffset Created { get; set; }
+    public string CreatedBy { get; set; }
+    public DateTimeOffset Updated { get; set; }
+    public string UpdatedBy { get; set; }
+
+    [ConcurrencyCheck]
+    [DatabaseGenerated(DatabaseGeneratedOption.Computed)]
+    [DataFieldConverter(typeof(ConcurrencyTokenHandler))]
+    public ConcurrencyToken RowVersion { get; set; }
+
+    [NotMapped]
+    public virtual ICollection<Task> Tasks { get; set; } = new List<Task>();
+}
+```
+
+Extension methods are generated to materialize data command to entities
+
+```c#
+string email = "[email protected]";
+string sql = "select * from [User] where EmailAddress = @EmailAddress";
+var session = configuration.CreateSession();
+var user = await session
+    .Sql(sql)
+    .Parameter("@EmailAddress", email)
+    .QuerySingleAsync<User>();
+```

docs/guide/logging.md

@@ -0,0 +1 @@
+# Logging

docs/guide/parameter.md

@@ -0,0 +1,101 @@
+# Parameters
+
+## Calling a stored procedure with an out parameter
+
+```csharp
+long total = -1;
+var email = "%@battlestar.com";
+
+using var session = Services.GetRequiredService<IDataSession>();
+
+var users = session
+    .StoredProcedure("[dbo].[UserListByEmailAddress]")
+    .Parameter("@EmailAddress", email)
+    .Parameter("@Offset", 0)
+    .Parameter("@Size", 10)
+    .Parameter<long>(parameter => parameter
+        .Name("@Total")
+        .Type(DbType.Int64)
+        .Output(v => total = v)
+        .Direction(ParameterDirection.Output)
+    )
+    .Query<User>()
+    .ToList();
+```
+
+## SQL query with a parameter
+
+```csharp
+var session = Services.GetRequiredService<IDataSession>();
+
+var email = "[email protected]";
+var sql = "select * from [User] where EmailAddress = @EmailAddress";
+
+var user = session.Sql(sql)
+    .Parameter("@EmailAddress", email)
+    .QuerySingle(r => new User
+    {
+        Id = r.GetGuid("Id"),
+        EmailAddress = r.GetString("EmailAddress"),
+        IsEmailAddressConfirmed = r.GetBoolean("IsEmailAddressConfirmed"),
+        DisplayName = r.GetString("DisplayName"),
+        PasswordHash = r.GetString("PasswordHash"),
+        ResetHash = r.GetString("ResetHash"),
+        InviteHash = r.GetString("InviteHash"),
+        AccessFailedCount = r.GetInt32("AccessFailedCount"),
+        LockoutEnabled = r.GetBoolean("LockoutEnabled"),
+        LockoutEnd = r.GetDateTimeOffsetNull("LockoutEnd"),
+        LastLogin = r.GetDateTimeOffsetNull("LastLogin"),
+        IsDeleted = r.GetBoolean("IsDeleted"),
+        Created = r.GetDateTimeOffset("Created"),
+        CreatedBy = r.GetString("CreatedBy"),
+        Updated = r.GetDateTimeOffset("Updated"),
+        UpdatedBy = r.GetString("UpdatedBy"),
+        RowVersion = r.GetBytes("RowVersion"),
+    });
+```
+
+## Executing an Upsert stored procedure
+
+```csharp
+int errorCode = -1;
+
+var userId = Guid.NewGuid();
+var username = "test." + DateTime.Now.Ticks;
+var email = username + "@email.com";
+
+using var session = Services.GetRequiredService<IDataSession>();
+
+var user = session
+    .StoredProcedure("[dbo].[UserUpsert]")
+    .Parameter("@Id", userId)
+    .Parameter("@EmailAddress", email)
+    .Parameter("@IsEmailAddressConfirmed", true)
+    .Parameter("@DisplayName", "Unit Test")
+    .Parameter("@PasswordHash", "T@est" + DateTime.Now.Ticks)
+    .Parameter<string>("@ResetHash", null)
+    .Parameter<string>("@InviteHash", null)
+    .Parameter("@AccessFailedCount", 0)
+    .Parameter("@LockoutEnabled", false)
+    .Parameter("@IsDeleted", false)
+    .Return<int>(p => errorCode = p)
+    .QuerySingle<User>();
+```
+
+## Executing a stored procedure with a return parameter
+
+```csharp
+int result = -1;
+long total = -1;
+
+var email = "[email protected]";
+
+using var session = Services.GetRequiredService<IDataSession>();
+
+result = session
+    .StoredProcedure("[dbo].[UserCountByEmailAddress]")
+    .Parameter("@EmailAddress", email)
+    .Return<long>(p => total = p)
+    .Execute();
+
+```

docs/guide/query.md

@@ -0,0 +1,124 @@
+# Query Methods
+
+## Execute or ExecuteAsync
+
+Executes the command against a connection and returns the number of rows affected.
+
+```csharp
+int result = -1;
+long total = -1;
+
+var email = "[email protected]";
+
+using var session = Services.GetRequiredService<IDataSession>();
+
+result = session
+    .StoredProcedure("[dbo].[UserCountByEmailAddress]")
+    .Parameter("@EmailAddress", email)
+    .Return<long>(p => total = p)
+    .Execute();
+```
+
+
+## Query or QueryAsync
+
+Executes the command against the connection and converts the results to a list of objects.
+
+```csharp
+long total = -1;
+var email = "%@battlestar.com";
+
+using var session = Services.GetRequiredService<IDataSession>();
+
+var users = session
+    .StoredProcedure("[dbo].[UserListByEmailAddress]")
+    .Parameter("@EmailAddress", email)
+    .Parameter("@Offset", 0)
+    .Parameter("@Size", 10)
+    .Parameter<long>(parameter => parameter
+        .Name("@Total")
+        .Type(DbType.Int64)
+        .Output(v => total = v)
+        .Direction(ParameterDirection.Output)
+    )
+    .Query<User>() // using source generated factor
+    .ToList();
+```
+
+## QuerySingle or QuerySingleAsync
+
+Executes the query and returns the first row in the result as an object.
+
+```csharp
+var session = Services.GetRequiredService<IDataSession>();
+
+var email = "[email protected]";
+var sql = "select * from [User] where EmailAddress = @EmailAddress";
+
+var user = session.Sql(sql)
+    .Parameter("@EmailAddress", email)
+    .QuerySingle(r => new User
+    {
+        Id = r.GetGuid("Id"),
+        EmailAddress = r.GetString("EmailAddress"),
+        IsEmailAddressConfirmed = r.GetBoolean("IsEmailAddressConfirmed"),
+        DisplayName = r.GetString("DisplayName"),
+        PasswordHash = r.GetString("PasswordHash"),
+        ResetHash = r.GetString("ResetHash"),
+        InviteHash = r.GetString("InviteHash"),
+        AccessFailedCount = r.GetInt32("AccessFailedCount"),
+        LockoutEnabled = r.GetBoolean("LockoutEnabled"),
+        LockoutEnd = r.GetDateTimeOffsetNull("LockoutEnd"),
+        LastLogin = r.GetDateTimeOffsetNull("LastLogin"),
+        IsDeleted = r.GetBoolean("IsDeleted"),
+        Created = r.GetDateTimeOffset("Created"),
+        CreatedBy = r.GetString("CreatedBy"),
+        Updated = r.GetDateTimeOffset("Updated"),
+        UpdatedBy = r.GetString("UpdatedBy"),
+        RowVersion = r.GetBytes("RowVersion"),
+    });
+```
+
+## QueryValue or QueryValueAsync
+
+Executes the query and returns the first column of the first row in the result set returned by the query asynchronously. All other columns and rows are ignored.
+
+```csharp
+await using var session = Services.GetRequiredService<IDataSession>();
+
+string email = "@battlestar.com";
+
+var count = await session
+    .Sql(builder => builder
+        .Select<User>()
+        .Count()
+        .Where(p => p.EmailAddress, email, FilterOperators.Contains)
+    )
+    .QueryValueAsync<int>();
+```
+
+## QueryMultiple or QueryMultipleAsync
+
+Executes the command against the connection and sends the results for reading multiple results sets
+
+```csharp
+string email = "[email protected]";
+string sql = "select * from [User] where EmailAddress = @EmailAddress; " +
+             "select * from [Role]; " +
+             "select * from [Priority]; ";
+
+User user = null;
+List<Role> roles = null;
+List<Priority> priorities = null;
+
+await using var session = Services.GetRequiredService<IDataSession>();
+
+await session.Sql(sql)
+    .Parameter("@EmailAddress", email)
+    .QueryMultipleAsync(async q =>
+    {
+        user = await q.QuerySingleAsync<User>();
+        roles = (await q.QueryAsync<Role>()).ToList();
+        priorities = (await q.QueryAsync<Priority>()).ToList();
+    });
+```