diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBase.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBase.xml index 3766fa205e..3557cb287e 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBase.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBase.xml @@ -1,57 +1,87 @@ - - - - - Retrieves the next time interval with respect to the number of retries if a transient condition occurs. - - - Maximum number of retries. - - that returns the maximum number of retry execution attempts that will be attempted after the first failure. - - - Current retry number starting from zero. - - that returns the number of retry execution attempts after the first failure. - - - The timer interval enumerator. - - value that indicates an enumerator to generate a sequence of time intervals. - - - Delegate to a transient condition predicate. The function that this delegate points to must return a true value when an expected transient exception happens. - - value that delegates to a function that receives a input parameter. - - - The sender object. - Pre-retry validation for the sender state. - Returns if the sender is authorized to retry the operation. - - [IMPORTANT!] -> Operations that are part of a **Transaction** are not safe to retry without specific knowledge of business logic. Due to this complexity, retry logic should be managed at the application level. - -> [!NOTE] -> The `RetryCondition` is an extra condition that checks before executing the `TransientPredicate` and the default condition always returns **true**. - -]]> - - - - The interval time that is generated by the `RetryIntervalEnumerator`. - Try to get the next interval time by using the enumerator if the counter does not exceed the number of retries. - Returns if the number of retry attempts has not been exceeded; otherwise . - - - Set the counters and enumerator to default values for next use. - - - Creates a new object that is a copy of the current instance. - When implemented in a derived class, the method is expected to return a new object of the current instance. The default implementation throws NotImplementedException. - In all cases. - - + + + + + Retrieves the next time interval with respect to the number of retries if a transient condition occurs. + + + + + Maximum number of retries. + + + that returns the maximum number of retry execution attempts that will be attempted after the first failure. + + + + + Current retry number starting from zero. + + + that returns the number of retry execution attempts after the first failure. + + + + + The timer interval enumerator. + + + value that indicates an enumerator to generate a sequence of time intervals. + + + + + Delegate to a transient condition predicate. The function that this delegate points to must return a true value when an expected transient exception happens. + + + value that delegates to a function that receives a input parameter. + + + + + The sender object. + + + Pre-retry validation for the sender state. + + + Returns if the sender is authorized to retry the operation. + + + + Operations that are part of a Transaction are not safe to retry without specific knowledge of business logic. Due to this complexity, retry logic should be managed at the application level. + + + The RetryCondition is an extra condition that checks before executing the and the default condition always returns . + + + + + + The interval time that is generated by the . + + + Try to get the next interval time by using the enumerator if the counter does not exceed the number of retries. + + + Returns if the number of retry attempts has not been exceeded; otherwise . + + + + + Set the counters and enumerator to default values for next use. + + + + + Creates a new object that is a copy of the current instance. + + + When implemented in a derived class, the method is expected to return a new object of the current instance. The default implementation throws . + + + In all cases. + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBaseProvider.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBaseProvider.xml index 031c2b1ff7..72bd0d7ced 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBaseProvider.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicBaseProvider.xml @@ -1,90 +1,136 @@ - - - - - Applies retry logic on an operation through the `Execute` or `ExecuteAsync` function. - - - Occurs before applying the calculated delay time and executing the function on a next attempt. - - with event argument of object can be subscribed. - - [IMPORTANT!] -> Don't block execution with a time consuming action when an event occurs. For instance, if you log data to a file, run it in a new thread to avoid blocking the main execution thread. - -]]> - - - - - Defines the retry logic used to decide when to retry based on the encountered exception. - - [!NOTE] -> The `RetryLogic` property is assigned at `SqlRetryLogicBaseProvider` creation and its value is used as a template internally. Don't use it to monitor the status of the retry logic during and after execution. Instead, use the event to collect data about retry executions. - -]]> - - - - - The object that the `function` returns when executed. - The source of the event. - The operation to re-execute if a transient condition occurs. - Executes a function and applies retry logic, if enabled. **Note:** Exceptions will be reported via an aggregate exception if the execution isn't successful via retry attempts. - - The return value of the `function` if it runs without exception. - - [!NOTE] -> The type of exception depends on the `function`'s internal implementation. But if the exception is due to all retry attempts failing, it will be an that consists of all exceptions that happened during the failed attempts. - -]]> - - - The `function` parameter can't be `null`. - The collection of exceptions after all retry attempts have failed. - - - The object that the `function` returns in a Task when executed. - The source of the event. - The operation to re-execute if a transient condition occurs. - The cancellation instruction. - Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. **Note:** Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts. - A task representing the asynchronous operation. The results of the task will be the return value of the `function`, if it runs without exception. - - [!NOTE] -> If the exception comes from all retry attempts failing, it will be an that consists of all exceptions from the failed attempts. - -]]> - - - The `function` parameter can't be `null`. - The collection of exceptions after failed retry attempts. - - - The source of the event. - The operation to re-execute if a transient condition occurs. - The cancellation instruction. - Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. **Note:** Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts. - A Task or an exception. - - [!NOTE] -> If the exception comes from all retry attempts failing, it will be an that consists of all exceptions from the failed attempts. - -]]> - - - The `function` parameter can't be `null`. - The collection of exceptions after failed retry attempts. - - + + + + + Applies retry logic on an operation through the or function. + + + + + Occurs before applying the calculated delay time and executing the function on a next attempt. + + + with event argument of object can be subscribed. + + + + Don't block execution with a time-consuming action when an event occurs. For instance, if you log data to a file, run it in a new thread to avoid blocking the main execution thread. + + + + + + Defines the retry logic used to decide when to retry based on the encountered exception. + + + + The RetryLogic property is assigned at construction of the creation and its value is used as a template internally. Don't use it to monitor the status of the retry logic during and after execution. Instead, use the event to collect data about retry executions. + + + + + + The object that the `function` returns when executed. + + + The source of the event. + + + The operation to re-execute if a transient condition occurs. + + + + Executes a function and applies retry logic, if enabled. + + + Exceptions will be reported via an aggregate exception if the execution isn't successful via retry attempts. + + + + The return value of the if it runs without exception. + + + + + The type of exception depends on the 's internal implementation. But if the exception is due to all retry attempts failing, it will be an that consists of all exceptions that happened during the failed attempts. + + + + + The parameter can't be . + + + The collection of exceptions after all retry attempts have failed. + + + + + The object that the returns in a Task when executed. + + + The source of the event. + + + The operation to re-execute if a transient condition occurs. + + + The cancellation instruction. + + + + Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. + + + Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts. + + + + A task representing the asynchronous operation. The results of the task will be the return value of the , if it runs without exception. + + + + If the exception comes from all retry attempts failing, it will be an that consists of all exceptions from the failed attempts. + + + + The parameter can't be . + + + The collection of exceptions after failed retry attempts. + + + + + The source of the event. + + + The operation to re-execute if a transient condition occurs. + + + The cancellation instruction. + + + + Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. + + + Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts. + + + + A Task or an exception. + + + + If the exception comes from all retry attempts failing, it will be an that consists of all exceptions from the failed attempts. + + + + The parameter can't be . + + + The collection of exceptions after failed retry attempts. + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicOption.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicOption.xml index 8ba200753b..4c5f1d6de6 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicOption.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRetryLogicOption.xml @@ -1,47 +1,88 @@ - - - - - Provides the retry logic parameters to create an instance of the class by using methods. - - - object that is configured to apply retry logic for the error number **102** for a maximum of **5** times and **3** to **60** seconds gap time between each run. It will only work for the `Select` SQL statements assigned to the . - -[!code-csharp[SqlConfigurableRetryLogic_SqlRetryLogicOptions#1](~/../sqlclient/doc/samples/SqlConfigurableRetryLogic_SqlRetryLogicOptions.cs#1)] - -]]> - - - Sets the number of times to try and execute the function. - - between 1 and 60; 1 means to execute one time and if an error is encountered, don't retry. - - - Sets the gap time interval as a object. - - The upcoming gap time before the next execution attempt; must be between 0 and 120 seconds. - - - Sets the minimum allowed gap time interval as a object. - - The minimum upcoming gap time before the next execution attempt; the default value is **zero** and must be between 0 and 120 seconds. - - - Sets the allowed maximum gap time interval as a object. - - The maximum upcoming gap time interval before the next execution attempt; must be between 0 and 120 seconds. - - - Sets the list of transient error numbers on which to retry when they occur. - List of ; Set to to use the internal list of exceptions from the object. - - - Sets a pre-retry validation function on the to only include specific SQL statements. - - The pre-retry validation delegate function; if the `CommandText` is authorized to retry the operation. - - + + + + + Provides the retry logic parameters to create an instance of the class by using methods. + + + + The following sample declares a object that is configured to apply retry logic for the error number 102 for a maximum of 5 times and 3 to 60 seconds gap time between each run. It will only work for the SELECT SQL statements assigned to the . + + + + using System; + using System.Text.RegularExpressions; + using Microsoft.Data.SqlClient; + + class RetryLogicSample + { + static void Main(string[] args) + { + var RetryLogicOption = new SqlRetryLogicOption() + { + NumberOfTries = 5, + // Declare the error number 102 as a transient error to apply the retry logic when it occurs. + TransientErrors = new int[] { 102 }, + // When a SqlCommand executes out of a transaction, + // the retry logic will apply if it contains a 'select' keyword. + AuthorizedSqlCondition = x => string.IsNullOrEmpty(x) + || Regex.IsMatch(x, @"\b(SELECT)\b", RegexOptions.IgnoreCase), + DeltaTime = TimeSpan.FromSeconds(1), + MaxTimeInterval = TimeSpan.FromSeconds(60), + MinTimeInterval = TimeSpan.FromSeconds(3) + }; + } + } + + + + + + Sets the number of times to try and execute the function. + + + between 1 and 60; 1 means to execute one time and if an error is encountered, don't retry. + + + + + Sets the gap time interval as a object. + + + The upcoming gap time before the next execution attempt; must be between 0 and 120 seconds. + + + + + Sets the minimum allowed gap time interval as a object. + + + The minimum upcoming gap time before the next execution attempt; the default value is zero and must be between 0 and 120 seconds. + + + + + Sets the allowed maximum gap time interval as a object. + + + The maximum upcoming gap time interval before the next execution attempt; must be between 0 and 120 seconds. + + + + + Sets the list of transient error numbers on which to retry when they occur. + + + List of ; Set to to use the internal list of exceptions from the object. + + + + + Sets a pre-retry validation function on the to only include specific SQL statements. + + + The pre-retry validation delegate function; if the is authorized to retry the operation. + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventArgs.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventArgs.xml index c71d543248..f0d95737a1 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventArgs.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventArgs.xml @@ -1,60 +1,146 @@ - - - - - Provides data for the event. - - event is raised when an to a row is completed. - - When using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, and the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows how to use both the and events. - - The event returns this output: - - Event Arguments: (command=Microsoft.Data.SqlClient.SqlCommand commandType=2 status=0) - - The event returns this output: - - Event Arguments: (command=Microsoft.Data.SqlClient.SqlCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) - - [!code-csharp[SqlDataAdapter_RowUpdated Example#1](~/../sqlclient/doc/samples/SqlDataAdapter_RowUpdated.cs#1)] - - ]]> - - - - The sent through an . - The executed when is called. - One of the values that specifies the type of query executed. - The sent through an . - Initializes a new instance of the class. - To be added. - - - Gets or sets the executed when is called. - The executed when is called. - To be added. - - + + + + + Provides data for the event. + + + + The event is raised when an to a row is completed. + + + When using , there are two events that occur for each data row updated. The order of execution is as follows: + + + The values in the are moved to the parameter values. + The event is raised. + The command executes. + If the command is set to FirstReturnedRecord, and the first returned result is placed in the . + If there are output parameters, they are placed in the . + The event is raised. + is called. + + + + + The following example shows how to use both the and events. + + + + using System; + using System.Data; + using System.Data.Common; + using System.Windows.Forms; + using System.Xml; + using Microsoft.Data.SqlClient; + + public class Form1 : Form + { + private DataSet DataSet1; + private DataGrid dataGrid1; + + // handler for RowUpdating event + private static void OnRowUpdating(object sender, SqlRowUpdatingEventArgs e) + { + PrintEventArgs(e); + } + + // handler for RowUpdated event + private static void OnRowUpdated(object sender, SqlRowUpdatedEventArgs e) + { + PrintEventArgs(e); + } + + public static int Main() + { + const string connectionString = + "Integrated Security=SSPI;database=Northwind;server=MSSQL1"; + const string queryString = "SELECT * FROMProducts"; + + // create DataAdapter + SqlDataAdapter adapter = new SqlDataAdapter(queryString, connectionString); + SqlCommandBuilder builder = new SqlCommandBuilder(adapter); + + // Create and fill DataSet (select only first 5 rows) + DataSet dataSet = new DataSet(); + adapter.Fill(dataSet, 0, 5, "Table"); + + // Modify DataSet + DataTable table = dataSet.Tables["Table"]; + table.Rows[0][1] = "new product"; + + // add handlers + adapter.RowUpdating += new SqlRowUpdatingEventHandler(OnRowUpdating); + adapter.RowUpdated += new SqlRowUpdatedEventHandler(OnRowUpdated); + + // update, this operation fires two events + // (RowUpdating/RowUpdated) per changed row + adapter.Update(dataSet, "Table"); + + // remove handlers + adapter.RowUpdating -= new SqlRowUpdatingEventHandler(OnRowUpdating); + adapter.RowUpdated -= new SqlRowUpdatedEventHandler(OnRowUpdated); + return 0; + } + + private static void PrintEventArgs(SqlRowUpdatingEventArgs args) + { + Console.WriteLine("OnRowUpdating"); + Console.WriteLine(" event args: (" + + " command=" + args.Command + + " commandType=" + args.StatementType + + " status=" + args.Status + ")"); + } + + private static void PrintEventArgs(SqlRowUpdatedEventArgs args) + { + Console.WriteLine("OnRowUpdated"); + Console.WriteLine(" event args: (" + + " command=" + args.Command + + " commandType=" + args.StatementType + + " recordsAffected=" + args.RecordsAffected + + " status=" + args.Status + ")"); + } + } + + + The event returns this output: + + + Event Arguments: (command=Microsoft.Data.SqlClient.SqlCommand commandType=2 status=0) + + + The event returns this output: + + + Event Arguments: (command=Microsoft.Data.SqlClient.SqlCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) + + + + + + The sent through an . + + + The executed when is called. + + + One of the values that specifies the type of query executed. + + + The sent through an . + + + Initializes a new instance of the class. + + + + + Gets or sets the executed when is called. + + + The executed when is called. + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventHandler.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventHandler.xml index 1dab5604a5..ac66308043 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventHandler.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatedEventHandler.xml @@ -1,20 +1,23 @@ - - - - - The source of the event. - The that contains the event data. - Represents the method that will handle the event of a . - - delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - ]]> - - - + + + + + The source of the event. + + + The that contains the event data. + + + Represents the method that will handle the event of a . + + + + The handler is not required to perform any action, and your code should avoid generating exceptions or allowing exceptions to propagate to the calling method. Any exceptions that do reach the caller are ignored. + + + When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see Handling and Raising Events. + + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventArgs.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventArgs.xml index a8d644fa08..e1a9ffe8e5 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventArgs.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventArgs.xml @@ -1,65 +1,155 @@ - - - - - Provides data for the event. - - event is raised before an to a row. - - When you are using , there are two events that occur for each data row updated. The order of execution is as follows: - -1. The values in the are moved to the parameter values. - -2. The event is raised. - -3. The command executes. - -4. If the command is set to `FirstReturnedRecord`, and the first returned result is placed in the . - -5. If there are output parameters, they are placed in the . - -6. The event is raised. - -7. is called. - - - -## Examples - The following example shows how to use both the and events. - - The event returns this output: - - event args: (command=Microsoft.Data.SqlClient.SQLCommand commandType=2 status=0) - - The event returns this output: - - event args: (command=Microsoft.Data.SqlClient.SQLCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) - - [!code-csharp[SqlRowUpdatingEventArgs Example#1](~/../sqlclient/doc/samples/SqlRowUpdatingEventArgs.cs#1)] - - ]]> - - - - The to . - The to execute during . - One of the values that specifies the type of query executed. - The sent through an . - Initializes a new instance of the class. - To be added. - - - To be added. - To be added. - To be added. - - - Gets or sets the to execute when performing the . - The to execute when performing the . - To be added. - - + + + + + Provides data for the event. + + + + The event is raised before an to a row. + + + When you are using , there are two events that occur for each data row updated. The order of execution is as follows: + + + The values in the are moved to the parameter values. + The event is raised. + The command executes. + If the command is set to FirstReturnedRecord, and the first returned result is placed in the . + If there are output parameters, they are placed in the . + The event is raised. + is called. + + + + + The following example shows how to use both the and events. + + + + using System; + using System.Data; + using System.Data.Common; + using System.Windows.Forms; + using System.Xml; + using Microsoft.Data.SqlClient; + + public class Form1 : Form + { + private DataSet DataSet1; + private DataGrid dataGrid1; + + + // handler for RowUpdating event + private static void OnRowUpdating(object sender, SqlRowUpdatingEventArgs e) + { + PrintEventArgs(e); + } + + //Handler for RowUpdated event. + private static void OnRowUpdated(object sender, SqlRowUpdatedEventArgs e) + { + PrintEventArgs(e); + } + + public static int Main() + { + const string CONNECTION_STRING = "Persist Security Info=False;Integrated Security=SSPI;database=northwind;server=mySQLServer"; + const string SELECT_ALL = "select * from Products"; + + //Create DataAdapter. + SqlDataAdapter rAdapter = new SqlDataAdapter(SELECT_ALL, CONNECTION_STRING); + + //Create and fill DataSet (Select only first 5 rows.). + DataSet rDataSet = new DataSet(); + rAdapter.Fill(rDataSet, 0, 5, "Table"); + + //Modify DataSet. + DataTable rTable = rDataSet.Tables["Table"]; + rTable.Rows[0][1] = "new product"; + + //Add handlers. + rAdapter.RowUpdating += new SqlRowUpdatingEventHandler(OnRowUpdating); + rAdapter.RowUpdated += new SqlRowUpdatedEventHandler(OnRowUpdated); + + //Update--this operation fires two events (RowUpdating and RowUpdated) for each changed row. + rAdapter.Update(rDataSet, "Table"); + + //Remove handlers. + rAdapter.RowUpdating -= new SqlRowUpdatingEventHandler(OnRowUpdating); + rAdapter.RowUpdated -= new SqlRowUpdatedEventHandler(OnRowUpdated); + return 0; + } + + private static void PrintEventArgs(SqlRowUpdatingEventArgs args) + { + Console.WriteLine("OnRowUpdating"); + Console.WriteLine(" event args: (" + + " command=" + args.Command + + " commandType=" + args.StatementType + + " status=" + args.Status + ")"); + } + + private static void PrintEventArgs(SqlRowUpdatedEventArgs args) + { + Console.WriteLine("OnRowUpdated"); + Console.WriteLine(" event args: (" + + " command=" + args.Command + + " commandType=" + args.StatementType + + " recordsAffected=" + args.RecordsAffected + + " status=" + args.Status + ")"); + } + } + + + The event returns this output: + + + event args: (command=Microsoft.Data.SqlClient.SQLCommand commandType=2 status=0) + + + The event returns this output: + + + event args: (command=Microsoft.Data.SqlClient.SQLCommand commandType=2 recordsAffected=1 row=System.Data.DataRow[37] status=0) + + + + + + The to . + + + The to execute during . + + + One of the values that specifies the type of query executed. + + + The sent through an . + + + Initializes a new instance of the class. + + + + + To be added. + + + To be added. + + + To be added. + + + + + Gets or sets the to execute when performing the . + + + The to execute when performing the . + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventHandler.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventHandler.xml index 9abc365553..e861f4c855 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventHandler.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRowUpdatingEventHandler.xml @@ -1,22 +1,26 @@ - - - - - The source of the event. - The that contains the event data. - Represents the method that will handle the event of a . - - to influence the processing of the updates. For example, the handler may opt to skip the update of the current row or skip the update of all remaining rows. Note that the rows are updated in the order that they were received from the data source. - - When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - ]]> - - - + + + + + The source of the event. + + + The that contains the event data. + + + Represents the method that will handle the event of a . + + + + The handler is not required to perform any action, and your code should avoid generating exceptions or allowing exceptions to propagate to the calling method. Any exceptions that do reach the caller are ignored. + + + The handler may use the to influence the processing of the updates. For example, the handler may opt to skip the update of the current row or skip the update of all remaining rows. Note that the rows are updated in the order that they were received from the data source. + + + When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event handler delegates, see Handling and Raising Events. + + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventArgs.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventArgs.xml index d655582980..07cd09770c 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventArgs.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventArgs.xml @@ -1,51 +1,48 @@ - - - - - Represents the set of arguments passed to the . - To be added. - - - An that indicates the number of rows copied during the current bulk copy operation. - Creates a new instance of the object. - - - - - - Gets or sets a value that indicates whether the bulk copy operation should be aborted. - - if the bulk copy operation should be aborted; otherwise . - - property to cancel a bulk copy operation. Set to `true` to abort the bulk copy operation. - - If you call the **Close** method from , an exception is generated, and the object state does not change. - - If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to rollback the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. - - ]]> - - - - Gets a value that returns the number of rows copied during the current bulk copy operation. - - that returns the number of rows copied. - - property is reset on each call to any of the `SqlBulkCopy.WriteToServer` methods. - - ]]> - - - + + + + + Represents the set of arguments passed to the . + + + + + An that indicates the number of rows copied during the current bulk copy operation. + + + Creates a new instance of the object. + + + The value in the parameter is reset on each call to any one of the methods. + + + + + Gets or sets a value that indicates whether the bulk copy operation should be aborted. + + if the bulk copy operation should be aborted; otherwise . + + + Use the Abort property to cancel a bulk copy operation. Set Abort to to abort the bulk copy operation. + + + If you call the method from , an exception is generated, and the object state does not change. + + + If an application specifically creates a object in the constructor, the transaction is not rolled back. The application is responsible for determining whether it is required to roll back the operation, and if so, it must call the method. If the application does not create a transaction, the internal transaction corresponding to the current batch is automatically rolled back. However, changes related to previous batches within the bulk copy operation are retained, because the transactions for them already have been committed. + + + + + + Gets a value that returns the number of rows copied during the current bulk copy operation. + + + that returns the number of rows copied. + + + The value in the property is reset on each call to any of the methods. + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventHandler.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventHandler.xml index 325fcf10f1..3ed80e6cc3 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventHandler.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlRowsCopiedEventHandler.xml @@ -1,11 +1,15 @@ - - - - - The source of the event. - A object that contains the event data. - Represents the method that handles the event of a . - To be added. - - + + + + + The source of the event. + + + A object that contains the event data. + + + Represents the method that handles the event of a . + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlTransaction.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlTransaction.xml index 56908b095e..2a7aae8798 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlTransaction.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlTransaction.xml @@ -1,193 +1,499 @@ - - - - - Represents a Transact-SQL transaction to be made in a SQL Server database. This class cannot be inherited. - - object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. - -> [!NOTE] -> `Try`/`Catch` exception handling should always be used when committing or rolling back a . Both and generate an if the connection is terminated or if the transaction has already been rolled back on the server. - - For more information on SQL Server transactions, see [Explicit Transactions](https://msdn.microsoft.com/library/ms175127\(SQL.105\).aspx) and [Coding Efficient Transactions](https://msdn.microsoft.com/library/ms187484\(SQL.105\).aspx). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error, or if it is disposed without first being committed. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - - [!code-csharp[SqlConnection_BeginTransaction Example#1](~/../sqlclient/doc/samples/SqlConnection_BeginTransaction.cs#1)] - - ]]> - - - - Commits the database transaction. - - method is equivalent to the Transact-SQL COMMIT TRANSACTION statement. You cannot roll back a transaction once it has been committed, because all modifications have become a permanent part of the database. For more information, see [COMMIT TRANSACTION (Transact-SQL)](/sql/t-sql/language-elements/commit-transaction-transact-sql). - -> [!NOTE] -> `Try`/`Catch` exception handling should always be used when committing or rolling back a . Both `Commit` and generates an if the connection is terminated or if the transaction has already been rolled back on the server. - - For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - - [!code-csharp[SqlConnection_BeginTransaction Example#1](~/../sqlclient/doc/samples/SqlConnection_BeginTransaction.cs#1)] - - ]]> - - An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - - The connection is broken. - - - Gets the object associated with the transaction, or if the transaction is no longer valid. - The object associated with the transaction. - - . - - ]]> - - - - To be added. - To be added. - To be added. - - - Releases the resources that are held by the object. - To be added. - - - to release managed and unmanaged resources; to release only unmanaged resources. - Releases the unmanaged resources used and optionally releases the managed resources. - - . + + + + + Represents a Transact-SQL transaction to be made in a SQL Server database. This class cannot be inherited. + + + + The application creates a object by calling on the object. All subsequent operations associated with the transaction (for example, committing or aborting the transaction), are performed on the object. + + + Try / Catch exception handling should always be used when committing or rolling back a . Both and generate an if the connection is terminated or if the transaction has already been rolled back on the server. + + + For more information on SQL Server transactions, see Explicit Transactions and Coding Efficient Transactions + + + + + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error, or if it is disposed without first being committed. Try / Catch error handling is used to handle any errors when attempting to commit or roll back the transaction. + + + + using System; + using System.Data; + using Microsoft.Data.SqlClient; + + namespace Transaction1CS + { + class Program + { + static void Main() + { + string connectionString = + "Persist Security Info=False;Integrated Security=SSPI;database=Northwind;server=(local)"; + ExecuteSqlTransaction(connectionString); + Console.ReadLine(); + } + + private static void ExecuteSqlTransaction(string connectionString) + { + using (SqlConnection connection = new SqlConnection(connectionString)) + { + connection.Open(); + + SqlCommand command = connection.CreateCommand(); + SqlTransaction transaction; + + // Start a local transaction. + transaction = connection.BeginTransaction(); + + // Must assign both transaction object and connection + // to Command object for a pending local transaction + command.Connection = connection; + command.Transaction = transaction; + + try + { + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')"; + command.ExecuteNonQuery(); + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')"; + command.ExecuteNonQuery(); + + // Attempt to commit the transaction. + transaction.Commit(); + Console.WriteLine("Both records are written to database."); + } + catch (Exception ex) + { + Console.WriteLine("Commit Exception Type: {0}", ex.GetType()); + Console.WriteLine(" Message: {0}", ex.Message); + + // Attempt to roll back the transaction. + try + { + transaction.Rollback(); + } + catch (Exception ex2) + { + // This catch block will handle any errors that may have occurred + // on the server that would cause the rollback to fail, such as + // a closed connection. + Console.WriteLine("Rollback Exception Type: {0}", ex2.GetType()); + Console.WriteLine(" Message: {0}", ex2.Message); + } + } + } + } + } + } + + + + + + Commits the database transaction. + + + + The method is equivalent to the Transact-SQL COMMIT TRANSACTION statement. You cannot roll back a transaction once it has been committed, because all modifications have become a permanent part of the database. For more information, see COMMIT TRANSACTION (Transact-SQL). + + + Try / Catch exception handling should always be used when committing or rolling back a . Both Commit and generates an if the connection is terminated or if the transaction has already been rolled back on the server. + + + For more information on SQL Server transactions, see Transactions (Transact-SQL). + + + + + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. Try / Catch error handling is used to handle any errors when attempting to commit or roll back the transaction. + + + + using System; + using System.Data; + using Microsoft.Data.SqlClient; + + namespace Transaction1CS + { + class Program + { + static void Main() + { + string connectionString = + "Persist Security Info=False;Integrated Security=SSPI;database=Northwind;server=(local)"; + ExecuteSqlTransaction(connectionString); + Console.ReadLine(); + } + + private static void ExecuteSqlTransaction(string connectionString) + { + using (SqlConnection connection = new SqlConnection(connectionString)) + { + connection.Open(); + + SqlCommand command = connection.CreateCommand(); + SqlTransaction transaction; + + // Start a local transaction. + transaction = connection.BeginTransaction(); + + // Must assign both transaction object and connection + // to Command object for a pending local transaction + command.Connection = connection; + command.Transaction = transaction; + + try + { + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')"; + command.ExecuteNonQuery(); + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')"; + command.ExecuteNonQuery(); + + // Attempt to commit the transaction. + transaction.Commit(); + Console.WriteLine("Both records are written to database."); + } + catch (Exception ex) + { + Console.WriteLine("Commit Exception Type: {0}", ex.GetType()); + Console.WriteLine(" Message: {0}", ex.Message); + + // Attempt to roll back the transaction. + try + { + transaction.Rollback(); + } + catch (Exception ex2) + { + // This catch block will handle any errors that may have occurred + // on the server that would cause the rollback to fail, such as + // a closed connection. + Console.WriteLine("Rollback Exception Type: {0}", ex2.GetType()); + Console.WriteLine(" Message: {0}", ex2.Message); + } + } + } + } + } + } + + + + An error occurred while trying to commit the transaction. + + + + The transaction has already been committed or rolled back. + The connection is broken. + + + + + + Gets the object associated with the transaction, or if the transaction is no longer valid. + + + The object associated with the transaction. + + + A single application may have multiple database connections, each with zero or more transactions. This property lets you determine the connection object associated with a particular transaction created by . + + + + + To be added. + + + To be added. + + + To be added. + + + + + Releases the resources that are held by the object. + + + + + to release managed and unmanaged resources; to release only unmanaged resources. + + + Releases the unmanaged resources used and optionally releases the managed resources. + + + This method calls . + + + + + Specifies the for this transaction. + + + The for this transaction. The default is . + + + + Parallel transactions are not supported. Therefore, the applies to the whole transaction. + + + For more information on SQL Server isolation levels, see Transaction Isolation Levels. + + + + + + Rolls back a transaction from a pending state. + + + + + Rolls back a transaction from a pending state. + + + + The Rollback method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see ROLLBACK TRANSACTION (Transact-SQL). + + + The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back in the event it is disposed before or Rollback is called. + + + Try / Catch exception handling should always be used when rolling back a transaction. A Rollback generates an if the connection is terminated or if the transaction has already been rolled back on the server. + + + For more information on SQL Server transactions, see Transactions (Transact-SQL). + + + + + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. Try / Catch error handling is used to handle any errors when attempting to commit or roll back the transaction. + + + + using System; + using System.Data; + using Microsoft.Data.SqlClient; + + namespace Transaction1CS + { + class Program + { + static void Main() + { + string connectionString = + "Persist Security Info=False;Integrated Security=SSPI;database=Northwind;server=(local)"; + ExecuteSqlTransaction(connectionString); + Console.ReadLine(); + } + + private static void ExecuteSqlTransaction(string connectionString) + { + using (SqlConnection connection = new SqlConnection(connectionString)) + { + connection.Open(); + + SqlCommand command = connection.CreateCommand(); + SqlTransaction transaction; + + // Start a local transaction. + transaction = connection.BeginTransaction(); + + // Must assign both transaction object and connection + // to Command object for a pending local transaction + command.Connection = connection; + command.Transaction = transaction; + + try + { + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')"; + command.ExecuteNonQuery(); + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')"; + command.ExecuteNonQuery(); + + // Attempt to commit the transaction. + transaction.Commit(); + Console.WriteLine("Both records are written to database."); + } + catch (Exception ex) + { + Console.WriteLine("Commit Exception Type: {0}", ex.GetType()); + Console.WriteLine(" Message: {0}", ex.Message); + + // Attempt to roll back the transaction. + try + { + transaction.Rollback(); + } + catch (Exception ex2) + { + // This catch block will handle any errors that may have occurred + // on the server that would cause the rollback to fail, such as + // a closed connection. + Console.WriteLine("Rollback Exception Type: {0}", ex2.GetType()); + Console.WriteLine(" Message: {0}", ex2.Message); + } + } + } + } + } + } + + + + An error occurred while trying to commit the transaction. + + + + The transaction has already been committed or rolled back. + The connection is broken. + + + + + + The name of the transaction to roll back, or the savepoint to which to roll back. + + + Rolls back a transaction from a pending state, and specifies the transaction or savepoint name. + + + + The method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see Transactions (Transact-SQL). + + + The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back if it is disposed before or Rollback is called. + + + Try / Catch exception handling should always be used when rolling back a transaction. A Rollback generates an if the connection is terminated or if the transaction has already been rolled back on the server. + + + For more information on SQL Server transactions, see Transactions (Transact-SQL). + + + + + The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. Try / Catch error handling is used to handle any errors when attempting to commit or roll back the transaction. + + + + using System; + using System.Data; + using Microsoft.Data.SqlClient; + + namespace Transaction1CS + { + class Program + { + static void Main() + { + string connectionString = + "Persist Security Info=False;Integrated Security=SSPI;database=Northwind;server=(local)"; + ExecuteSqlTransaction(connectionString); + Console.ReadLine(); + } -]]> - - - - Specifies the for this transaction. - The for this transaction. The default is . - - applies to the whole transaction. - - For more information on SQL Server isolation levels, see [Transaction Isolation Levels](/sql/t-sql/language-elements/transaction-isolation-levels). - - ]]> - - - - Rolls back a transaction from a pending state. - - - Rolls back a transaction from a pending state. - - method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see [ROLLBACK TRANSACTION (Transact-SQL) -](/sql/t-sql/language-elements/rollback-transaction-transact-sql). - - The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back in the event it is disposed before `Commit` or `Rollback` is called. - -> [!NOTE] -> `Try`/`Catch` exception handling should always be used when rolling back a transaction. A `Rollback` generates an if the connection is terminated or if the transaction has already been rolled back on the server. - - For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - - [!code-csharp[SqlConnection_BeginTransaction Example#1](~/../sqlclient/doc/samples/SqlConnection_BeginTransaction.cs#1)] - - ]]> - - An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - - The connection is broken. - - - The name of the transaction to roll back, or the savepoint to which to roll back. - Rolls back a transaction from a pending state, and specifies the transaction or savepoint name. - - method is equivalent to the Transact-SQL ROLLBACK TRANSACTION statement. For more information, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - The transaction can only be rolled back from a pending state (after has been called, but before is called). The transaction is rolled back if it is disposed before `Commit` or `Rollback` is called. - -> [!NOTE] -> `Try`/`Catch` exception handling should always be used when rolling back a transaction. A `Rollback` generates an if the connection is terminated or if the transaction has already been rolled back on the server. - - For more information on SQL Server transactions, see [Transactions (Transact-SQL)](/sql/t-sql/language-elements/transactions-transact-sql). - - - -## Examples - The following example creates a and a . It also demonstrates how to use the , , and methods. The transaction is rolled back on any error. `Try`/`Catch` error handling is used to handle any errors when attempting to commit or roll back the transaction. - - [!code-csharp[SqlConnection_BeginTransaction2 Example#1](~/../sqlclient/doc/samples/SqlConnection_BeginTransaction2.cs#1)] - - ]]> - - No transaction name was specified. - The transaction has already been committed or rolled back. - - -or- - - The connection is broken. - - - The name of the savepoint. - Creates a savepoint in the transaction that can be used to roll back a part of the transaction, and specifies the savepoint name. - - method is equivalent to the Transact-SQL SAVE TRANSACTION statement. - - The value used in the `savePoint` parameter can be the same value used in the `transactionName` parameter of some implementations of the method. - - Savepoints offer a mechanism to roll back parts of transactions. You create a savepoint using the method, and then later call the method to roll back to the savepoint instead of rolling back to the start of the transaction. - - ]]> - - An error occurred while trying to commit the transaction. - The transaction has already been committed or rolled back. - - -or- - - The connection is broken. - - + private static void ExecuteSqlTransaction(string connectionString) + { + using (SqlConnection connection = new SqlConnection(connectionString)) + { + connection.Open(); + + SqlCommand command = connection.CreateCommand(); + SqlTransaction transaction; + + // Start a local transaction. + transaction = connection.BeginTransaction("SampleTransaction"); + + // Must assign both transaction object and connection + // to Command object for a pending local transaction + command.Connection = connection; + command.Transaction = transaction; + + try + { + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (100, 'Description')"; + command.ExecuteNonQuery(); + command.CommandText = + "Insert into Region (RegionID, RegionDescription) VALUES (101, 'Description')"; + command.ExecuteNonQuery(); + + // Attempt to commit the transaction. + transaction.Commit(); + Console.WriteLine("Both records are written to database."); + } + catch (Exception ex) + { + Console.WriteLine("Commit Exception Type: {0}", ex.GetType()); + Console.WriteLine(" Message: {0}", ex.Message); + + // Attempt to roll back the transaction. + try + { + transaction.Rollback("SampleTransaction"); + } + catch (Exception ex2) + { + // This catch block will handle any errors that may have occurred + // on the server that would cause the rollback to fail, such as + // a closed connection. + Console.WriteLine("Rollback Exception Type: {0}", ex2.GetType()); + Console.WriteLine(" Message: {0}", ex2.Message); + } + } + } + } + } + } + + + + No transaction name was specified. + + + + The transaction has already been committed or rolled back. + The connection is broken. + + + + + + The name of the savepoint. + + + Creates a savepoint in the transaction that can be used to roll back a part of the transaction, and specifies the savepoint name. + + + + The Save method is equivalent to the Transact-SQL SAVE TRANSACTION statement. + + + The value used in the parameter can be the same value used in the transactionName parameter of some implementations of the method. + + + Savepoints offer a mechanism to roll back parts of transactions. You create a savepoint using the Save method, and then later call the method to roll back to the savepoint instead of rolling back to the start of the transaction. + + + + An error occurred while trying to commit the transaction. + + + + The transaction has already been committed or rolled back. + The connection is broken. + + + +