From 63505426ab01f2cd9e51ede099f686c2a2d3e3e1 Mon Sep 17 00:00:00 2001 From: Davoud Date: Tue, 20 Feb 2024 12:13:32 -0800 Subject: [PATCH 1/6] Squashed commit of the following: commit 0ec519b3fa4f188aa0e523b76cf74a764cdec17f Merge: 94b4384e e3cf59d2 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 15 11:59:28 2024 -0800 Merge branch 'dotnet:main' into Task-28274-Update-API-Documentation commit 94b4384ea0f533ee19926b753ede2db60202dfa0 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 13 16:30:55 2024 -0800 Reviewed Intellisense Just clean-up, and removing the extra space between sentences. commit 79d979e375195d1f07db595ce2cf13be2ecbf30c Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 13 16:24:22 2024 -0800 Update SqlBatch.xml Remove namespaces that are breaking the documentation generator commit 8e5d8376da64787d2281aa77edfc0fb79e1ad61e Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 13 14:09:01 2024 -0800 Corrections to Namespace/Wrong Attributes Remove DbBatchCommandCollection commit a0af3d6c25e8010d075fba874fd87fc084743878 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 13 08:36:08 2024 -0800 Correct Case Mistakes commit f6c994fd32d79eaa5defb8e1c872ebaa8514bded Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 13 08:33:53 2024 -0800 Correct some missing documentation Missing tag headings commit 1cc876ea6c5f3f7db991dde5242e2de0eb7c57bd Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 13 08:24:12 2024 -0800 Manual Copy Paste of DBBatch version replacements Copy manual DB Batch (parent Class Documentation) commit c7fd5f1e9e8f9107880e9c30160979b0bc77a67e Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Feb 12 17:20:08 2024 -0800 Duplicate Features from DbBatch commit 0e8e54a382d3927148a79dd579f7d169f94dae55 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 8 13:08:29 2024 -0800 SQLBatchCommandCollection Changes Update to InheritDoc for SQLBatchCommandCollection commit a89449373bc9535abb3aa120b9229ae30d47e81a Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 8 10:20:53 2024 -0800 Update Batch documentation with InheritDoc and Resolved Paths Re-generate NuGet API Documentation with InheritDoc Changes for cref References commit 040df8829535f2f6e083f6f76fffdd04fb5241f9 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Feb 7 16:28:41 2024 -0800 Clean-up / Experiment 2 Remove DB Batch XML references, this documentation is not supported by this repository. Update smaller changes on Document inheritance, and find the correct formatting for usage. Existing inheritdoc references don't seem to be aligning very closely to their reference base classes. commit 3ca9b7ef4c0b795c01f8a1ece1392f7418264ce3 Merge: eed5b4b0 507e8dd6 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Feb 7 09:11:06 2024 -0800 Merge branch 'main' into Task-28274-Update-API-Documentation commit eed5b4b0c95d83d95cbb855fdc70c7d4bd225826 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Feb 7 09:05:10 2024 -0800 Explicit Declaration for SQLBatch and SQLBatchCommandCollection For InheritDoc, Explicit declaration of where the reference is located. commit 5d2cfd7808cf546d90f8ee0fccfa2eb82bd586f1 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 6 13:36:38 2024 -0800 Test Experimental Changes for API Documentation commit 20bacb0ef67699b58b21c617333ed11a314f7e70 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Feb 6 10:22:55 2024 -0800 Update Conditions for all .NetCore commit 2c95099a695f5f5c9c48882eb4789b6e7b94c509 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Feb 5 17:21:29 2024 -0800 Missing PrepareAsync commit cf03fb0ec0d5105c93045a3b2f9585866800ad77 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Feb 5 09:00:05 2024 -0800 Check if there's an Easier way to use InheritDoc Verify Different way of using InheritDoc will allow usage as attribute header. commit a1e5a1f915d1c00b434978b078f585b2f5266a6f Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Feb 2 10:39:22 2024 -0800 IList looks like the correct namespace Update namespace commit 42611b50e566f2ead1e121e6e6ebf8d6e3dfb8a6 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Feb 2 09:26:12 2024 -0800 Missing Definition for Property commit 17a95bb2965c0bf20e263e76507e82ced619aae3 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Feb 2 09:21:04 2024 -0800 Clean-up Mix up for Property vs Methods commit 66ad6a517815418eef83d0ae454a19f3c59e87ae Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 1 16:23:33 2024 -0800 Fix SqlBatch API Documentation - For Consistency Verification Against MS Doc Generation commit 17c86d464122a09a8615d23fd49e92895c612164 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 1 11:02:46 2024 -0800 Correct mistake on references Clean-up Connection Reference Mistake. commit 0a56b250fc5b7b81f4c6acd74684aa7ea1b0b1f4 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 1 10:38:53 2024 -0800 Test Possible Corrections on "Cross Reference Not Found" for System.Collection and "Found no member can be inherited by key" commit 0afee4c18facc12e5090a8ffe2c74deb093446bd Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Feb 1 08:11:11 2024 -0800 Correct NameSpace commit 6779d295dc3c45fbcb2dc110fbc2ccc334225a45 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 31 14:40:05 2024 -0800 Revert "Test Change in Pragma Directives" This reverts commit 17f22ba5eda43a1d1d73ac93ed17ddf6581427cd. commit 4fe316e4de1c976147ac2d45553ee891f73f1a59 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 31 14:32:52 2024 -0800 Fix mistake on format Correct format Type commit 17f22ba5eda43a1d1d73ac93ed17ddf6581427cd Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 31 13:50:49 2024 -0800 Test Change in Pragma Directives Change conditions, so that the class handles necessary changes commit c4a7a5448ceeceb053f031cd0949a3c9bde9c7e3 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 31 13:07:28 2024 -0800 Undo Incorrect Pathing - Physical Location VS Representation is not the same as physical location commit 04b25db823483422ffcbcd445ad82c598ce05127 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Jan 30 15:53:45 2024 -0800 Reference Paths Seem busted Pathing looks messed up commit 8036b9d12e78e8513b8fb212b88aaa46f4a3c7a5 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Jan 30 08:42:30 2024 -0800 Remove reference to System.Collections.Generic.IEnumerable. commit f5127374434df57e611f8890949d0e5f7f479840 Merge: bb3103cc 14d7292d Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Tue Jan 30 08:28:57 2024 -0800 Merge branch 'main' into Task-28274-Update-API-Documentation # Conflicts: # doc/snippets/Microsoft.Data.SqlClient/SqlException.xml commit bb3103cc017bb2b5618947cd6ee008c73f9686bc Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 29 16:35:50 2024 -0800 Wrong Namespace was used, Git rid of Extra Space, using the name of SqlBatch instead of Xref, just to see if the error will go away. Then figure out why Xref SQLBatch keeps failing as a reference, which might be a separate problem for documentation outside of the actual SQLBatch. It may be not able to properly get the XREF from a different file. commit 6afbd491f7a59232b872a48030b304f03546bfda Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 29 15:04:38 2024 -0800 Missing Documentation for Context on Page. https://review.learn.microsoft.com/en-us/dotnet/api/microsoft.data.sqlclient?view=sqlclient-dotnet-5.2&branch=pr-en-us-69 commit 135e4eae5d7905c35973113808f15a5758769d0f Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 29 13:06:42 2024 -0800 Revert SqlBatch test Test other Ienumerable fix commit 567ff897165b6dd20fb58c91bc25a986ba7c018b Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 29 09:07:02 2024 -0800 Try to Resolve Batch/IEnumerable Errors Making slightly changes on which signature needs to be added to resolve errors. commit 9608bbd21a4ad36e66518f1f28d6ca57e5696e8c Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Jan 26 17:11:31 2024 -0800 Include SqlBatch Reference Need to test if this reference is required, as it appears to be missing. commit b828a47dc88b6cb7ada56d87daba0a10d8cb7ae9 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Jan 26 13:20:16 2024 -0800 Reference BatchCommand Update Inherit doc cref references. commit ca05e53d6c50f497d9e1917a3a51b758ad02c7f6 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Jan 26 11:48:56 2024 -0800 Resolving Path References Working to resolve Path References commit 0823b743913be2676d0f7c5df1795735e18e1cf1 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 22 08:44:35 2024 -0800 Update XML Reference Looks like references to XREF paths in documentations require a specific XML pattern. commit e47715c8ad6407f0f3d5926c7a9a36765b01a1a4 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Fri Jan 19 15:31:20 2024 -0800 Updates to SqlBatchCommand PR failures commit 532ed2ae8313b967c0f3c3850ed2add390b77912 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Thu Jan 18 08:43:18 2024 -0800 Add a Change for Nuget on Updating SqlException - Match Javad's work. commit b8811273a9a055299bb2f6b8679ac4b621a11ee8 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 17 16:01:12 2024 -0800 Do Delta Differences Make changes, where one has an explicit definition in the .cs file/xml; While the other uses , based on the System.... series of libraries. commit 9c4e0df58c7808382125d08b3b2ab2f90e0ed795 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 17 13:54:53 2024 -0800 Partial Changes This is the first attempt to partially align formatting to the original way of doing things by marking up headers, prior to implementation of inheritdoc of base classes. commit c99502c9002d3c1ee195d9da017b87bc58362927 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Wed Jan 17 10:40:55 2024 -0800 Restore tags commit afe0ee478a3820f26108f1d46619d6f2598ed560 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 15 14:41:06 2024 -0800 Small Test - Inherit Doc verification to XML Following guided instructions, testing incrementally whether this is correct. Which appears to be sort of working based on compiled Microsoft XML document (no errors). commit 1495903d9a173e08bcda8a421daef95f056fbdb7 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 15 14:06:19 2024 -0800 Restore Based on documentation, inheritdoc should not be used here. commit 12623b0e63bc7862097d6915261542b02dab2583 Author: H. Yeo <138053434+H-Yeo@users.noreply.github.com> Date: Mon Jan 15 13:24:00 2024 -0800 Update SqlBatchCommand Class Starting with Update of SqlBatchCommand class document header --- .../Microsoft.Data.Common/DbBatch.xml | 651 ------------------ .../Microsoft.Data.Common/DbBatchCommand.xml | 113 --- .../DbBatchCommandCollection.xml | 410 ----------- .../Microsoft.Data.SqlClient/SqlBatch.xml | 101 ++- .../SqlBatchCommand.xml | 29 +- .../SqlBatchCommandCollection.xml | 146 +++- .../Microsoft.Data.SqlClient/SqlBulkCopy.xml | 2 +- .../SqlConnection.xml | 5 +- .../Microsoft.Data.SqlClient/SqlException.xml | 2 +- .../netcore/ref/Microsoft.Data.SqlClient.cs | 1 - .../ref/Microsoft.Data.SqlClient.csproj | 2 +- ...crosoft.Data.SqlClient.Batch.NetCoreApp.cs | 4 +- .../ref/Microsoft.Data.SqlClient.Batch.cs | 88 +-- .../src/Microsoft/Data/SqlClient/SqlBatch.cs | 39 +- .../Data/SqlClient/SqlBatchCommand.cs | 13 +- .../SqlClient/SqlBatchCommandCollection.cs | 34 +- 16 files changed, 311 insertions(+), 1329 deletions(-) delete mode 100644 doc/snippets/Microsoft.Data.Common/DbBatch.xml delete mode 100644 doc/snippets/Microsoft.Data.Common/DbBatchCommand.xml delete mode 100644 doc/snippets/Microsoft.Data.Common/DbBatchCommandCollection.xml diff --git a/doc/snippets/Microsoft.Data.Common/DbBatch.xml b/doc/snippets/Microsoft.Data.Common/DbBatch.xml deleted file mode 100644 index 1c9dcdd68b..0000000000 --- a/doc/snippets/Microsoft.Data.Common/DbBatch.xml +++ /dev/null @@ -1,651 +0,0 @@ - - - - - - - - - System.Object - - - - System.IAsyncDisposable - - - System.IDisposable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - Represents a batch of commands which can be executed against a data source in a single round trip. Provides a base class for database-specific classes that represent command batches. - - - - - - - - - - - Constructor - - - - Initializes a new instance of the class. - - To be added. - - - - - - Property - - System.Data.Common.DbBatchCommandCollection - - - - Gets the collection of objects. - - The commands contained within the batch. - To be added. - - - - - - Method - - System.Void - - - - - Attempts to cancel the execution of a . - - - - - - - - - - - - Property - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - [set: System.Runtime.CompilerServices.NullableContext(2)] - [<set: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Data.Common.DbConnection - - - - Gets or sets the used by this . - - The connection to the data source. - To be added. - - - - - - Method - - System.Data.Common.DbBatchCommand - - - - - Creates a new instance of a object. - - - A object. - - To be added. - - - - - - Method - - System.Data.Common.DbBatchCommand - - - - - When overridden in a derived class, creates a new instance of a object. - - - A object. - - To be added. - - - - - - Property - - System.Data.Common.DbBatchCommandCollection - - - - When overridden in a derived class, gets the collection of objects. - - The commands contained within the batch. - To be added. - - - - - - Property - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - [set: System.Runtime.CompilerServices.NullableContext(2)] - [<set: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Data.Common.DbConnection - - - - When overridden in a derived class, gets or sets the used by this . - - The connection to the data source. - To be added. - - - - - - Property - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - [set: System.Runtime.CompilerServices.NullableContext(2)] - [<set: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Data.Common.DbTransaction - - - - When overridden in a derived class, gets or sets the within which this object executes. - - - The transaction within which a batch of a .NET data provider executes. The default value is a null reference ( in Visual Basic). - - To be added. - - - - - - Method - - M:System.IDisposable.Dispose - - - System.Void - - - - Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. - To be added. - - - - - - Method - - M:System.IAsyncDisposable.DisposeAsync - - - System.Threading.Tasks.ValueTask - - - - Asynchronously diposes the batch object. - - A representing the asynchronous operation. - - - - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -]]> - - - - - - - - Method - - System.Data.Common.DbDataReader - - - - - - - An instance of , specifying options for batch execution and data retrieval. - - - When overridden in a derived class, executes the batch against its connection, returning a which can be used to access the results. - - - A object. - - - - can be used to advance the reader to the next result set. - - ]]> - - - An error occurred while executing the batch. - - The value is invalid. - - - - - - - Method - - System.Threading.Tasks.Task<System.Data.Common.DbDataReader> - - - - - - - One of the enumeration values that specifies options for batch execution and data retrieval. - A token to cancel the asynchronous operation. - - Providers should implement this method to provide a non-default implementation for overloads. - - The default implementation invokes the synchronous 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. - - This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request. - - A task representing the asynchronous operation. - - - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -]]> - - - - - - - - Method - - System.Int32 - - - - Executes the batch against its connection object, returning the total number of rows affected across all the batch commands. - The total number of rows affected across all the batch commands. - - - to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database by executing UPDATE, INSERT, or DELETE statements. - - Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. - - For UPDATE, INSERT, and DELETE statements, the return value is the total number of rows affected by the batch. If no UPDATE, INSERT, or DELETE statements are included in the batch, the return value is -1. - - ]]> - - - - - - - - Method - - System.Threading.Tasks.Task<System.Int32> - - - - - - A token to cancel the asynchronous operation. - - This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. - - The default implementation invokes the synchronous 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 will be communicated via the returned Task Exception property. - - Do not invoke other methods and properties of the object until the returned Task is complete. - - A task representing the asynchronous operation. - - - , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -]]> - - - An error occurred while executing the batch. - ADO.NET Overview - - - - - - Method - - System.Data.Common.DbDataReader - - - - - - One of the enumeration values that specifies options for batch execution and data retrieval. - - Executes the batch against its connection, returning a which can be used to access the results. - - - A object. - - - - can be used to advance the reader to the next result set. - - ]]> - - - - - - - - Method - - System.Threading.Tasks.Task<System.Data.Common.DbDataReader> - - - - - - To be added. - - An asynchronous version of , which executes the batch against its connection, returning a which can be used to access the results. - - A task representing the asynchronous operation. - - - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - - ]]> - - - An error occurred while executing the batch. - - The value is invalid. - - - - - - - Method - - System.Threading.Tasks.Task<System.Data.Common.DbDataReader> - - - - - - - One of the enumeration values that specifies options for batch execution and data retrieval. - A token to cancel the asynchronous operation. - - An asynchronous version of , which executes the batch against its connection, returning a which can be used to access the results. - - A task representing the asynchronous operation. - - - in . For more information about asynchronous programming, see [Asynchronous Programming](/dotnet/framework/data/adonet/asynchronous-programming). - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - -]]> - - - An error occurred while executing the batch. - - The value is invalid. - - - - - - - Method - - - [System.Runtime.CompilerServices.NullableContext(2)] - [<System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Object - - - - Executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and resultsets are ignored. - The first column of the first row in the first result set. - To be added. - An error occurred while executing the batch. - - - - - - Method - - System.Threading.Tasks.Task<System.Object> - - - - - - A token to cancel the asynchronous operation. - - An asynchronous version of , which executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored. - - The first column of the first row in the first result set. - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - - An error occurred while executing the batch. - - - - - - Method - - System.Void - - - - Creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source. - To be added. - - - - - - Method - - System.Threading.Tasks.Task - - - - - - - An optional token to cancel the asynchronous operation. The default value is . - - Asynchronously creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source. - - A representing the asynchronous operation. - - - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . - - - - - - - Property - - System.Int32 - - - Gets or sets the wait time (in seconds) before terminating the attempt to execute the batch and generating an error. - The time in seconds to wait for the batch to execute. - - - is generated if the assigned property value is less than 0. - - Note to implementers: it's recommended that 0 mean no timeout. - - ]]> - - - - - - - - Property - - - [System.Runtime.CompilerServices.Nullable(2)] - [<System.Runtime.CompilerServices.Nullable(2)>] - - - [get: System.Runtime.CompilerServices.NullableContext(2)] - [<get: System.Runtime.CompilerServices.NullableContext(2)>] - - - [set: System.Runtime.CompilerServices.NullableContext(2)] - [<set: System.Runtime.CompilerServices.NullableContext(2)>] - - - - System.Data.Common.DbTransaction - - - - Gets or sets the within which this object executes. - - - The transaction within which a batch of a .NET data provider executes. The default value is a null reference ( in Visual Basic). - - To be added. - - - - diff --git a/doc/snippets/Microsoft.Data.Common/DbBatchCommand.xml b/doc/snippets/Microsoft.Data.Common/DbBatchCommand.xml deleted file mode 100644 index 68efa39676..0000000000 --- a/doc/snippets/Microsoft.Data.Common/DbBatchCommand.xml +++ /dev/null @@ -1,113 +0,0 @@ - - - - - System.Object - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - - Represents a single command within a . A batch can be executed against a data source in a single round trip. - - To be added. - - - - - - Constructor - - - - Constructs an instance of the object. - - To be added. - - - - - - Property - - System.String - - - Gets or sets the text command to run against the data source. - The text command to execute. The default value is an empty string (""). - To be added. - - - - - - Property - - System.Data.CommandType - - - - Gets or sets how the property is interpreted. - - - One of the enumeration values that specifies how a command string is interpreted. The default is . - - To be added. - - - - - - Property - - System.Data.Common.DbParameterCollection - - - - Gets the collection of objects. - - The parameters of the SQL statement or stored procedure. - To be added. - - - - - - Property - - System.Data.Common.DbParameterCollection - - - - Gets the collection of objects. For more information on parameters, see [Configuring Parameters and Parameter Data Types](/dotnet/framework/data/adonet/configuring-parameters-and-parameter-data-types). - - The parameters of the SQL statement or stored procedure. - To be added. - - - - - - Property - - System.Int32 - - - - Gets the number of rows changed, inserted, or deleted by execution of this specific . - - The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected or the statement failed. - To be added. - - - - diff --git a/doc/snippets/Microsoft.Data.Common/DbBatchCommandCollection.xml b/doc/snippets/Microsoft.Data.Common/DbBatchCommandCollection.xml deleted file mode 100644 index 610c7860f7..0000000000 --- a/doc/snippets/Microsoft.Data.Common/DbBatchCommandCollection.xml +++ /dev/null @@ -1,410 +0,0 @@ - - - - - System.Object - - - - System.Collections.Generic.ICollection<Microsoft.Data.Common.DbBatchCommand> - - - System.Collections.Generic.ICollection<T> - - - System.Collections.Generic.IEnumerable<Microsoft.Data.Common.DbBatchCommand> - - - System.Collections.Generic.IEnumerable<T> - - - System.Collections.Generic.IList<Microsoft.Data.Common.DbBatchCommand> - - - System.Collections.IEnumerable - - - - - [System.Runtime.CompilerServices.Nullable(0)] - [<System.Runtime.CompilerServices.Nullable(0)>] - - - [System.Runtime.CompilerServices.NullableContext(1)] - [<System.Runtime.CompilerServices.NullableContext(1)>] - - - - - The base class for a collection of instances of , contained in a . - - To be added. - - - - - Constructor - - - - Initializes a new instance of the class. - - To be added. - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Add(`0) - - - System.Void - - - - - - - The object to add to the . - - - Adds the specified object to the . - - To be added. - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Clear - - - System.Void - - - - - Removes all values from the . - - To be added. - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Contains(`0) - - - System.Boolean - - - - - - - The object to locate in the . - - - Indicates whether a is contained in the collection. - - - if the is in the collection; otherwise . - - To be added. - - - - - - Method - - M:System.Collections.Generic.ICollection`1.CopyTo(`0[],System.Int32) - - - System.Void - - - - - - - - The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. - - - The zero-based index in at which copying begins. - - - Copies the elements of the to an , starting at a particular index. - - To be added. - - - - - - Property - - P:System.Collections.Generic.ICollection`1.Count - - - System.Int32 - - - - Gets the number of elements contained in the . - - - The number of elements contained in the . - - To be added. - - - - - - Method - - Microsoft.Data.Common.DbBatchCommand - - - - - - To be added. - To be added. - To be added. - To be added. - - - - - - Method - - M:System.Collections.Generic.IEnumerable`1.GetEnumerator - - - System.Collections.Generic.IEnumerator<Microsoft.Data.Common.DbBatchCommand> - - - - - Returns the object at the specified index in the collection. - - - The object at the specified index in the collection. - - To be added. - - - - - - Method - - M:System.Collections.Generic.IList`1.IndexOf(`0) - - - System.Int32 - - - - - - - The object to locate in the . - - - Returns the index of the specified object. - - - The index of the specified object. - - To be added. - - - - - - - - - - Method - - M:System.Collections.Generic.IList`1.Insert(System.Int32,`0) - - - System.Void - - - - - - - - The index at which to insert the object. - - - The object to insert into the . - - - Inserts the specified index of the object with the specified name into the collection at the specified index. - - To be added. - - - - - - Property - - P:System.Collections.Generic.ICollection`1.IsReadOnly - - - System.Boolean - - - Specifies whether the collection is read-only. - - if the collection is read-only; otherwise . - - To be added. - - - - - - Property - - P:System.Collections.Generic.IList`1.Item(System.Int32) - - - Microsoft.Data.Common.DbBatchCommand - - - - - - - The zero-based index of the . - - - Gets or sets the at the specified index. - - - The at the specified index. - - To be added. - The specified index does not exist. - - - - - - Method - - M:System.Collections.Generic.ICollection`1.Remove(`0) - - - System.Boolean - - - - - - - The object to remove from the . - - - Removes the specified object from the collection. - - - if was successfully removed; otherwise, . This method also returns if was not found in the . - - To be added. - - - - - - Method - - M:System.Collections.Generic.IList`1.RemoveAt(System.Int32) - - - System.Void - - - - - - - The index where the object is located. - - - Removes the object at the specified from the collection. - - To be added. - - - - - - Method - - System.Void - - - - - - - - The index where the object is located. - - To be added. - - Sets the object at the specified index to a new value. - - To be added. - - - - - - Method - - M:System.Collections.IEnumerable.GetEnumerator - - - System.Collections.IEnumerator - - - - Returns an enumerator that iterates through a collection. - - An object that can be used to iterate through the collection. - - - - instance is cast to an interface. - - ]]> - - - - - - diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml index 476a7a492e..a5fd4e16e4 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml @@ -52,31 +52,6 @@ The following example creates a an - - The list of commands contained in the batch in a . - - - - and a , then adds multiple objects to the batch. It then executes the batch, creating a . The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the and then the as the `using` blocks fall out of scope. - -[!code-csharp[SqlCommand Example#1](~/../sqlclient/doc/samples/SqlBatch_ExecuteReader.cs#1)] -]]> - - - - - - The list of commands contained in the batch in a . - - - - - - - Gets or sets the @@ -101,6 +76,31 @@ The following example creates a an + + + The list of commands contained in the batch in a . + + + + and a , then adds multiple objects to the batch. It then executes the batch, creating a . The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the and then the as the `using` blocks fall out of scope. + +[!code-csharp[SqlCommand Example#1](~/../sqlclient/doc/samples/SqlBatch_ExecuteReader.cs#1)] +]]> + + + + + + The list of commands contained in the batch in a + of + objects. + + + + + Sends the @@ -125,14 +125,14 @@ The following example creates a an An asynchronous version of - + , which sends the - + to the - + and builds a - - . Exceptions will be reported via the returned Task object. + . + Exceptions will be reported via the returned Task object. @@ -141,5 +141,46 @@ The following example creates a an + + Gets or sets the wait time (in seconds) before terminating the attempt to execute the batch and generating an error. + The time in seconds to wait for the batch to execute. + + + A token to cancel the asynchronous operation. + This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. + +The default implementation invokes the synchronous 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 will be communicated via the returned Task Exception property. + +Do not invoke other methods and properties of the object until the returned Task is complete. + A task representing the asynchronous operation. + + + To be added. + An asynchronous version, which executes the batch against its connection, returning a which can be used to access the results. + A task representing the asynchronous operation. + + + An optional token to cancel the asynchronous operation. The default value is . + Asynchronously creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source. + A representing the asynchronous operation. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + + + An instance of , specifying options for batch execution and data retrieval. + When overridden in a derived class, executes the batch against its connection, returning a which can be used to access the results. + A object. + + + One of the enumeration values that specifies options for batch execution and data retrieval. + A token to cancel the asynchronous operation. + Providers should implement this method to provide a non-default implementation. + + The default implementation invokes the synchronous 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. + + This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request. + A task representing the asynchronous operation. + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml index 9ad24b8abf..df652693aa 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml @@ -1,13 +1,18 @@ + + + SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch. + + Initializes a new . and a , then adds multiple objects to the batch. It then executes the batch, creating a . The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the and then the as the `using` blocks fall out of scope. +The following example creates a and a SqlBatch, then adds multiple objects to the batch. It then executes the batch, creating a . The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the and then the as the `using` blocks fall out of scope. [!code-csharp[SqlCommand Example#1](~/../sqlclient/doc/samples/SqlBatch_ExecuteReader.cs#1)] ]]> @@ -17,8 +22,8 @@ The following example creates a an Initializes a new . The text of the . - Indicates how the property is to be interpreted. - A , which is used to crate the . + Indicates how the property is to be interpreted. + A collection of objects is used to create the . The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine). @@ -28,11 +33,7 @@ The following example creates a an - - Gets the - - . - + Gets the . The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection. @@ -72,5 +73,17 @@ The following example creates a an Returns whether the method is implemented. + + + + + + + + + + + + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml index f350a48731..e707557928 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml @@ -2,8 +2,11 @@ - A collection of instances of , contained within a . - + + A collection of instances of + , contained within a + . + - - Add a to the end of the . + + + Add a + to the end of the + . + @@ -20,9 +27,22 @@ ]]> - - - Determines whether a is in the . + + + + The object to add to the . + + + Adds the specified object to the . + + To be added. + + + + Determines whether a + is in the + . + @@ -30,9 +50,23 @@ ]]> - - - Copies the entire to a one dimensional array, starting at the target index of the target array. + + + + The object to locate in the . + + + Indicates whether a is contained in the collection. + + + if the is in the collection; otherwise . + + To be added. + + + + Copies the entire to a one dimensional array, starting at the target index of the target array. + @@ -40,9 +74,23 @@ ]]> - - - Searches for the specified within the and returns the zero-based index of the first occurence within the entire . + + + + The one-dimensional that is the destination of the elements copied from . The must have zero-based indexing. + + + The zero-based index in at which copying begins. + + + Copies the elements of the to an , starting at a particular index. + + To be added. + + + + Searches for the specified within the and returns the zero-based index of the first occurence within the entire . + Returns the zero-based index of the first occurence within the entire . @@ -52,9 +100,23 @@ ]]> - - - Inserts an item into the at the specified index. + + + + The object to locate in the . + + + Returns the index of the specified object. + + + The index of the specified object. + + To be added. + + + + Inserts an item into the at the specified index. + @@ -62,17 +124,46 @@ ]]> - - - Removes the first occurence of the specific item from the . - Returns if an item is successfully removed. Returns false if an item could not be removed or no item was not found. + + + + The index at which to insert the object. + + + The object to insert into the . + + + Inserts the specified index of the object with the specified name into the collection at the specified index. + + To be added. + + + + Removes the first occurence of the specific item from the + . + + + Returns if an item is successfully removed. Returns false if an item could not be removed or no item was not found. + - + + + + The object to remove from the . + + + Removes the specified object from the collection. + + + if was successfully removed; otherwise, . This method also returns if was not found in the . + + To be added. + Gets or Sets the element at the specified index. The element at the specified index. @@ -95,5 +186,18 @@ + + To be added. + + + + The index where the object is located. + + To be added. + + Sets the object at the specified index to a new value. + + To be added. + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBulkCopy.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBulkCopy.xml index 06fdf1b5b6..6f7cc400d5 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBulkCopy.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBulkCopy.xml @@ -5,7 +5,7 @@ Lets you efficiently bulk load a SQL Server table with data from another source. - class lets you write managed code solutions that provide similar functionality. There are other ways to load data into a SQL Server table (INSERT statements, for example), but offers a significant performance advantage over them. The class can be used to write data only to SQL Server tables. However, the data source is not limited to SQL Server; any data source can be used, as long as the data can be loaded to a instance or read with a instance. will fail when bulk loading a column of type into a SQL Server column whose type is one of the date/time types added in SQL Server 2008. diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index dde09d58b7..413ae0356d 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -145,10 +145,11 @@ using (SqlConnection connection = new SqlConnection(connectionString)) The Func that takes a and and returns a . - + . + The following example demonstrates how to define and set an . [!code-csharp[SqlConnection_AccessTokenCallback Example#1](~/../sqlclient/doc/samples/SqlConnection_AccessTokenCallback.cs#1)] diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml index 044606269f..bc1e2eeaf3 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml @@ -140,7 +140,7 @@ catch (Exception ex) { - + Gets the line number within the Transact-SQL command batch or stored procedure that generated the error. diff --git a/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.cs b/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.cs index b114fc57b1..ba7a1cd534 100644 --- a/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.cs +++ b/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.cs @@ -388,7 +388,6 @@ public void Remove(SqlBulkCopyColumnOrderHint columnOrderHint) { } /// public new void RemoveAt(int index) { } } - /// [System.FlagsAttribute] public enum SqlBulkCopyOptions diff --git a/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.csproj b/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.csproj index 9d29c3009a..9ab6b8d80f 100644 --- a/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.csproj +++ b/src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.csproj @@ -16,7 +16,7 @@ - + diff --git a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs index 6ff4060093..c96275acb2 100644 --- a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs +++ b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs @@ -1,9 +1,9 @@ -namespace System.Data.Common +namespace Microsoft.Data.SqlClient { /// public partial class SqlBatchCommand { - /// + /// public Microsoft.Data.SqlClient.SqlCommandColumnEncryptionSetting ColumnEncryptionSetting { get { throw null; } set { } } } } diff --git a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs index be9b716150..3ef5e7791a 100644 --- a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs +++ b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs @@ -11,63 +11,65 @@ public class SqlBatch : System.Data.Common.DbBatch public SqlBatch() { throw null; } /// public SqlBatch(Microsoft.Data.SqlClient.SqlConnection connection, Microsoft.Data.SqlClient.SqlTransaction transaction = null) { throw null; } - /// - public override int Timeout { get => throw null; set { } } /// - public new Microsoft.Data.SqlClient.SqlConnection Connection { get => throw null; set { } } + public override int Timeout { get => throw null; set { } } /// - public new Microsoft.Data.SqlClient.SqlTransaction Transaction { get => throw null; set { } } + public new Microsoft.Data.SqlClient.SqlConnection Connection { get => throw null; set { } } /// + public new Microsoft.Data.SqlClient.SqlTransaction Transaction { get => throw null; set { } } + /// public new SqlBatchCommandCollection BatchCommands { get => throw null; } - /// + /// protected override System.Data.Common.DbBatchCommandCollection DbBatchCommands { get => throw null; } - /// + /// protected override System.Data.Common.DbConnection DbConnection { get => throw null; set { } } - /// - protected override System.Data.Common.DbTransaction DbTransaction { get => throw null; set { } } - /// + /// + protected override System.Data.Common.DbTransaction DbTransaction { get => throw null; set { } } + /// public override void Cancel() => throw null; - /// + /// public override int ExecuteNonQuery() => throw null; - /// + /// public override System.Threading.Tasks.Task ExecuteNonQueryAsync(System.Threading.CancellationToken cancellationToken = default) => throw null; - /// + /// public override object ExecuteScalar() => throw null; - /// + /// public override System.Threading.Tasks.Task ExecuteScalarAsync(System.Threading.CancellationToken cancellationToken = default) => throw null; - /// + /// public override void Prepare() => throw null; - /// + /// public override System.Threading.Tasks.Task PrepareAsync(System.Threading.CancellationToken cancellationToken = default) => throw null; - /// + /// protected override System.Data.Common.DbDataReader ExecuteDbDataReader(System.Data.CommandBehavior behavior) => throw null; - /// + /// protected override System.Threading.Tasks.Task ExecuteDbDataReaderAsync(System.Data.CommandBehavior behavior, System.Threading.CancellationToken cancellationToken) => throw null; /// public System.Collections.Generic.List Commands { get { throw null; } } /// - public Microsoft.Data.SqlClient.SqlDataReader ExecuteReader() => throw null; - /// + public Microsoft.Data.SqlClient.SqlDataReader ExecuteReader() => throw null; + /// + public Microsoft.Data.SqlClient.SqlDataReader ExecuteReaderAsync() => throw null; + /// protected override System.Data.Common.DbBatchCommand CreateDbBatchCommand() => throw null; } - /// + /// public partial class SqlBatchCommand : System.Data.Common.DbBatchCommand { - /// + /// public SqlBatchCommand() => throw null; - /// + /// public SqlBatchCommand(string commandText, System.Data.CommandType commandType = System.Data.CommandType.Text, System.Collections.Generic.IEnumerable parameters = null, Microsoft.Data.SqlClient.SqlCommandColumnEncryptionSetting columnEncryptionSetting = Microsoft.Data.SqlClient.SqlCommandColumnEncryptionSetting.UseConnectionSetting) { throw null; } /// public new Microsoft.Data.SqlClient.SqlParameterCollection Parameters { get { throw null; } } - /// + /// public override string CommandText { get { throw null; } set { } } - /// + /// public override System.Data.CommandType CommandType { get { throw null; } set { } } /// public System.Data.CommandBehavior CommandBehavior { get { throw null; } set { } } - /// + /// public override int RecordsAffected { get { throw null; } } - /// + /// protected override System.Data.Common.DbParameterCollection DbParameterCollection => throw null; } /// @@ -77,45 +79,45 @@ public class SqlBatchCommandCollection : System.Data.Common.DbBatchCommandCollec public override int Count => throw null; /// public override bool IsReadOnly => throw null; - /// System.Collections.Generic.IEnumerator System.Collections.Generic.IEnumerable.GetEnumerator() => throw null; - /// + /// public override System.Collections.Generic.IEnumerator GetEnumerator() => throw null; - /// + /// public void Add(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; - /// + /// public override void Add(System.Data.Common.DbBatchCommand item) => throw null; /// public override void Clear() => throw null; - /// + /// public bool Contains(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; - /// + /// public override bool Contains(System.Data.Common.DbBatchCommand item) => throw null; - /// + /// public void CopyTo(Microsoft.Data.SqlClient.SqlBatchCommand[] array, int arrayIndex) => throw null; - /// + /// public override void CopyTo(System.Data.Common.DbBatchCommand[] array, int arrayIndex) => throw null; - /// + /// public int IndexOf(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; - /// + /// public override int IndexOf(System.Data.Common.DbBatchCommand item) => throw null; - /// + /// public void Insert(int index, Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; - /// + /// public override void Insert(int index, System.Data.Common.DbBatchCommand item) => throw null; - /// + /// public bool Remove(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; - /// + /// public override bool Remove(System.Data.Common.DbBatchCommand item) => throw null; /// public override void RemoveAt(int index) => throw null; + /// Microsoft.Data.SqlClient.SqlBatchCommand System.Collections.Generic.IList.this[int index] { get => throw null; set { } } - /// + /// public new Microsoft.Data.SqlClient.SqlBatchCommand this[int index] { get => throw null; set { } } System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator() => throw null; - /// + /// protected override System.Data.Common.DbBatchCommand GetBatchCommand(int index) => throw null; - /// + /// protected override void SetBatchCommand(int index, System.Data.Common.DbBatchCommand batchCommand) => throw null; } /// diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs index ff12f3a572..c95bc4456f 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs @@ -32,7 +32,7 @@ public SqlBatch(SqlConnection connection = null, SqlTransaction transaction = nu Connection = connection; Transaction = transaction; } - /// + /// public override int Timeout { get @@ -46,11 +46,11 @@ public override int Timeout _batchCommand.CommandTimeout = value; } } - /// + /// protected override DbBatchCommandCollection DbBatchCommands => BatchCommands; /// public new SqlBatchCommandCollection BatchCommands => _providerCommands != null ? _providerCommands : _providerCommands = new SqlBatchCommandCollection(Commands); // Commands call will check disposed - /// + /// protected override DbConnection DbConnection { get @@ -64,7 +64,7 @@ protected override DbConnection DbConnection Connection = (SqlConnection)value; } } - /// + /// protected override DbTransaction DbTransaction { get @@ -78,47 +78,46 @@ protected override DbTransaction DbTransaction Transaction = (SqlTransaction)value; } } - - /// + /// public override void Cancel() { CheckDisposed(); _batchCommand.Cancel(); } - /// + /// public override int ExecuteNonQuery() { CheckDisposed(); SetupBatchCommandExecute(); return _batchCommand.ExecuteNonQuery(); } - /// + /// public override Task ExecuteNonQueryAsync(CancellationToken cancellationToken = default) { CheckDisposed(); SetupBatchCommandExecute(); return _batchCommand.ExecuteNonQueryAsync(cancellationToken); } - /// + /// public override object ExecuteScalar() { CheckDisposed(); SetupBatchCommandExecute(); return _batchCommand.ExecuteScalar(); } - /// + /// public override Task ExecuteScalarAsync(CancellationToken cancellationToken = default) { CheckDisposed(); SetupBatchCommandExecute(); return _batchCommand.ExecuteScalarBatchAsync(cancellationToken); } - /// + /// public override void Prepare() { CheckDisposed(); } - /// + /// public override Task PrepareAsync(CancellationToken cancellationToken = default) { CheckDisposed(); @@ -184,9 +183,9 @@ public SqlDataReader ExecuteReader() SetupBatchCommandExecute(); return _batchCommand.ExecuteReaderAsync(cancellationToken); } - /// + /// protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior) => ExecuteReader(); - /// + /// protected override Task ExecuteDbDataReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken) { CheckDisposed(); @@ -204,8 +203,12 @@ protected override Task ExecuteDbDataReaderAsync(CommandBehavior b TaskContinuationOptions.ExecuteSynchronously | TaskContinuationOptions.NotOnCanceled, TaskScheduler.Default ); + } + /// + protected override DbBatchCommand CreateDbBatchCommand() + { + return new SqlBatchCommand(); } - private void CheckDisposed() { if (_batchCommand is null) @@ -213,7 +216,6 @@ private void CheckDisposed() throw ADP.ObjectDisposed(this); } } - private void SetupBatchCommandExecute() { SqlConnection connection = Connection; @@ -231,11 +233,6 @@ private void SetupBatchCommandExecute() } _batchCommand.SetBatchRPCModeReadyToExecute(); } - /// - protected override DbBatchCommand CreateDbBatchCommand() - { - return new SqlBatchCommand(); - } } } diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommand.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommand.cs index b9cf7296b5..8a40450b2d 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommand.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommand.cs @@ -9,7 +9,7 @@ namespace Microsoft.Data.SqlClient { - /// + /// public partial class SqlBatchCommand #if NET6_0_OR_GREATER : DbBatchCommand @@ -68,35 +68,37 @@ internal SqlBatchCommand(string commandText, SqlParameterCollection parameterCol _parameters = parameterCollection; } - /// + /// public #if NET6_0_OR_GREATER override #endif string CommandText { get => _text; set => _text = value; } - /// + /// public #if NET6_0_OR_GREATER override #endif CommandType CommandType { get => _type; set => SetCommandType(value); } + /// public CommandBehavior CommandBehavior { get => _behavior; set => _behavior = value; } - /// + /// public #if NET6_0_OR_GREATER override #endif int RecordsAffected { get => _recordsAffected; } - /// + /// protected #if NET6_0_OR_GREATER override #endif DbParameterCollection DbParameterCollection => Parameters; + /// public #if NET6_0_OR_GREATER @@ -117,6 +119,7 @@ internal set _parameters = value; } } + /// public SqlCommandColumnEncryptionSetting ColumnEncryptionSetting { get => _encryptionSetting; set => _encryptionSetting = value; } diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs index e824c2f414..ae1d1df6d8 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs @@ -5,7 +5,6 @@ using System.Collections.Generic; using System.Data.Common; -using Microsoft.Data.Common; namespace Microsoft.Data.SqlClient { @@ -22,39 +21,38 @@ internal SqlBatchCommandCollection(List batchCommands) public override int Count => _list.Count; /// public override bool IsReadOnly => false; - /// IEnumerator IEnumerable.GetEnumerator() => _list.GetEnumerator(); - /// + /// public override IEnumerator GetEnumerator() => _list.GetEnumerator(); - /// + /// public void Add(SqlBatchCommand item) => _list.Add(item); - /// + /// public override void Add(DbBatchCommand item) => Add((SqlBatchCommand)item); /// public override void Clear() => _list.Clear(); - /// + /// public bool Contains(SqlBatchCommand item) => _list.Contains(item); - /// + /// public override bool Contains(DbBatchCommand item) => Contains((SqlBatchCommand)item); - /// + /// public void CopyTo(SqlBatchCommand[] array, int arrayIndex) => _list.CopyTo(array, arrayIndex); - /// + /// public override void CopyTo(DbBatchCommand[] array, int arrayIndex) { SqlBatchCommand[] target = (SqlBatchCommand[])array; CopyTo(target, arrayIndex); } - /// + /// public int IndexOf(SqlBatchCommand item) => _list.IndexOf(item); - /// + /// public override int IndexOf(DbBatchCommand item) => IndexOf((SqlBatchCommand)item); - /// + /// public void Insert(int index, SqlBatchCommand item) => _list.Insert(index, item); - /// + /// public override void Insert(int index, DbBatchCommand item) => Insert(index, (SqlBatchCommand)item); - /// + /// public bool Remove(SqlBatchCommand item) => _list.Remove(item); - /// + /// public override bool Remove(DbBatchCommand item) => Remove((SqlBatchCommand)item); /// public override void RemoveAt(int index) => _list.RemoveAt(index); @@ -70,13 +68,11 @@ SqlBatchCommand IList.this[int index] get => _list[index]; set => _list[index] = value; } - /// + /// protected override DbBatchCommand GetBatchCommand(int index) => _list[index]; - - /// + /// protected override void SetBatchCommand(int index, DbBatchCommand batchCommand) => _list[index] = (SqlBatchCommand)batchCommand; - } } From c42654c11727c12bf5ad040a2dba484f69fd63f0 Mon Sep 17 00:00:00 2001 From: Davoud Date: Tue, 20 Feb 2024 17:52:25 -0800 Subject: [PATCH 2/6] SqlBatch - use inheritdoc in xml file --- .../Microsoft.Data.SqlClient/SqlBatch.xml | 70 ++++++++++--------- .../ref/Microsoft.Data.SqlClient.Batch.cs | 40 ++++++----- .../src/Microsoft/Data/SqlClient/SqlBatch.cs | 18 ++--- 3 files changed, 67 insertions(+), 61 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml index a5fd4e16e4..9cd4b0bde6 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml @@ -141,46 +141,50 @@ The following example creates a an + + + + + + + + + - Gets or sets the wait time (in seconds) before terminating the attempt to execute the batch and generating an error. - The time in seconds to wait for the batch to execute. + + + + + + + + + + + + + + + + + + + - A token to cancel the asynchronous operation. - This is the asynchronous version of . Providers should override with an appropriate implementation. The cancellation token may optionally be ignored. - -The default implementation invokes the synchronous 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 will be communicated via the returned Task Exception property. - -Do not invoke other methods and properties of the object until the returned Task is complete. - A task representing the asynchronous operation. + + + + - To be added. - An asynchronous version, which executes the batch against its connection, returning a which can be used to access the results. - A task representing the asynchronous operation. + + + + - An optional token to cancel the asynchronous operation. The default value is . - Asynchronously creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source. - A representing the asynchronous operation. - This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + - - An instance of , specifying options for batch execution and data retrieval. - When overridden in a derived class, executes the batch against its connection, returning a which can be used to access the results. - A object. - - - One of the enumeration values that specifies options for batch execution and data retrieval. - A token to cancel the asynchronous operation. - Providers should implement this method to provide a non-default implementation. - - The default implementation invokes the synchronous 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. - - This method accepts a cancellation token that can be used to request the operation to be cancelled early. Implementations may ignore this request. - A task representing the asynchronous operation. - diff --git a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs index 3ef5e7791a..4f1c431cc8 100644 --- a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs +++ b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs @@ -13,44 +13,46 @@ public class SqlBatch : System.Data.Common.DbBatch public SqlBatch(Microsoft.Data.SqlClient.SqlConnection connection, Microsoft.Data.SqlClient.SqlTransaction transaction = null) { throw null; } /// public override int Timeout { get => throw null; set { } } + /// + public System.Collections.Generic.List Commands { get { throw null; } } /// public new Microsoft.Data.SqlClient.SqlConnection Connection { get => throw null; set { } } /// public new Microsoft.Data.SqlClient.SqlTransaction Transaction { get => throw null; set { } } /// public new SqlBatchCommandCollection BatchCommands { get => throw null; } - /// + /// protected override System.Data.Common.DbBatchCommandCollection DbBatchCommands { get => throw null; } - /// + /// protected override System.Data.Common.DbConnection DbConnection { get => throw null; set { } } - /// + /// protected override System.Data.Common.DbTransaction DbTransaction { get => throw null; set { } } - /// + /// public override void Cancel() => throw null; - /// + /// + protected override System.Data.Common.DbBatchCommand CreateDbBatchCommand() => throw null; + /// + public override void Dispose() => throw null; + /// + protected override System.Data.Common.DbDataReader ExecuteDbDataReader(System.Data.CommandBehavior behavior) => throw null; + /// + protected override System.Threading.Tasks.Task ExecuteDbDataReaderAsync(System.Data.CommandBehavior behavior, System.Threading.CancellationToken cancellationToken) => throw null; + /// public override int ExecuteNonQuery() => throw null; /// public override System.Threading.Tasks.Task ExecuteNonQueryAsync(System.Threading.CancellationToken cancellationToken = default) => throw null; - /// + /// + public Microsoft.Data.SqlClient.SqlDataReader ExecuteReader() => throw null; + /// + public Microsoft.Data.SqlClient.SqlDataReader ExecuteReaderAsync() => throw null; + /// public override object ExecuteScalar() => throw null; /// public override System.Threading.Tasks.Task ExecuteScalarAsync(System.Threading.CancellationToken cancellationToken = default) => throw null; - /// + /// public override void Prepare() => throw null; /// public override System.Threading.Tasks.Task PrepareAsync(System.Threading.CancellationToken cancellationToken = default) => throw null; - /// - protected override System.Data.Common.DbDataReader ExecuteDbDataReader(System.Data.CommandBehavior behavior) => throw null; - /// - protected override System.Threading.Tasks.Task ExecuteDbDataReaderAsync(System.Data.CommandBehavior behavior, System.Threading.CancellationToken cancellationToken) => throw null; - /// - public System.Collections.Generic.List Commands { get { throw null; } } - /// - public Microsoft.Data.SqlClient.SqlDataReader ExecuteReader() => throw null; - /// - public Microsoft.Data.SqlClient.SqlDataReader ExecuteReaderAsync() => throw null; - /// - protected override System.Data.Common.DbBatchCommand CreateDbBatchCommand() => throw null; } /// public partial class SqlBatchCommand : System.Data.Common.DbBatchCommand diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs index c95bc4456f..efc81eae1a 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatch.cs @@ -46,11 +46,11 @@ public override int Timeout _batchCommand.CommandTimeout = value; } } - /// + /// protected override DbBatchCommandCollection DbBatchCommands => BatchCommands; /// public new SqlBatchCommandCollection BatchCommands => _providerCommands != null ? _providerCommands : _providerCommands = new SqlBatchCommandCollection(Commands); // Commands call will check disposed - /// + /// protected override DbConnection DbConnection { get @@ -64,7 +64,7 @@ protected override DbConnection DbConnection Connection = (SqlConnection)value; } } - /// + /// protected override DbTransaction DbTransaction { get @@ -78,13 +78,13 @@ protected override DbTransaction DbTransaction Transaction = (SqlTransaction)value; } } - /// + /// public override void Cancel() { CheckDisposed(); _batchCommand.Cancel(); } - /// + /// public override int ExecuteNonQuery() { CheckDisposed(); @@ -98,7 +98,7 @@ public override Task ExecuteNonQueryAsync(CancellationToken cancellationTok SetupBatchCommandExecute(); return _batchCommand.ExecuteNonQueryAsync(cancellationToken); } - /// + /// public override object ExecuteScalar() { CheckDisposed(); @@ -112,7 +112,7 @@ public override Task ExecuteScalarAsync(CancellationToken cancellationTo SetupBatchCommandExecute(); return _batchCommand.ExecuteScalarBatchAsync(cancellationToken); } - /// + /// public override void Prepare() { CheckDisposed(); @@ -123,7 +123,7 @@ public override Task PrepareAsync(CancellationToken cancellationToken = default) CheckDisposed(); return Task.CompletedTask; } - /// + /// public override void Dispose() { _batchCommand?.Dispose(); @@ -204,7 +204,7 @@ protected override Task ExecuteDbDataReaderAsync(CommandBehavior b TaskScheduler.Default ); } - /// + /// protected override DbBatchCommand CreateDbBatchCommand() { return new SqlBatchCommand(); From 15388880490b7b2725f0af5f4f470857da4d99cb Mon Sep 17 00:00:00 2001 From: Davoud Date: Tue, 20 Feb 2024 18:53:30 -0800 Subject: [PATCH 3/6] SqlBatchCommand - use inheritdoc in xml file --- .../Microsoft.Data.SqlClient/SqlBatchCommand.xml | 15 ++++++++++----- .../Microsoft.Data.SqlClient/SqlCommand.xml | 4 ++-- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml index df652693aa..1db2b096e3 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml @@ -3,7 +3,7 @@ - SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch. + SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch. @@ -74,16 +74,21 @@ The following example creates a an - + - + - + - + + Gets the number of rows changed, inserted, or deleted by execution of this specific . + + + The number of rows changed, inserted, or deleted. -1 for SELECT statements; 0 if no rows were affected or the statement failed. + diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml index 8dea0674cc..a19cff3c8a 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlCommand.xml @@ -1339,10 +1339,10 @@ The method is a st - To be added. + Gets the collection of objects. - To be added. + The parameters of the SQL statement or stored procedure. To be added. From 4b74322c4c2e85f9f97708e9cdbd6e3c71339442 Mon Sep 17 00:00:00 2001 From: Davoud Date: Tue, 20 Feb 2024 19:26:12 -0800 Subject: [PATCH 4/6] SqlBatchCommandCollection - use inheritdoc in xml file --- .../SqlBatchCommandCollection.xml | 25 ++++++++++++++++++- .../ref/Microsoft.Data.SqlClient.Batch.cs | 10 ++++---- .../SqlClient/SqlBatchCommandCollection.cs | 10 ++++---- 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml index e707557928..0a646bb90c 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml @@ -187,7 +187,15 @@ - To be added. + + The index where the object is located. + + + Returns the object at the specified index in the list. + + + The object at the specified index in the list. + @@ -199,5 +207,20 @@ To be added. + + + + + + + + + + + + + + + diff --git a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs index 4f1c431cc8..1b66106439 100644 --- a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs +++ b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs @@ -77,18 +77,18 @@ public partial class SqlBatchCommand : System.Data.Common.DbBatchCommand /// public class SqlBatchCommandCollection : System.Data.Common.DbBatchCommandCollection, System.Collections.Generic.IList { - /// + /// public override int Count => throw null; - /// + /// public override bool IsReadOnly => throw null; System.Collections.Generic.IEnumerator System.Collections.Generic.IEnumerable.GetEnumerator() => throw null; - /// + /// public override System.Collections.Generic.IEnumerator GetEnumerator() => throw null; /// public void Add(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; /// public override void Add(System.Data.Common.DbBatchCommand item) => throw null; - /// + /// public override void Clear() => throw null; /// public bool Contains(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; @@ -110,7 +110,7 @@ public class SqlBatchCommandCollection : System.Data.Common.DbBatchCommandCollec public bool Remove(Microsoft.Data.SqlClient.SqlBatchCommand item) => throw null; /// public override bool Remove(System.Data.Common.DbBatchCommand item) => throw null; - /// + /// public override void RemoveAt(int index) => throw null; /// Microsoft.Data.SqlClient.SqlBatchCommand System.Collections.Generic.IList.this[int index] { get => throw null; set { } } diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs index ae1d1df6d8..97c5fb01d9 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBatchCommandCollection.cs @@ -17,18 +17,18 @@ internal SqlBatchCommandCollection(List batchCommands) { _list = batchCommands; } - /// + /// public override int Count => _list.Count; - /// + /// public override bool IsReadOnly => false; IEnumerator IEnumerable.GetEnumerator() => _list.GetEnumerator(); - /// + /// public override IEnumerator GetEnumerator() => _list.GetEnumerator(); /// public void Add(SqlBatchCommand item) => _list.Add(item); /// public override void Add(DbBatchCommand item) => Add((SqlBatchCommand)item); - /// + /// public override void Clear() => _list.Clear(); /// public bool Contains(SqlBatchCommand item) => _list.Contains(item); @@ -54,7 +54,7 @@ public override void CopyTo(DbBatchCommand[] array, int arrayIndex) public bool Remove(SqlBatchCommand item) => _list.Remove(item); /// public override bool Remove(DbBatchCommand item) => Remove((SqlBatchCommand)item); - /// + /// public override void RemoveAt(int index) => _list.RemoveAt(index); /// SqlBatchCommand IList.this[int index] From e340f930a77a118294664cbd622986ac19105938 Mon Sep 17 00:00:00 2001 From: Davoud Date: Thu, 22 Feb 2024 17:03:32 -0800 Subject: [PATCH 5/6] Take out inheritdoc --- .../Microsoft.Data.SqlClient/SqlBatch.xml | 156 ++++++++++++++---- .../SqlBatchCommand.xml | 33 +--- .../SqlBatchCommandCollection.xml | 78 ++------- .../SqlConnection.xml | 19 +++ .../Microsoft.Data.SqlClient/SqlException.xml | 13 ++ .../Microsoft/Data/SqlClient/SqlConnection.cs | 4 +- ...crosoft.Data.SqlClient.Batch.NetCoreApp.cs | 22 ++- .../Microsoft/Data/SqlClient/SqlException.cs | 2 +- 8 files changed, 199 insertions(+), 128 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml index 9cd4b0bde6..998f3788d6 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml @@ -60,21 +60,9 @@ The following example creates a an . - - - - - Gets or sets the within which the commands execute. - - - - - @@ -134,57 +122,159 @@ The following example creates a an . Exceptions will be reported via the returned Task object. - - - - - - + Gets the collection of objects. + The commands contained within the batch. - + Gets or sets the used by this . + The connection to the data source. - + Gets or sets the within which this object executes. + The transaction within which a batch of a ADO.NET data provider executes. The default value is a null reference ( in Visual Basic). - + Gets or sets the wait time (in seconds) before terminating the attempt to execute the batch and generating an error. + The time in seconds to wait for the batch to execute, which is in contract with the underlaying + + is generated if the assigned property value is less than 0. + + Note to implementers: it's recommended that 0 mean no timeout. + + ]]> + - + Attempts to cancel the execution of a . + + + - + Creates a new instance of a object. + A object. - + Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. - + An instance of , specifying options for batch execution and data retrieval. + Executes the batch against its connection, returning a which can be used to access the results. + A object. + + can be used to advance the reader to the next result set. + + > [!NOTE] + > This method benefits from , and all the excpeted exceptions of that method also apply here. + + ]]> + + An error occurred while executing the batch. + The value is invalid. - + One of the enumeration values that specifies options for batch execution and data retrieval. + A token to cancel the asynchronous operation. + This implementation invokes the method and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellation token. + +This method accepts a cancellation token that can be used to request the operation to be cancelled early. + A task representing the asynchronous operation. + + , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + + > [!NOTE] + > This method benefits from , and all the excpeted exceptions of that method also apply here. + +]]> + + The cancellation token was canceled. This exception is stored into the returned task. - + Executes the batch against its connection object, returning the total number of rows affected across all the batch commands. + The total number of rows affected across all the batch commands. + + to perform catalog operations (for example, querying the structure of a database or creating database objects such as tables), or to change the data in a database by executing UPDATE, INSERT, or DELETE statements. + + Although does not return any rows, any output parameters or return values mapped to parameters are populated with data. + + For UPDATE, INSERT, and DELETE statements, the return value is the total number of rows affected by the batch. If no UPDATE, INSERT, or DELETE statements are included in the batch, the return value is -1. + +> [!NOTE] +> This method benefits from , and all the excpeted exceptions of that method also apply here. + + ]]> + - + A token to cancel the asynchronous operation. + This is the asynchronous version of . + + The implementation invokes the method and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellation token. + + Do not invoke other methods and properties of the object until the returned Task is complete. + A task representing the asynchronous operation. + + , are still thrown synchronously. + +> [!NOTE] +> This method benefits from , and all the excpeted exceptions of that method also apply here. + +]]> + + An error occurred while executing the batch. + ADO.NET Overview + The cancellation token was canceled. This exception is stored into the returned task. - + Executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and resultsets are ignored. + The first column of the first row in the first result set. + An error occurred while executing the batch. - + A token to cancel the asynchronous operation. + An asynchronous version of , which executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored. + The first column of the first row in the first result set. + This method benefits from , and all the excpeted exceptions of that method also apply here. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. + + An error occurred while executing the batch. + The cancellation token was canceled. This exception is stored into the returned task. - + Creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source. - + An optional token to cancel the asynchronous operation. The default value is . + Asynchronously creates a prepared (or compiled) version of the batch, or of each of its commands, on the data source. + A representing the asynchronous operation. + This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . + + The cancellation token was canceled. This exception is stored into the returned task. diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml index 1db2b096e3..be3744d730 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml @@ -25,45 +25,21 @@ The following example creates a an Indicates how the property is to be interpreted. A collection of objects is used to create the . The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine). - - - - - Gets the . The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection. - - - - - One of the values, indicating options for statement execution and data retrieval. - - - - - Not currently implemented. The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine). - - - - - Creates a new instance of a object. @@ -74,13 +50,16 @@ The following example creates a an - + Gets or sets the text command to run against the data source. + The text command to execute. The default value is an empty string (""). - + Gets or sets how the property is interpreted. + One of the enumeration values that specifies how a command string is interpreted. The default is . - + Gets the collection of objects. + The parameters of the SQL statement or stored procedure. diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml index 0a646bb90c..ca089e9712 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml @@ -7,12 +7,6 @@ , contained within a . - - - - - @@ -21,12 +15,6 @@ . - - - - - @@ -44,12 +32,6 @@ . - - - - - @@ -68,12 +50,6 @@ Copies the entire to a one dimensional array, starting at the target index of the target array. - - - - - @@ -94,12 +70,6 @@ Returns the zero-based index of the first occurence within the entire . - - - - - @@ -118,12 +88,6 @@ Inserts an item into the at the specified index. - - - - - @@ -139,25 +103,18 @@ - Removes the first occurence of the specific item from the - . + Removes the first occurence of a specific object from the collection. Returns if an item is successfully removed. Returns false if an item could not be removed or no item was not found. - - - - - The object to remove from the . - Removes the specified object from the collection. + Removes the specified object from the collection. if was successfully removed; otherwise, . This method also returns if was not found in the . @@ -168,23 +125,11 @@ Gets or Sets the element at the specified index. The element at the specified index. - - - - - Gets or Sets the element at the specified index. The element at the specified index. - - - - - @@ -199,28 +144,33 @@ - The index where the object is located. + The index where the object should be located. To be added. - Sets the object at the specified index to a new value. + Sets the object at the specified index to a new value. To be added. - + Gets the number of elements contained in the . + The number of elements contained in the . - + Specifies whether the collection is read-only. + + if the collection is read-only; otherwise . - + Returns the object at the specified index in the collection. + The object at the specified index in the collection. - + Removes all values from the . - + The index where the object is located. + Removes the object at the specified index from the collection. diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml index 413ae0356d..7833db6f4a 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlConnection.xml @@ -300,6 +300,21 @@ using (SqlConnection connection = new SqlConnection(connectionString)) Parallel transactions are not allowed when using Multiple Active Result Sets (MARS). Parallel transactions are not supported. + + Gets a value that indicates whether this instance supports the class. + + if this instance supports the class; otherwise, . The default is . + + + and overrides `CanCreateBatch` property to return `true`. + + ]]> + + The name of the database to use instead of the current database. Changes the current database for an open . @@ -660,6 +675,10 @@ End Module ]]> + + Returns a new instance of the class that implements the class. + A new instance of . + To be added. To be added. diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml index bc1e2eeaf3..c6441167cf 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlException.xml @@ -292,6 +292,19 @@ catch (Exception ex) { + + If this was thrown when executing a , references the specific which triggered the exception. + The specific which triggered the exception. + + wasn't thrown when executing a , the value is `null`. + + ]]> + + Gets a numeric error code from SQL Server that represents an error, warning or "no data found" message. For more information about how to decode these values, see Database Engine Events and Errors. The number representing the error code. diff --git a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnection.cs b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnection.cs index d9812157a5..4b4e7ccc43 100644 --- a/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnection.cs +++ b/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlConnection.cs @@ -1793,10 +1793,10 @@ public override DataTable GetSchema(string collectionName, string[] restrictionV } #if NET6_0_OR_GREATER - /// + /// public override bool CanCreateBatch => true; - /// + /// protected override DbBatch CreateDbBatch() => new SqlBatch(this); #endif diff --git a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs index c96275acb2..c49273bbf8 100644 --- a/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs +++ b/src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs @@ -1,4 +1,8 @@ -namespace Microsoft.Data.SqlClient +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. +// See the LICENSE file in the project root for more information. + +namespace Microsoft.Data.SqlClient { /// public partial class SqlBatchCommand @@ -6,4 +10,20 @@ public partial class SqlBatchCommand /// public Microsoft.Data.SqlClient.SqlCommandColumnEncryptionSetting ColumnEncryptionSetting { get { throw null; } set { } } } + + /// + public partial class SqlConnection + { + /// + public override bool CanCreateBatch { get { throw null; } } + /// + protected override System.Data.Common.DbBatch CreateDbBatch() => throw null; + } + + /// + public partial class SqlException + { + /// + protected override System.Data.Common.DbBatchCommand DbBatchCommand => throw null; + } } diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlException.cs b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlException.cs index fd812f065d..336a788c73 100644 --- a/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlException.cs +++ b/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlException.cs @@ -116,7 +116,7 @@ public override void GetObjectData(SerializationInfo si, StreamingContext contex #if NET6_0_OR_GREATER - /// + /// protected override DbBatchCommand DbBatchCommand => BatchCommand; /// From 43a1a04899a6896985bbb486110fdab9ba4608cc Mon Sep 17 00:00:00 2001 From: Davoud Date: Mon, 26 Feb 2024 12:36:01 -0800 Subject: [PATCH 6/6] fix --- doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml index 998f3788d6..9ce061e042 100644 --- a/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml +++ b/doc/snippets/Microsoft.Data.SqlClient/SqlBatch.xml @@ -178,7 +178,7 @@ The following example creates a an When the batch returns multiple result sets from different commands, can be used to advance the reader to the next result set. > [!NOTE] - > This method benefits from , and all the excpeted exceptions of that method also apply here. + > This method benefits from , and all the expected exceptions of that method also apply here. ]]> @@ -201,7 +201,7 @@ This method accepts a cancellation token that can be used to request the operati This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. For the stored exceptions, see the exceptions thrown by . > [!NOTE] - > This method benefits from , and all the excpeted exceptions of that method also apply here. + > This method benefits from , and all the expected exceptions of that method also apply here. ]]> @@ -221,7 +221,7 @@ This method accepts a cancellation token that can be used to request the operati For UPDATE, INSERT, and DELETE statements, the return value is the total number of rows affected by the batch. If no UPDATE, INSERT, or DELETE statements are included in the batch, the return value is -1. > [!NOTE] -> This method benefits from , and all the excpeted exceptions of that method also apply here. +> This method benefits from , and all the expected exceptions of that method also apply here. ]]> @@ -230,7 +230,7 @@ This method accepts a cancellation token that can be used to request the operati A token to cancel the asynchronous operation. This is the asynchronous version of . - The implementation invokes the method and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellation token. + The implementation invokes the method and returns a completed task. The default implementation will return a cancelled task if passed an already cancelled cancellation token. Do not invoke other methods and properties of the object until the returned Task is complete. A task representing the asynchronous operation. @@ -243,7 +243,7 @@ This method accepts a cancellation token that can be used to request the operati If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. > [!NOTE] -> This method benefits from , and all the excpeted exceptions of that method also apply here. +> This method benefits from , and all the expected exceptions of that method also apply here. ]]> @@ -260,7 +260,7 @@ This method accepts a cancellation token that can be used to request the operati A token to cancel the asynchronous operation. An asynchronous version of , which executes the batch and returns the first column of the first row in the first returned result set. All other columns, rows and result sets are ignored. The first column of the first row in the first result set. - This method benefits from , and all the excpeted exceptions of that method also apply here. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. + This method benefits from , and all the expected exceptions of that method also apply here. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as , are still thrown synchronously. An error occurred while executing the batch. The cancellation token was canceled. This exception is stored into the returned task.