Skip to content

Commit 764add3

Browse files
benrr101benrr101
authored
XML Documentation Fix - Batch #2 (#2834)
* Batch #2 * Reverting removal of the snippet files. * Fixing build break caused by parameter not having a comment. * These changes should fix the broken comments
1 parent b1d3a82 commit 764add3

File tree

13 files changed

+6972
-2880
lines changed

13 files changed

+6972
-2880
lines changed

‎doc/samples/SqlBatch_ExecuteReader.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// <Snippet1>
1+
// <Snippet1>
22
using Microsoft.Data.SqlClient;
33

44
class Program

‎doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommand.xml‎

Lines changed: 99 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,89 @@
1-
<?xml version="1.0"?>
2-
<docs>
1+
<docs>
32
<members name="SqlBatchCommand">
43
<SqlBatchCommand>
54
<summary>
6-
SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch.
7-
</summary>
5+
SqlBatchCommand allows for the execution of multiple SQL commands in a SqlBatch.
6+
</summary>
87
</SqlBatchCommand>
98
<ctor1>
10-
<summary>Initializes a new <see cref="SqlBatchCommand"/>.</summary>
11-
<remarks>
12-
<format type="text/markdown">
13-
<![CDATA[
14-
## Examples
15-
The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection> and a SqlBatch, then adds multiple <xref:Microsoft.Data.SqlClient.SqlBatchCommand> objects to the batch. It then executes the batch, creating a <xref:Microsoft.Data.SqlClient.SqlDataReader>. The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the <xref:Microsoft.Data.SqlClient.SqlDataReader> and then the <xref:Microsoft.Data.SqlClient.SqlConnection> as the `using` blocks fall out of scope.
9+
<summary>
10+
Initializes a new <see cref="T:SqlBatchCommand" />.
11+
</summary>
12+
<example>
13+
The following example creates a <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> and a SqlBatch, then adds multiple <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> objects to the batch. It then executes the batch, creating a <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> . The example reads through the results of the batch commands, writing them to the console. Finally, the example closes the <see cref="T:Microsoft.Data.SqlClient.SqlDataReader" /> and then the <see cref="T:Microsoft.Data.SqlClient.SqlConnection" /> as the <c>using</c> blocks fall out of scope.
14+
<code language="c#">
15+
using Microsoft.Data.SqlClient;
16+
17+
class Program
18+
{
19+
static void Main()
20+
{
21+
string str = "Data Source=(local);Initial Catalog=Northwind;"
22+
+ "Integrated Security=SSPI;Encrypt=False";
23+
RunBatch(str);
24+
}
25+
26+
static void RunBatch(string connString)
27+
{
28+
using var connection = new SqlConnection(connString);
29+
connection.Open();
30+
31+
var batch = new SqlBatch(connection);
32+
33+
const int count = 10;
34+
const string parameterName = "parameter";
35+
for (int i = 0; i &lt; count; i++)
36+
{
37+
var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
38+
batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
39+
batch.BatchCommands.Add(batchCommand);
40+
}
41+
42+
// Optionally Prepare
43+
batch.Prepare();
1644

17-
[!code-csharp[SqlCommand Example#1](~/../sqlclient/doc/samples/SqlBatch_ExecuteReader.cs#1)]
18-
]]>
19-
</format>
20-
</remarks>
45+
var results = new List&lt;int&gt;(count);
46+
using (SqlDataReader reader = batch.ExecuteReader())
47+
{
48+
do
49+
{
50+
while (reader.Read())
51+
{
52+
results.Add(reader.GetFieldValue&lt;int&gt;(0));
53+
}
54+
} while (reader.NextResult());
55+
}
56+
Console.WriteLine(string.Join(", ", results));
57+
}
58+
}
59+
60+
</code>
61+
</example>
2162
</ctor1>
2263
<ctor2>
23-
<summary>Initializes a new <see cref="SqlBatchCommand"/>.</summary>
24-
<param name="commandText">The text of the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand"/>.</param>
25-
<param name="commandType">Indicates how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText"/> property is to be interpreted.</param>
26-
<param name="parameters">A collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter"/> objects is used to create the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection"/>.</param>
27-
<param name="columnEncryptionSetting">The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine).</param>
64+
<summary>
65+
Initializes a new <see cref="T:SqlBatchCommand" />.
66+
</summary>
67+
<param name="commandText">
68+
The text of the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" />.
69+
</param>
70+
<param name="commandType">
71+
Indicates how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText" /> property is to be interpreted.
72+
</param>
73+
<param name="parameters">
74+
A collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects is used to create the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection" />.
75+
</param>
76+
<param name="columnEncryptionSetting">
77+
The encryption setting. For more information, see <see href="/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
78+
</param>
2879
</ctor2>
2980
<Parameters>
30-
<summary>Gets the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection"/>.</summary>
31-
<value>The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection.</value>
81+
<summary>
82+
Gets the <see cref="T:Microsoft.Data.SqlClient.SqlParameterCollection" />.
83+
</summary>
84+
<value>
85+
The parameters of the Transact-SQL statement or stored procedure. The default is an empty collection.
86+
</value>
3287
</Parameters>
3388
<CommandBehavior>
3489
<summary>
@@ -38,28 +93,42 @@ The following example creates a <xref:Microsoft.Data.SqlClient.SqlConnection> an
3893
<ColumnEncryptionSetting>
3994
<summary>
4095
Not currently implemented.
41-
The encryption setting. For more information, see [Always Encrypted](/sql/relational-databases/security/encryption/always-encrypted-database-engine).
96+
The encryption setting. For more information, see <see href="/sql/relational-databases/security/encryption/always-encrypted-database-engine">Always Encrypted</see>.
4297
</summary>
4398
</ColumnEncryptionSetting>
4499
<CreateParameter>
45-
<summary>Creates a new instance of a <see cref="T:Microsoft.Data.SqlClient.SqlParameter"/> object.</summary>
100+
<summary>
101+
Creates a new instance of a <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> object.
102+
</summary>
46103
</CreateParameter>
47104
<CanCreateParameter>
48105
<summary>
49-
Returns whether the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CreateParameter"/> method is implemented.
106+
Returns whether the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CreateParameter" /> method is implemented.
50107
</summary>
51108
</CanCreateParameter>
52109
<CommandText>
53-
<summary>Gets or sets the text command to run against the data source.</summary>
54-
<value>The text command to execute. The default value is an empty string ("").</value>
110+
<summary>
111+
Gets or sets the text command to run against the data source.
112+
</summary>
113+
<value>
114+
The text command to execute. The default value is an empty string ("").
115+
</value>
55116
</CommandText>
56117
<CommandType>
57-
<summary>Gets or sets how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText" /> property is interpreted.</summary>
58-
<value>One of the enumeration values that specifies how a command string is interpreted. The default is <see langword="Text" />.</value>
118+
<summary>
119+
Gets or sets how the <see cref="P:Microsoft.Data.SqlClient.SqlBatchCommand.CommandText" /> property is interpreted.
120+
</summary>
121+
<value>
122+
One of the enumeration values that specifies how a command string is interpreted. The default is <see cref="F:System.Data.CommandType.Text" />.
123+
</value>
59124
</CommandType>
60125
<DbParameterCollection>
61-
<summary>Gets the collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects.</summary>
62-
<value>The parameters of the SQL statement or stored procedure.</value>
126+
<summary>
127+
Gets the collection of <see cref="T:Microsoft.Data.SqlClient.SqlParameter" /> objects.
128+
</summary>
129+
<value>
130+
The parameters of the SQL statement or stored procedure.
131+
</value>
63132
</DbParameterCollection>
64133
<RecordsAffected>
65134
<summary>

‎doc/snippets/Microsoft.Data.SqlClient/SqlBatchCommandCollection.xml‎

Lines changed: 49 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,27 @@
1-
<?xml version="1.0"?>
2-
<docs>
1+
<docs>
32
<members name="SqlBatchCommandCollection">
43
<SqlBatchCommandCollection>
54
<summary>
6-
A collection of instances of
7-
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" />, contained within a
8-
<see cref="T:Microsoft.Data.SqlClient.SqlBatch" />.
5+
A collection of instances of <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" />, contained within a <see cref="T:Microsoft.Data.SqlClient.SqlBatch" />.
96
</summary>
107
</SqlBatchCommandCollection>
118
<Add1>
129
<summary>
13-
Add a
14-
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> to the end of the
15-
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
10+
Add a <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> to the end of the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
1611
</summary>
17-
<value></value>
1812
</Add1>
1913
<Add2>
2014
<param name="item">
2115
The object to add to the <see cref="T:System.Collections.Generic.ICollection`1" />.
2216
</param>
2317
<summary>
2418
Adds the specified <see cref="T:System.Data.Common.DbBatchCommand" /> object to the <see cref="T:System.Collections.Generic.ICollection`1" />.
25-
</summary>
26-
<remarks>To be added.</remarks>
19+
</summary>
2720
</Add2>
2821
<Contains1>
2922
<summary>
30-
Determines whether a
31-
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> is in the
32-
<see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
23+
Determines whether a <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> is in the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
3324
</summary>
34-
<value></value>
3525
</Contains1>
3626
<Contains2>
3727
<param name="item">
@@ -43,13 +33,11 @@
4333
<returns>
4434
<see langword="true" /> if the <see cref="T:System.Data.Common.DbBatchCommand" /> is in the collection; otherwise <see langword="false" />.
4535
</returns>
46-
<remarks>To be added.</remarks>
4736
</Contains2>
4837
<CopyTo1>
4938
<summary>
5039
Copies the entire <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" /> to a one dimensional array, starting at the target index of the target array.
5140
</summary>
52-
<value></value>
5341
</CopyTo1>
5442
<CopyTo2>
5543
<param name="array">
@@ -61,7 +49,6 @@
6149
<summary>
6250
Copies the elements of the <see cref="T:System.Collections.Generic.ICollection`1" /> to an <see cref="T:System.Array" />, starting at a particular <see cref="T:System.Array" /> index.
6351
</summary>
64-
<remarks>To be added.</remarks>
6552
</CopyTo2>
6653
<IndexOf1>
6754
<summary>
@@ -81,13 +68,11 @@
8168
<returns>
8269
The index of the specified <see cref="T:System.Data.Common.DbBatchCommand" /> object.
8370
</returns>
84-
<remarks>To be added.</remarks>
85-
</IndexOf2>
71+
</IndexOf2>
8672
<Insert1>
8773
<summary>
8874
Inserts an item into the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" /> at the specified index.
8975
</summary>
90-
<exception cref="T:System.ArgumentOutOfRangeException"></exception>
9176
</Insert1>
9277
<Insert2>
9378
<param name="index">
@@ -99,7 +84,6 @@
9984
<summary>
10085
Inserts the specified index of the <see cref="T:System.Data.Common.DbBatchCommand" /> object with the specified name into the collection at the specified index.
10186
</summary>
102-
<remarks>To be added.</remarks>
10387
</Insert2>
10488
<Remove1>
10589
<summary>
@@ -111,25 +95,30 @@
11195
</Remove1>
11296
<Remove2>
11397
<param name="item">
114-
The object to remove from the <see cref="T:System.Collections.Generic.ICollection`1" />.
98+
The object to remove from the <see cref="T:System.Collections.Generic.ICollection`1" /> .
11599
</param>
116100
<summary>
117101
Removes the specified <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object from the collection.
118102
</summary>
119103
<returns>
120104
<see langword="true" /> if <paramref name="item" /> was successfully removed; otherwise, <see langword="false" />. This method also returns <see langword="false" /> if <paramref name="item" /> was not found in the <see cref="T:System.Collections.Generic.ICollection`1" />.
121-
</returns>
122-
<remarks>To be added.</remarks>
105+
</returns>
123106
</Remove2>
124107
<this1>
125-
<summary>Gets or Sets the element at the specified index.</summary>
126-
<returns>The element at the specified index.</returns>
127-
<exception cref="T:System.ArgumentOutOfRangeException"></exception>
108+
<summary>
109+
Gets or Sets the element at the specified index.
110+
</summary>
111+
<returns>
112+
The element at the specified index.
113+
</returns>
128114
</this1>
129115
<this2>
130-
<summary>Gets or Sets the element at the specified index.</summary>
131-
<returns>The element at the specified index.</returns>
132-
<exception cref="T:System.ArgumentOutOfRangeException"></exception>
116+
<summary>
117+
Gets or Sets the element at the specified index.
118+
</summary>
119+
<returns>
120+
The element at the specified index.
121+
</returns>
133122
</this2>
134123
<GetBatchCommand>
135124
<param name="index">
@@ -146,31 +135,49 @@
146135
<param name="index">
147136
The index where the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object should be located.
148137
</param>
149-
<param name="batchCommand">To be added.</param>
138+
<param name="batchCommand">
139+
The <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object to add to the collection.
140+
</param>
150141
<summary>
151142
Sets the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index to a new value.
152143
</summary>
153-
<remarks>To be added.</remarks>
154144
</SetBatchCommand>
155145
<Count>
156-
<summary>Gets the number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.</summary>
157-
<value>The number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.</value>
146+
<summary>
147+
Gets the number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.
148+
</summary>
149+
<value>
150+
The number of elements contained in the <see cref="T:System.Collections.Generic.ICollection`1" />.
151+
</value>
158152
</Count>
159153
<IsReadOnly>
160-
<summary>Specifies whether the collection is read-only.</summary>
154+
<summary>
155+
Specifies whether the collection is read-only.
156+
</summary>
161157
<value>
162-
<see langword="true" /> if the collection is read-only; otherwise <see langword="false" />.</value>
158+
<see langword="true" /> if the collection is read-only; otherwise <see langword="false" />.
159+
</value>
163160
</IsReadOnly>
164161
<GetEnumerator>
165-
<summary>Returns the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index in the collection.</summary>
166-
<returns>The <see cref="T:System.Data.Common.DbBatchCommand" /> object at the specified index in the collection.</returns>
162+
<summary>
163+
Returns the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index in the collection.
164+
</summary>
165+
<returns>
166+
The <see cref="T:System.Data.Common.DbBatchCommand" /> object at the specified index in the collection.
167+
</returns>
167168
</GetEnumerator>
168169
<Clear>
169-
<summary>Removes all <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> values from the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.</summary>
170+
<summary>
171+
Removes all <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> values from the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommandCollection" />.
172+
</summary>
170173
</Clear>
171174
<RemoveAt>
172-
<param name="index">The index where the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object is located.</param>
173-
<summary>Removes the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index from the collection.</summary>
175+
<param name="index">
176+
The index where the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object is located.
177+
</param>
178+
<summary>
179+
Removes the <see cref="T:Microsoft.Data.SqlClient.SqlBatchCommand" /> object at the specified index from the collection.
180+
</summary>
174181
</RemoveAt>
175182
</members>
176183
</docs>

0 commit comments

Comments
 (0)