Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Port System.Net.Http docs for HttpRequestError and metrics additions #9305

Merged
merged 8 commits into from
Sep 18, 2023
Merged

Port System.Net.Http docs for HttpRequestError and metrics additions #9305

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d7820ee
HTTP: docs for HttpRequestError and metrics additions
antonfirsov Sep 18, 2023
bba3fa5
add namespace docs
antonfirsov Sep 18, 2023
2795e6c
Apply suggestions from code review
carlossanlop Sep 18, 2023
311529c
inheritdoc is stupid
antonfirsov Sep 18, 2023
dac4379
Merge branch 'http-8.0-1' of https://github.com/antonfirsov/dotnet-ap…
antonfirsov Sep 18, 2023
01434c9
Apply suggestions from code review
antonfirsov Sep 18, 2023
1fa5632
Fix invalid xref
carlossanlop Sep 18, 2023
6f0991e
missing <returns>
carlossanlop Sep 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 18 additions & 15 deletions xml/System.Net.Http.Metrics/HttpMetricsEnrichmentContext.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,11 @@
</Attribute>
</Attributes>
<Docs>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<summary>Provides functionality for enriching the `http.client.request.duration` metric.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>Enrichment is done on per-request basis by callbacks registered with <see cref="M:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCallback(System.Net.Http.HttpRequestMessage,System.Action{System.Net.Http.Metrics.HttpMetricsEnrichmentContext})" />.
The callbacks are responsible for adding custom tags via <see cref="M:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCustomTag(System.String,System.Object)" /> for which they can use the request, response and error information exposed on the <see cref="T:System.Net.Http.Metrics.HttpMetricsEnrichmentContext" /> instance.

&gt; [!IMPORTANT] &gt; The <see cref="T:System.Net.Http.Metrics.HttpMetricsEnrichmentContext" /> intance must not be used from outside of the enrichment callbacks.</remarks>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
</Docs>
<Members>
<Member MemberName="AddCallback">
Expand All @@ -48,9 +51,9 @@
<Parameter Name="callback" Type="System.Action&lt;System.Net.Http.Metrics.HttpMetricsEnrichmentContext&gt;" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<param name="callback">To be added.</param>
<summary>To be added.</summary>
<param name="request">The <see cref="T:System.Net.Http.HttpRequestMessage" /> to apply enrichment to.</param>
<param name="callback">The callback responsible to add custom tags via <see cref="M:System.Net.Http.Metrics.HttpMetricsEnrichmentContext.AddCustomTag(System.String,System.Object)" />.</param>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<summary>Adds a callback to register custom tags for the `http.client.request.duration` metric.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -81,10 +84,10 @@
</Parameter>
</Parameters>
<Docs>
<param name="name">To be added.</param>
<param name="value">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="name">The name of the tag.</param>
<param name="value">The value of the tag.</param>
<summary>Appends a custom tag to the list of tags to be recorded with the `http.client.request.duration` metric..</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>This method must not be used from outside of the enrichment callbacks.</remarks>
</Docs>
</Member>
<Member MemberName="Exception">
Expand Down Expand Up @@ -113,9 +116,9 @@
<ReturnType>System.Exception</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the exception that occurred or <see langword="null" /> if there was no error.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
</Docs>
</Member>
<Member MemberName="Request">
Expand All @@ -134,9 +137,9 @@
<ReturnType>System.Net.Http.HttpRequestMessage</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestMessage" /> that has been sent.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
</Docs>
</Member>
<Member MemberName="Response">
Expand Down Expand Up @@ -165,9 +168,9 @@
<ReturnType>System.Net.Http.HttpResponseMessage</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestMessage" /> received from the server or <see langword="null" /> if the request failed.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<value>To be added.</value>
<remarks>To be added.</remarks>
<remarks>This property must not be used from outside of the enrichment callbacks.</remarks>
</Docs>
</Member>
</Members>
Expand Down
4 changes: 2 additions & 2 deletions xml/System.Net.Http/HttpClientHandler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -850,9 +850,9 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA
<ReturnType>System.Diagnostics.Metrics.IMeterFactory</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<value>To be added.</value>
<remarks>To be added.</remarks>
<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>
</Docs>
</Member>
<Member MemberName="PreAuthenticate">
Expand Down
12 changes: 6 additions & 6 deletions xml/System.Net.Http/HttpIOException.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
</Base>
<Interfaces />
<Docs>
<summary>To be added.</summary>
<summary>An exception thrown when an error occurs while reading the response.</summary>
antonfirsov marked this conversation as resolved.
Show resolved Hide resolved
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -41,10 +41,10 @@
<Parameter Name="innerException" Type="System.Exception" />
</Parameters>
<Docs>
<param name="httpRequestError">To be added.</param>
<param name="message">To be added.</param>
<param name="innerException">To be added.</param>
<summary>To be added.</summary>
<param name="httpRequestError">The <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</param>
<param name="message">The message string describing the error.</param>
<param name="innerException">The exception that is the cause of the current exception.</param>
<summary>Initializes a new instance of the <see cref="T:System.Net.Http.HttpIOException" /> class.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -64,7 +64,7 @@
<ReturnType>System.Net.Http.HttpRequestError</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
8 changes: 4 additions & 4 deletions xml/System.Net.Http/HttpMethod.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -599,10 +599,10 @@
<Parameter Name="method" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="net-8.0" />
</Parameters>
<Docs>
<param name="method">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="method">The method to parse.</param>
<summary>Parses the provided <paramref name="method" /> into an <see cref="T:System.Net.Http.HttpMethod" /> instance.</summary>
<returns>An <see cref="T:System.Net.Http.HttpMethod" /> instance for the provided <paramref name="method" />.</returns>
<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>
</Docs>
</Member>
<Member MemberName="Patch">
Expand Down
26 changes: 13 additions & 13 deletions xml/System.Net.Http/HttpRequestError.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
<BaseTypeName>System.Enum</BaseTypeName>
</Base>
<Docs>
<summary>To be added.</summary>
<summary>Defines error categories representing the reason for <see cref="T:System.Net.Http.HttpRequestException" /> or <see cref="T:System.Net.Http.HttpIOException" />.</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
Expand All @@ -34,7 +34,7 @@
</ReturnValue>
<MemberValue>11</MemberValue>
<Docs>
<summary>To be added.</summary>
<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>
</Docs>
</Member>
<Member MemberName="ConnectionError">
Expand All @@ -54,7 +54,7 @@
</ReturnValue>
<MemberValue>2</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>A transport-level failure occurred while connecting to the remote endpoint.</summary>
</Docs>
</Member>
<Member MemberName="ExtendedConnectNotSupported">
Expand All @@ -74,7 +74,7 @@
</ReturnValue>
<MemberValue>5</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Extended CONNECT for WebSockets over HTTP/2 is not supported by the peer.</summary>
</Docs>
</Member>
<Member MemberName="HttpProtocolError">
Expand All @@ -94,7 +94,7 @@
</ReturnValue>
<MemberValue>4</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>An HTTP/2 or HTTP/3 protocol error occurred.</summary>
</Docs>
</Member>
<Member MemberName="InvalidResponse">
Expand All @@ -114,7 +114,7 @@
</ReturnValue>
<MemberValue>9</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>An invalid or malformed response has been received.</summary>
</Docs>
</Member>
<Member MemberName="NameResolutionError">
Expand All @@ -134,7 +134,7 @@
</ReturnValue>
<MemberValue>1</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The DNS name resolution failed.</summary>
</Docs>
</Member>
<Member MemberName="ProxyTunnelError">
Expand All @@ -154,7 +154,7 @@
</ReturnValue>
<MemberValue>8</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>An error occurred while establishing a connection to the proxy tunnel.</summary>
</Docs>
</Member>
<Member MemberName="ResponseEnded">
Expand All @@ -174,7 +174,7 @@
</ReturnValue>
<MemberValue>10</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The response ended prematurely.</summary>
</Docs>
</Member>
<Member MemberName="SecureConnectionError">
Expand All @@ -194,7 +194,7 @@
</ReturnValue>
<MemberValue>3</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>An error occurred during the TLS handshake.</summary>
</Docs>
</Member>
<Member MemberName="Unknown">
Expand All @@ -214,7 +214,7 @@
</ReturnValue>
<MemberValue>0</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>A generic or unknown error occurred.</summary>
</Docs>
</Member>
<Member MemberName="UserAuthenticationError">
Expand All @@ -234,7 +234,7 @@
</ReturnValue>
<MemberValue>7</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>The authentication failed.</summary>
</Docs>
</Member>
<Member MemberName="VersionNegotiationError">
Expand All @@ -254,7 +254,7 @@
</ReturnValue>
<MemberValue>6</MemberValue>
<Docs>
<summary>To be added.</summary>
<summary>Cannot negotiate the HTTP Version requested.</summary>
antonfirsov marked this conversation as resolved.
Show resolved Hide resolved
</Docs>
</Member>
</Members>
Expand Down
12 changes: 6 additions & 6 deletions xml/System.Net.Http/HttpRequestException.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,11 +222,11 @@
<Parameter Name="statusCode" Type="System.Nullable&lt;System.Net.HttpStatusCode&gt;" Index="3" FrameworkAlternate="net-8.0" />
</Parameters>
<Docs>
<param name="httpRequestError">To be added.</param>
<param name="message">To be added.</param>
<param name="inner">To be added.</param>
<param name="statusCode">To be added.</param>
<summary>To be added.</summary>
<param name="httpRequestError">The <see cref="P:System.Net.Http.HttpRequestException.HttpRequestError" /> that caused the exception.</param>
<param name="message">A message that describes the current exception.</param>
<param name="inner">The inner exception.</param>
<param name="statusCode">The HTTP status code.</param>
<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>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -249,7 +249,7 @@
<ReturnType>System.Net.Http.HttpRequestError</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<summary>Gets the <see cref="T:System.Net.Http.HttpRequestError" /> that caused the exception.</summary>
<value>To be added.</value>
<remarks>To be added.</remarks>
</Docs>
Expand Down
1 change: 1 addition & 0 deletions xml/System.Net.Http/HttpRequestOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -850,6 +850,7 @@ This member is an explicit interface member implementation. It can be used only
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<inheritdoc />
</Docs>
</Member>
<Member MemberName="System.Collections.Generic.IReadOnlyDictionary&lt;System.String,System.Object&gt;.Values">
Expand Down
4 changes: 2 additions & 2 deletions xml/System.Net.Http/SocketsHttpHandler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -766,9 +766,9 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
<ReturnType>System.Diagnostics.Metrics.IMeterFactory</ReturnType>
</ReturnValue>
<Docs>
<summary>To be added.</summary>
<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>
<value>To be added.</value>
<remarks>To be added.</remarks>
<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>
</Docs>
</Member>
<Member MemberName="PlaintextStreamFilter">
Expand Down
2 changes: 1 addition & 1 deletion xml/ns-System.Net.Http.Metrics.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<Namespace Name="System.Net.Http.Metrics">
<Docs>
<summary>To be added.</summary>
<summary>Provides additional API-s for advanced metrics use-cases.</summary>
carlossanlop marked this conversation as resolved.
Show resolved Hide resolved
<remarks>To be added.</remarks>
</Docs>
</Namespace>