From a2b77ca2c6b57241ea1099f7539ff7eaa1de658b Mon Sep 17 00:00:00 2001
From: Shay Rojansky <roji@roji.org>
Date: Tue, 27 Aug 2019 10:15:12 +0200
Subject: [PATCH] Additional tweaks to new System.Data async APIs
* Fixes to PrepareAsync
* Made cancellation token description more consistent and added
note where default values are present.
* Changed default value for cancellation tokens to be
CancellationToken.None instead of null
---
xml/System.Data.Common/DbCommand.xml | 14 +++++++-------
xml/System.Data.Common/DbConnection.xml | 6 +++---
xml/System.Data.Common/DbTransaction.xml | 4 ++--
3 files changed, 12 insertions(+), 12 deletions(-)
diff --git a/xml/System.Data.Common/DbCommand.xml b/xml/System.Data.Common/DbCommand.xml
index ddcaf4d7916..15b0e808837 100644
--- a/xml/System.Data.Common/DbCommand.xml
+++ b/xml/System.Data.Common/DbCommand.xml
@@ -732,7 +732,7 @@
</Parameters>
<Docs>
<param name="behavior">Options for statement execution and data retrieval.</param>
- <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+ <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>Providers should implement this method to provide a non-default implementation for <see cref="Overload:System.Data.Common.DbCommand.ExecuteReader" /> overloads.
The default implementation invokes the synchronous <see cref="M:System.Data.Common.DbCommand.ExecuteReader" /> method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteReader will be communicated via the returned Task Exception property.
@@ -898,7 +898,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
</Parameters>
<Docs>
- <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+ <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>This is the asynchronous version of <see cref="M:System.Data.Common.DbCommand.ExecuteNonQuery" />. Providers should override with an appropriate implementation. The cancellation token may optionally be ignored.
The default implementation invokes the synchronous <see cref="M:System.Data.Common.DbCommand.ExecuteNonQuery" /> method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by <see cref="M:System.Data.Common.DbCommand.ExecuteNonQuery" /> will be communicated via the returned Task Exception property.
@@ -1151,7 +1151,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
</Parameters>
<Docs>
- <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+ <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>An asynchronous version of <see cref="Overload:System.Data.Common.DbCommand.ExecuteReader" />, which executes the <see cref="P:System.Data.Common.DbCommand.CommandText" /> against the <see cref="P:System.Data.Common.DbCommand.Connection" /> and returns a <see cref="T:System.Data.Common.DbDataReader" />. This method propagates a notification that operations should be canceled.
Invokes <see cref="M:System.Data.Common.DbCommand.ExecuteDbDataReaderAsync(System.Data.CommandBehavior,System.Threading.CancellationToken)" />.</summary>
@@ -1202,7 +1202,7 @@
</Parameters>
<Docs>
<param name="behavior">One of the enumeration values that specifies the command behavior.</param>
- <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+ <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>Invokes <see cref="M:System.Data.Common.DbCommand.ExecuteDbDataReaderAsync(System.Data.CommandBehavior,System.Threading.CancellationToken)" />.</summary>
<returns>A task representing the asynchronous operation.</returns>
<remarks>
@@ -1362,7 +1362,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
</Parameters>
<Docs>
- <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+ <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
<summary>This is the asynchronous version of <see cref="M:System.Data.Common.DbCommand.ExecuteScalar" />. Providers should override with an appropriate implementation. The cancellation token may optionally be ignored.
The default implementation invokes the synchronous <see cref="M:System.Data.Common.DbCommand.ExecuteScalar" /> method and returns a completed task, blocking the calling thread. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Exceptions thrown by ExecuteScalar will be communicated via the returned Task Exception property.
@@ -1495,7 +1495,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
- <param name="cancellationToken">To be added.</param>
+ <param name="cancellationToken">An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.</param>
<summary>Asynchronously creates a prepared (or compiled) version of the command on the data source.</summary>
<returns>A <see cref="P:System.Threading.Tasks.Task" /> representing the asynchronous operation.</returns>
<remarks>
@@ -1506,7 +1506,7 @@
Data providers that support [asynchronous programming](~/docs/framework/data/adonet/asynchronous-programming.md) should override the default implementation using asynchronous I/O operations.
- If the <xref:System.Data.Common.DbCommand.CommandType%2A> property is set to `TableDirect`, `Prepare` does nothing. If <xref:System.Data.Common.DbCommand.CommandType%2A> is set to `StoredProcedure`, the call to `Prepare` should succeed, although it may result in a no-op.
+ If the <xref:System.Data.Common.DbCommand.CommandType%2A> property is set to `TableDirect`, `PrepareAsync` does nothing. If <xref:System.Data.Common.DbCommand.CommandType%2A> is set to `StoredProcedure`, the call to `PrepareAsync` should succeed, although it may result in a no-op.
]]></format>
</remarks>
diff --git a/xml/System.Data.Common/DbConnection.xml b/xml/System.Data.Common/DbConnection.xml
index 44184593b27..a26ffdadf82 100644
--- a/xml/System.Data.Common/DbConnection.xml
+++ b/xml/System.Data.Common/DbConnection.xml
@@ -294,7 +294,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
- <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+ <param name="cancellationToken">An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.</param>
<summary>Asynchronously begins a database transaction.</summary>
<returns>A task whose <see cref="P:System.Threading.Tasks.Task`1.Result" /> property is an object representing the new transaction.</returns>
<remarks>
@@ -337,7 +337,7 @@
</Parameters>
<Docs>
<param name="isolationLevel">One of the enumeration values that specifies the isolation level for the transaction to use.</param>
- <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+ <param name="cancellationToken">An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.</param>
<summary>Asynchronously begins a database transaction.</summary>
<returns>A task whose <see cref="P:System.Threading.Tasks.Task`1.Result" /> property is an object representing the new transaction.</returns>
<remarks>
@@ -427,7 +427,7 @@
</Parameters>
<Docs>
<param name="databaseName">The name of the database for the connection to use.</param>
- <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+ <param name="cancellationToken">An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.</param>
<summary>Asynchronously changes the current database for an open connection.</summary>
<returns>A task representing the asynchronous operation.</returns>
<remarks>
diff --git a/xml/System.Data.Common/DbTransaction.xml b/xml/System.Data.Common/DbTransaction.xml
index d5abea6dc59..bd75bbb3a40 100644
--- a/xml/System.Data.Common/DbTransaction.xml
+++ b/xml/System.Data.Common/DbTransaction.xml
@@ -138,7 +138,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
- <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+ <param name="cancellationToken">An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.</param>
<summary>Asynchronously commits the database transaction.</summary>
<returns>A <see cref="P:System.Threading.Tasks.Task" /> representing the asynchronous operation.</returns>
<remarks>
@@ -499,7 +499,7 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="netcore-3.0;netstandard-2.1" />
</Parameters>
<Docs>
- <param name="cancellationToken">A token to cancel the asynchronous operation.</param>
+ <param name="cancellationToken">An optional token to cancel the asynchronous operation. The default value is <see cref="CancellationToken.None"/>.</param>
<summary>Asynchronously rolls back a transaction from a pending state.</summary>
<returns>A task representing the asynchronous operation.</returns>
<remarks>