Skip to content

Commit ea6147b

Browse files
antonfirsovcarlossanlopgewarren
authored
Port System.Net.Http docs for HttpRequestError and metrics additions (#9305)
* HTTP: docs for HttpRequestError and metrics additions * add namespace docs * Apply suggestions from code review * inheritdoc is stupid * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> * Fix invalid xref * missing <returns> --------- Co-authored-by: Carlos Sánchez López <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
1 parent eb9031c commit ea6147b

9 files changed

+68
-53
lines changed

‎xml/System.Net.Http.Metrics/HttpMetricsEnrichmentContext.xml

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,21 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
28-
<remarks>To be added.</remarks>
27+
<summary>Provides functionality for enriching the <c>http.client.request.duration</c> metric.</summary>
28+
<remarks>
29+
<format type="text/markdown"><![CDATA[
30+
31+
## Remarks
32+
33+
Enrichment is done on per-request basis by callbacks registered with <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCallback(System.Net.Http.HttpRequestMessage,System.Action{System.Net.Http.Metrics.HttpMetricsEnrichmentContext})>.
34+
35+
The callbacks are responsible for adding custom tags via <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCustomTag(System.String,System.Object)> for which they can use the request, response, and error information exposed on the <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext> instance.
36+
37+
> [!IMPORTANT]
38+
> The <xref:System.Net.Http.Metrics.HttpMetricsEnrichmentContext> instance must not be used from outside of the enrichment callbacks.
39+
40+
]]></format>
41+
</remarks>
2942
</Docs>
3043
<Members>
3144
<Member MemberName="AddCallback">
@@ -48,9 +61,9 @@
4861
<Parameter Name="callback" Type="System.Action&lt;System.Net.Http.Metrics.HttpMetricsEnrichmentContext&gt;" />
4962
</Parameters>
5063
<Docs>
51-
<param name="request">To be added.</param>
52-
<param name="callback">To be added.</param>
53-
<summary>To be added.</summary>
64+
<param name="request">The <see cref="T:System.Net.Http.HttpRequestMessage" /> to apply enrichment to.</param>
65+
<param name="callback">The callback responsible for adding custom tags via <see cref="M:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCustomTag(System.String,System.Object)" />.</param>
66+
<summary>Adds a callback to register custom tags for the <c>http.client.request.duration</c> metric.</summary>
5467
<remarks>To be added.</remarks>
5568
</Docs>
5669
</Member>
@@ -81,10 +94,10 @@
8194
</Parameter>
8295
</Parameters>
8396
<Docs>
84-
<param name="name">To be added.</param>
85-
<param name="value">To be added.</param>
86-
<summary>To be added.</summary>
87-
<remarks>To be added.</remarks>
97+
<param name="name">The name of the tag.</param>
98+
<param name="value">The value of the tag.</param>
99+
<summary>Appends a custom tag to the list of tags to be recorded with the <c>http.client.request.duration</c> metric.</summary>
100+
<remarks>This method must not be used from outside of the enrichment callbacks.</remarks>
88101
</Docs>
89102
</Member>
90103
<Member MemberName="Exception">
@@ -113,9 +126,9 @@
113126
<ReturnType>System.Exception</ReturnType>
114127
</ReturnValue>
115128
<Docs>
116-
<summary>To be added.</summary>
129+
<summary>Gets the exception that occurred, or <see langword="null" /> if there was no error.</summary>
117130
<value>To be added.</value>
118-
<remarks>To be added.</remarks>
131+
<remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
119132
</Docs>
120133
</Member>
121134
<Member MemberName="Request">
@@ -134,9 +147,9 @@
134147
<ReturnType>System.Net.Http.HttpRequestMessage</ReturnType>
135148
</ReturnValue>
136149
<Docs>
137-
<summary>To be added.</summary>
150+
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestMessage" /> that has been sent.</summary>
138151
<value>To be added.</value>
139-
<remarks>To be added.</remarks>
152+
<remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
140153
</Docs>
141154
</Member>
142155
<Member MemberName="Response">
@@ -165,9 +178,9 @@
165178
<ReturnType>System.Net.Http.HttpResponseMessage</ReturnType>
166179
</ReturnValue>
167180
<Docs>
168-
<summary>To be added.</summary>
181+
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestMessage" /> received from the server, or <see langword="null" /> if the request failed.</summary>
169182
<value>To be added.</value>
170-
<remarks>To be added.</remarks>
183+
<remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
171184
</Docs>
172185
</Member>
173186
</Members>

‎xml/System.Net.Http/HttpClientHandler.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -850,9 +850,9 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA
850850
<ReturnType>System.Diagnostics.Metrics.IMeterFactory</ReturnType>
851851
</ReturnValue>
852852
<Docs>
853-
<summary>To be added.</summary>
853+
<summary>Gets or sets the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" /> to create a custom <see cref="T:System.Diagnostics.Metrics.Meter" /> for the <see cref="T:System.Net.Http.HttpClientHandler" /> instance.</summary>
854854
<value>To be added.</value>
855-
<remarks>To be added.</remarks>
855+
<remarks>When <see cref="P:System.Net.Http.HttpClientHandler.MeterFactory" /> is set to a non-<see langword="null" /> value, all metrics emitted by the <see cref="T:System.Net.Http.HttpClientHandler" /> instance will be recorded using the <see cref="T:System.Diagnostics.Metrics.Meter" /> provided by the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" />.</remarks>
856856
</Docs>
857857
</Member>
858858
<Member MemberName="PreAuthenticate">

‎xml/System.Net.Http/HttpIOException.xml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
</Base>
1515
<Interfaces />
1616
<Docs>
17-
<summary>To be added.</summary>
17+
<summary>The exception that is thrown when an error occurs while reading the response.</summary>
1818
<remarks>To be added.</remarks>
1919
</Docs>
2020
<Members>
@@ -41,10 +41,10 @@
4141
<Parameter Name="innerException" Type="System.Exception" />
4242
</Parameters>
4343
<Docs>
44-
<param name="httpRequestError">To be added.</param>
45-
<param name="message">To be added.</param>
46-
<param name="innerException">To be added.</param>
47-
<summary>To be added.</summary>
44+
<param name="httpRequestError">The <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</param>
45+
<param name="message">The message string describing the error.</param>
46+
<param name="innerException">The exception that is the cause of the current exception.</param>
47+
<summary>Initializes a new instance of the <see cref="T:System.Net.Http.HttpIOException" /> class.</summary>
4848
<remarks>To be added.</remarks>
4949
</Docs>
5050
</Member>
@@ -64,7 +64,7 @@
6464
<ReturnType>System.Net.Http.HttpRequestError</ReturnType>
6565
</ReturnValue>
6666
<Docs>
67-
<summary>To be added.</summary>
67+
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</summary>
6868
<value>To be added.</value>
6969
<remarks>To be added.</remarks>
7070
</Docs>

‎xml/System.Net.Http/HttpMethod.xml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -599,10 +599,10 @@
599599
<Parameter Name="method" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="net-8.0" />
600600
</Parameters>
601601
<Docs>
602-
<param name="method">To be added.</param>
603-
<summary>To be added.</summary>
604-
<returns>To be added.</returns>
605-
<remarks>To be added.</remarks>
602+
<param name="method">The method to parse.</param>
603+
<summary>Parses the provided <paramref name="method" /> into an <see cref="T:System.Net.Http.HttpMethod" /> instance.</summary>
604+
<returns>An <see cref="T:System.Net.Http.HttpMethod" /> instance for the provided <paramref name="method" />.</returns>
605+
<remarks>This method may return a singleton instance for known methods; for example, it may return <see cref="P:System.Net.Http.HttpMethod.Get" /> if "GET" is specified. The parsing is performed in a case-insensitive manner, so it may also return <see cref="P:System.Net.Http.HttpMethod.Get" /> if "get" is specified. For unknown methods, a new <see cref="T:System.Net.Http.HttpMethod" /> instance is returned, with the same validation being performed as by the <see cref="M:System.Net.Http.HttpMethod.#ctor(System.String)" /> constructor.</remarks>
606606
</Docs>
607607
</Member>
608608
<Member MemberName="Patch">

‎xml/System.Net.Http/HttpRequestError.xml

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
<BaseTypeName>System.Enum</BaseTypeName>
1414
</Base>
1515
<Docs>
16-
<summary>To be added.</summary>
16+
<summary>Defines error categories representing the reason for <see cref="T:System.Net.Http.HttpRequestException" /> or <see cref="T:System.Net.Http.HttpIOException" />.</summary>
1717
<remarks>To be added.</remarks>
1818
</Docs>
1919
<Members>
@@ -34,7 +34,7 @@
3434
</ReturnValue>
3535
<MemberValue>11</MemberValue>
3636
<Docs>
37-
<summary>To be added.</summary>
37+
<summary>The response exceeded a pre-configured limit such as <see cref="P:System.Net.Http.HttpClient.MaxResponseContentBufferSize" /> or <see cref="P:System.Net.Http.HttpClientHandler.MaxResponseHeadersLength" />.</summary>
3838
</Docs>
3939
</Member>
4040
<Member MemberName="ConnectionError">
@@ -54,7 +54,7 @@
5454
</ReturnValue>
5555
<MemberValue>2</MemberValue>
5656
<Docs>
57-
<summary>To be added.</summary>
57+
<summary>A transport-level failure occurred while connecting to the remote endpoint.</summary>
5858
</Docs>
5959
</Member>
6060
<Member MemberName="ExtendedConnectNotSupported">
@@ -74,7 +74,7 @@
7474
</ReturnValue>
7575
<MemberValue>5</MemberValue>
7676
<Docs>
77-
<summary>To be added.</summary>
77+
<summary>Extended CONNECT for WebSockets over HTTP/2 is not supported by the peer.</summary>
7878
</Docs>
7979
</Member>
8080
<Member MemberName="HttpProtocolError">
@@ -94,7 +94,7 @@
9494
</ReturnValue>
9595
<MemberValue>4</MemberValue>
9696
<Docs>
97-
<summary>To be added.</summary>
97+
<summary>An HTTP/2 or HTTP/3 protocol error occurred.</summary>
9898
</Docs>
9999
</Member>
100100
<Member MemberName="InvalidResponse">
@@ -114,7 +114,7 @@
114114
</ReturnValue>
115115
<MemberValue>9</MemberValue>
116116
<Docs>
117-
<summary>To be added.</summary>
117+
<summary>An invalid or malformed response has been received.</summary>
118118
</Docs>
119119
</Member>
120120
<Member MemberName="NameResolutionError">
@@ -134,7 +134,7 @@
134134
</ReturnValue>
135135
<MemberValue>1</MemberValue>
136136
<Docs>
137-
<summary>To be added.</summary>
137+
<summary>The DNS name resolution failed.</summary>
138138
</Docs>
139139
</Member>
140140
<Member MemberName="ProxyTunnelError">
@@ -154,7 +154,7 @@
154154
</ReturnValue>
155155
<MemberValue>8</MemberValue>
156156
<Docs>
157-
<summary>To be added.</summary>
157+
<summary>An error occurred while establishing a connection to the proxy tunnel.</summary>
158158
</Docs>
159159
</Member>
160160
<Member MemberName="ResponseEnded">
@@ -174,7 +174,7 @@
174174
</ReturnValue>
175175
<MemberValue>10</MemberValue>
176176
<Docs>
177-
<summary>To be added.</summary>
177+
<summary>The response ended prematurely.</summary>
178178
</Docs>
179179
</Member>
180180
<Member MemberName="SecureConnectionError">
@@ -194,7 +194,7 @@
194194
</ReturnValue>
195195
<MemberValue>3</MemberValue>
196196
<Docs>
197-
<summary>To be added.</summary>
197+
<summary>An error occurred during the TLS handshake.</summary>
198198
</Docs>
199199
</Member>
200200
<Member MemberName="Unknown">
@@ -214,7 +214,7 @@
214214
</ReturnValue>
215215
<MemberValue>0</MemberValue>
216216
<Docs>
217-
<summary>To be added.</summary>
217+
<summary>A generic or unknown error occurred.</summary>
218218
</Docs>
219219
</Member>
220220
<Member MemberName="UserAuthenticationError">
@@ -234,7 +234,7 @@
234234
</ReturnValue>
235235
<MemberValue>7</MemberValue>
236236
<Docs>
237-
<summary>To be added.</summary>
237+
<summary>The authentication failed.</summary>
238238
</Docs>
239239
</Member>
240240
<Member MemberName="VersionNegotiationError">
@@ -254,7 +254,7 @@
254254
</ReturnValue>
255255
<MemberValue>6</MemberValue>
256256
<Docs>
257-
<summary>To be added.</summary>
257+
<summary>Cannot negotiate the HTTP version requested.</summary>
258258
</Docs>
259259
</Member>
260260
</Members>

‎xml/System.Net.Http/HttpRequestException.xml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -222,11 +222,11 @@
222222
<Parameter Name="statusCode" Type="System.Nullable&lt;System.Net.HttpStatusCode&gt;" Index="3" FrameworkAlternate="net-8.0" />
223223
</Parameters>
224224
<Docs>
225-
<param name="httpRequestError">To be added.</param>
226-
<param name="message">To be added.</param>
227-
<param name="inner">To be added.</param>
228-
<param name="statusCode">To be added.</param>
229-
<summary>To be added.</summary>
225+
<param name="httpRequestError">The <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" /> that caused the exception.</param>
226+
<param name="message">A message that describes the current exception.</param>
227+
<param name="inner">The inner exception.</param>
228+
<param name="statusCode">The HTTP status code.</param>
229+
<summary>Initializes a new instance of the <see cref="T:System.Net.Http.HttpRequestException" /> class with a specific message an inner exception, and an HTTP status code and an <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" />.</summary>
230230
<remarks>To be added.</remarks>
231231
</Docs>
232232
</Member>
@@ -249,7 +249,7 @@
249249
<ReturnType>System.Net.Http.HttpRequestError</ReturnType>
250250
</ReturnValue>
251251
<Docs>
252-
<summary>To be added.</summary>
252+
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</summary>
253253
<value>To be added.</value>
254254
<remarks>To be added.</remarks>
255255
</Docs>

‎xml/System.Net.Http/HttpRequestOptions.xml

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -845,10 +845,12 @@ This member is an explicit interface member implementation. It can be used only
845845
<Parameter Name="value" Type="System.Object" RefType="out" Index="1" FrameworkAlternate="net-8.0" />
846846
</Parameters>
847847
<Docs>
848-
<param name="key">To be added.</param>
849-
<param name="value">To be added.</param>
850-
<summary>To be added.</summary>
851-
<returns>To be added.</returns>
848+
<param name="key">The key to locate.</param>
849+
<param name="value">When this method returns, contains the value associated with the specified key, if the key is found; otherwise, the default value for the type of the <paramref name="value" /> parameter. This parameter is passed uninitialized.</param>
850+
<summary>Gets the value that is associated with the specified key.</summary>
851+
<returns><see langword="true" /> if the <see cref="T:System.Net.Http.HttpRequestOptions"/> instance contains an element with the specified key; otherwise, <see langword="false" />.</returns>
852+
853+
852854
<remarks>To be added.</remarks>
853855
</Docs>
854856
</Member>

‎xml/System.Net.Http/SocketsHttpHandler.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -766,9 +766,9 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
766766
<ReturnType>System.Diagnostics.Metrics.IMeterFactory</ReturnType>
767767
</ReturnValue>
768768
<Docs>
769-
<summary>To be added.</summary>
769+
<summary>Gets or sets the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" /> to create a custom <see cref="T:System.Diagnostics.Metrics.Meter" /> for the <see cref="T:System.Net.Http.SocketsHttpHandler" /> instance.</summary>
770770
<value>To be added.</value>
771-
<remarks>To be added.</remarks>
771+
<remarks>When <see cref="P:System.Net.Http.SocketsHttpHandler.MeterFactory" /> is set to a non-<see langword="null" /> value, all metrics emitted by the <see cref="T:System.Net.Http.SocketsHttpHandler" /> instance will be recorded using the <see cref="T:System.Diagnostics.Metrics.Meter" /> provided by the <see cref="T:System.Diagnostics.Metrics.IMeterFactory" />.</remarks>
772772
</Docs>
773773
</Member>
774774
<Member MemberName="PlaintextStreamFilter">

‎xml/ns-System.Net.Http.Metrics.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
<Namespace Name="System.Net.Http.Metrics">
22
<Docs>
3-
<summary>To be added.</summary>
3+
<summary>Provides additional APIs for advanced metrics use-cases.</summary>
44
<remarks>To be added.</remarks>
55
</Docs>
66
</Namespace>

0 commit comments

Comments
 (0)