Skip to content

Commit c690120

Browse files
benrr101benrr101
authored
XML Documentation Fixes - Batch 7 (#2869)
* Batch 7 w/o testing * Spot checking! * Fixing build issue
1 parent 3d9c1e4 commit c690120

10 files changed

+1212
-605
lines changed

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

+86-56
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,87 @@
1-
<?xml version="1.0"?>
2-
<docs>
3-
<members name="SqlRetryLogicBase">
4-
<SqlRetryLogicBase>
5-
<summary>Retrieves the next time interval with respect to the number of retries if a transient condition occurs.</summary>
6-
</SqlRetryLogicBase>
7-
<NumberOfTries>
8-
<summary>Maximum number of retries.</summary>
9-
<value>
10-
<see langword="int" /> that returns the maximum number of retry execution attempts that will be attempted after the first failure.</value>
11-
</NumberOfTries>
12-
<Current>
13-
<summary>Current retry number starting from zero.</summary>
14-
<value>
15-
<see langword="int" /> that returns the number of retry execution attempts after the first failure.</value>
16-
</Current>
17-
<RetryIntervalEnumerator>
18-
<summary>The timer interval enumerator.</summary>
19-
<value>
20-
<see cref="T:Microsoft.Data.SqlClient.SqlRetryIntervalBaseEnumerator" /> value that indicates an enumerator to generate a sequence of time intervals.</value>
21-
</RetryIntervalEnumerator>
22-
<TransientPredicate>
23-
<summary>Delegate to a transient condition predicate. The function that this delegate points to must return a true value when an expected transient exception happens.</summary>
24-
<value>
25-
<see cref="T:System.Predicate`1" /> value that delegates to a function that receives a <see cref="T:System.Exception" /> input parameter.</value>
26-
</TransientPredicate>
27-
<RetryCondition>
28-
<param name="sender">The sender object.</param>
29-
<summary>Pre-retry validation for the sender state.</summary>
30-
<returns>Returns <see langword="true"/> if the sender is authorized to retry the operation.</returns>
31-
<remarks>
32-
<format type="text/markdown"><![CDATA[
33-
34-
> [IMPORTANT!]
35-
> Operations that are part of a **Transaction** are not safe to retry without specific knowledge of business logic. Due to this complexity, retry logic should be managed at the application level.
36-
37-
> [!NOTE]
38-
> The `RetryCondition` is an extra condition that checks before executing the `TransientPredicate` and the default condition always returns **true**.
39-
40-
]]></format>
41-
</remarks>
42-
</RetryCondition>
43-
<TryNextInterval>
44-
<param name="intervalTime">The interval time that is generated by the `RetryIntervalEnumerator`.</param>
45-
<summary>Try to get the next interval time by using the enumerator if the counter does not exceed the number of retries.</summary>
46-
<returns>Returns <see langword='true'/> if the number of retry attempts has not been exceeded; otherwise <see langword='false'/>.</returns>
47-
</TryNextInterval>
48-
<Reset>
49-
<summary>Set the counters and enumerator to default values for next use.</summary>
50-
</Reset>
51-
<Clone>
52-
<summary>Creates a new object that is a copy of the current instance.</summary>
53-
<returns>When implemented in a derived class, the method is expected to return a new object of the current instance. The default implementation throws NotImplementedException.</returns>
54-
<exception cref="T:System.NotImplementedException" >In all cases.</exception>
55-
</Clone>
56-
</members>
1+
<docs>
2+
<members name="SqlRetryLogicBase">
3+
<SqlRetryLogicBase>
4+
<summary>
5+
Retrieves the next time interval with respect to the number of retries if a transient condition occurs.
6+
</summary>
7+
</SqlRetryLogicBase>
8+
<NumberOfTries>
9+
<summary>
10+
Maximum number of retries.
11+
</summary>
12+
<value>
13+
<see langword="int" /> that returns the maximum number of retry execution attempts that will be attempted after the first failure.
14+
</value>
15+
</NumberOfTries>
16+
<Current>
17+
<summary>
18+
Current retry number starting from zero.
19+
</summary>
20+
<value>
21+
<see langword="int" /> that returns the number of retry execution attempts after the first failure.
22+
</value>
23+
</Current>
24+
<RetryIntervalEnumerator>
25+
<summary>
26+
The timer interval enumerator.
27+
</summary>
28+
<value>
29+
<see cref="T:Microsoft.Data.SqlClient.SqlRetryIntervalBaseEnumerator" /> value that indicates an enumerator to generate a sequence of time intervals.
30+
</value>
31+
</RetryIntervalEnumerator>
32+
<TransientPredicate>
33+
<summary>
34+
Delegate to a transient condition predicate. The function that this delegate points to must return a true value when an expected transient exception happens.
35+
</summary>
36+
<value>
37+
<see cref="T:System.Predicate`1" /> value that delegates to a function that receives a <see cref="T:System.Exception" /> input parameter.
38+
</value>
39+
</TransientPredicate>
40+
<RetryCondition>
41+
<param name="sender">
42+
The sender object.
43+
</param>
44+
<summary>
45+
Pre-retry validation for the sender state.
46+
</summary>
47+
<returns>
48+
Returns <see langword="true" /> if the sender is authorized to retry the operation.
49+
</returns>
50+
<remarks>
51+
<note type="important">
52+
Operations that are part of a <b>Transaction</b> are not safe to retry without specific knowledge of business logic. Due to this complexity, retry logic should be managed at the application level.
53+
</note>
54+
<note type="note">
55+
The <b>RetryCondition</b> is an extra condition that checks before executing the <see cref="P:Microsoft.Data.SqlClient.SqlRetryLogicBase.TransientPredicate" /> and the default condition always returns <see langword="true" />.
56+
</note>
57+
</remarks>
58+
</RetryCondition>
59+
<TryNextInterval>
60+
<param name="intervalTime">
61+
The interval time that is generated by the <see cref="P:Microsoft.Data.SqlClient.SqlRetryLogicBase.RetryIntervalEnumerator" />.
62+
</param>
63+
<summary>
64+
Try to get the next interval time by using the enumerator if the counter does not exceed the number of retries.
65+
</summary>
66+
<returns>
67+
Returns <see langword="true" /> if the number of retry attempts has not been exceeded; otherwise <see langword="false" />.
68+
</returns>
69+
</TryNextInterval>
70+
<Reset>
71+
<summary>
72+
Set the counters and enumerator to default values for next use.
73+
</summary>
74+
</Reset>
75+
<Clone>
76+
<summary>
77+
Creates a new object that is a copy of the current instance.
78+
</summary>
79+
<returns>
80+
When implemented in a derived class, the method is expected to return a new object of the current instance. The default implementation throws <see cref="T:System.NotImplementedException" />.
81+
</returns>
82+
<exception cref="T:System.NotImplementedException">
83+
In all cases.
84+
</exception>
85+
</Clone>
86+
</members>
5787
</docs>

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

+135-89
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,136 @@
1-
<?xml version="1.0"?>
2-
<docs>
3-
<members name="SqlRetryLogicBaseProvider">
4-
<SqlRetryLogicBaseProvider>
5-
<summary>Applies retry logic on an operation through the `Execute` or `ExecuteAsync` function.</summary>
6-
</SqlRetryLogicBaseProvider>
7-
<Retrying>
8-
<summary>Occurs before applying the calculated delay time and executing the function on a next attempt.</summary>
9-
<value>
10-
<see cref="System.EventHandler" /> with event argument of <see cref="T:Microsoft.Data.SqlClient.SqlRetryingEventArgs" /> object can be subscribed.</value>
11-
<remarks>
12-
<format type="text/markdown"><![CDATA[
13-
14-
> [IMPORTANT!]
15-
> Don't block execution with a time consuming action when an event occurs. For instance, if you log data to a file, run it in a new thread to avoid blocking the main execution thread.
16-
17-
]]>
18-
</format>
19-
</remarks>
20-
</Retrying>
21-
<RetryLogic>
22-
<summary>Defines the retry logic used to decide when to retry based on the encountered exception.</summary>
23-
<remarks>
24-
<format type="text/markdown"><![CDATA[
25-
26-
> [!NOTE]
27-
> The `RetryLogic` property is assigned at `SqlRetryLogicBaseProvider` creation and its value is used as a template internally. Don't use it to monitor the status of the retry logic during and after execution. Instead, use the <xref=E:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Retrying> event to collect data about retry executions.
28-
29-
]]>
30-
</format>
31-
</remarks>
32-
</RetryLogic>
33-
<Execute>
34-
<typeparam name = "TResult">The object that the `function` returns when executed.</typeparam>
35-
<param name="sender">The source of the event.</param>
36-
<param name="function">The operation to re-execute if a transient condition occurs.</param>
37-
<summary>Executes a function and applies retry logic, if enabled. **Note:** Exceptions will be reported via an aggregate exception if the execution isn't successful via retry attempts.
38-
</summary>
39-
<returns>The return value of the `function` if it runs without exception.</returns>
40-
<remarks>
41-
<format type="text/markdown"><![CDATA[
42-
43-
> [!NOTE]
44-
> The type of exception depends on the `function`'s internal implementation. But if the exception is due to all retry attempts failing, it will be an <xref:System.AggregateException> that consists of all exceptions that happened during the failed attempts.
45-
46-
]]>
47-
</format>
48-
</remarks>
49-
<exception cref="T:System.ArgumentNullException">The `function` parameter can't be `null`.</exception>
50-
<exception cref="T:System.AggregateException">The collection of exceptions after all retry attempts have failed.</exception>
51-
</Execute>
52-
<ExecuteAsync1>
53-
<typeparam name = "TResult">The object that the `function` returns in a Task when executed.</typeparam>
54-
<param name="sender">The source of the event.</param>
55-
<param name="function">The operation to re-execute if a transient condition occurs.</param>
56-
<param name="cancellationToken">The cancellation instruction.</param>
57-
<summary>Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. **Note:** Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.</summary>
58-
<returns>A task representing the asynchronous operation. The results of the task will be the return value of the `function`, if it runs without exception.</returns>
59-
<remarks>
60-
<format type="text/markdown"><![CDATA[
61-
62-
> [!NOTE]
63-
> If the exception comes from all retry attempts failing, it will be an <xref:System.AggregateException> that consists of all exceptions from the failed attempts.
64-
65-
]]>
66-
</format>
67-
</remarks>
68-
<exception cref="T:System.ArgumentNullException">The `function` parameter can't be `null`.</exception>
69-
<exception cref="T:System.AggregateException">The collection of exceptions after failed retry attempts.</exception>
70-
</ExecuteAsync1>
71-
<ExecuteAsync2>
72-
<param name="sender">The source of the event.</param>
73-
<param name="function">The operation to re-execute if a transient condition occurs.</param>
74-
<param name="cancellationToken">The cancellation instruction.</param>
75-
<summary>Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded. **Note:** Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.</summary>
76-
<returns>A Task or an exception.</returns>
77-
<remarks>
78-
<format type="text/markdown"><![CDATA[
79-
80-
> [!NOTE]
81-
> If the exception comes from all retry attempts failing, it will be an <xref:System.AggregateException> that consists of all exceptions from the failed attempts.
82-
83-
]]>
84-
</format>
85-
</remarks>
86-
<exception cref="T:System.ArgumentNullException">The `function` parameter can't be `null`.</exception>
87-
<exception cref="T:System.AggregateException">The collection of exceptions after failed retry attempts.</exception>
88-
</ExecuteAsync2>
89-
</members>
1+
<docs>
2+
<members name="SqlRetryLogicBaseProvider">
3+
<SqlRetryLogicBaseProvider>
4+
<summary>
5+
Applies retry logic on an operation through the <see cref="M:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute{TResult}(System.Object,System.Func{TResult})" /> or <see cref="M:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Execute{TResult}(System.Object,System.Func{System.Threading.Task{TResult}},System.Threading.CancellationToken)" /> function.
6+
</summary>
7+
</SqlRetryLogicBaseProvider>
8+
<Retrying>
9+
<summary>
10+
Occurs before applying the calculated delay time and executing the function on a next attempt.
11+
</summary>
12+
<value>
13+
<see cref="T:System.EventHandler" /> with event argument of <see cref="T:Microsoft.Data.SqlClient.SqlRetryingEventArgs" /> object can be subscribed.
14+
</value>
15+
<remarks>
16+
<note type="important">
17+
Don't block execution with a time-consuming action when an event occurs. For instance, if you log data to a file, run it in a new thread to avoid blocking the main execution thread.
18+
</note>
19+
</remarks>
20+
</Retrying>
21+
<RetryLogic>
22+
<summary>
23+
Defines the retry logic used to decide when to retry based on the encountered exception.
24+
</summary>
25+
<remarks>
26+
<note type="note">
27+
The <b>RetryLogic</b> property is assigned at construction of the <see cref="T:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider" /> creation and its value is used as a template internally. Don't use it to monitor the status of the retry logic during and after execution. Instead, use the <see cref="P:Microsoft.Data.SqlClient.SqlRetryLogicBaseProvider.Retrying" /> event to collect data about retry executions.
28+
</note>
29+
</remarks>
30+
</RetryLogic>
31+
<Execute>
32+
<typeparam name="TResult">
33+
The object that the `function` returns when executed.
34+
</typeparam>
35+
<param name="sender">
36+
The source of the event.
37+
</param>
38+
<param name="function">
39+
The operation to re-execute if a transient condition occurs.
40+
</param>
41+
<summary>
42+
<para>
43+
Executes a function and applies retry logic, if enabled.
44+
</para>
45+
<note type="note">
46+
Exceptions will be reported via an aggregate exception if the execution isn't successful via retry attempts.
47+
</note>
48+
</summary>
49+
<returns>
50+
The return value of the <paramref name="function" /> if it runs without exception.
51+
</returns>
52+
<remarks>
53+
<para>
54+
<note type="note">
55+
The type of exception depends on the <paramref name="function" />'s internal implementation. But if the exception is due to all retry attempts failing, it will be an <see cref="T:System.AggregateException" /> that consists of all exceptions that happened during the failed attempts.
56+
</note>
57+
</para>
58+
</remarks>
59+
<exception cref="T:System.ArgumentNullException">
60+
The <paramref name="function" /> parameter can't be <see langword="null" />.
61+
</exception>
62+
<exception cref="T:System.AggregateException">
63+
The collection of exceptions after all retry attempts have failed.
64+
</exception>
65+
</Execute>
66+
<ExecuteAsync1>
67+
<typeparam name="TResult">
68+
The object that the <paramref name="function" /> returns in a Task when executed.
69+
</typeparam>
70+
<param name="sender">
71+
The source of the event.
72+
</param>
73+
<param name="function">
74+
The operation to re-execute if a transient condition occurs.
75+
</param>
76+
<param name="cancellationToken">
77+
The cancellation instruction.
78+
</param>
79+
<summary>
80+
<para>
81+
Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded.
82+
</para>
83+
<note type="note">
84+
Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.
85+
</note>
86+
</summary>
87+
<returns>
88+
A task representing the asynchronous operation. The results of the task will be the return value of the <paramref name="function" />, if it runs without exception.
89+
</returns>
90+
<remarks>
91+
<note type="note">
92+
If the exception comes from all retry attempts failing, it will be an <see cref="T:System.AggregateException" /> that consists of all exceptions from the failed attempts.
93+
</note>
94+
</remarks>
95+
<exception cref="T:System.ArgumentNullException">
96+
The <paramref name="function" /> parameter can't be <see langword="null" />.
97+
</exception>
98+
<exception cref="T:System.AggregateException">
99+
The collection of exceptions after failed retry attempts.
100+
</exception>
101+
</ExecuteAsync1>
102+
<ExecuteAsync2>
103+
<param name="sender">
104+
The source of the event.
105+
</param>
106+
<param name="function">
107+
The operation to re-execute if a transient condition occurs.
108+
</param>
109+
<param name="cancellationToken">
110+
The cancellation instruction.
111+
</param>
112+
<summary>
113+
<para>
114+
Executes a function and applies retry logic, if enabled. The cancellation token can be used to request that the operation be abandoned before the execution attempts are exceeded.
115+
</para>
116+
<note type="note">
117+
Exceptions will be reported via the returned Task object, which will contain an aggregate exception if execution fails for all retry attempts.
118+
</note>
119+
</summary>
120+
<returns>
121+
A Task or an exception.
122+
</returns>
123+
<remarks>
124+
<note type="note">
125+
If the exception comes from all retry attempts failing, it will be an <see cref="T:System.AggregateException" /> that consists of all exceptions from the failed attempts.
126+
</note>
127+
</remarks>
128+
<exception cref="T:System.ArgumentNullException">
129+
The <paramref name="function" /> parameter can't be <see langword="null" />.
130+
</exception>
131+
<exception cref="T:System.AggregateException">
132+
The collection of exceptions after failed retry attempts.
133+
</exception>
134+
</ExecuteAsync2>
135+
</members>
90136
</docs>

0 commit comments

Comments
 (0)