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
dotnet · Aug 27, 2019 · a2b77ca · a2b77ca
1 parent a464a88
commit a2b77ca
Show file tree

Hide file tree

Showing 3 changed files with 12 additions and 12 deletions.
diff --git 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
@@ -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
@@ -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>