Skip to content

Commit f932914

Browse files
electricessenceelectricessence
authored
Merge pull request #5 from electricessence/development
Updated docs.
2 parents 7e65e71 + 89db694 commit f932914

8 files changed

Lines changed: 227 additions & 30 deletions

File tree

‎Core/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Open.Database.Extensions
22

3-
(Full API Documenation)[]
3+
[Full API Documentation](https://electricessence.github.io/Open.Database.Extensions/api/index.html)
44

55
Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.
66

@@ -34,14 +34,14 @@ var myResult = new List<T>();
3434
using(var reader = await mySqlCommand.ExecuteReaderAsync(CommandBehavior.CloseConnection))
3535
{
3636
while(await reader.ReadAsync())
37-
list.Add(transform(reader));
37+
myResult.Add(transform(reader));
3838
}
3939
```
4040

4141
Is now simplified to this:
4242

4343
```cs
44-
var myResult = await cmd.ToListAsync(transform);
44+
var myResult = await mySqlCommand.ToListAsync(transform);
4545
```
4646

4747
## Deferred Transformation
@@ -86,7 +86,7 @@ var people = cmd.Results<Person>(new Dictionary<string,string>{
8686
{"LastName", "last_name"});
8787
```
8888

89-
### `Retrieve()` and `RetrieveAsync()`
89+
#### `Retrieve()` and `RetrieveAsync()`
9090

9191
Queues all the data. Returns a `QueryResult<Queue<object[]>>` containing the requested data and column information. The `.AsDequeueingMappedEnumerable()` extension will iteratively convert the results to dictionaries for ease of access.
9292

‎Core/api/index.md‎

Lines changed: 121 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,121 @@
1-
# PLACEHOLDER
2-
TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
1+
# Open.Database.Extensions
2+
3+
[GitHub](https://github.com/electricessence/Open.Database.Extensions)
4+
5+
Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.
6+
7+
## Connection Factories
8+
9+
Connection factories facilitate creation and disposal of connections without the concern of a connection reference or need for awareness of a connection string.
10+
11+
## Expressive Commands
12+
13+
The provided expressive command classes allow for an expressive means to append parameters and execute the results without lengthy complicated setup.
14+
15+
Extensions are provided to create commands from connection factories.
16+
17+
### Example
18+
19+
```cs
20+
var result = connectionFactory
21+
.StoredProcedure("[procedure name]")
22+
.AddParam("a",1)
23+
.AddParam("b",true)
24+
.AddParam("c","hello")
25+
.ExecuteScalar();
26+
```
27+
28+
## Extensions
29+
30+
Instead of writing this:
31+
32+
```cs
33+
var myResult = new List<T>();
34+
using(var reader = await mySqlCommand.ExecuteReaderAsync(CommandBehavior.CloseConnection))
35+
{
36+
while(await reader.ReadAsync())
37+
myResult.Add(transform(reader));
38+
}
39+
```
40+
41+
Is now simplified to this:
42+
43+
```cs
44+
var myResult = await mySqlCommand.ToListAsync(transform);
45+
```
46+
47+
## Deferred Transformation
48+
49+
In order to keep connection open time to a minimum, some methods cache data before closing the connection and then subsequently applying the transformations as needed.
50+
51+
### `Results<T>()` and `ResultsAsync<T>()`
52+
53+
Queues all the data. Then using the provided type `T` entity, the data is coerced by which properties intersect with the ones available to the `IDataReader`.
54+
55+
Optionally a field to column override map can be passed as a parameter. If a column is set as `null` then that field is ignored (not applied to the model).
56+
57+
### Examples
58+
59+
If all the columns in the database map exactly to a field: (A column that has no associated field/property is ignored.)
60+
61+
```cs
62+
var people = cmd.Results<Person>();
63+
```
64+
65+
If the database fields don't map exactly:
66+
67+
```cs
68+
var people = cmd.Results<Person>(
69+
(Field:"FirstName", Column:"first_name"),
70+
(Field:"LastName", Column:"last_name")));
71+
```
72+
73+
or
74+
75+
```cs
76+
var people = cmd.Results<Person>(
77+
("FirstName", "first_name"),
78+
("LastName", "last_name"));
79+
```
80+
81+
or
82+
83+
```cs
84+
var people = cmd.Results<Person>(new Dictionary<string,string>{
85+
{"FirstName", "first_name"},
86+
{"LastName", "last_name"});
87+
```
88+
89+
#### `Retrieve()` and `RetrieveAsync()`
90+
91+
Queues all the data. Returns a `QueryResult<Queue<object[]>>` containing the requested data and column information. The `.AsDequeueingMappedEnumerable()` extension will iteratively convert the results to dictionaries for ease of access.
92+
93+
### `ResultsAsync<T>`
94+
95+
`ResultsAsync<T>()` is fully asynchronous from end-to-end but returns an `IEnumerable<T>` that although has fully buffered the all the data into memory, has deferred the transformation until enumerated. This way, the asynchronous data pipeline is fully complete before synchronously transforming the data.
96+
97+
## Transactions
98+
99+
Example:
100+
101+
```cs
102+
// Returns true if the transaction is successful.
103+
public static bool TryTransaction()
104+
=> ConnectionFactory.Using(connection =>
105+
// Open a connection and start a transaction.
106+
connection.ExecuteTransactionConditional(transaction => {
107+
108+
// First procedure does some updates.
109+
var count = transaction
110+
.StoredProcedure("[Updated Procedure]")
111+
.ExecuteNonQuery();
112+
113+
// Second procedure validates the results.
114+
// If it returns true, then the transaction is committed.
115+
// If it returns false, then the transaction is rolled back.
116+
return transaction
117+
.StoredProcedure("[Validation Procedure]")
118+
.AddParam("@ExpectedCount", count)
119+
.ExecuteScalar<bool>();
120+
}));
121+
```

‎Core/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Open.Database.Extensions
22

3-
(Full API Documenation)[]
3+
[Full API Documentation](https://electricessence.github.io/Open.Database.Extensions/api/index.html)
44

55
Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.
66

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Open.Database.Extensions
22

3+
[Full API Documentation](https://electricessence.github.io/Open.Database.Extensions/api/index.html)
4+
35
Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.
46

57
## Connection Factories

‎docs/README.html‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@
6262
<article class="content wrap" id="_content" data-uid="">
6363
<h1 id="opendatabaseextensions">Open.Database.Extensions</h1>
6464

65-
<p>(Full API Documenation)[]</p>
65+
<p><a href="https://electricessence.github.io/Open.Database.Extensions/api/index.html">Full API Documentation</a></p>
6666
<p>Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.</p>
6767
<h2 id="connection-factories">Connection Factories</h2>
6868
<p>Connection factories facilitate creation and disposal of connections without the concern of a connection reference or need for awareness of a connection string.</p>
@@ -83,11 +83,11 @@ <h2 id="extensions">Extensions</h2>
8383
using(var reader = await mySqlCommand.ExecuteReaderAsync(CommandBehavior.CloseConnection))
8484
{
8585
while(await reader.ReadAsync())
86-
list.Add(transform(reader));
86+
myResult.Add(transform(reader));
8787
}
8888
</code></pre>
8989
<p>Is now simplified to this:</p>
90-
<pre><code class="lang-cs">var myResult = await cmd.ToListAsync(transform);
90+
<pre><code class="lang-cs">var myResult = await mySqlCommand.ToListAsync(transform);
9191
</code></pre>
9292
<h2 id="deferred-transformation">Deferred Transformation</h2>
9393
<p>In order to keep connection open time to a minimum, some methods cache data before closing the connection and then subsequently applying the transformations as needed.</p>
@@ -113,7 +113,7 @@ <h3 id="examples">Examples</h3>
113113
{&quot;FirstName&quot;, &quot;first_name&quot;},
114114
{&quot;LastName&quot;, &quot;last_name&quot;});
115115
</code></pre>
116-
<h3 id="retrieve-and-retrieveasync"><code>Retrieve()</code> and <code>RetrieveAsync()</code></h3>
116+
<h4 id="retrieve-and-retrieveasync"><code>Retrieve()</code> and <code>RetrieveAsync()</code></h4>
117117
<p>Queues all the data. Returns a <code>QueryResult&lt;Queue&lt;object[]&gt;&gt;</code> containing the requested data and column information. The <code>.AsDequeueingMappedEnumerable()</code> extension will iteratively convert the results to dictionaries for ease of access.</p>
118118
<h3 id="resultsasynct"><code>ResultsAsync&lt;T&gt;</code></h3>
119119
<p><code>ResultsAsync&lt;T&gt;()</code> is fully asynchronous from end-to-end but returns an <code>IEnumerable&lt;T&gt;</code> that although has fully buffered the all the data into memory, has deferred the transformation until enumerated. This way, the asynchronous data pipeline is fully complete before synchronously transforming the data.</p>

‎docs/api/index.html‎

Lines changed: 80 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
<head>
66
<meta charset="utf-8">
77
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
8-
<title>PLACEHOLDER </title>
8+
<title>Open.Database.Extensions </title>
99
<meta name="viewport" content="width=device-width">
10-
<meta name="title" content="PLACEHOLDER ">
10+
<meta name="title" content="Open.Database.Extensions ">
1111
<meta name="generator" content="docfx 2.47.0.0">
1212

1313
<link rel="shortcut icon" href="../favicon.ico">
@@ -67,9 +67,85 @@
6767
<div class="article row grid-right">
6868
<div class="col-md-10">
6969
<article class="content wrap" id="_content" data-uid="">
70-
<h1 id="placeholder">PLACEHOLDER</h1>
70+
<h1 id="opendatabaseextensions">Open.Database.Extensions</h1>
7171

72-
<p>TODO: Add .NET projects to the <em>src</em> folder and run <code>docfx</code> to generate <strong>REAL</strong> <em>API Documentation</em>!</p>
72+
<p><a href="https://github.com/electricessence/Open.Database.Extensions">GitHub</a></p>
73+
<p>Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.</p>
74+
<h2 id="connection-factories">Connection Factories</h2>
75+
<p>Connection factories facilitate creation and disposal of connections without the concern of a connection reference or need for awareness of a connection string.</p>
76+
<h2 id="expressive-commands">Expressive Commands</h2>
77+
<p>The provided expressive command classes allow for an expressive means to append parameters and execute the results without lengthy complicated setup.</p>
78+
<p>Extensions are provided to create commands from connection factories.</p>
79+
<h3 id="example">Example</h3>
80+
<pre><code class="lang-cs">var result = connectionFactory
81+
.StoredProcedure(&quot;[procedure name]&quot;)
82+
.AddParam(&quot;a&quot;,1)
83+
.AddParam(&quot;b&quot;,true)
84+
.AddParam(&quot;c&quot;,&quot;hello&quot;)
85+
.ExecuteScalar();
86+
</code></pre>
87+
<h2 id="extensions">Extensions</h2>
88+
<p>Instead of writing this:</p>
89+
<pre><code class="lang-cs">var myResult = new List&lt;T&gt;();
90+
using(var reader = await mySqlCommand.ExecuteReaderAsync(CommandBehavior.CloseConnection))
91+
{
92+
while(await reader.ReadAsync())
93+
myResult.Add(transform(reader));
94+
}
95+
</code></pre>
96+
<p>Is now simplified to this:</p>
97+
<pre><code class="lang-cs">var myResult = await mySqlCommand.ToListAsync(transform);
98+
</code></pre>
99+
<h2 id="deferred-transformation">Deferred Transformation</h2>
100+
<p>In order to keep connection open time to a minimum, some methods cache data before closing the connection and then subsequently applying the transformations as needed.</p>
101+
<h3 id="resultst-and-resultsasynct"><code>Results&lt;T&gt;()</code> and <code>ResultsAsync&lt;T&gt;()</code></h3>
102+
<p>Queues all the data. Then using the provided type <code>T</code> entity, the data is coerced by which properties intersect with the ones available to the <code>IDataReader</code>.</p>
103+
<p>Optionally a field to column override map can be passed as a parameter. If a column is set as <code>null</code> then that field is ignored (not applied to the model).</p>
104+
<h3 id="examples">Examples</h3>
105+
<p>If all the columns in the database map exactly to a field: (A column that has no associated field/property is ignored.)</p>
106+
<pre><code class="lang-cs">var people = cmd.Results&lt;Person&gt;();
107+
</code></pre>
108+
<p>If the database fields don't map exactly:</p>
109+
<pre><code class="lang-cs">var people = cmd.Results&lt;Person&gt;(
110+
(Field:&quot;FirstName&quot;, Column:&quot;first_name&quot;),
111+
(Field:&quot;LastName&quot;, Column:&quot;last_name&quot;)));
112+
</code></pre>
113+
<p>or</p>
114+
<pre><code class="lang-cs">var people = cmd.Results&lt;Person&gt;(
115+
(&quot;FirstName&quot;, &quot;first_name&quot;),
116+
(&quot;LastName&quot;, &quot;last_name&quot;));
117+
</code></pre>
118+
<p>or</p>
119+
<pre><code class="lang-cs">var people = cmd.Results&lt;Person&gt;(new Dictionary&lt;string,string&gt;{
120+
{&quot;FirstName&quot;, &quot;first_name&quot;},
121+
{&quot;LastName&quot;, &quot;last_name&quot;});
122+
</code></pre>
123+
<h4 id="retrieve-and-retrieveasync"><code>Retrieve()</code> and <code>RetrieveAsync()</code></h4>
124+
<p>Queues all the data. Returns a <code>QueryResult&lt;Queue&lt;object[]&gt;&gt;</code> containing the requested data and column information. The <code>.AsDequeueingMappedEnumerable()</code> extension will iteratively convert the results to dictionaries for ease of access.</p>
125+
<h3 id="resultsasynct"><code>ResultsAsync&lt;T&gt;</code></h3>
126+
<p><code>ResultsAsync&lt;T&gt;()</code> is fully asynchronous from end-to-end but returns an <code>IEnumerable&lt;T&gt;</code> that although has fully buffered the all the data into memory, has deferred the transformation until enumerated. This way, the asynchronous data pipeline is fully complete before synchronously transforming the data.</p>
127+
<h2 id="transactions">Transactions</h2>
128+
<p>Example:</p>
129+
<pre><code class="lang-cs">// Returns true if the transaction is successful.
130+
public static bool TryTransaction()
131+
=&gt; ConnectionFactory.Using(connection =&gt;
132+
// Open a connection and start a transaction.
133+
connection.ExecuteTransactionConditional(transaction =&gt; {
134+
135+
// First procedure does some updates.
136+
var count = transaction
137+
.StoredProcedure(&quot;[Updated Procedure]&quot;)
138+
.ExecuteNonQuery();
139+
140+
// Second procedure validates the results.
141+
// If it returns true, then the transaction is committed.
142+
// If it returns false, then the transaction is rolled back.
143+
return transaction
144+
.StoredProcedure(&quot;[Validation Procedure]&quot;)
145+
.AddParam(&quot;@ExpectedCount&quot;, count)
146+
.ExecuteScalar&lt;bool&gt;();
147+
}));
148+
</code></pre>
73149
</article>
74150
</div>
75151

‎docs/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@
6262
<article class="content wrap" id="_content" data-uid="">
6363
<h1 id="opendatabaseextensions">Open.Database.Extensions</h1>
6464

65-
<p>(Full API Documenation)[]</p>
65+
<p><a href="https://electricessence.github.io/Open.Database.Extensions/api/index.html">Full API Documentation</a></p>
6666
<p>Useful set of utilities and abstractions for simplifying modern database operations and ensuring dependency injection compatibility.</p>
6767
<h2 id="connection-factories">Connection Factories</h2>
6868
<p>Connection factories facilitate creation and disposal of connections without the concern of a connection reference or need for awareness of a connection string.</p>

‎docs/manifest.json‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,10 @@
99
"output": {
1010
".html": {
1111
"relative_path": "README.html",
12-
"hash": "tyD8A/u7sWAfe+8R1dLxxA=="
12+
"hash": "6n0p5fClpr18KwRHo3OGSg=="
1313
}
1414
},
15-
"is_incremental": true,
15+
"is_incremental": false,
1616
"version": ""
1717
},
1818
{
@@ -405,10 +405,10 @@
405405
"output": {
406406
".html": {
407407
"relative_path": "api/index.html",
408-
"hash": "tF+QKSRFfWltk151Do+gpA=="
408+
"hash": "R3roe74Czsq4LUqX9ardkg=="
409409
}
410410
},
411-
"is_incremental": true,
411+
"is_incremental": false,
412412
"version": ""
413413
},
414414
{
@@ -429,10 +429,10 @@
429429
"output": {
430430
".html": {
431431
"relative_path": "index.html",
432-
"hash": "WT75xuCxVHlY08oHgFRFfg=="
432+
"hash": "+6gZq5CVqvXPB5cqlxvhdQ=="
433433
}
434434
},
435-
"is_incremental": true,
435+
"is_incremental": false,
436436
"version": ""
437437
},
438438
{
@@ -457,13 +457,6 @@
457457
"skipped_file_count": 0
458458
},
459459
"processors": {
460-
"TocDocumentProcessor": {
461-
"can_incremental": false,
462-
"details": "Processor TocDocumentProcessor cannot support incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.",
463-
"incrementalPhase": "build",
464-
"total_file_count": 0,
465-
"skipped_file_count": 0
466-
},
467460
"ManagedReferenceDocumentProcessor": {
468461
"can_incremental": true,
469462
"incrementalPhase": "build",
@@ -474,7 +467,14 @@
474467
"can_incremental": true,
475468
"incrementalPhase": "build",
476469
"total_file_count": 3,
477-
"skipped_file_count": 3
470+
"skipped_file_count": 0
471+
},
472+
"TocDocumentProcessor": {
473+
"can_incremental": false,
474+
"details": "Processor TocDocumentProcessor cannot support incremental build because the processor doesn't implement ISupportIncrementalDocumentProcessor interface.",
475+
"incrementalPhase": "build",
476+
"total_file_count": 0,
477+
"skipped_file_count": 0
478478
}
479479
}
480480
},

0 commit comments

Comments
 (0)