From 692f97f39e1e25f3f696243eb5790e2528d041b6 Mon Sep 17 00:00:00 2001
From: FERNAN OVIEDO CANDELARESI <feoviedo@microsoft.com>
Date: Tue, 10 Dec 2024 11:28:11 -0800
Subject: [PATCH] What will this look like?

---
 xml/System.Net.Http/HttpCompletionOption.xml | 33 +++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/xml/System.Net.Http/HttpCompletionOption.xml b/xml/System.Net.Http/HttpCompletionOption.xml
index c040cd0dc98..8c88c1841de 100644
--- a/xml/System.Net.Http/HttpCompletionOption.xml
+++ b/xml/System.Net.Http/HttpCompletionOption.xml
@@ -36,7 +36,38 @@
   </Base>
   <Docs>
     <summary>Indicates if <see cref="T:System.Net.Http.HttpClient" /> operations should be considered completed either as soon as a response is available, or after reading the entire response message including the content.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ <xref:System.Net.Http.HttpClient> is intended to be instantiated once and re-used throughout the life of an application. Instantiating an HttpClient class for every request will exhaust the number of sockets available under heavy loads. This will result in SocketException errors. Below is an example using HttpClient correctly.
+
+```csharp
+public class GoodController : ApiController
+{
+    private static readonly HttpClient HttpClient;
+
+    static GoodController()
+    {
+        HttpClient = new HttpClient();
+    }
+}
+```
+
+```vb
+  Public Class GoodController
+    Inherits ApiController
+
+    Private Shared ReadOnly HttpClient As HttpClient
+
+    Shared Sub New()
+        HttpClient = New HttpClient()
+    End Sub
+End Class
+```
+
+ ]]></format>
+        </remarks>
   </Docs>
   <Members>
     <Member MemberName="ResponseContentRead">