Update docs to include note about existing issues with Async APIs (#2118

)
dotnet · Aug 11, 2023 · b82b1eb · b82b1eb
1 parent 930133e
commit b82b1eb
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 0 deletions.
diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml
@@ -1698,6 +1698,11 @@ The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and t
 
 ## Remarks
 For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
+
+> [!NOTE]
+>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteNonQuery%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.
+
+
 ]]></format>
 			</remarks>
 			<exception cref="T:System.InvalidCastException">
@@ -1986,6 +1991,10 @@ The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand>, and
 
 ## Remarks
 For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
+
+> [!NOTE]
+>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReader%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.
+
 ]]></format>
 			</remarks>
 			<exception cref="T:System.InvalidCastException">
@@ -2466,6 +2475,10 @@ The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and t
 
 ## Remarks
 For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
+
+> [!NOTE]
+>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteScalar%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.
+
 ]]></format>
 			</remarks>
 			<exception cref="T:System.InvalidCastException">
@@ -2657,6 +2670,10 @@ The following example creates a <xref:Microsoft.Data.SqlClient.SqlCommand> and t
 ## Remarks
 The **XmlReader** returned by this method does not support asynchronous operations.
 For more information about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).
+
+> [!NOTE]
+>  For long running queries on the server, consider using <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteXmlReader%2A> due to a known issue with canceling queries via a cancellation token. Also, consider canceling execution using the <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> method.
+
 ]]></format>
 			</remarks>
 			<exception cref="T:System.InvalidCastException">

diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlDataReader.xml
@@ -1173,6 +1173,10 @@
  If the `behavior` parameter of <xref:Microsoft.Data.SqlClient.SqlCommand.ExecuteReaderAsync%2A> is set to `Default`, <xref:Microsoft.Data.SqlClient.SqlDataReader.ReadAsync%2A> reads the entire row before returning the Task.  
   
  For more information, including code samples, about asynchronous programming in the .NET Framework Data Provider for SQL Server, see [Asynchronous Programming](/sql/connect/ado-net/asynchronous-programming).  
+
+> [!NOTE]
+>  When reading large data (binary/text), it is recommended to use <xref:Microsoft.Data.SqlClient.SqlDataReader.Read%2A> for optimal performance.
+
   
  ]]></format>
             </remarks>