8000 HttpClient sync operations by aik-jahoda · Pull Request #4776 · dotnet/dotnet-api-docs · GitHub
[go: up one dir, main page]
Skip to content

HttpClient sync operations #4776

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

Merged
merged 20 commits into from
Sep 22, 2020
Merged

HttpClient sync operations #4776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
77399c7
Draft for @manickap
Sep 2, 2020
680ef84
Apply suggestions from code review
aik-jahoda Sep 3, 2020
e34b691
Format verification
Sep 3, 2020
9efb1cf
Format verification
Sep 3, 2020
d89511d
Fix links
Sep 8, 2020
9aad677
Fix links
Sep 8, 2020
0b92a0b
Fix xml tag
Sep 8, 2020
87515ae
Fix links
Sep 9, 2020
fd0792f
Fix links
Sep 11, 2020
cc123b3
Fix links
Sep 11, 2020
312f0f6
Apply suggestions from code review
aik-jahoda Sep 11, 2020
8cb69c4
Fix links
Sep 14, 2020
e3b69dd
Add CreateContentReadStream
Sep 14, 2020
699d465
Fix links
Sep 14, 2020
4188305
Add System.Net.Http.DelegatingHandler.Send
Sep 14, 2020
367674f 8000
Fix links
Sep 14, 2020
7d65351
Apply suggestions from code review
aik-jahoda Sep 21, 2020
ced8bab
Remove "Synchronous" information from summary
Sep 21, 2020
898def7
Apply suggestions from code review
aik-jahoda Sep 22, 2020
71a5890
Fix the exception description
Sep 22, 2020
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
32 changes: 23 additions & 9 deletions xml/System.Net.Http/ByteArrayContent.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,10 +156,17 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
<summary>Creates an HTTP content stream for reading. It uses the memory from the <see cref="T:System.Net.Http.ByteArrayContent" /> as a backing store.</summary>
<returns>The HTTP content stream.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until all of the content stream has been created.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="CreateContentReadStreamAsync">
Expand Down Expand Up @@ -226,11 +233,18 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="stream">To be added.</param>
<param name="context">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="stream">The target stream.</param>
<param name="context">Optional information about the transport, like the channel binding token. This parameter can be <see langword="null" />.</param>
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
<summary>Serializes and writes the byte array provided in the constructor to an HTTP content stream.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the whole byte array has been written to `stream` or until `cancellationToken` cancels the operation.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="SerializeToStreamAsync">
Expand Down
19 changes: 14 additions & 5 deletions xml/System.Net.Http/DelegatingHandler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,11 +221,20 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="request">The HTTP request message to send to the server.</param>
<param name="cancellationToken">A cancellation token to cancel operation.</param>
<summary>Sends an HTTP request to the inner handler to send to the server.</summary>
<returns>An HTTP response message.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the entire response, including content, is read.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not true, handlers do not buffer response content.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@carlossanlop some of your team mentioned that we don't explicitly note the method is synchronous. What about remove sentence like "This operation blocks until the entire response, including content, is read." from all remarks?

Copy link
8000
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed via chat, you can remove the sentence.


The <xref:System.Net.Http.DelegatingHandler.Send%2A> method is mainly used by the system and not by applications. When this method is called, it calls the <xref:System.Net.Http.DelegatingHandler.Send%2A> method on the inner handler.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="SendAsync">
Expand Down
132 changes: 112 additions & 20 deletions xml/System.Net.Http/HttpClient.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2686,10 +2686,31 @@ The <paramref name="requestUri" /> is not an absolute URI.
<Parameter Name="request" Type="System.Net.Http.HttpRequestMessage" Index="0" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="request">The HTTP request message to send.</param>
<summary>Sends an HTTP request with the specified request.</summary>
<returns>An HTTP response message.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the entire response, including content, is read.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">The HTTP version is 2.0 or higher or the version policy is set to <see cref="F:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher" />.

-or-

The custom class derived from <see cref="T:System.Net.Http.HttpContent" /> does not override the <see cref="M:System.Net.Http.HttpContent.SerializeToStream(System.IO.Stream,System.Net.TransportContext,System.Threading.CancellationToken)" /> method.

-or-

The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
<exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
<exception cref="T:System.Threading.Tasks.TaskCanceledException">If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
</Member>
<Member MemberName="Send">
Expand All @@ -2715,11 +2736,32 @@ The <paramref name="requestUri" /> is not an absolute URI.
<Parameter Name="completionOption" Type="System.Net.Http.HttpCompletionOption" Index="1" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<param name="completionOption">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="request">The HTTP request message to send.</param>
<param name="completionOption">One of the enumeration values that specifies when the operation should complete (as soon as a response is available or after reading the response content).</param>
<summary>Sends an HTTP request.</summary>
<returns>The HTTP response message.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the entire response, including content, is read.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not true for completionOption == ResponseHeadersRead. If it's specified, it blocks only the request sending and response headers reading, not the response content reading.
If the ResponseContentRead is used the remark holds, it blocks till the response content is read.


]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">The HTTP version is 2.0 or higher or the version policy is set to <see cref="F:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher" />.

-or-

The custom class derived from <see cref="T:System.Net.Http.HttpContent" /> does not override the <see cref="M:System.Net.Http.HttpContent.SerializeToStream(System.IO.Stream,System.Net.TransportContext,System.Threading.CancellationToken)" /> method.

-or-

The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
<exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
<exception cref="T:System.Threading.Tasks.TaskCanceledException">If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
</Member>
<Member MemberName="Send">
Expand All @@ -2745,11 +2787,36 @@ The <paramref name="requestUri" /> is not an absolute URI.
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="request">The HTTP request message to send.</param>
<param name="cancellationToken">The token to cancel the operation.</param>
<summary>Sends an HTTP request with the specified request and cancellation token.</summary>
<returns>The HTTP response message.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the entire response, including content, is read or `cancellationToken` cancels the operation.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">The HTTP version is 2.0 or higher or the version policy is set to <see cref="F:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher" />.

-or-

The custom class derived from <see cref="T:System.Net.Http.HttpContent" /> does not override the <see cref="M:System.Net.Http.HttpContent.SerializeToStream(System.IO.Stream,System.Net.TransportContext,System.Threading.CancellationToken)" /> method.

-or-

The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
<exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
<exception cref="T:System.Threading.Tasks.TaskCanceledException">The request was canceled.

-or-

If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
</Member>
<Member MemberName="Send">
Expand All @@ -2776,12 +2843,37 @@ The <paramref name="requestUri" /> is not an absolute URI.
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<param name="completionOption">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="request">The HTTP request message to send.</param>
<param name="completionOption">One of the enumeration values that specifies when the operation should complete (as soon as a response is available or after reading the response content).</param>
<param name="cancellationToken">The token to cancel the operation.</param>
<summary>Sends an HTTP request with the specified request, completion option and cancellation token.</summary>
<returns>The HTTP response message.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the entire response, including content, is read or `cancellationToken` cancels the operation.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The same as above, depends on the completionOption.


]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">The HTTP version is 2.0 or higher or the version policy is set to <see cref="F:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher" />.

-or-

The custom class derived from <see cref="T:System.Net.Http.HttpContent" /> does not override the <see cref="M:System.Net.Http.HttpContent.SerializeToStream(System.IO.Stream,System.Net.TransportContext,System.Threading.CancellationToken)" /> method.

-or-

The custom <see cref="T:System.Net.Http.HttpMessageHandler" /> does not override the <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
<exception cref="T:System.Net.Http.HttpRequestException">The request failed due to an underlying issue such as network connectivity, DNS failure, or server certificate validation.</exception>
<exception cref="T:System.Threading.Tasks.TaskCanceledException">The request was canceled.

-or-

If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
</Member>
<MemberGroup MemberName="SendAsync">
Expand Down
33 changes: 28 additions & 5 deletions xml/System.Net.Http/HttpClientHandler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -828,11 +828,34 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="request">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="request">The HTTP request message.</param>
<param name="cancellationToken">A cancellation token to cancel the operation.</param>
<summary>Creates an instance of <see cref="T:System.Net.Http.HttpResponseMessage" /> based on the information provided in the <see cref="T:System.Net.Http.HttpRequestMessage" />.</summary>
<returns>The HTTP response message.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until the response message is read.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> was <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">For HTTP/2 and higher or when requesting version upgrade is enabled by <see cref="F:System.Net.Http.HttpVersionPolicy.RequestVersionOrHigher" />.

-or-

If using custom class derived from <see cref="T:System.Net.Http.HttpContent" /> not overriding <see cref="M:System.Net.Http.HttpContent.SerializeToStream(System.IO.Stream,System.Net.TransportContext,System.Threading.CancellationToken)" /> method.

-or-

If using custom <see cref="T:System.Net.Http.HttpMessageHandler" /> not overriding <see cref="M:System.Net.Http.HttpMessageHandler.Send(System.Net.Http.HttpRequestMessage,System.Threading.CancellationToken)" /> method.</exception>
<exception cref="T:System.Threading.Tasks.TaskCanceledException">The request was canceled.

-or-

If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
The request failed due to timeout.</exception>
</Docs>
</Member>
<Member MemberName="SendAsync">
Expand Down
64 changes: 47 additions & 17 deletions xml/System.Net.Http/HttpContent.xml
View file
Open in desktop
EED3
Original file line number Diff line number Diff line change
Expand Up @@ -88,11 +88,19 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="stream">To be added.</param>
<param name="context">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="stream">The target stream.</param>
<param name="context">Information about the transport (for example, the channel binding token). This parameter may be <see langword="null" />.</param>
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
<summary>Serializes the HTTP content into a stream of bytes and copies it to <paramref name="stream" />.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until all of the content is written to the stream object.

]]></format>
</remarks>
<exception cref="T:System.ArgumentNullException">The <paramref name="stream" /> was <see langword="null" />.</exception>
</Docs>
</Member>
<MemberGroup MemberName="CopyToAsync">
Expand Down Expand Up @@ -737,9 +745,16 @@
</ReturnValue>
<Parameters />
<Docs>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<summary>Serializes the HTTP content and returns a stream that represents the content.</summary>
<returns>The stream that represents the HTTP content.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until all of the stream that represents content has been read.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="ReadAsStream">
Expand All @@ -764,10 +779,17 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<remarks>To be added.</remarks>
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
<summary>Serializes the HTTP content and returns a stream that represents the content.</summary>
<returns>The stream that represents the HTTP content.</returns>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until all of the stream that represents content has been read.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="ReadAsStreamAsync">
Expand Down Expand Up @@ -964,11 +986,19 @@
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
</Parameters>
<Docs>
<param name="stream">To be added.</param>
<param name="context">To be added.</param>
<param name="cancellationToken">To be added.</param>
<summary>To be added.</summary>
<remarks>To be added.</remarks>
<param name="stream">The target stream.</param>
<param name="context">Information about the transport (for example, the channel binding token). This parameter may be <see langword="null" />.</param>
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
<summary>When overridden in a derived class, serializes the HTTP content to a stream. Otherwise, throws a <see cref="T:System.NotImplementedException" />.</summary>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Throws NotSupportedException.

<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This operation blocks until all of the content has been serialized to the stream object.

]]></format>
</remarks>
<exception cref="T:System.NotImplementedException">The method is not overridden in the derived class.</exception>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Throws NotSupportedException

</Docs>
</Member>
<Member MemberName="SerializeToStreamAsync">
Expand Down
Loading
0