Change names, namespaces and visibility
Add the Async suffix, rename Dto and Params, set the namespace of the models, make them classes, return a List<T>, or make a method internal.
Use this when the names or the shapes of the generated code do not fit the conventions of your project. Use it too when a method must go on your own class, or must be hidden from other code.
End the method names with Async
If you want GetUserAsync in place of GetUser, turn on the Async suffix with the line -- generator: async-method-suffix:
-- generator: async-method-suffix
-- name: GetUser -> one-optional
SELECT
id,
name,
email
FROM users
WHERE id = @userId;
GetUserDto? user = await users.GetUserAsync(new GetUserParams(1));
What you get. The method of GetUser is GetUserAsync. The line is in the file header, so each query of the file gets Async at the end of its method's name.
The rules you need.
async-method-suffixis a generator parameter. For a whole project, write"generatorParameters": ["async-method-suffix"]insqlsource.json. Seeasync-method-suffix.- The name of a synchronous method never ends with
Async. Undermethod-type=both, the name of the asynchronous method always does. See Synchronous methods.
Change the model names (Dto and Params)
If you do not want Dto and Params at the end of the model names, set your own suffixes in the file header:
-- input-model-suffix: Args
-- output-model-suffix: Row
-- name: GetUser
SELECT id, name FROM users WHERE id = @id;
To name the models of one query, write -- input-model: and -- output-model: inside the query:
-- name: GetUser
-- input-model: UserArgs
-- output-model: App.Models.UserRow
SELECT id, name FROM users WHERE id = @id;
What you get. With the suffixes, GetUser gets GetUserArgs and GetUserRow. With the two names, it gets UserArgs, and UserRow in the namespace App.Models.
The rules you need.
- A suffix stands in the file header only, not inside a query. For a whole project, write
"outputModelSuffix": "Row"insqlsource.json. See Suffix of a model's name. -- input-model:and-- output-model:stand inside a query only. The name gets no suffix. See Name of one query's model.- Two queries whose models have one full name share one model, if the models are the same. See Names.
The namespace of the models
If you want the models in a namespace of their own, write -- model-namespace: in the file header of a .sql file:
-- model-namespace: App.Models
-- name: ListUsers
SELECT id, name FROM users;
What you get. The models of ListUsers are in App.Models. Without the setting, the models are in the namespace of the type that claims the query.
The rules you need.
- For the whole project, set
"modelNamespace": "App.Models"in thesqlsource.jsonbeside your project file. See namespace of the models. - Two types in two namespaces that read one table each get a model of it, one in each namespace. The setting gives them one model. See namespace of the models.
- A name with a period in an
-- output-model:line,App.Rows.UserRow, is a full name, and ignores the setting. See namespace of the models.
Make the models classes, not records
If you need a class and not a record, set the shape of the models:
// sqlsource.json, in the project's folder
{
"root": true,
"dialect": "postgres",
"outputModelType": "class",
}
What you get. Each output model is a class, with a get and a set for each property, and no constructor of its own. Your input models, such as GetUserParams, are still records, since the sample sets only outputModelType. See Shape.
The rules you need.
inputModelTypesets the shape of the input models. In a.sqlfile, write-- output-model-type: classin the file header or inside a query. See Shape of a model.- To read rows through Dapper into models whose properties are sorted, make the models classes. See Run the models through Dapper.
Return a list, not an array
If you want a list, such as List<T> or IReadOnlyList<T>, in place of an array, set the collection type of the query:
-- name: ListUsersNewestFirst
-- collection-type: IReadOnlyList
SELECT
id,
name,
email
FROM users
ORDER BY created_at DESC, id ASC;
What you get. The method of ListUsersNewestFirst returns Task<IReadOnlyList<ListUsersNewestFirstDto>>. For a List<T> that you can add to, write -- collection-type: List.
The rules you need.
- The collection is filled before the task completes, so reading it runs no query. To read rows one at a time, see Read rows one at a time. See Collection type.
- It changes nothing for a query whose shape is not
many, and nothing under the outputmodelsorsql. See Collection type.
Choose where the methods go, and who can see them
If you want to know where the methods go, or want them internal or on your class, set the member location and the visibility. The folder of this file sets the output methods:
-- name: ListOrdersOfUser -> many
-- member-location: class
-- visibility: public
SELECT
id,
placed_at,
shipped_at
FROM orders
WHERE user_id = @userId
ORDER BY placed_at DESC;
-- name: CountOrderLines -> one
-- member-location: nested-class
SELECT count(*) AS line_count
FROM order_lines
WHERE order_id = @orderId;
[SqlSourceGenerate]
public static partial class OrderQueries;
// elsewhere
ListOrdersOfUserDto[] orders = await OrderQueries.ListOrdersOfUser(connection, new ListOrdersOfUserParams(userId));
What you get. ListOrdersOfUser is a public static method of OrderQueries, and takes the connection first. CountOrderLines is a method of the private class Sql nested in OrderQueries, so only code inside OrderQueries can call it: Sql.CountOrderLines(connection, ...).
The rules you need.
- Remove the
-- member-location:and-- visibility:lines ofListOrdersOfUser, and it is aninternalextension method ofDbConnection, in the classOrderQueriesExtensions. In a repository, a query's method is a public instance method of your class. See Where the members go. - Only a
methodsmethod can go in the extension class. See Where the members go. -- visibility: internalmakes a repository method internal, and its interface leaves it out. See Visibility.- The models do not follow the visibility. They are
publicorinternalas your class is. See Where the members go. - To give the nested class another name, write
-- nested-class: Counts. A constant is thenCounts.CountUsers. See Name of the nested class.
If it does not work
- SQLSRC274. A method would take a name that is used, such as
GetAsyncof the queriesGetandGetAsyncunderasync-method-suffix. Rename one of the queries. See SQLSRC274. - SQLSRC257. Two models of one name are not the same. Give one query another model name. See SQLSRC257.
- SQLSRC122. A member location does not fit a query, such as
extension-classfor a repository query. A value in the file header reaches each query of the file: write it on the query. See SQLSRC122. - SQLSRC123. A visibility does not fit the member location, such as
privatein the extension class. Write the visibility on the query. See SQLSRC123.