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.

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

Add note about other types #10651

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
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
58 changes: 24 additions & 34 deletions xml/ns-System.Net.Http.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,51 +5,41 @@
<format type="text/markdown"><![CDATA[

## Remarks
The <xref:System.Net.Http> namespace is designed to provide the following:

1. HTTP client components that allow users to consume modern web services over HTTP.
> [!TIP]
> Some of the types in this namespace are built into .NET, and some are provided through NuGet packages. This page only shows the types for the selected version. There might be other types available in other versions (for example, the corresponding "package-provided" version).

2. HTTP components that can be used by both clients and servers (HTTP headers and messages, for example). This provides a consistent programming model on both the client and the server side for modern web services over HTTP.
The <xref:System.Net.Http> namespace is designed to provide the following components:

The <xref:System.Net.Http> namespace and the related <xref:System.Net.Http.Headers> namespace provide the following set of components:
- HTTP client components that allow users to consume modern web services over HTTP.
- HTTP components that can be used by both clients and servers (HTTP headers and messages, for example). This provides a consistent programming model on both the client and the server side for modern web services over HTTP.

1. <xref:System.Net.Http.HttpClient> - the primary class used to send and receive requests over HTTP.
The <xref:System.Net.Http> namespace and the related <xref:System.Net.Http.Headers> namespace provide the following set of components:

2. <xref:System.Net.Http.HttpRequestMessage> and <xref:System.Net.Http.HttpResponseMessage> - HTTP messages as defined in RFC 2616 by the IETF.
- <xref:System.Net.Http.HttpClient> - The primary class used to send and receive requests over HTTP.
- <xref:System.Net.Http.HttpRequestMessage> and <xref:System.Net.Http.HttpResponseMessage> - HTTP messages as defined in RFC 2616 by the IETF.
- <xref:System.Net.Http.Headers.HttpHeaders> - HTTP headers as defined in RFC 2616 by the IETF.
- <xref:System.Net.Http.HttpClientHandler> - HTTP handlers responsible for producing HTTP response messages.

3. <xref:System.Net.Http.Headers.HttpHeaders> - HTTP headers as defined in RFC 2616 by the IETF.
There are various HTTP message handlers that you can use:

4. <xref:System.Net.Http.HttpClientHandler> - HTTP handlers responsible for producing HTTP response messages.
- <xref:System.Net.Http.DelegatingHandler> - A class used to plug a handler into a handler chain.
- <xref:System.Net.Http.HttpMessageHandler> - A simple class to derive from that supports the most common requirements for most applications.
- <xref:System.Net.Http.HttpClientHandler> - A class that operates at the bottom of the handler chain that actually handles the HTTP transport operations.
- <xref:System.Net.Http.WebRequestHandler> - A specialty class that operates at the bottom of the handler chain class that handles HTTP transport operations with options that are specific to the <xref:System.Net.HttpWebRequest?displayProperty=nameWithType> object.

There are various HTTP message handlers that can be used. These include the following.
The contents of an HTTP message corresponds to the entity body defined in RFC 2616.

1. <xref:System.Net.Http.DelegatingHandler> - A class used to plug a handler into a handler chain.
The following classes can be used for HTTP content:

2. <xref:System.Net.Http.HttpMessageHandler> - A simple class to derive from that supports the most common requirements for most applications.
- <xref:System.Net.Http.ByteArrayContent> - HTTP content based on a byte array.
- <xref:System.Net.Http.FormUrlEncodedContent> - HTTP content of name/value tuples encoded using application/x-www-form-urlencoded MIME type.
- <xref:System.Net.Http.MultipartContent> - HTTP content that gets serialized using the multipart/* content type specification.
- <xref:System.Net.Http.MultipartFormDataContent> - HTTP content encoded using the multipart/form-data MIME type.
- <xref:System.Net.Http.StreamContent> - HTTP content based on a stream.
- <xref:System.Net.Http.StringContent> - HTTP content based on a string.

3. <xref:System.Net.Http.HttpClientHandler> - A class that operates at the bottom of the handler chain that actually handles the HTTP transport operations.

4. <xref:System.Net.Http.WebRequestHandler> - A specialty class that operates at the bottom of the handler chain class that handles HTTP transport operations with options that are specific to the <xref:System.Net.HttpWebRequest?displayProperty=nameWithType> object.

The contents of an HTTP message corresponds to the entity body defined in RFC 2616.

A number of classes can be used for HTTP content. These include the following.

1. <xref:System.Net.Http.ByteArrayContent> - HTTP content based on a byte array.

2. <xref:System.Net.Http.FormUrlEncodedContent> - HTTP content of name/value tuples encoded using application/x-www-form-urlencoded MIME type.

3. <xref:System.Net.Http.MultipartContent> - HTTP content that gets serialized using the multipart/* content type specification.

4. <xref:System.Net.Http.MultipartFormDataContent> - HTTP content encoded using the multipart/form-data MIME type.

5. <xref:System.Net.Http.StreamContent> - HTTP content based on a stream.

6. <xref:System.Net.Http.StringContent> - HTTP content based on a string.

If an app using the <xref:System.Net.Http> and <xref:System.Net.Http.Headers> namespaces intends to download large amounts of data (50 megabytes or more), then the app should stream those downloads and not use the default buffering. If the default buffering is used the client memory usage will get very large, potentially resulting in substantially reduced performance.

Classes in the <xref:System.Net.Http> and <xref:System.Net.Http.Headers> namespaces can be used to develop Windows Store apps or desktop apps. When used in a Windows Store app, classes in the <xref:System.Net.Http> and <xref:System.Net.Http.Headers> namespaces are affected by network isolation feature, part of the application security model used by the Windows 8. The appropriate network capabilities must be enabled in the app manifest for a Windows Store app for the system to allow network access by a Windows store app. For more information, see the [Network Isolation for Windows Store Apps](/dotnet/framework/network-programming/network-isolation-for-windows-store-apps).
If your app uses the <xref:System.Net.Http> and <xref:System.Net.Http.Headers> namespaces intends to download large amounts of data (50 megabytes or more), then it should stream those downloads and not use the default buffering. If you use the default buffering, the client memory usage will get very large, potentially resulting in substantially reduced performance.

]]></format>
</remarks>
Expand Down