Skip to content

Commit d315c93

Browse files
pwelter34pwelter34
committed
update docs
1 parent bd1ff17 commit d315c93

File tree

10 files changed

+602
-11
lines changed

10 files changed

+602
-11
lines changed

‎docs/docfx.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44
"src": [
55
{
66
"files": [
7-
"src/FluentCommand/bin/Release/net7.0/FluentCommand.dll",
8-
"src/FluentCommand.SqlServer/bin/Release/net7.0/FluentCommand.SqlServer.dll",
9-
"src/FluentCommand.Json/bin/Release/net7.0/FluentCommand.Json.dll"
7+
"src/FluentCommand/bin/Release/net8.0/FluentCommand.dll",
8+
"src/FluentCommand.SqlServer/bin/Release/net8.0/FluentCommand.SqlServer.dll",
9+
"src/FluentCommand.Json/bin/Release/net8.0/FluentCommand.Json.dll"
1010
],
1111
"src": "../"
1212
}
@@ -44,7 +44,7 @@
4444
"globalMetadata": {
4545
"_appTitle": "FluentCommand",
4646
"_appName": "FluentCommand",
47-
"_appFooter": "Copyright © 2023 LoreSoft",
47+
"_appFooter": "Copyright © 2024 LoreSoft",
4848
"_appLogoPath": "assets/logo.png",
4949
"_appFaviconPath": "assets/logo.png",
5050
"_enableSearch": true

‎docs/guide/cache.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Caching

‎docs/guide/configuration.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Configuration
22

3-
Configuration for SQL Server
3+
## Configuration for SQL Server
44

55
```csharp
66
var dataConfiguration = new DataConfiguration(
@@ -9,7 +9,7 @@ var dataConfiguration = new DataConfiguration(
99
);
1010
```
1111

12-
Configure data logger
12+
## Configure data logger
1313

1414
```csharp
1515
var dataLogger = new DataQueryLogger(Output.WriteLine);
@@ -20,7 +20,7 @@ var dataConfiguration = new DataConfiguration(
2020
);
2121
```
2222

23-
Register with dependency injection
23+
## Register with dependency injection
2424

2525
```csharp
2626
services.AddFluentCommand(builder => builder
@@ -29,7 +29,7 @@ services.AddFluentCommand(builder => builder
2929
);
3030
```
3131

32-
Register using a connection name from the appsettings.json
32+
## Register using a connection name from the appsettings.json
3333

3434
```csharp
3535
services.AddFluentCommand(builder => builder
@@ -46,7 +46,7 @@ services.AddFluentCommand(builder => builder
4646
}
4747
```
4848

49-
Register for PostgreSQL
49+
## Register for PostgreSQL
5050

5151
```csharp
5252
services.AddFluentCommand(builder => builder

‎docs/guide/execute.md‎

Whitespace-only changes.

‎docs/guide/generation.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Source Generator
2+
3+
The project supports generating a DbDataReader from a class via an attribute. Add the `TableAttribute` to a class to generate the needed extension methods.
4+
5+
```c#
6+
[Table("Status", Schema = "dbo")]
7+
public class Status
8+
{
9+
public int Id { get; set; }
10+
public string Name { get; set; }
11+
public string Description { get; set; }
12+
public int DisplayOrder { get; set; }
13+
public bool IsActive { get; set; }
14+
public DateTimeOffset Created { get; set; }
15+
public string CreatedBy { get; set; }
16+
public DateTimeOffset Updated { get; set; }
17+
public string UpdatedBy { get; set; }
18+
19+
[ConcurrencyCheck]
20+
[DatabaseGenerated(DatabaseGeneratedOption.Computed)]
21+
[DataFieldConverter(typeof(ConcurrencyTokenHandler))]
22+
public ConcurrencyToken RowVersion { get; set; }
23+
24+
[NotMapped]
25+
public virtual ICollection<Task> Tasks { get; set; } = new List<Task>();
26+
}
27+
```
28+
29+
Extension methods are generated to materialize data command to entities
30+
31+
```c#
32+
string email = "[email protected]";
33+
string sql = "select * from [User] where EmailAddress = @EmailAddress";
34+
var session = configuration.CreateSession();
35+
var user = await session
36+
.Sql(sql)
37+
.Parameter("@EmailAddress", email)
38+
.QuerySingleAsync<User>();
39+
```

‎docs/guide/logging.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Logging

‎docs/guide/parameter.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Parameters
2+
3+
## Calling a stored procedure with an out parameter
4+
5+
```csharp
6+
long total = -1;
7+
var email = "%@battlestar.com";
8+
9+
using var session = Services.GetRequiredService<IDataSession>();
10+
11+
var users = session
12+
.StoredProcedure("[dbo].[UserListByEmailAddress]")
13+
.Parameter("@EmailAddress", email)
14+
.Parameter("@Offset", 0)
15+
.Parameter("@Size", 10)
16+
.Parameter<long>(parameter => parameter
17+
.Name("@Total")
18+
.Type(DbType.Int64)
19+
.Output(v => total = v)
20+
.Direction(ParameterDirection.Output)
21+
)
22+
.Query<User>()
23+
.ToList();
24+
```
25+
26+
## SQL query with a parameter
27+
28+
```csharp
29+
var session = Services.GetRequiredService<IDataSession>();
30+
31+
var email = "[email protected]";
32+
var sql = "select * from [User] where EmailAddress = @EmailAddress";
33+
34+
var user = session.Sql(sql)
35+
.Parameter("@EmailAddress", email)
36+
.QuerySingle(r => new User
37+
{
38+
Id = r.GetGuid("Id"),
39+
EmailAddress = r.GetString("EmailAddress"),
40+
IsEmailAddressConfirmed = r.GetBoolean("IsEmailAddressConfirmed"),
41+
DisplayName = r.GetString("DisplayName"),
42+
PasswordHash = r.GetString("PasswordHash"),
43+
ResetHash = r.GetString("ResetHash"),
44+
InviteHash = r.GetString("InviteHash"),
45+
AccessFailedCount = r.GetInt32("AccessFailedCount"),
46+
LockoutEnabled = r.GetBoolean("LockoutEnabled"),
47+
LockoutEnd = r.GetDateTimeOffsetNull("LockoutEnd"),
48+
LastLogin = r.GetDateTimeOffsetNull("LastLogin"),
49+
IsDeleted = r.GetBoolean("IsDeleted"),
50+
Created = r.GetDateTimeOffset("Created"),
51+
CreatedBy = r.GetString("CreatedBy"),
52+
Updated = r.GetDateTimeOffset("Updated"),
53+
UpdatedBy = r.GetString("UpdatedBy"),
54+
RowVersion = r.GetBytes("RowVersion"),
55+
});
56+
```
57+
58+
## Executing an Upsert stored procedure
59+
60+
```csharp
61+
int errorCode = -1;
62+
63+
var userId = Guid.NewGuid();
64+
var username = "test." + DateTime.Now.Ticks;
65+
var email = username + "@email.com";
66+
67+
using var session = Services.GetRequiredService<IDataSession>();
68+
69+
var user = session
70+
.StoredProcedure("[dbo].[UserUpsert]")
71+
.Parameter("@Id", userId)
72+
.Parameter("@EmailAddress", email)
73+
.Parameter("@IsEmailAddressConfirmed", true)
74+
.Parameter("@DisplayName", "Unit Test")
75+
.Parameter("@PasswordHash", "T@est" + DateTime.Now.Ticks)
76+
.Parameter<string>("@ResetHash", null)
77+
.Parameter<string>("@InviteHash", null)
78+
.Parameter("@AccessFailedCount", 0)
79+
.Parameter("@LockoutEnabled", false)
80+
.Parameter("@IsDeleted", false)
81+
.Return<int>(p => errorCode = p)
82+
.QuerySingle<User>();
83+
```
84+
85+
## Executing a stored procedure with a return parameter
86+
87+
```csharp
88+
int result = -1;
89+
long total = -1;
90+
91+
var email = "[email protected]";
92+
93+
using var session = Services.GetRequiredService<IDataSession>();
94+
95+
result = session
96+
.StoredProcedure("[dbo].[UserCountByEmailAddress]")
97+
.Parameter("@EmailAddress", email)
98+
.Return<long>(p => total = p)
99+
.Execute();
100+
101+
```

‎docs/guide/query.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Query Methods
2+
3+
## Execute or ExecuteAsync
4+
5+
Executes the command against a connection and returns the number of rows affected.
6+
7+
```csharp
8+
int result = -1;
9+
long total = -1;
10+
11+
var email = "[email protected]";
12+
13+
using var session = Services.GetRequiredService<IDataSession>();
14+
15+
result = session
16+
.StoredProcedure("[dbo].[UserCountByEmailAddress]")
17+
.Parameter("@EmailAddress", email)
18+
.Return<long>(p => total = p)
19+
.Execute();
20+
```
21+
22+
23+
## Query or QueryAsync
24+
25+
Executes the command against the connection and converts the results to a list of objects.
26+
27+
```csharp
28+
long total = -1;
29+
var email = "%@battlestar.com";
30+
31+
using var session = Services.GetRequiredService<IDataSession>();
32+
33+
var users = session
34+
.StoredProcedure("[dbo].[UserListByEmailAddress]")
35+
.Parameter("@EmailAddress", email)
36+
.Parameter("@Offset", 0)
37+
.Parameter("@Size", 10)
38+
.Parameter<long>(parameter => parameter
39+
.Name("@Total")
40+
.Type(DbType.Int64)
41+
.Output(v => total = v)
42+
.Direction(ParameterDirection.Output)
43+
)
44+
.Query<User>() // using source generated factor
45+
.ToList();
46+
```
47+
48+
## QuerySingle or QuerySingleAsync
49+
50+
Executes the query and returns the first row in the result as an object.
51+
52+
```csharp
53+
var session = Services.GetRequiredService<IDataSession>();
54+
55+
var email = "[email protected]";
56+
var sql = "select * from [User] where EmailAddress = @EmailAddress";
57+
58+
var user = session.Sql(sql)
59+
.Parameter("@EmailAddress", email)
60+
.QuerySingle(r => new User
61+
{
62+
Id = r.GetGuid("Id"),
63+
EmailAddress = r.GetString("EmailAddress"),
64+
IsEmailAddressConfirmed = r.GetBoolean("IsEmailAddressConfirmed"),
65+
DisplayName = r.GetString("DisplayName"),
66+
PasswordHash = r.GetString("PasswordHash"),
67+
ResetHash = r.GetString("ResetHash"),
68+
InviteHash = r.GetString("InviteHash"),
69+
AccessFailedCount = r.GetInt32("AccessFailedCount"),
70+
LockoutEnabled = r.GetBoolean("LockoutEnabled"),
71+
LockoutEnd = r.GetDateTimeOffsetNull("LockoutEnd"),
72+
LastLogin = r.GetDateTimeOffsetNull("LastLogin"),
73+
IsDeleted = r.GetBoolean("IsDeleted"),
74+
Created = r.GetDateTimeOffset("Created"),
75+
CreatedBy = r.GetString("CreatedBy"),
76+
Updated = r.GetDateTimeOffset("Updated"),
77+
UpdatedBy = r.GetString("UpdatedBy"),
78+
RowVersion = r.GetBytes("RowVersion"),
79+
});
80+
```
81+
82+
## QueryValue or QueryValueAsync
83+
84+
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.
85+
86+
```csharp
87+
await using var session = Services.GetRequiredService<IDataSession>();
88+
89+
string email = "@battlestar.com";
90+
91+
var count = await session
92+
.Sql(builder => builder
93+
.Select<User>()
94+
.Count()
95+
.Where(p => p.EmailAddress, email, FilterOperators.Contains)
96+
)
97+
.QueryValueAsync<int>();
98+
```
99+
100+
## QueryMultiple or QueryMultipleAsync
101+
102+
Executes the command against the connection and sends the results for reading multiple results sets
103+
104+
```csharp
105+
string email = "[email protected]";
106+
string sql = "select * from [User] where EmailAddress = @EmailAddress; " +
107+
"select * from [Role]; " +
108+
"select * from [Priority]; ";
109+
110+
User user = null;
111+
List<Role> roles = null;
112+
List<Priority> priorities = null;
113+
114+
await using var session = Services.GetRequiredService<IDataSession>();
115+
116+
await session.Sql(sql)
117+
.Parameter("@EmailAddress", email)
118+
.QueryMultipleAsync(async q =>
119+
{
120+
user = await q.QuerySingleAsync<User>();
121+
roles = (await q.QueryAsync<Role>()).ToList();
122+
priorities = (await q.QueryAsync<Priority>()).ToList();
123+
});
124+
```

0 commit comments

Comments
 (0)