5.14 Asynchronous Methods

The Task-based Asynchronous Pattern (TAP) is a pattern for asynchrony in the .NET Framework. It is based on the Task and Task<TResult> types in the System.Threading.Tasks namespace, which are used to represent arbitrary asynchronous operations.

Async-Await are new keywords introduced to work with the TAP. The Async modifier is used to specify that a method, lambda expression, or anonymous method is asynchronous. The Await operator is applied to a task in an asynchronous method to suspend the execution of the method until the awaited task completes.

Requirements

Async-Await support requires .NET Framework 4.5 or later
TAP support requires .NET Framework 4.0 or later
MySQL Connector/NET 6.9 or later

Methods

The following methods can be used with either TAP or Async-Await.

Namespace MySql.Data.Entity
- Class EFMySqlCommand
  - Task PrepareAsync()
  - Task PrepareAsync(CancellationToken)
Namespace MySql.Data
- Class MySqlBulkLoader
  - Task<int> LoadAsync()
  - Task<int> LoadAsync(CancellationToken
- Class MySqlConnection
  - Task<MySqlTransaction> BeginTransactionAsync()
  - Task<MySqlTransaction> BeginTransactionAsync (CancellationToken)
  - Task<MySqlTransaction> BeginTransactionAsync(IsolationLevel)
  - Task<MySqlTransaction> BeginTransactionAsync (IsolationLevel , CancellationToken)
  - Task ChangeDatabaseAsync(string)
  - Task ChangeDatabaseAsync(string, CancellationToken)
  - Task CloseAsync()
  - Task CloseAsync(CancellationToken)
  - Task ClearPoolAsync(MySqlConnection)
  - Task ClearPoolAsync(MySqlConnection, CancellationToken)
  - Task ClearAllPoolsAsync()
  - Task ClearAllPoolsAsync(CancellationToken)
  - Task<MySqlSchemaCollection> GetSchemaCollection(string, string[])
  - Task<MySqlSchemaCollection> GetSchemaCollection(string, string[], CancellationToken)
- Class MySqlDataAdapter
  - Task<int> FillAsync(DataSet)
  - Task<int> FillAsync(DataSet, CancellationToken)
  - Task<int> FillAsync(DataTable)
  - Task<int> FillAsync(DataTable, CancellationToken)
  - Task<int> FillAsync(DataSet, string)
  - Task<int> FillAsync(DataSet, string, CancellationToken)
  - Task<int> FillAsync(DataTable, IDataReader)
  - Task<int> FillAsync(DataTable, IDataReader, CancellationToken)
  - Task<int> FillAsync(DataTable, IDbCommand, CommandBehavior)
  - Task<int> FillAsync(DataTable, IDbCommand, CommandBehavior, CancellationToken)
  - Task<int> FillAsync(int, int, params DataTable[])
  - Task<int> FillAsync(int, int, params DataTable[], CancellationToken)
  - Task<int> FillAsync(DataSet, int, int, string)
  - Task<int> FillAsync(DataSet, int, int, string, CancellationToken)
  - Task<int> FillAsync(DataSet, string, IDataReader, int, int)
  - Task<int> FillAsync(DataSet, string, IDataReader, int, int, CancellationToken)
  - Task<int> FillAsync(DataTable[], int, int, IDbCommand, CommandBehavior)
  - Task<int> FillAsync(DataTable[], int, int, IDbCommand, CommandBehavior, CancellationToken)
  - Task<int> FillAsync(DataSet, int, int, string, IDbCommand, CommandBehavior)
  - Task<int> FillAsync(DataSet, int, int, string, IDbCommand, CommandBehavior, CancellationToken)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, CancellationToken)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, string)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, string, CancellationToken)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, string, IDataReader)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, string, IDataReader, CancellationToken)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, IDbCommand, string, CommandBehavior)
  - Task<DataTable[]> FillSchemaAsync(DataSet, SchemaType, IDbCommand, string, CommandBehavior, CancellationToken)
  - Task<DataTable> FillSchemaAsync(DataTable, SchemaType)
  - Task<DataTable> FillSchemaAsync(DataTable, SchemaType, CancellationToken)
  - Task<DataTable> FillSchemaAsync(DataTable, SchemaType, IDataReader)
  - Task<DataTable> FillSchemaAsync(DataTable, SchemaType, IDataReader, CancellationToken)
  - Task<DataTable> FillSchemaAsync(DataTable, SchemaType, IDbCommand, CommandBehavior)
  - Task<DataTable> FillSchemaAsync(DataTable, SchemaType, IDbCommand, CommandBehavior, CancellationToken)
  - Task<int> UpdateAsync(DataRow[])
  - Task<int> UpdateAsync(DataRow[], CancellationToken)
  - Task<int> UpdateAsync(DataSet)
  - Task<int> UpdateAsync(DataSet, CancellationToken)
  - Task<int> UpdateAsync(DataTable)
  - Task<int> UpdateAsync(DataTable, CancellationToken)
  - Task<int> UpdateAsync(DataRow[], DataTableMapping, CancellationToken)
  - Task<int> UpdateAsync(DataSet, string)
  - Task<int> UpdateAsync(DataSet, string, CancellationToken)
- Class MySqlHelper
  - Task<DataRow> ExecuteDataRowAsync(string, string, params MySqlParameter[])
  - Task<DataRow> ExecuteDataRowAsync(string, string, CancellationToken, params MySqlParameter[])
  - Task<int> ExecuteNonQueryAsync(MySqlConnection, string, params MySqlParameter[])
  - Task<int> ExecuteNonQueryAsync(MySqlConnection, string, CancellationToken, params MySqlParameter[])
  - Task<int> ExecuteNonQueryAsync(string, string, params MySqlParameter[])
  - Task<int> ExecuteNonQueryAsync(string, string, CancellationToken, params MySqlParameter[])
  - Task<DataSet> ExecuteDatasetAsync(string, string)
  - Task<DataSet> ExecuteDatasetAsync(string, string, CancellationToken)
  - Task<DataSet> ExecuteDatasetAsync(string, string, CancellationToken, params MySqlParameter[])
  - Task<DataSet> ExecuteDatasetAsync(MySqlConnection, string)
  - Task<DataSet> ExecuteDatasetAsync(MySqlConnection, string, CancellationToken)
  - Task<DataSet> ExecuteDatasetAsync(MySqlConnection, string, params MySqlParameter[])
  - Task<DataSet> ExecuteDatasetAsync(MySqlConnection, string, CancellationToken, params MySqlParameter[])
  - Task UpdateDataSetAsync(string, string, DataSet, string)
  - Task UpdateDataSetAsync(string, string, DataSet, string, CancellationToken)
  - Task<MySqlDataReader> ExecuteReaderAsync(MySqlConnection, MySqlTransaction, string, MySqlParameter[], bool)
  - Task<MySqlDataReader> ExecuteReaderAsync(MySqlConnection, MySqlTransaction, string, MySqlParameter[], bool, CancellationToken)
  - Task<MySqlDataReader> ExecuteReaderAsync(string, string)
  - Task<MySqlDataReader> ExecuteReaderAsync(string, string, CancellationToken)
  - Task<MySqlDataReader> ExecuteReaderAsync(MySqlConnection, string)
  - Task<MySqlDataReader> ExecuteReaderAsync(MySqlConnection, string, CancellationToken)
  - Task<MySqlDataReader> ExecuteReaderAsync(string, string, params MySqlParameter[])
  - Task<MySqlDataReader> ExecuteReaderAsync(string, string, CancellationToken, params MySqlParameter[])
  - Task<MySqlDataReader> ExecuteReaderAsync(MySqlConnection, string, params MySqlParameter[])
  - Task<MySqlDataReader> ExecuteReaderAsync(MySqlConnection, string, CancellationToken, params MySqlParameter[])
  - Task<object> ExecuteScalarAsync(string, string)
  - Task<object> ExecuteScalarAsync(string, string, CancellationToken)
  - Task<object> ExecuteScalarAsync(string, string, params MySqlParameter[])
  - Task<object> ExecuteScalarAsync(string, string, CancellationToken, params MySqlParameter[])
  - Task<object> ExecuteScalarAsync(MySqlConnection, string)
  - Task<object> ExecuteScalarAsync(MySqlConnection, string, CancellationToken)
  - Task<object> ExecuteScalarAsync(MySqlConnection, string, params MySqlParameter[])
  - Task<object> ExecuteScalarAsync(MySqlConnection, string, CancellationToken, params MySqlParameter[])
- Class MySqlScript
  - Task<int> ExecuteAsync()
  - Task<int> ExecuteAsync(CancellationToken)

In addition to the methods listed above, the following are methods inherited from the .NET Framework:

Namespace MySql.Data.Entity
- Class EFMySqlCommand
  - Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehaviour, CancellationToken)
  - Task<int> ExecuteNonQueryAsync()
  - Task<int> ExecuteNonQueryAsync(CancellationToken)
  - Task<DbDataReader> ExecuteReaderAsync()
  - Task<DbDataReader> ExecuteReaderAsync(CancellationToken)
  - Task<DbDataReader> ExecuteReaderAsync(CommandBehaviour)
  - Task<DbDataReader> ExecuteReaderAsync(CommandBehaviour, CancellationToken)
  - Task<object> ExecuteScalarAsync()
  - Task<object> ExecuteScalarAsync(CancellationToken)
Namespace MySql.Data
- Class MySqlCommand
  - Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehaviour, CancellationToken)
  - Task<int> ExecuteNonQueryAsync()
  - Task<int> ExecuteNonQueryAsync(CancellationToken)
  - Task<DbDataReader> ExecuteReaderAsync()
  - Task<DbDataReader> ExecuteReaderAsync(CancellationToken)
  - Task<DbDataReader> ExecuteReaderAsync(CommandBehaviour)
  - Task<DbDataReader> ExecuteReaderAsync(CommandBehaviour, CancellationToken)
  - Task<object> ExecuteScalarAsync()
  - Task<object> ExecuteScalarAsync(CancellationToken)
- Class MySqlConnection
  - Task OpenAsync()
  - Task OpenAsync(CancellationToken)
- Class MySqlDataReader
  - Task<T> GetFieldValueAsync<T>(int)
  - Task<T> GetFieldValueAsync<T>(int, CancellationToken)
  - Task<bool> IsDBNullAsync(int)
  - Task<bool> IsDBNullAsync(int, CancellationToken)
  - Task<bool> NextResultAsync()
  - Task<bool> NextResultAsync(CancellationToken)
  - Task<bool> ReadAsync()
  - Task<bool> ReadAsync(CancellationToken)

Examples

The following C# code examples demonstrate how to use the asynchronous methods:

In this example, a method has the async modifier because the method await call made applies to the method LoadAsync. The method returns a Task object that contains information about the result of the awaited method. Returning Task is like having a void method, but you should not use async void if your method is not a top-level access method like an event.

public async Task BulkLoadAsync()
{
  MySqlConnection myConn = new MySqlConnection("MyConnectionString");
  MySqlBulkLoader loader = new MySqlBulkLoader(myConn);

  loader.TableName       = "BulkLoadTest";
  loader.FileName        = @"c:\MyPath\MyFile.txt";
  loader.Timeout         = 0;

  var result             = await loader.LoadAsync();
}

In this example, an "async void" method is used with "await" for the ExecuteNonQueryAsync method, to correspond to the onclick event of a button. This is why the method does not return a Task.

private async void myButton_Click()
{
  MySqlConnection myConn = new MySqlConnection("MyConnectionString");
  MySqlCommand proc      = new MySqlCommand("MyAsyncSpTest", myConn);

  proc.CommandType       = CommandType.StoredProcedure;

  int result             = await proc.ExecuteNonQueryAsync();
}