WebRequest deprecation (#20310)

Author: Jan Jahoda

docs/core/compatibility/6.0.md

@@ -35,6 +35,10 @@ If you're migrating an app to .NET 6, the breaking changes listed here might aff
 - [Standard numeric format parsing precision](core-libraries/6.0/numeric-format-parsing-handles-higher-precision.md)
 - [Unhandled exceptions from a BackgroundService](core-libraries/6.0/hosting-exception-handling.md)
 
+## Networking
+
+- [WebRequest, WebClient, and ServicePoint are obsolete](networking/6.0/webrequest-deprecated.md)
+
 ## Windows Forms
 
 - [Selected TableLayoutSettings properties throw InvalidEnumArgumentException](windows-forms/6.0/tablelayoutsettings-apis-throw-invalidenumargumentexception.md)

docs/core/compatibility/networking/6.0/webrequest-deprecated.md

@@ -0,0 +1,46 @@
+---
+title: "Breaking change: WebRequest, WebClient, and ServicePoint are obsolete"
+description: Learn about the breaking change in .NET 6.0 where WebRequest, WebClient, and ServicePoint are deprecated in favor of HttpClient.
+ms.date: 04/26/2021
+---
+# WebRequest, WebClient, and ServicePoint are obsolete
+
+<xref:System.Net.WebRequest>, <xref:System.Net.WebClient>, and <xref:System.Net.ServicePoint> classes are marked as obsolete and generate a `SYSLIB0014` warning at compile time.
+
+## Version introduced
+
+6.0
+
+## Change description
+
+<xref:System.Net.WebRequest>, <xref:System.Net.WebClient>, and <xref:System.Net.ServicePoint> classes were added to .NET Core in version 2.0 for backward compatibility. However, they introduced several runtime breaking changes, for example, `WebRequest.GetRequestStream` allocates memory for the whole response, and `WebClient.CancelAsync` doesn't always cancel immediately.
+
+Starting in .NET 6, the <xref:System.Net.WebRequest>, <xref:System.Net.WebClient>, and <xref:System.Net.ServicePoint> classes are deprecated. The classes are still available, but they're not recommended for new development. To reduce the number of analyzer warnings, only construction methods are decorated with the <xref:System.ObsoleteAttribute> attribute.
+
+## Recommended action
+
+Use the <xref:System.Net.Http.HttpClient?displayProperty=fullName> class instead.
+
+## Affected APIs
+
+- <xref:System.Net.WebRequest>
+- <xref:System.Net.HttpWebRequest>
+- <xref:System.Net.FtpWebRequest>
+- <xref:System.Net.WebClient>
+- <xref:System.Net.ServicePoint>
+
+<!--
+
+### Affected APIs
+
+- `T:System.Net.WebRequest`
+- `T:System.Net.HttpWebRequest`
+- `T:System.Net.FtpWebRequest`
+- `T:System.Net.WebClient`
+- `T:System.Net.ServicePoint`
+
+### Category
+
+Networking
+
+-->

docs/core/compatibility/toc.yml

@@ -61,6 +61,10 @@ items:
           href: core-libraries/6.0/numeric-format-parsing-handles-higher-precision.md
         - name: Unhandled exceptions from a BackgroundService
           href: core-libraries/6.0/hosting-exception-handling.md
+      - name: Networking
+        items:
+        - name: WebRequest, WebClient, and ServicePoint are obsolete
+          href: networking/6.0/webrequest-deprecated.md
       - name: Windows Forms
         items:
         - name: APIs throw ArgumentNullException
@@ -539,7 +543,7 @@ items:
           href: core-libraries/5.0/vector-lerp-behavior-change.md
         - name: Vector<T> throws NotSupportedException
           href: core-libraries/5.0/vectort-throws-notsupportedexception.md
-      - name: .NET 1.0-3.1
+      - name: .NET Core 1.0-3.1
         href: corefx.md
     - name: Cryptography
       items:
@@ -575,7 +579,7 @@ items:
           href: globalization/5.0/unicode-categories-for-latin1-chars.md
         - name: ListSeparator values changed
           href: globalization/5.0/listseparator-value-change.md
-      - name: .NET 3.0
+      - name: .NET Core 3.0
         href: globalization.md
     - name: Interop
       items:
@@ -603,6 +607,10 @@ items:
         href: msbuild.md
     - name: Networking
       items:
+      - name: .NET 6
+        items:
+        - name: WebRequest, WebClient, and ServicePoint are obsolete
+          href: networking/6.0/webrequest-deprecated.md
       - name: .NET 5
         items:
         - name: Cookie path handling conforms to RFC 6265
@@ -615,7 +623,7 @@ items:
           href: networking/5.0/negotiatestream-sslstream-dont-fail-on-successive-begin-calls.md
         - name: WinHttpHandler removed from .NET runtime
           href: networking/5.0/winhttphandler-removed-from-runtime.md
-      - name: .NET 2.0-3.0
+      - name: .NET Core 2.0-3.0
         href: networking.md
     - name: Security
       items: