Skip to content

Commit d8855a8

Browse files
bgraingerbgrainger
authored
Merge pull request #125 from caleblloyd/docs_getting_started
Add Getting Started docs. Fixes #107
2 parents 49de34d + 369a324 commit d8855a8

File tree

9 files changed

+157
-66
lines changed

9 files changed

+157
-66
lines changed

‎docs/content/connection-options.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ menu:
1111
Connection Options
1212
==================
1313

14-
MySqlConnector supports a subset of Oracle's [MySql.Data connection options](https://dev.mysql.com/doc/connector-net/en/connector-net-connection-options.html).
14+
MySqlConnector supports a subset of Oracle's [Connector/NET connection options](https://dev.mysql.com/doc/connector-net/en/connector-net-connection-options.html).
1515

1616
Base Options
1717
------------

‎docs/content/home.md

Lines changed: 55 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -12,43 +12,61 @@ menu:
1212
Home
1313
====
1414

15-
Here is some C# code
15+
MySqlConnector is an [ADO.NET](https://msdn.microsoft.com/en-us/library/e80y5yhx.aspx) data
16+
provider for [MySQL](https://www.mysql.com/). It provides implementations of
17+
`DbConnection`, `DbCommand`, `DbDataReader`, `DbTransaction` – the classes
18+
needed to query and update databases from managed code. Its features include:
1619

17-
```csharp
18-
using System.Threading.Tasks;
19-
using Microsoft.AspNetCore.Mvc;
20-
using MySqlConnector.Performance.Models;
20+
* .NET Core Compatibility
21+
* Truly Asynchronous: async functions implement asynchronous I/O
22+
* High Performance: code is stress tested for performance bottlenecks
23+
* Lightweight: Library only implements ADO.NET core
2124

22-
namespace MySqlConnector.Performance.Controllers
23-
{
24-
[Route("api/[controller]")]
25-
public class AsyncController : Controller
26-
{
27-
// GET api/async
28-
[HttpGet]
29-
public async Task<IActionResult> Get()
30-
{
31-
using (var db = new AppDb())
32-
{
33-
await db.OpenAsync();
34-
var cmd = BlogPost.LatestPosts(db);
35-
var reader = await cmd.ExecuteReaderAsync();
36-
var result = await BlogPost.ReadAllAsync(reader);
37-
return new OkObjectResult(result);
38-
}
39-
}
25+
### Why use MySql over Oracle's Connector/NET?
4026

41-
// POST api/async
42-
[HttpPost]
43-
public async Task<IActionResult> Post([FromBody]BlogPost body)
44-
{
45-
using (var db = new AppDb())
46-
{
47-
await db.OpenAsync();
48-
await BlogPost.InsertAsync(db, body);
49-
return new OkObjectResult(body);
50-
}
51-
}
52-
}
53-
}
54-
```
27+
MySqlConnector is a clean-room reimplementation of the [MySQL Protocol](https://dev.mysql.com/doc/internals/en/client-server-protocol.html)
28+
and is not based on [Oracle's Connector/NET](https://github.com/mysql/mysql-connector-net).
29+
30+
<table class="table table-striped table-hover" style="max-width: 650px">
31+
<thead>
32+
<th style="width:25%"></th>
33+
<th style="width:25%">MySqlConnector</th>
34+
<th style="width:25%">Oracle's Connector/NET</th>
35+
<th style="width:25%">MySqlConnector Advantage</th>
36+
</thead>
37+
<tr>
38+
<td><strong>Async</strong></td>
39+
<td><strong>Fully asynchronous</strong> I/O</td>
40+
<td>Async calls map to synchronous I/O</td>
41+
<td>Uses less thread pool threads</td>
42+
</tr>
43+
<tr>
44+
<td><strong>Development</strong></td>
45+
<td>
46+
<strong>Open and Collaborative</strong> Development on
47+
<a href="https://github.com/mysql/mysql-connector-net">GitHub</a>
48+
</td>
49+
<td>
50+
Closed Development Roadmap. Code is viewable on
51+
<a href="https://github.com/mysql/mysql-connector-net">GitHub</a>,
52+
some issues addressed in <a href="http://forums.mysql.com/list.php?38">Forums</a>
53+
</td>
54+
<td>
55+
Get involved! View
56+
<a href="https://github.com/mysql-net/MySqlConnector/projects/1">our roadmap</a>,
57+
discuss <a href="https://github.com/mysql-net/MySqlConnector/issues">issues</a>,
58+
contribute <a href="https://github.com/mysql-net/MySqlConnector/pulls">pull requests</a>
59+
</td>
60+
</tr>
61+
<tr>
62+
<td><strong>License</strong></td>
63+
<td>
64+
The <strong><a href="https://github.com/mysql-net/MySqlConnector/blob/master/LICENSE">MIT License</a></strong>
65+
</td>
66+
<td>
67+
<a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GPLv2</a>
68+
with <a href="http://www.mysql.com/about/legal/licensing/foss-exception/">FOSS Exception</a>
69+
</td>
70+
<td>More Permissive</td>
71+
</tr>
72+
</table>

‎docs/content/overview/configuration.md

Lines changed: 54 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,63 @@ menu:
55
main:
66
parent: getting started
77
title: Configuration
8-
weight: 30
8+
weight: 20
99
---
1010

1111
Configuration
1212
============
1313

14-
To connect to a database on `localhost` port `3306` with a user `mysqltest`, password `test;key=\"val`, and default schema `mysqldb`, the connection string would be:
14+
MySqlConnector uses a connection string in order to connect to your database.
1515

16-
`host=127.0.0.1;port=3306;user id=mysqltest;password='test;key=\"val';database=mysqldb;`
16+
To connect to a database on `localhost` port `3306` with a user `mysqltest`, password `Password123`, and default schema `mysqldb`, the connection string would be:
17+
18+
`host=127.0.0.1;port=3306;user id=mysqltest;password=Password123;database=mysqldb;`
19+
20+
For all connection string options, view the [Connection Options Reference](connection-options/)
21+
22+
### Application Database Object Example
23+
24+
It's a good idea to use an IDisposable object that configures the connection string globally, and closes the connection automatically:
25+
26+
```csharp
27+
public class AppDb : IDisposable
28+
{
29+
public readonly MySqlConnection Connection;
30+
31+
public AppDb()
32+
{
33+
Connection = new MySqlConnection("host=127.0.0.1;port=3306;user id=mysqltest;password=Password123;database=mysqldb;");
34+
}
35+
36+
public void Dispose()
37+
{
38+
Connection.Close();
39+
}
40+
}
41+
42+
```
43+
44+
Callers can use the Application Database Object object like so:
45+
46+
```csharp
47+
public async Task AsyncMethod()
48+
{
49+
using (var db = new AppDb())
50+
{
51+
await db.Connection.OpenAsync();
52+
// db.Connection is open and ready to use
53+
}
54+
// db.Connection was closed by AppDb.Dispose
55+
}
56+
57+
public void SyncMethod()
58+
{
59+
using (var db = new AppDb())
60+
{
61+
db.Connection.Open();
62+
// db.Connection is open and ready to use
63+
}
64+
// db.Connection was closed by AppDb.Dispose
65+
}
66+
67+
```

‎docs/content/overview/installing.md

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,30 @@
1-
21
---
32
lastmod: 2016-10-16
43
date: 2016-10-16
54
menu:
65
main:
76
parent: getting started
87
title: Installing
9-
weight: 20
8+
weight: 10
109
---
1110

1211
Installing
1312
==========
1413

15-
Installing
14+
The recommended way of installing MySqlConnector is through [NuGet](https://www.nuget.org/packages/MySqlConnector/)
15+
16+
**Step 1:** Add MySqlConnector to the dependencies in your `project.json` file:
17+
18+
```json
19+
{
20+
"title": "My Application",
21+
"description": "A great application",
22+
"dependencies": {
23+
"MySqlConnector": "0.*",
24+
// other dependencies
25+
},
26+
// other config
27+
}
28+
```
29+
30+
**Step 2:** Run the command `dotnet restore`

‎docs/content/overview/introduction.md

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs/content/overview/use-with-orms.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
lastmod: 2016-10-16
3+
date: 2016-10-16
4+
menu:
5+
main:
6+
parent: getting started
7+
title: Use with ORMs
8+
weight: 30
9+
---
10+
11+
Use with ORMs
12+
=============
13+
14+
This library is compatible with popular .NET ORMs including:
15+
16+
* [Dapper](https://github.com/StackExchange/dapper-dot-net) ([NuGet](https://www.nuget.org/packages/Dapper))
17+
* [NReco.Data](https://github.com/nreco/data) ([NuGet](https://www.nuget.org/packages/NReco.Data))
18+
* [SimpleStack.Orm](https://github.com/SimpleStack/simplestack.orm) ([NuGet](https://www.nuget.org/packages/SimpleStack.Orm.MySQLConnector))
19+
20+
For Entity Framework support, use:
21+
22+
* [Pomelo.EntityFrameworkCore.MySql](https://github.com/PomeloFoundation/Pomelo.EntityFrameworkCore.MySql) ([NuGet](https://www.nuget.org/packages/Pomelo.EntityFrameworkCore.MySql))

‎docs/content/tutorials/migrating-from-connector-net.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@ date: 2016-10-16
44
menu:
55
main:
66
parent: tutorials
7-
title: Migrating from Connector/Net
7+
title: Migrating from Connector/NET
88
weight: 20
99
---
1010

11-
Migrating from Connector/Net
11+
Migrating from Connector/NET
1212
=============
1313

14-
Migrating from Connector/Net
14+
Migrating from Connector/NET

‎docs/static/vendor/prism/css/prism.css

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/* http://prismjs.com/download.html?themes=prism&languages=markup+css+clike+javascript+aspnet+csharp */
1+
/* http://prismjs.com/download.html?themes=prism&languages=markup+css+clike+javascript+aspnet+csharp+json */
22
/**
33
* prism.js default theme for JavaScript, CSS and HTML
44
* Based on dabblet (http://dabblet.com)
@@ -56,7 +56,7 @@ pre[class*="language-"] {
5656

5757
:not(pre) > code[class*="language-"],
5858
pre[class*="language-"] {
59-
background: #f5f2f0;
59+
background: #f8f8f8;
6060
}
6161

6262
/* Inline code */
@@ -136,4 +136,3 @@ pre[class*="language-"] {
136136
.token.entity {
137137
cursor: help;
138138
}
139-

0 commit comments

Comments
 (0)