Synchronous methods
This page says when a query gets a synchronous query method, and how that method runs the query.
Synchronous methods
-- output: methods
-- name: GetUser -> one-optional
-- generator: method-type=both
SELECT id, name
FROM users
WHERE id = @id;
// Generated, shown without global::
internal static GetUserDto? GetUser(
this DbConnection connection,
GetUserParams parameters,
DbTransaction? transaction = null,
int? commandTimeout = null)
internal static async Task<GetUserDto?> GetUserAsync(
this DbConnection connection,
GetUserParams parameters,
DbTransaction? transaction = null,
int? commandTimeout = null,
CancellationToken cancellationToken = default)
// Your code, where it does not await
GetUserDto? user = connection.GetUser(new GetUserParams(42));
The generator parameter method-type gives a query a synchronous method, when the output of the query is repository or methods. A synchronous method is for code that does not await, such as a console tool or a library whose API is synchronous. It runs the query on the calling thread, with the synchronous calls of the driver, and never waits on a task. method-type takes one of these values:
async, the default, gives the asynchronous method alone.syncgives a synchronous method in place of the asynchronous one.bothgives the two, asGetUserin the sample has.
The names follow these rules:
- A synchronous method has the name of the query, never with
Asyncafter it, whateverasync-method-suffixsays. - Under
both, the name of the asynchronous method always hasAsyncafter it, with or withoutasync-method-suffix. Two methods that differ only bycancellationToken, an argument with a default, would make every call ambiguous. - Otherwise, the name of the asynchronous method has
Asyncafter it only underasync-method-suffix, which is off by default. - Each name of a query is checked as where the methods go says. If something else takes a name, the query is SQLSRC274, and gets none of its methods until you fix it. For a clash with a method of another type in an extension class, the query gets none of the methods of that name.
- A synchronous repository method with no argument cannot be named
Finalize(SQLSRC274). The compiler would take it for the finalizer of the type: see the signature. - A synchronous method takes the arguments of the asynchronous method, without
cancellationToken. A method that takes a connection takes the connection, the input model, astringfor each token,transactionandcommandTimeout, as the signature says. A repository method takes the input model and the tokens alone. - Nothing cancels a synchronous method, as the synchronous calls of ADO.NET take no token.
commandTimeoutstill limits the command. - A token still cannot be named
cancellationToken, under anymethod-type(SQLSRC275). - A synchronous method returns what the task of the asynchronous method holds, as what each shape returns says. It returns the collection for
many, the row forone, the row or null forone-optional, the count forrowcount, and nothing,void, fornone. - A synchronous method does what the asynchronous method does. It does each of these in the same way:
- It opens a closed connection, and closes it again before it returns or throws, as the connection says. A repository method gets its connection from the repository instead.
- It runs in the
transactionthat it is given. - It sends each parameter, and reads each row.
- It throws the same exceptions:
UnexpectedRowCountException, the exceptions of the driver and, on SQL Server,TransactionRolledBackException.
- The documentation of a synchronous method in IntelliSense is that of the asynchronous method, without
cancellationToken. Fornone, it has no line for what the method returns. - A synchronous repository method needs a member that gives the connection and returns no task (SQLSRC299). See synchronous repository methods.
- On PostgreSQL, a data source with
Multiplexing=truerefuses a synchronous method on a connection that has no transaction open. An example is the connection that a repository method gets from its data source. See what a method reads and throws. - A stream has no synchronous method. A
manyquery whose collection type isIAsyncEnumerablegives each row to the loop of the caller as it is read. Only an asynchronous method does that. - Under
both, a stream gets its asynchronous method alone, named withAsync. If it has a collection method, it gets both collection methods, as a collection method reads its rows into an array and never streams them. For a queryListUsers, they areListUsers(IEnumerable<ListUsersParams> parameters, ...)andListUsersAsync(IEnumerable<ListUsersParams> parameters, ...). - Under
sync, a stream is SQLSRC298, and gets no method and no collection method. For a synchronous method, give the query a collection type that is read whole, such asList.
The collection method of a query follows method-type as the query method does. Under sync, the collection method is synchronous, and has the name of the query. It is an overload of the synchronous method, by its IEnumerable argument. Under both, the query gets the two collection methods. The synchronous one has the name of the query, and the asynchronous one has Async after it:
// -- name: GetUser -> one-optional, with -- generator: collection-method method-type=both,
// generated beside GetUser and GetUserAsync, shown without global::
internal static GetUserDto[] GetUser(
this DbConnection connection,
IEnumerable<GetUserParams> parameters,
DbTransaction? transaction = null,
int? commandTimeout = null)
internal static async Task<GetUserDto[]> GetUserAsync(
this DbConnection connection,
IEnumerable<GetUserParams> parameters,
DbTransaction? transaction = null,
int? commandTimeout = null,
CancellationToken cancellationToken = default)
- A synchronous collection method takes the arguments of the asynchronous one, without
cancellationToken. - A synchronous collection method returns what the task of the asynchronous one holds: the collection, the count, or nothing,
void, fornone, as what it returns says. - A synchronous collection method does what the asynchronous one does. It does each of these in the same way:
- It reads the collection once, and runs the items 1,000 at a time.
- It begins a transaction of its own, unless it is given one or one is ambient, by the generator parameter
transaction. - It throws the same exceptions, as what it throws says:
CollectionItemException, with theItemIndexof the item;UnexpectedRowCountException;- on SQL Server,
TransactionRolledBackException, and theInvalidOperationExceptionof a query that returns more than one result set.
- The name of a synchronous collection method, the name of the query, is checked as the name of a method is, by where the methods go. If something else takes it, the query is SQLSRC274. This holds for the collection method of a stream too, which has no synchronous method of that name.