ISqlExecutor.ExecuteAsync(string sqlText, object[] parameters, CancellationToken cancellationToken) Method

.NET Standard 2.x

Asynchronously executes a SQL statement which does not need to return any data. It is used to execute the SQL statements like UPDATE, INSERT, DELETE, etc.

Namespace: SnapObjects.Data

Assembly: SnapObjects.Data.dll

Syntax

  public Task<int> ExecuteAsync(string sqlText, params object[] parameters, CancellationToken cancellationToken);

Parameters

sqlText System.String

A raw SQL statement which contains the parameter placeholders.

The proper syntax of a parameter placeholder is specific to the data source (e.g., @newFirstName for SQL Server). To make a parameterized SQL ( e.g, update Person set FirstName = @newFirstName where PersonId = 1), these placeholders are filled in with the actual parameter values when the SQL statement is executed.

parameters System.Object[]

One or more objects which contain the values corresponding to the SQL parameter identifier names.

You can also pass the arguments directly in the order in which they appear in the SQL SELECT statement generated by sqlQueryBuilder without using the objects.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task<int>

Returns a task that represents the asynchronous operation.

Remarks

You can use parameter placeholders in the raw SQL Statement. It is recommended to use the syntax for parameter placeholders that is specific to the data source. e.g., uses @parametername for SQL Server and uses :parametername for Oracle.

Examples

The following code example use this method to asynchronously execute the SQL statement to update data. It uses a CancellationTokenSource type parameter to make this operation cancelable.

using System;
using System.Threading;
using System.Threading.Tasks;
using SnapObjects.Data;

namespace Appeon.ApiDoc.ISqlExecutorExamples
{
    public class ExecuteAsyncExample
    {
        private readonly SchoolContext _context;
        
        public ExecuteAsyncExample(SchoolContext dataContext)
        {
            // Sets the data context.
            _context = dataContext;
        }

        public async Task<int> Example2(CancellationTokenSource cts) 
        {
            // Define the SQL Statement which contains the parameter placeholders.
            string sql = @"UPDATE Course SET Title = 'New Course'
                            WHERE CourseID = @id";
                            
            int rowAffected = 0;
            
            try
            {
                // If a task has been cancelled, the call to the 
                // SqlExecutor.ExecuteAsync method throws an OperationCanceledException.
                rowAffected = await _context.SqlExecutor.ExecuteAsync(sql,
                                                                  new object[] { 1045 }, 
                                                                  cts.Token);
                    
                Console.WriteLine("{0} records have been updated into the database.",
                    rowAffected);
            }
            catch (OperationCanceledException ex)
            {
                // The operation was cancelled before completion.
                Console.WriteLine(ex.Message);
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
            finally 
            {
                cts.Dispose();
            }
            
            return rowAffected;
            
            /*This code produces the following output:
            
                A task was canceled.
            */
        }
    }
}

Applies to

.NET Standard

2.x