{"id":13457956,"url":"https://github.com/Drizin/DapperQueryBuilder","last_synced_at":"2025-03-24T14:32:31.094Z","repository":{"id":39925500,"uuid":"283642044","full_name":"Drizin/DapperQueryBuilder","owner":"Drizin","description":"Dapper Query Builder using String Interpolation and Fluent API","archived":false,"fork":false,"pushed_at":"2024-05-23T01:19:16.000Z","size":292,"stargazers_count":527,"open_issues_count":1,"forks_count":49,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-01T03:48:16.833Z","etag":null,"topics":["dapper","dapper-query-builder","interpolated-strings","querybuilder"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Drizin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["Drizin"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2020-07-30T01:42:52.000Z","updated_at":"2025-02-17T03:34:23.000Z","dependencies_parsed_at":"2024-05-21T03:01:43.020Z","dependency_job_id":null,"html_url":"https://github.com/Drizin/DapperQueryBuilder","commit_stats":{"total_commits":117,"total_committers":10,"mean_commits":11.7,"dds":"0.17948717948717952","last_synced_commit":"997627b1fc2a86209ef501a6edd27ca769380210"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drizin%2FDapperQueryBuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drizin%2FDapperQueryBuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drizin%2FDapperQueryBuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drizin%2FDapperQueryBuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Drizin","download_url":"https://codeload.github.com/Drizin/DapperQueryBuilder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245289728,"owners_count":20591122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dapper","dapper-query-builder","interpolated-strings","querybuilder"],"created_at":"2024-07-31T09:00:40.640Z","updated_at":"2025-03-24T14:32:30.701Z","avatar_url":"https://github.com/Drizin.png","language":"C#","readme":"[![Nuget](https://img.shields.io/nuget/v/Dapper-QueryBuilder?label=Dapper-QueryBuilder)](https://www.nuget.org/packages/Dapper-QueryBuilder)\n[![Downloads](https://img.shields.io/nuget/dt/Dapper-QueryBuilder.svg)](https://www.nuget.org/packages/Dapper-QueryBuilder)\n[![Nuget](https://img.shields.io/nuget/v/DapperQueryBuilder.StrongName?label=DapperQueryBuilder.StrongName)](https://www.nuget.org/packages/DapperQueryBuilder.StrongName)\n[![Downloads](https://img.shields.io/nuget/dt/DapperQueryBuilder.StrongName.svg)](https://www.nuget.org/packages/DapperQueryBuilder.StrongName)\n\n# **Important Notice**\n\nDapperQueryBuilder was fully rewritten into a new library [InterpolatedSql](https://github.com/Drizin/InterpolatedSql/) which is faster, much more extensible, and does not depend on Dapper (you can use our magic string interpolation with any ORM or Micro-ORM or even bare ADO.NET).  \nThe Dapper-specific features (Dapper extensions and mapping of Dapper types) were moved into [InterpolatedSql.Dapper](https://github.com/Drizin/InterpolatedSql/tree/main/src/InterpolatedSql.Dapper), which is our \"batteries-included library\", and it still supports all databases supported by Dapper.  \n\nThe current release of DapperQueryBuilder (2.x.x) is just a copy of InterpolatedSql.Dapper with some minor facades added for backward compatibility (e.g. you can still use the old `DapperQueryBuilder` namespace). For long-term support (new features and bug fixes) please consider moving to [InterpolatedSql.Dapper](https://github.com/Drizin/InterpolatedSql/tree/main/src/InterpolatedSql.Dapper), which will get more frequent updates.  \n\nPlease consider starring :star: both repositories.\n\n# Dapper Query Builder\n\n**Dapper Query Builder using String Interpolation and Fluent API**\n\nWe all love Dapper and how Dapper is a minimalist library.\n\nThis library is a tiny wrapper around Dapper to help manual building of dynamic SQL queries and commands. It's based on 2 fundamentals:\n\n## Fundamental 1: Parameters are passed using String Interpolation (but it's safe against SQL injection!)\n\nBy using interpolated strings we can pass parameters directly (embedded in the query) without having to use anonymous objects and without worrying about matching the property names with the SQL parameters. We can just build our queries with regular string interpolation and this library **will automatically \"parameterize\" our interpolated objects (sql-injection safe)**.\n\nWith plain Dapper we would write a parameterized query like this:\n\n```cs\nstring productName = \"%Computer%\";\nint subCategoryId = 10;\n\n// Note that the SQL parameter names (@productName and @subCategoryId)...\nvar products = cn\n    .Query\u003cProduct\u003e($@\"\n    SELECT * FROM Product\n    WHERE\n    Name LIKE @productName\n    AND ProductSubcategoryID = @subCategoryId\n    ORDER BY ProductId\",\n    new { productName, subCategoryId }); // ... must match the anonymous object\n```\n\n**With Dapper Query Builder we can just embed variables inside the query:**\n```cs\nstring productName = \"%Computer%\";\nint subCategoryId = 10;\n\nvar products = cn\n    .QueryBuilder($@\"\n    SELECT * FROM Product\n    WHERE\n    Name LIKE {productName}\n    AND ProductSubcategoryID = {subCategoryId}\n    ORDER BY ProductId\"\n    ).Query\u003cProduct\u003e();\n```\nWhen `.Query\u003cT\u003e()` is invoked `QueryBuilder` will basically invoke Dapper equivalent method (`Query\u003cT\u003e()`) and pass a fully parameterized query (without risk of SQL-injection) even though it looks like you're just building dynamic sql.  \n\nDapper would receive a fully parameterized query, but without the risk of having mismatches in the names or number of parameters. Dapper would get this sql:\n\n```sql\nSELECT * FROM Product\nWHERE\nName LIKE @p0\nAND ProductSubcategoryID = @p1\nORDER BY ProductId\n``` \nand these parameters: ```new { p0 = productName, p1 = subCategoryId } ```\n\n\n\n## Fundamental 2: Query and Parameters walk side-by-side\n\nQueryBuilder basically wraps 2 things that should always stay together: the query which you're building, and the parameters which must go together with our query.\nThis is a simple concept but it allows us to dynamically add new parameterized SQL clauses/conditions in a single statement.\n\nThis is how we would build a query with a variable number of conditions using plain Dapper:\n\n```cs\nvar dynamicParams = new DynamicParameters();\nstring sql = \"SELECT * FROM Product WHERE 1=1\";\nsql += \" AND Name LIKE @productName\"; \ndynamicParams.Add(\"productName\", productName);\nsql += \" AND ProductSubcategoryID = @subCategoryId\"; \ndynamicParams.Add(\"subCategoryId\", subCategoryId);\nvar products = cn.Query\u003cProduct\u003e(sql, dynamicParams);\n``` \n\n\n**With Dapper Query Builder the SQL statement and the associated Parameters are kept together**, making it easy to append dynamic conditions:\n```cs\nvar query = cn.QueryBuilder($\"SELECT * FROM Product WHERE 1=1\");\nquery += $\"AND Name LIKE {productName}\"; \nquery += $\"AND ProductSubcategoryID = {subCategoryId}\"; \nvar products = query.Query\u003cProduct\u003e(); \n```\n\nOur classes (`QueryBuilder` and `CommandBuilder`) wrap the SQL statement and the associated Parameters, and when we invoke the Query (or run the Command) the underlying statement and parameters are just passed to Dapper. So we don't have to keep statement and parameters separated and we don't have to manually use `DynamicParameters`.\n\n\n\n# Quickstart / NuGet Package\n\n1. Install the [NuGet package Dapper-QueryBuilder](https://www.nuget.org/packages/Dapper-QueryBuilder) (don't forget the dash to get the right package!) or [NuGet package DapperQueryBuilder.StrongName](https://www.nuget.org/packages/DapperQueryBuilder.StrongName)\n1. Start using like this:\n```cs\nusing DapperQueryBuilder;\n// ...\n\ncn = new SqlConnection(connectionString);\n\n// Build your query with interpolated parameters\n// which are automagically converted into safe SqlParameters\nvar products = cn.QueryBuilder($@\"\n    SELECT ProductId, Name, ListPrice, Weight\n    FROM Product\n    WHERE ListPrice \u003c= {maxPrice}\n    AND Weight \u003c= {maxWeight}\n    AND Name LIKE {search}\n    ORDER BY ProductId\").Query\u003cProduct\u003e();\n```\n\nOr building dynamic conditions like this:\n```cs\nusing DapperQueryBuilder;\n// ...\n\ncn = new SqlConnection(connectionString);\n\n// Build initial query\nvar q = cn.QueryBuilder($@\"\n    SELECT ProductId, Name, ListPrice, Weight\n    FROM Product\n    WHERE 1=1\");\n\n// and dynamically append extra filters\nq += $\"AND ListPrice \u003c= {maxPrice}\";\nq += $\"AND Weight \u003c= {maxWeight}\";\nq += $\"AND Name LIKE {search}\";\nq += $\"ORDER BY ProductId\";\n\nvar products = q.Query\u003cProduct\u003e();\n```\n\n# Full Documentation and Features\n\n## Static Query\n\n```cs\n// Create a QueryBuilder with a static query.\n// QueryBuilder will automatically convert interpolated parameters to Dapper parameters (injection-safe)\nvar q = cn.QueryBuilder($@\"\n    SELECT ProductId, Name, ListPrice, Weight FROM Product \n    WHERE ListPrice \u003c= {maxPrice}\n    ORDER BY ProductId\");\n\n// Query\u003cT\u003e() will automatically pass our query and injection-safe SqlParameters to Dapper\nvar products = q.Query\u003cProduct\u003e();\n// all other Dapper extensions are also available: QueryAsync, QueryMultiple, ExecuteScalar, etc..\n```\n\nSo, basically you pass parameters as interpolated strings, but they are converted to safe SqlParameters.\n\nThis is our mojo :-) \n\n## Dynamic Query\n\nOne of the top reasons for dynamically building SQL statements is to dynamically append new filters (`where` statements).  \n\n```cs\n// create a QueryBuilder with initial query\nvar q = cn.QueryBuilder($\"SELECT ProductId, Name, ListPrice, Weight FROM Product WHERE 1=1\");\n\n// Dynamically append whatever statements you need, and QueryBuilder will automatically \n// convert interpolated parameters to Dapper parameters (injection-safe)\nq += $\"AND ListPrice \u003c= {maxPrice}\";\nq += $\"AND Weight \u003c= {maxWeight}\";\nq += $\"AND Name LIKE {search}\";\nq += $\"ORDER BY ProductId\";\n\nvar products = q.Query\u003cProduct\u003e(); \n```\n\n## Static Command\n\n```cs\nvar cmd = cn.CommandBuilder($\"DELETE FROM Orders WHERE OrderId = {orderId};\");\nint deletedRows = cmd.Execute();\n```\n\n```cs\ncn.CommandBuilder($@\"\n   INSERT INTO Product (ProductName, ProductSubCategoryId)\n   VALUES ({productName}, {ProductSubcategoryID})\n\").Execute();\n```\n\n\n## Command with Multiple statements\n\nIn a single roundtrip we can run multiple SQL commands:\n\n```cs\nvar cmd = cn.CommandBuilder();\ncmd += $\"DELETE FROM Orders WHERE OrderId = {orderId}; \";\ncmd += $\"INSERT INTO Logs (Action, UserId, Description) VALUES ({action}, {orderId}, {description}); \";\ncmd.Execute();\n```\n\n\n## Dynamic Query with /\\*\\*where\\*\\*/ keyword\n\nIf you don't like the idea of using `WHERE 1=1` (even though it [doesn't hurt performance](https://dba.stackexchange.com/a/33958/85815)), you can use the special keyword **/\\*\\*where\\*\\*/** that act as a placeholder to render dynamically-defined filters.  \n\n`QueryBuilder` maintains an internal list of filters (property called `Filters`) which keeps track of all filters you've added using `.Where()` method.\nThen, when `QueryBuilder` invokes Dapper and sends the underlying query it will search for the keyword `/**where**/` in our query and if it exists it will replace it with the filters added (if any), combined using `AND` statements.\n\n\nExample: \n\n```cs\n// We can write the query structure and use QueryBuilder to render the \"where\" filters (if any)\nvar q = cn.QueryBuilder($@\"\n    SELECT ProductId, Name, ListPrice, Weight\n    FROM Product\n    /**where**/\n    ORDER BY ProductId\n    \");\n    \n// You just pass the parameters as if it was an interpolated string, \n// and QueryBuilder will automatically convert them to Dapper parameters (injection-safe)\nq.Where($\"ListPrice \u003c= {maxPrice}\");\nq.Where($\"Weight \u003c= {maxWeight}\");\nq.Where($\"Name LIKE {search}\");\n\n// Query() will automatically render your query and replace /**where**/ keyword (if any filter was added)\nvar products = q.Query\u003cProduct\u003e();\n\n// In this case Dapper would get \"WHERE ListPrice \u003c= @p0 AND Weight \u003c= @p1 AND Name LIKE @p2\" and the associated values\n```\n\nWhen Dapper is invoked we replace the `/**where**/` by `WHERE \u003cfilter1\u003e AND \u003cfilter2\u003e AND \u003cfilter3...\u003e` (if any filter was added).\n\n## Dynamic Query with /\\*\\*filters\\*\\*/ keyword\n\n**/\\*\\*filters\\*\\*/** is exactly like **/\\*\\*where\\*\\*/**, but it's used if we already have other fixed conditions before:\n```cs\nvar q = cn.QueryBuilder($@\"\n    SELECT ProductId, Name, ListPrice, Weight\n    FROM Product\n    WHERE Price\u003e{minPrice} /**filters**/\n    ORDER BY ProductId\n    \");\n```\n\nWhen Dapper is invoked we replace the `/**filters**/` by `AND \u003cfilter1\u003e AND \u003cfilter2...\u003e` (if any filter was added).\n\n\n## Writing complex filters (combining AND/OR Filters) and using the Filters class\n\nAs explained above, `QueryBuilder` internally contains an instance of `Filters` class, which basically contains a list of filters and a combining operator (default is AND but can be changed to OR).\nThese filters are defined using `.Where()` and are rendered through the keywords `/**where**/` or `/**filters**/`.\n\nEach filter (inside a parent list of `Filters`) can be a simple condition (using interpolated strings) or it can recursively be another list of filters (`Filters` class), \nand this can be used to write complex combinations of AND/OR conditions (inner filters filters are grouped by enclosing parentheses):\n\n```cs\nvar q = cn.QueryBuilder($@\"\n    SELECT ProductId, Name, ListPrice, Weight\n    FROM Product\n    /**where**/\n    ORDER BY ProductId\n    \");\n\nvar priceFilters = new Filters(Filters.FiltersType.OR)\n{\n    new Filter($\"ListPrice \u003e= {minPrice}\"),\n    new Filter($\"ListPrice \u003c= {maxPrice}\")\n};\n// Or we could add filters one by one like:  priceFilters.Add($\"Weight \u003c= {maxWeight}\");\n\nq.Where(\"Status={status}\");\n// /**where**/ would be replaced by \"Status=@p0\"\n\nq.Where(priceFilters);\n// /**where**/ would be replaced as \"Status=@p0 AND (ListPrice \u003e= @p1 OR ListPrice \u003c= @p2)\".\n// Note that priceFilters is an inner Filter and it's enclosed with parentheses\n\n// It's also possible to change the combining operator of the outer query or of inner filters:\n// q.FiltersType = Filters.FiltersType.OR;\n// priceFilters.FiltersType = Filters.FiltersType.AND;\n// /**where**/ would be replaced as \"Status=@p0 OR (ListPrice \u003e= @p1 AND ListPrice \u003e= @p2)\".\n\nvar products = q.Query\u003cProduct\u003e();\n```\n\nTo sum, `Filters` class will render whatever conditions you define, conditions can be combined with `AND` or `OR`, and conditions can be defined as inner filters (will use parentheses).\nThis is all vendor-agnostic (`AND`/`OR`/parentheses are all SQL ANSI) so it should work with any vendor.\n\n## IN lists\n\nDapper allows us to use IN lists magically. And it also works with our string interpolation:\n\n```cs\nvar q = cn.QueryBuilder($@\"\n    SELECT c.Name as Category, sc.Name as Subcategory, p.Name, p.ProductNumber\n    FROM Product p\n    INNER JOIN ProductSubcategory sc ON p.ProductSubcategoryID=sc.ProductSubcategoryID\n    INNER JOIN ProductCategory c ON sc.ProductCategoryID=c.ProductCategoryID\");\n\nvar categories = new string[] { \"Components\", \"Clothing\", \"Acessories\" };\nq += $\"WHERE c.Name IN {categories}\";\n```\n\n## ValueTuple\n\nDapper allows us to map rows to ValueTuples. And it also works with our string interpolation:\n\n```cs\n// Sometimes we don't want to declare a class for a simple query\nvar q = cn.QueryBuilder($@\"\n    SELECT Name, ListPrice, Weight\n    FROM Product\n    WHERE ProductId={productId}\");\nvar productDetails = q.QuerySingle\u003c(string Name, decimal ListPrice, decimal Weight)\u003e();\n```\n\nWarning: Dapper Tuple mapping is based on positions (it's not possible to map by names)\n\n\n## Raw Modifier: Dynamic Column Names\n\nWhen we want to use regular string interpolation for building up our queries/commands but the interpolated values are not supposed to be converted into SQL parameters we can use the **raw modifier**.\n\nOne popular example of the **raw modifier** is when we want to use **dynamic columns**:\n\n```cs\nvar query = connection.QueryBuilder($\"SELECT * FROM Employee WHERE 1=1\");\nforeach(var filter in filters)\n    query += $\" AND {filter.ColumnName:raw} = {filter.Value}\";\n```\n\nOr:\n\n```cs\nvar query = connection.QueryBuilder($\"SELECT * FROM Employee /**where**/\");\nforeach(var filter in filters)\n    query.Where($\"{filter.ColumnName:raw} = {filter.Value}\");\n```\n\nWhatever we pass as `:raw` should be either \"trusted\" or if it's untrusted (user-input) it should be sanitized correctly to avoid SQL-injection issues. (e.g. if `filter.ColumnName` comes from the UI we should validate it or sanitize it against SQL injection).\n\n\n## Raw Modifier: Dynamic Table Names\n\nAnother common use for **raw modifier** is when we're creating a global temporary table and want a unique (random) name:\n\n```cs\nstring uniqueId = Guid.NewGuid().ToString().Substring(0, 8);\nstring name = \"Rick\";\n\ncn.QueryBuilder($@\"\n    CREATE TABLE ##tmpTable{uniqueId:raw}\n    (\n        Name nvarchar(200)\n    );\n    INSERT INTO ##tmpTable{uniqueId:raw} (Name) VALUES ({name});\n\").Execute();\n```\n\nLet's emphasize again: strings that you interpolate using `:raw` modifier are not passed as parameters and therefore you should ensure validade it or sanitize it against SQL injection.\n\n\n## Raw Modifier: nameof\nAnother example of using the **raw modifier** is when we want to use **nameof expression** (which allows to \"find references\" for a column, \"rename\", etc):\n\n```cs\nvar q = cn.QueryBuilder($@\"\n    SELECT\n        c.{nameof(Category.Name):raw} as Category, \n        sc.{nameof(Subcategory.Name):raw} as Subcategory, \n        p.{nameof(Product.Name):raw}, p.ProductNumber\"\n    FROM Product p\n    INNER JOIN ProductSubcategory sc ON p.ProductSubcategoryID=sc.ProductSubcategoryID\n    INNER JOIN ProductCategory c ON sc.ProductCategoryID=c.ProductCategoryID\");\n```\n\n## Explicitly describing varchar/char data types (to avoid varchar performance issues)\n\nFor Dapper (and consequently for us) strings are always are assumed to be unicode strings (nvarchar) by default.  \n\nThis causes a [known Dapper issue](https://jithilmt.medium.com/sql-server-hidden-load-evil-performance-issue-with-dapper-465a08f922f6): If the column datatype is varchar the query may not give the best performance and may even ignore existing indexed columns and do a full table scan.  \nSo for achieving best performance we may want to explicitly describe if our strings are unicode (nvarchar) or ansi (varchar), and also describe their exact sizes.\n\nDapper's solution is to use the `DbString` class as a wrapper to describe the data type more explicitly, and QueryBuilder can also take this `DbString` in the interpolated values:\n\n```cs\nstring productName = \"Mountain%\";\n\n// This is how we declare a varchar(50) in plain Dapper\nvar productVarcharParm = new DbString { \n    Value = productName, \n    IsFixedLength = true, \n    Length = 50, \n    IsAnsi = true \n};\n\n// DapperQueryBuilder understands Dapper DbString:\nvar query = cn.QueryBuilder($@\"\n    SELECT * FROM Production.Product p \n    WHERE Name LIKE {productVarcharParm}\");\n```\n\n**But we can also specify the datatype (using the well-established SQL syntax) after the value (`{value:datatype}`):**\n\n```cs\nstring productName = \"Mountain%\";\n\nvar query = cn.QueryBuilder($@\"\n    SELECT * FROM Production.Product p \n    WHERE Name LIKE {productName:varchar(50)}\");\n```\n\nThe library will parse the datatype specified after the colon, and it understands sql types like `varchar(size)`, `nvarchar(size)`, `char(size)`, `nchar(size)`, `varchar(MAX)`, `nvarchar(MAX)`.  \n\n`nvarchar` and `nchar` are unicode strings, while `varchar` and `char` are ansi strings.  \n`nvarchar` and `varchar` are variable-length strings, while `nchar` and `char` are fixed-length strings.\n\nDon't worry if your database does not use those exact types - we basically convert from those formats back into Dapper `DbString` class (with the appropriate hints `IsAnsi` and `IsFixedLength`), and Dapper will convert that to your database.\n\n\n## Inner Queries\n\nIt's possible to add sql-safe queries inside other queries (e.g. to use as subqueries) as long as you declare them as FormattableString.\nThis makes it easier to break very complex queries into smaller methods/blocks, or reuse queries as subqueries.\nThe parameters are fully preserved and safe:\n\n```cs\nint orgId = 123;\nFormattableString innerQuery = $\"SELECT Id, Name FROM SomeTable where OrganizationId={orgId}\";\nvar q = cn.QueryBuilder($@\"\n    SELECT FROM ({innerQuery}) a \n    JOIN AnotherTable b ON a.Id=b.Id \n    WHERE b.OrganizationId={321}\");\n\n// q.Sql is like:\n// SELECT FROM (SELECT Id, Name FROM SomeTable where OrganizationId=@p0) a \n// JOIN AnotherTable b ON a.Id=b.Id \n// WHERE b.OrganizationId=@p1\"\n```\n\n\n## Fluent API (Chained-methods)\n\nFor those who like method-chaining guidance (or for those who allow end-users to build their own queries), there's a Fluent API which allows you to build queries step-by-step mimicking dynamic SQL concatenation.  \n\nSo, basically, instead of starting with a full query and just appending new filters (`.Where()`), the FluentQueryBuilder will build the whole query for you:\n\n```cs\nvar q = cn.FluentQueryBuilder()\n    .Select($\"ProductId\")\n    .Select($\"Name\")\n    .Select($\"ListPrice\")\n    .Select($\"Weight\")\n    .From($\"Product\")\n    .Where($\"ListPrice \u003c= {maxPrice}\")\n    .Where($\"Weight \u003c= {maxWeight}\")\n    .Where($\"Name LIKE {search}\")\n    .OrderBy($\"ProductId\");\n    \nvar products = q.Query\u003cProduct\u003e();\n```\n\nYou would get this query:\n\n```sql\nSELECT ProductId, Name, ListPrice, Weight\nFROM Product\nWHERE ListPrice \u003c= @p0 AND Weight \u003c= @p1 AND Name LIKE @p2\nORDER BY ProductId\n```\nOr more elaborated:\n\n```cs\nvar q = cn.FluentQueryBuilder()\n    .SelectDistinct($\"ProductId, Name, ListPrice, Weight\")\n    .From(\"Product\")\n    .Where($\"ListPrice \u003c= {maxPrice}\")\n    .Where($\"Weight \u003c= {maxWeight}\")\n    .Where($\"Name LIKE {search}\")\n    .OrderBy(\"ProductId\");\n```\n\nBuilding joins dynamically using Fluent API:\n\n```cs\nvar categories = new string[] { \"Components\", \"Clothing\", \"Acessories\" };\n\nvar q = cn.FluentQueryBuilder()\n    .SelectDistinct($\"c.Name as Category, sc.Name as Subcategory, p.Name, p.ProductNumber\")\n    .From($\"Product p\")\n    .From($\"INNER JOIN ProductSubcategory sc ON p.ProductSubcategoryID=sc.ProductSubcategoryID\")\n    .From($\"INNER JOIN ProductCategory c ON sc.ProductCategoryID=c.ProductCategoryID\")\n    .Where($\"c.Name IN {categories}\");\n```\n\nThere are also chained-methods for adding GROUP BY, HAVING, ORDER BY, and paging (OFFSET x ROWS / FETCH NEXT x ROWS ONLY).\n\n\n\n## Using Type-Safe Filters without QueryBuilder\n\nIf you want to use our type-safe dynamic filters but for some reason you don't want to use our QueryBuilder:\n\n```cs\nDapper.DynamicParameters parms = new Dapper.DynamicParameters();\n\nvar filters = new Filters(Filters.FiltersType.AND);\nfilters.Add(new Filters()\n{\n    new Filter($\"ListPrice \u003e= {minPrice}\"),\n    new Filter($\"ListPrice \u003c= {maxPrice}\")\n});\nfilters.Add(new Filters(Filters.FiltersType.OR)\n{\n    new Filter($\"Weight \u003c= {maxWeight}\"),\n    new Filter($\"Name LIKE {search}\")\n});\n\nstring where = filters.BuildFilters(parms);\n// \"WHERE (ListPrice \u003e= @p0 AND ListPrice \u003c= @p1) AND (Weight \u003c= @p2 OR Name LIKE @p3)\"\n// parms contains @p0 as minPrice, @p1 as maxPrice, etc..\n```\n\n## Invoking Stored Procedures\n```cs\n// This is basically Dapper, but with a FluentAPI where you can append parameters dynamically.\nvar q = cn.CommandBuilder($\"HumanResources.uspUpdateEmployeePersonalInfo\")\n    .AddParameter(\"ReturnValue\", dbType: DbType.Int32, direction: ParameterDirection.ReturnValue)\n    .AddParameter(\"ErrorLogID\", dbType: DbType.Int32, direction: ParameterDirection.Output)\n    .AddParameter(\"BusinessEntityID\", businessEntityID)\n    .AddParameter(\"NationalIDNumber\", nationalIDNumber)\n    .AddParameter(\"BirthDate\", birthDate)\n    .AddParameter(\"MaritalStatus\", maritalStatus)\n    .AddParameter(\"Gender\", gender);\n    \nint affected = q.Execute(commandType: CommandType.StoredProcedure);\nint returnValue = q.Parameters.Get\u003cint\u003e(\"ReturnValue\");\n```\n\n# Database Support\n\nQueryBuilder is database agnostic (like Dapper) - it should work with all ADO.NET providers (including Microsoft SQL Server, PostgreSQL, MySQL, SQLite, Firebird, SQL CE and Oracle), since it's basically a wrapper around the way parameters are passed to the database provider.  \n\nDapperQueryBuilder doesn't generate SQL statements (except for simple clauses which should work in all databases like `WHERE`/`AND`/`OR` - if you're using `/**where**/` keyword).  \n\n\nIt was tested with **Microsoft SQL Server** and with **PostgreSQL** (using Npgsql driver), and works fine in both.  \n\n## Parameters prefix\n\nBy default the parameters are generated using \"at-parameters\" format (the first parameter is named `@p0`, the next is `@p1`, etc), and that should work with most database providers (including PostgreSQL Npgsql).  \nIf your provider doesn't accept at-parameters (like Oracle) you can modify `DapperQueryBuilderOptions.DatabaseParameterSymbol`:\n\n```cs\n// Default database-parameter-symbol is \"@\", which mean the underlying query will use @p0, @p1, etc..\n// Some database vendors (like Oracle) expect \":\" parameters instead of \"@\" parameters\nDapperQueryBuilderOptions.DatabaseParameterSymbol = \":\";\n\nOracleConnection cn = new OracleConnection(\"DATA SOURCE=server;PASSWORD=password;PERSIST SECURITY INFO=True;USER ID=user\");\n\nstring search = \"%Dinosaur%\";\nvar cmd = cn.QueryBuilder($\"SELECT * FROM film WHERE title like {search}\");\n// Underlying SQL will be: SELECT * FROM film WHERE title like :p0\n```\n\nIf for any reason you don't want parameters to be named `p0`, `p1`, etc, you can change the auto-naming prefix by setting `AutoGeneratedParameterName`:\n\n```cs\nDapperQueryBuilderOptions.AutoGeneratedParameterName = \"PARAM_\";\n\n// your parameters will be named @PARAM_0, @PARAM_1, etc..\n```\n\n## Some extra string magic we do:\n\n**Automatic spacing:**\n```cs\nvar query = cn.QueryBuilder($\"SELECT * FROM Product WHERE 1=1\");\nquery += $\"AND Name LIKE {productName}\"; \nquery += $\"AND ProductSubcategoryID = {subCategoryId}\"; \nvar products = query.Query\u003cProduct\u003e(); \n```\n\nNo need to worry about adding a space before or after a new clause. We'll handle that for you\n\n\n**Automatic strip of surrounding single-quotes**:\n\nIf by mistake you add single quotes around interpolated arguments (as if it was dynamic SQL) we'll just strip it for you.\n\n```cs\ncn.CommandBuilder($@\"\n   INSERT INTO Product (ProductName, ProductSubCategoryId)\n   VALUES ('{productName}', '{ProductSubcategoryID}')\n\").Execute();\n// Dapper will get \"... VALUES (@p0, @p1) \" (we'll remove the surrounding single quotes)\n```\n\n```cs\nstring productName = \"%Computer%\";\nvar products = cnQueryBuilder($\"SELECT * FROM Product WHERE Name LIKE '{productName}'\");\n// Dapper will get \"... WHERE Name LIKE @p0 \" (we'll remove the surrounding single quotes)\n```\n\n**Automatic reuse of duplicated parameters**:\n\nIf you use the same value twice in the query we'll just pass it once and reuse the existing parameter.\n\n```cs\nstring productName = \"Computer\";\nvar products = cnQueryBuilder($\"SELECT * FROM Product WHERE Name = {productName} OR Category = {productName}\");\n// Dapper will get \"... WHERE Name = @p0 OR Category = @p0 \" (we'll send @p0 only once)\n```\n\n\n**Automatic trimming for multi-line queries**:\n```cs\nvar products = cn\n    .Query\u003cProduct\u003e($@\"\n    SELECT * FROM Product\n    WHERE\n    Name LIKE {productName}\n    AND ProductSubcategoryID = {subCategoryId}\n    ORDER BY ProductId\");\n```\n\nSince this is a multi-line interpolated string we'll automatically trim the first empty line and \"dock to the left\"  (remove left padding). What Dapper receives does not have whitespace, making it easier for logging or debugging:\n```sql\nSELECT * FROM Product\nWHERE\nName LIKE @p0\nAND ProductSubcategoryID = @p1\nORDER BY ProductId\n``` \n\n\n\n\n\n# FAQ\n\n## Why should we always use Parameterized Queries instead of Dynamic SQL?\n\nThe whole purpose of Dapper is to safely map our objects to the database (and to map database records back to our objects).  \nIf you build SQL statements by concatenating parameters as strings it means that:\n\n- It would be more vulnerable to SQL injection.\n- You would have to manually sanitize your inputs [against SQL-injection attacks](https://stackoverflow.com/a/7505842)\n- You would have to manually convert null values\n- Your queries wouldn't benefit from cached execution plan\n- You would go crazy by not using Dapper like it was supposed to be used\n\nBuilding dynamic SQL (**which is a TERRIBLE idea**) would be like this:\n\n```cs \nstring sql = \"SELECT * FROM Product WHERE Name LIKE \" \n   + \"'\" + productName.Replace(\"'\", \"''\") + \"'\"; \n// now you pray that you've correctly sanitized inputs against sql-injection\nvar products = cn.Query\u003cProduct\u003e(sql);\n```\n\nWith plain Dapper it's safer:\n```cs\nstring sql = \"SELECT * FROM Product WHERE Name LIKE @productName\";\nvar products = cn.Query\u003cProduct\u003e(sql, new { productName });\n``` \n\n\n**But with Dapper Query Builder it's even easier**:\n```cs\nvar query = cn.QueryBuilder($\"SELECT * FROM Product WHERE Name LIKE {productName}\");\nvar products = query.Query\u003cProduct\u003e(); \n```\n\n\n\n## Why this library if we could just use interpolated strings directly with plain Dapper?\n\nDapper does not take interpolated strings, and therefore it doesn't do any kind of manipulation magic on interpolated strings (which is exactly what we do).  \nThis means that if you pass an interpolated string to Dapper it will be converted as a plain string (**so it would run as dynamic SQL, not as parameterized SQL**), meaning it has **the same issues as dynamic sql** (see previous question).  \n\nSo it WOULD be possible (but ugly) to use Dapper with interpolated strings (as long as you sanitize the inputs):\n\n```cs\ncn.Execute($@\"\n   INSERT INTO Product (ProductName, ProductSubCategoryId)\n   VALUES ( \n      '{productName.Replace(\"'\", \"''\")}', \n      {ProductSubcategoryID == null ? \"NULL\" : int.Parse(ProductSubcategoryID).ToString()}\n   )\");\n// now you pray that you've correctly sanitized inputs against sql-injection\n```\n\nBut with our library this is not only safer but also much simpler:\n\n```cs\ncn.CommandBuilder($@\"\n   INSERT INTO Product (ProductName, ProductSubCategoryId)\n   VALUES ({productName}, {ProductSubcategoryID})\n\").Execute();\n```\n\nIn other words, passing interpolated strings to Dapper is dangerous because you may forget to sanitize the inputs.  \n\nOur library makes the use of interpolated strings easier and safer because:\n- You don't have to sanitize the parameters (we rely on Dapper parameters)\n- You don't have to convert from nulls (we rely on Dapper parameters)\n- Our methods will never accept plain strings to avoid programmer mistakes\n- If you want to embed in the interpolated statement a regular string a do NOT want it to be converted to a parameter you need to explicitly describe it with the `:raw` modifier\n\n## Why do I have to write everything using interpolated strings (`$`)\n\nThe magic is that when you write an interpolated string our methods can identify the embedded parameters (interpolated values) and can correctly extract them and parameterize them.  \nBy enforcing that all methods only take `FormattableString` we can be confident that our methods will never receive an implicit conversion to string, which would defeat the whole purpose of the library and would make you vulnerable to SQL injection.  \nThe only way you can pass an unsafe string in your interpolation is if you explicitly add the **`:raw` modifier**, so it's easy to review all statements for vulnerabilities.  \nAs Alan Kay says, \"Simple things should be simple and complex things should be possible\" - so interpolating regular sql parameters is very simple, while interpolating plain strings is still possible.\n\n## Is building queries with string interpolation really safe?\n\nIn our library String Interpolation is just an abstraction used for hiding the complexity of manually creating SqlParameters.  \nThis library is as safe as possible because it never accepts plain strings, so there's no risk of accidentally converting an interpolated string into a vulnerable string. But obviously there are a few possible scenarios where mistakes could happen.\n\n**First possible mistake - using raw modifier for things that should be parameters:**\n\n```cs\nusing DapperQueryBuilder;\n\n// If you don't understand what raw is for, DON'T USE IT - code below is unsafe!\nvar products = cn.QueryBuilder($@\"\n    SELECT * FROM Product WHERE ProductId={productId:raw}\"\n).Query\u003cProduct\u003e();\n```\n\n**Second possible mistake - passing interpolated strings to Dapper instead of DapperQueryBuilder:**\n\n```cs\nusing Dapper;\n\n// UNSAFE CODE. Dapper will get an unsafe (not parameterized) query.\nvar products = cn.Query\u003cProduct\u003e($@\"\n    SELECT * FROM Product WHERE ProductId={productId}\"\n);\n\n// To avoid this type of mistake you can just avoid Dapper namespace\n// and just use \"using DapperQueryBuilder;\"\n```\n\n**Third possible mistake - Create a \"fake\" FormattableString by passing an unsafe plain string to FormattableStringFactory:**\n\n```cs\nusing DapperQueryBuilder;\nusing System.Runtime.CompilerServices; // needs System.Runtime.dll\n\n// Explicitly create an interpolated string in a totally incorrect way\nvar products = cn.QueryBuilder(FormattableStringFactory.Create($@\"\n    SELECT * FROM Product WHERE ProductId={productId}\")\n).Query\u003cProduct\u003e();\n\n// FormattableStringFactory.Create above is used totally incorrect.\n// Basically the interpolated string will be converted into an unsafe string\n// and then it's converted back into a fake interpolated string.\n\n```\n\n\n## How can I use Dapper async extensions?\n\nThis documentation is mostly using sync methods, but we have [facades](/src/DapperQueryBuilder/ICompleteCommandExtensions.cs) for **all** Dapper extensions, including `ExecuteAsync()`, `QueryAsync\u003cT\u003e`, etc. \n\n## How can I use Dapper Multi-Mapping?\n\nWe do not have facades for invoking Dapper Multi-mapper extensions directly, but you can combine QueryBuilder with Multi-mapper extensions by explicitly passing CommandBuillder `.Sql` and `.Parameters`:\n\n```cs\n// DapperQueryBuilder CommandBuilder\nvar orderAndDetailsQuery = cn\n    .QueryBuilder($@\"\n    SELECT * FROM Orders AS A \n    INNER JOIN OrderDetails AS B ON A.OrderID = B.OrderID\n    /**where**/\n    ORDER BY A.OrderId, B.OrderDetailId\");\n// Dynamic Filters\norderAndDetailsQuery.Where($\"[ListPrice] \u003c= {maxPrice}\");\norderAndDetailsQuery.Where($\"[Weight] \u003c= {maxWeight}\");\norderAndDetailsQuery.Where($\"[Name] LIKE {search}\");\n\n// Dapper Multi-mapping extensions\nvar orderAndDetails = cn.Query\u003cOrder, OrderDetail, Order\u003e(\n        /* orderAndDetailsQuery.Sql contains [ListPrice] \u003c= @p0 AND [Weight] \u003c= @p1 etc... */\n        sql: orderAndDetailsQuery.Sql,\n        map: (order, orderDetail) =\u003e\n        {\n            // whatever..\n        },\n        /* orderAndDetailsQuery.Parameters contains @p0, @p1 etc... */\n        param: orderAndDetailsQuery.Parameters,\n        splitOn: \"OrderDetailID\")\n    .Distinct()\n    .ToList();\n```\n\nTo sum, instead of using DapperQueryBuilder `.Query\u003cT\u003e` extensions (which invoke Dapper `IDbConnection.Query\u003cT\u003e`) you just invoke Dapper multimapper `.Query\u003cT1, T2, T3\u003e` directly, and use DapperQueryBuilder only for dynamically building your filters.  \n\n## How does DapperQueryBuilder compare to plain Dapper?\n\n**Building dynamic filters in plain Dapper is a little cumbersome / ugly:**\n```cs\nvar parms = new DynamicParameters();\nList\u003cstring\u003e filters = new List\u003cstring\u003e();\n\nfilters.Add(\"Name LIKE @productName\"); \nparms.Add(\"productName\", productName);\nfilters.Add(\"CategoryId = @categoryId\"); \nparms.Add(\"categoryId\", categoryId);\n\nstring where = (filters.Any() ? \" WHERE \" + string.Join(\" AND \", filters) : \"\");\n\nvar products = cn.Query\u003cProduct\u003e($@\"\n    SELECT * FROM Product\n    {where}\n    ORDER BY ProductId\", parms);\n```\n\n**With DapperQueryBuilder it's much easier to write queries with dynamic filters:**\n```cs\nvar query = cn.QueryBuilder($@\"\n    SELECT * FROM Product \n    /**where**/ \n    ORDER BY ProductId\");\n\nquery.Where($\"Name LIKE {productName}\");\nquery.Where($\"CategoryId = {categoryId}\");\n\n// If any filter was added, Query() will automatically replace the /**where**/ keyword\nvar products = query.Query\u003cProduct\u003e();\n```\n\nor without `/**where**/`:\n```cs\nvar query = cn.QueryBuilder($\"SELECT * FROM Product WHERE 1=1\");\nquery += $\"AND Name LIKE {productName}\";\nquery += $\"AND CategoryId = {categoryId}\";\nquery += $\"ORDER BY ProductId\";\nvar products = query.Query\u003cProduct\u003e();\n```\n\n\n## How does DapperQueryBuilder compare to [Dapper.SqlBuilder](https://github.com/DapperLib/Dapper/tree/main/Dapper.SqlBuilder)?\n\nDapper.SqlBuilder combines the filters using `/**where**/` keyword (like we do) but requires some auxiliar classes, and filters have to be defined using Dapper syntax (no string interpolation):\n\n```cs\n// SqlBuilder and Template are helper classes\nvar builder = new SqlBuilder();\n\n// We also use this /**where**/ syntax\nvar template = builder.AddTemplate(@\"\n    SELECT * FROM Product\n    /**where**/\n    ORDER BY ProductId\");\n    \n// Define the filters using regular Dapper syntax:\nbuilder.Where(\"Name LIKE @productName\", new { productName });\nbuilder.Where(\"CategoryId = @categoryId\", new { categoryId });\n\n// Use template to explicitly pass the rendered SQL and parameters to Dapper:\nvar products = cn.Query\u003cProduct\u003e(template.RawSql, template.Parameters);\n```\n\n\n## Why don't you have Typed Filters using Lambda Expressions?\n\nWe believe that SQL syntax is powerful, comprehensive and vendor-specific. Dapper allows us to use the full SQL syntax (of our database vendor), and so does DapperQueryBuilder.\nThat's why we decided to focus on our magic (converting interpolated strings into SQL parameters), while keeping Dapper simplicity (you write your own filters).\nIn other words, we won't try to reinvent SQL syntax or create a limited abstraction over SQL language.\n\n\n## How to Collaborate?\n\nPlease submit a pull-request or if you want to make a sugestion you can [create an issue](https://github.com/Drizin/DapperQueryBuilder/issues) or [contact me](https://rdrizin.com/pages/Contact/).\n\n## Stargazers over time\n\n[![Star History Chart](https://api.star-history.com/svg?repos=Drizin/DapperQueryBuilder\u0026type=Date)](https://star-history.com/#Drizin/DapperQueryBuilder\u0026Date)\n\n\n## License\nMIT License\n","funding_links":["https://github.com/sponsors/Drizin"],"categories":["C\\#","C#","ORM","Audio","C# #"],"sub_categories":["GUI - other"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDrizin%2FDapperQueryBuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDrizin%2FDapperQueryBuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDrizin%2FDapperQueryBuilder/lists"}