From 5b2716bd2e994a0fad91392e932c784f234d99d2 Mon Sep 17 00:00:00 2001 From: wei Date: Fri, 2 Jul 2021 09:30:10 +0800 Subject: [PATCH 1/2] Add Documentation for Dapper.SqlBuilder (Issue #688, #480) --- Dapper.SqlBuilder/Readme.md | 107 ++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 Dapper.SqlBuilder/Readme.md diff --git a/Dapper.SqlBuilder/Readme.md b/Dapper.SqlBuilder/Readme.md new file mode 100644 index 000000000..28ff23f94 --- /dev/null +++ b/Dapper.SqlBuilder/Readme.md @@ -0,0 +1,107 @@ +Dapper.SqlBuilder - a simple sql formatter for .Net +======================================== +[![Build status](https://ci.appveyor.com/api/projects/status/1w448i6nfxd14w75?svg=true)](https://ci.appveyor.com/project/StackExchange/dapper-SqlBuilder) + +Packages +-------- + +MyGet Pre-release feed: https://www.myget.org/gallery/dapper + +| Package | NuGet Stable | NuGet Pre-release | Downloads | MyGet | +| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | +| [Dapper.SqlBuilder](https://www.nuget.org/packages/Dapper.SqlBuilder/) | [![Dapper.SqlBuilder](https://img.shields.io/nuget/v/Dapper.SqlBuilder.svg)](https://www.nuget.org/packages/Dapper.SqlBuilder/) | [![Dapper.SqlBuilder](https://img.shields.io/nuget/vpre/Dapper.SqlBuilder.svg)](https://www.nuget.org/packages/Dapper.SqlBuilder/) | [![Dapper.SqlBuilder](https://img.shields.io/nuget/dt/Dapper.SqlBuilder.svg)](https://www.nuget.org/packages/Dapper.SqlBuilder/) | [![Dapper.SqlBuilder MyGet](https://img.shields.io/myget/dapper/vpre/Dapper.SqlBuilder.svg)](https://www.myget.org/feed/dapper/package/nuget/Dapper.SqlBuilder) | + +Features +-------- + +Dapper.SqlBuilder contains a number of helper methods for generating sql. + +The list of extension methods in Dapper.SqlBuilder right now are: + +```csharp= +SqlBuilder AddParameters(dynamic parameters); +SqlBuilder Select(string sql, dynamic parameters = null); +SqlBuilder Where(string sql, dynamic parameters = null); +SqlBuilder OrWhere(string sql, dynamic parameters = null); +SqlBuilder OrderBy(string sql, dynamic parameters = null); +SqlBuilder GroupBy(string sql, dynamic parameters = null); +SqlBuilder Having(string sql, dynamic parameters = null); +SqlBuilder Set(string sql, dynamic parameters = null); +SqlBuilder Join(string sql, dynamic parameters = null); +SqlBuilder InnerJoin(string sql, dynamic parameters = null); +SqlBuilder LeftJoin(string sql, dynamic parameters = null); +SqlBuilder RightJoin(string sql, dynamic parameters = null); +SqlBuilder Intersect(string sql, dynamic parameters = null); +``` + + +Template +-------- + +SqlBuilder allows you to generate N SQL templates from a composed query, it can easily format sql when you are attaching parameters and how, e.g: +```csharp= +var builder = new SqlBuilder() + .Where("a = @a", new { a = 1 }) + .Where("b = @b", new { b = 2 }) + .OrderBy("a") + .OrderBy("b"); +var counter = builder.AddTemplate("select count(*) from table /**where**/"); +var selector = builder.AddTemplate("select * from table /**where**/ /**orderby**/"); +var count = cnn.Query(counter.RawSql, counter.Parameters).Single(); +var rows = cnn.Query(selector.RawSql, selector.Parameters); +``` + +it's same as +```csharp= +var count = cnn.Query("select count(*) from table where a = @a and b = @b", new { a = 1, b = 1 }); +var rows = cnn.Query("select * from table where a = @a and b = @b order by a, b", new { a = 1, b = 1 }); +``` + +Dynamic Filter Paging Example +---------- + +```csharp= +var builder = new SqlBuilder(); +var selectTemplate = builder.AddTemplate(@"select X.* from ( + select us.*, ROW_NUMBER() OVER (/**orderby**/) AS RowNumber + from Users us + /**where**/ + ) as X + where RowNumber between @start and @finish", new { start, finish }); +var countTemplate = builder.AddTemplate(@"select count(*) from Users /**where**/"); + +if (userId.HasValue()) + builder.Where($"t.userId = @{nameof(userId)}", new { userId }); +if (isCancel) + builder.Where($"t.isCancel = @{nameof(isCancel)}", new { isCancel }); + +builder.OrderBy(string.Format("t.id {0}", orderDesc ? "desc" : "asc")); + +var users = conn.Query(selectTemplate.RawSql, selectTemplate.Parameters); +var count = conn.ExecuteScalar(countTemplate.RawSql, countTemplate.Parameters); +//..etc.. +``` + +Limitations and caveats +-------- + +OrWhere use `and` not `or` to concat sql problem + +[Issue 647](https://github.com/DapperLib/Dapper/issues/647) + +```csharp= +sql.Where("a = @a1"); +sql.OrWhere("b = @b1"); +sql.Where("a = @a2"); +sql.OrWhere("b = @b2"); +``` + +SqlBuilder will generate sql +```sql= +a = @a1 AND b = @b1 AND a = @a2 AND b = @b2 +``` + +not +```sql +a = @a1 OR b = @b1 AND a = @a2 OR b = @b2 +``` \ No newline at end of file From fe86b9d71c563621acd35e8c4d7f6696c1458b6a Mon Sep 17 00:00:00 2001 From: Wei Date: Fri, 2 Jul 2021 11:11:40 +0800 Subject: [PATCH 2/2] Update Readme.md `csharp=` -> `csharp` for github color code format --- Dapper.SqlBuilder/Readme.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Dapper.SqlBuilder/Readme.md b/Dapper.SqlBuilder/Readme.md index 28ff23f94..ea69d9b80 100644 --- a/Dapper.SqlBuilder/Readme.md +++ b/Dapper.SqlBuilder/Readme.md @@ -18,7 +18,7 @@ Dapper.SqlBuilder contains a number of helper methods for generating sql. The list of extension methods in Dapper.SqlBuilder right now are: -```csharp= +```csharp SqlBuilder AddParameters(dynamic parameters); SqlBuilder Select(string sql, dynamic parameters = null); SqlBuilder Where(string sql, dynamic parameters = null); @@ -39,7 +39,7 @@ Template -------- SqlBuilder allows you to generate N SQL templates from a composed query, it can easily format sql when you are attaching parameters and how, e.g: -```csharp= +```csharp var builder = new SqlBuilder() .Where("a = @a", new { a = 1 }) .Where("b = @b", new { b = 2 }) @@ -52,7 +52,7 @@ var rows = cnn.Query(selector.RawSql, selector.Parameters); ``` it's same as -```csharp= +```csharp var count = cnn.Query("select count(*) from table where a = @a and b = @b", new { a = 1, b = 1 }); var rows = cnn.Query("select * from table where a = @a and b = @b order by a, b", new { a = 1, b = 1 }); ``` @@ -60,7 +60,7 @@ var rows = cnn.Query("select * from table where a = @a and b = @b order by a, b" Dynamic Filter Paging Example ---------- -```csharp= +```csharp var builder = new SqlBuilder(); var selectTemplate = builder.AddTemplate(@"select X.* from ( select us.*, ROW_NUMBER() OVER (/**orderby**/) AS RowNumber @@ -89,7 +89,7 @@ OrWhere use `and` not `or` to concat sql problem [Issue 647](https://github.com/DapperLib/Dapper/issues/647) -```csharp= +```csharp sql.Where("a = @a1"); sql.OrWhere("b = @b1"); sql.Where("a = @a2"); @@ -104,4 +104,4 @@ a = @a1 AND b = @b1 AND a = @a2 AND b = @b2 not ```sql a = @a1 OR b = @b1 AND a = @a2 OR b = @b2 -``` \ No newline at end of file +```