Skip to content

Commit 3cc1ed8

Browse files
Jan JahodaJan JahodaManickaPcarlossanlopgewarren
committed
HttpClient sync operations (dotnet#4776)
* Draft for @ManickaP * Apply suggestions from code review Co-authored-by: Marie Píchová <[email protected]> * Format verification * Format verification * Fix links * Fix links * Fix xml tag * Fix links * Fix links * Fix links * Apply suggestions from code review Co-authored-by: Carlos Sanchez <[email protected]> * Fix links * Add CreateContentReadStream * Fix links * Add System.Net.Http.DelegatingHandler.Send * Fix links * Apply suggestions from code review Co-authored-by: Carlos Sanchez <[email protected]> * Remove "Synchronous" information from summary * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: Carlos Sanchez <[email protected]> * Fix the exception description Co-authored-by: Jan Jahoda <[email protected]> Co-authored-by: Marie Píchová <[email protected]> Co-authored-by: Carlos Sanchez <[email protected]> Co-authored-by: Genevieve Warren <[email protected]>
1 parent 286066b commit 3cc1ed8

12 files changed

+340
-97
lines changed

‎xml/System.Net.Http/ByteArrayContent.xml

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -156,10 +156,17 @@
156156
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="net-5.0" />
157157
</Parameters>
158158
<Docs>
159-
<param name="cancellationToken">To be added.</param>
160-
<summary>To be added.</summary>
161-
<returns>To be added.</returns>
162-
<remarks>To be added.</remarks>
159+
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
160+
<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>
161+
<returns>The HTTP content stream.</returns>
162+
<remarks>
163+
<format type="text/markdown"><![CDATA[
164+
165+
## Remarks
166+
This operation blocks until all of the content stream has been created.
167+
168+
]]></format>
169+
</remarks>
163170
</Docs>
164171
</Member>
165172
<Member MemberName="CreateContentReadStreamAsync">
@@ -226,11 +233,18 @@
226233
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
227234
</Parameters>
228235
<Docs>
229-
<param name="stream">To be added.</param>
230-
<param name="context">To be added.</param>
231-
<param name="cancellationToken">To be added.</param>
232-
<summary>To be added.</summary>
233-
<remarks>To be added.</remarks>
236+
<param name="stream">The target stream.</param>
237+
<param name="context">Optional information about the transport, like the channel binding token. This parameter can be <see langword="null" />.</param>
238+
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
239+
<summary>Serializes and writes the byte array provided in the constructor to an HTTP content stream.</summary>
240+
<remarks>
241+
<format type="text/markdown"><![CDATA[
242+
243+
## Remarks
244+
This operation blocks until the whole byte array has been written to `stream` or until `cancellationToken` cancels the operation.
245+
246+
]]></format>
247+
</remarks>
234248
</Docs>
235249
</Member>
236250
<Member MemberName="SerializeToStreamAsync">

‎xml/System.Net.Http/DelegatingHandler.xml

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -221,11 +221,20 @@
221221
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0" />
222222
</Parameters>
223223
<Docs>
224-
<param name="request">To be added.</param>
225-
<param name="cancellationToken">To be added.</param>
226-
<summary>To be added.</summary>
227-
<returns>To be added.</returns>
228-
<remarks>To be added.</remarks>
224+
<param name="request">The HTTP request message to send to the server.</param>
225+
<param name="cancellationToken">A cancellation token to cancel operation.</param>
226+
<summary>Sends an HTTP request to the inner handler to send to the server.</summary>
227+
<returns>An HTTP response message.</returns>
228+
<remarks>
229+
<format type="text/markdown"><![CDATA[
230+
231+
## Remarks
232+
This operation blocks until the entire response, including content, is read.
233+
234+
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.
235+
236+
]]></format>
237+
</remarks>
229238
</Docs>
230239
</Member>
231240
<Member MemberName="SendAsync">

‎xml/System.Net.Http/HttpClient.xml

Lines changed: 112 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2692,10 +2692,31 @@ The <paramref name="requestUri" /> is not an absolute URI.
26922692
<Parameter Name="request" Type="System.Net.Http.HttpRequestMessage" Index="0" FrameworkAlternate="net-5.0" />
26932693
</Parameters>
26942694
<Docs>
2695-
<param name="request">To be added.</param>
2696-
<summary>To be added.</summary>
2697-
<returns>To be added.</returns>
2698-
<remarks>To be added.</remarks>
2695+
<param name="request">The HTTP request message to send.</param>
2696+
<summary>Sends an HTTP request with the specified request.</summary>
2697+
<returns>An HTTP response message.</returns>
2698+
<remarks>
2699+
<format type="text/markdown"><![CDATA[
2700+
2701+
## Remarks
2702+
This operation blocks until the entire response, including content, is read.
2703+
2704+
]]></format>
2705+
</remarks>
2706+
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
2707+
<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" />.
2708+
2709+
-or-
2710+
2711+
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.
2712+
2713+
-or-
2714+
2715+
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>
2716+
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
2717+
<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>
2718+
<exception cref="T:System.Threading.Tasks.TaskCanceledException">If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
2719+
The request failed due to timeout.</exception>
26992720
</Docs>
27002721
</Member>
27012722
<Member MemberName="Send">
@@ -2721,11 +2742,32 @@ The <paramref name="requestUri" /> is not an absolute URI.
27212742
<Parameter Name="completionOption" Type="System.Net.Http.HttpCompletionOption" Index="1" FrameworkAlternate="net-5.0" />
27222743
</Parameters>
27232744
<Docs>
2724-
<param name="request">To be added.</param>
2725-
<param name="completionOption">To be added.</param>
2726-
<summary>To be added.</summary>
2727-
<returns>To be added.</returns>
2728-
<remarks>To be added.</remarks>
2745+
<param name="request">The HTTP request message to send.</param>
2746+
<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>
2747+
<summary>Sends an HTTP request.</summary>
2748+
<returns>The HTTP response message.</returns>
2749+
<remarks>
2750+
<format type="text/markdown"><![CDATA[
2751+
2752+
## Remarks
2753+
This operation blocks until the entire response, including content, is read.
2754+
2755+
]]></format>
2756+
</remarks>
2757+
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
2758+
<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" />.
2759+
2760+
-or-
2761+
2762+
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.
2763+
2764+
-or-
2765+
2766+
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>
2767+
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
2768+
<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>
2769+
<exception cref="T:System.Threading.Tasks.TaskCanceledException">If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
2770+
The request failed due to timeout.</exception>
27292771
</Docs>
27302772
</Member>
27312773
<Member MemberName="Send">
@@ -2751,11 +2793,36 @@ The <paramref name="requestUri" /> is not an absolute URI.
27512793
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0" />
27522794
</Parameters>
27532795
<Docs>
2754-
<param name="request">To be added.</param>
2755-
<param name="cancellationToken">To be added.</param>
2756-
<summary>To be added.</summary>
2757-
<returns>To be added.</returns>
2758-
<remarks>To be added.</remarks>
2796+
<param name="request">The HTTP request message to send.</param>
2797+
<param name="cancellationToken">The token to cancel the operation.</param>
2798+
<summary>Sends an HTTP request with the specified request and cancellation token.</summary>
2799+
<returns>The HTTP response message.</returns>
2800+
<remarks>
2801+
<format type="text/markdown"><![CDATA[
2802+
2803+
## Remarks
2804+
This operation blocks until the entire response, including content, is read or `cancellationToken` cancels the operation.
2805+
2806+
]]></format>
2807+
</remarks>
2808+
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
2809+
<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" />.
2810+
2811+
-or-
2812+
2813+
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.
2814+
2815+
-or-
2816+
2817+
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>
2818+
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
2819+
<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>
2820+
<exception cref="T:System.Threading.Tasks.TaskCanceledException">The request was canceled.
2821+
2822+
-or-
2823+
2824+
If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
2825+
The request failed due to timeout.</exception>
27592826
</Docs>
27602827
</Member>
27612828
<Member MemberName="Send">
@@ -2782,12 +2849,37 @@ The <paramref name="requestUri" /> is not an absolute URI.
27822849
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
27832850
</Parameters>
27842851
<Docs>
2785-
<param name="request">To be added.</param>
2786-
<param name="completionOption">To be added.</param>
2787-
<param name="cancellationToken">To be added.</param>
2788-
<summary>To be added.</summary>
2789-
<returns>To be added.</returns>
2790-
<remarks>To be added.</remarks>
2852+
<param name="request">The HTTP request message to send.</param>
2853+
<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>
2854+
<param name="cancellationToken">The token to cancel the operation.</param>
2855+
<summary>Sends an HTTP request with the specified request, completion option and cancellation token.</summary>
2856+
<returns>The HTTP response message.</returns>
2857+
<remarks>
2858+
<format type="text/markdown"><![CDATA[
2859+
2860+
## Remarks
2861+
This operation blocks until the entire response, including content, is read or `cancellationToken` cancels the operation.
2862+
2863+
]]></format>
2864+
</remarks>
2865+
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> is <see langword="null" />.</exception>
2866+
<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" />.
2867+
2868+
-or-
2869+
2870+
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.
2871+
2872+
-or-
2873+
2874+
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>
2875+
<exception cref="T:System.InvalidOperationException">The request message was already sent by the <see cref="T:System.Net.Http.HttpClient" /> instance.</exception>
2876+
<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>
2877+
<exception cref="T:System.Threading.Tasks.TaskCanceledException">The request was canceled.
2878+
2879+
-or-
2880+
2881+
If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
2882+
The request failed due to timeout.</exception>
27912883
</Docs>
27922884
</Member>
27932885
<MemberGroup MemberName="SendAsync">

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

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -862,11 +862,34 @@ handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousA
862862
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="net-5.0" />
863863
</Parameters>
864864
<Docs>
865-
<param name="request">To be added.</param>
866-
<param name="cancellationToken">To be added.</param>
867-
<summary>To be added.</summary>
868-
<returns>To be added.</returns>
869-
<remarks>To be added.</remarks>
865+
<param name="request">The HTTP request message.</param>
866+
<param name="cancellationToken">A cancellation token to cancel the operation.</param>
867+
<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>
868+
<returns>The HTTP response message.</returns>
869+
<remarks>
870+
<format type="text/markdown"><![CDATA[
871+
872+
## Remarks
873+
This operation blocks until the response message is read.
874+
875+
]]></format>
876+
</remarks>
877+
<exception cref="T:System.ArgumentNullException">The <paramref name="request" /> was <see langword="null" />.</exception>
878+
<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" />.
879+
880+
-or-
881+
882+
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.
883+
884+
-or-
885+
886+
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>
887+
<exception cref="T:System.Threading.Tasks.TaskCanceledException">The request was canceled.
888+
889+
-or-
890+
891+
If the <see cref="T:System.Threading.Tasks.TaskCanceledException" /> exception nests the <see cref="T:System.TimeoutException" />:
892+
The request failed due to timeout.</exception>
870893
</Docs>
871894
</Member>
872895
<Member MemberName="SendAsync">

‎xml/System.Net.Http/HttpContent.xml

Lines changed: 47 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -88,11 +88,19 @@
8888
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
8989
</Parameters>
9090
<Docs>
91-
<param name="stream">To be added.</param>
92-
<param name="context">To be added.</param>
93-
<param name="cancellationToken">To be added.</param>
94-
<summary>To be added.</summary>
95-
<remarks>To be added.</remarks>
91+
<param name="stream">The target stream.</param>
92+
<param name="context">Information about the transport (for example, the channel binding token). This parameter may be <see langword="null" />.</param>
93+
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
94+
<summary>Serializes the HTTP content into a stream of bytes and copies it to <paramref name="stream" />.</summary>
95+
<remarks>
96+
<format type="text/markdown"><![CDATA[
97+
98+
## Remarks
99+
This operation blocks until all of the content is written to the stream object.
100+
101+
]]></format>
102+
</remarks>
103+
<exception cref="T:System.ArgumentNullException">The <paramref name="stream" /> was <see langword="null" />.</exception>
96104
</Docs>
97105
</Member>
98106
<MemberGroup MemberName="CopyToAsync">
@@ -737,9 +745,16 @@
737745
</ReturnValue>
738746
<Parameters />
739747
<Docs>
740-
<summary>To be added.</summary>
741-
<returns>To be added.</returns>
742-
<remarks>To be added.</remarks>
748+
<summary>Serializes the HTTP content and returns a stream that represents the content.</summary>
749+
<returns>The stream that represents the HTTP content.</returns>
750+
<remarks>
751+
<format type="text/markdown"><![CDATA[
752+
753+
## Remarks
754+
This operation blocks until all of the stream that represents content has been read.
755+
756+
]]></format>
757+
</remarks>
743758
</Docs>
744759
</Member>
745760
<Member MemberName="ReadAsStream">
@@ -764,10 +779,17 @@
764779
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="0" FrameworkAlternate="net-5.0" />
765780
</Parameters>
766781
<Docs>
767-
<param name="cancellationToken">To be added.</param>
768-
<summary>To be added.</summary>
769-
<returns>To be added.</returns>
770-
<remarks>To be added.</remarks>
782+
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
783+
<summary>Serializes the HTTP content and returns a stream that represents the content.</summary>
784+
<returns>The stream that represents the HTTP content.</returns>
785+
<remarks>
786+
<format type="text/markdown"><![CDATA[
787+
788+
## Remarks
789+
This operation blocks until all of the stream that represents content has been read.
790+
791+
]]></format>
792+
</remarks>
771793
</Docs>
772794
</Member>
773795
<Member MemberName="ReadAsStreamAsync">
@@ -964,11 +986,19 @@
964986
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="2" FrameworkAlternate="net-5.0" />
965987
</Parameters>
966988
<Docs>
967-
<param name="stream">To be added.</param>
968-
<param name="context">To be added.</param>
969-
<param name="cancellationToken">To be added.</param>
970-
<summary>To be added.</summary>
971-
<remarks>To be added.</remarks>
989+
<param name="stream">The target stream.</param>
990+
<param name="context">Information about the transport (for example, the channel binding token). This parameter may be <see langword="null" />.</param>
991+
<param name="cancellationToken">The cancellation token to cancel the operation.</param>
992+
<summary>When overridden in a derived class, serializes the HTTP content to a stream. Otherwise, throws a <see cref="T:System.NotImplementedException" />.</summary>
993+
<remarks>
994+
<format type="text/markdown"><![CDATA[
995+
996+
## Remarks
997+
This operation blocks until all of the content has been serialized to the stream object.
998+
999+
]]></format>
1000+
</remarks>
1001+
<exception cref="T:System.NotImplementedException">The method is not overridden in the derived class.</exception>
9721002
</Docs>
9731003
</Member>
9741004
<Member MemberName="SerializeToStreamAsync">

0 commit comments

Comments
 (0)