Merge pull request #12010 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

xml/System.Net.Http/SocketsHttpHandler.xml

@@ -1124,7 +1124,20 @@ For example, if the value is 64, then 65,536 bytes are allowed for the maximum r
       <Docs>
         <summary>Gets or sets a callback that selects the <see cref="System.Text.Encoding" /> to encode request header values.</summary>
         <value>The header encoding selector callback that selects the <see cref="System.Text.Encoding" /> to encode the value for the specified request header name, or <see langword="null" /> to indicate the default behavior.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+When specifying an encoding, you're generally expected to use one of the following encoding schemes: <xref:System.Text.Encoding.ASCII>, <xref:System.Text.Encoding.Latin1>, or <xref:System.Text.Encoding.UTF8>. Other encoding schemes might be susceptible to request smuggling attacks.
+
+> [!CAUTION]
+> Fixed multi-byte encoding schemes in particular (for example, <xref:System.Text.Encoding.Unicode> or <xref:System.Text.Encoding.UTF32>) must never be used, as their binary representation is likely to be misinterpreted and break the protocol. For instance, part of `✊` might be interpreted as a new line (`\n`) that terminates the header value.
+
+When you specify an encoding, it's your responsibility to ensure that the values are representable via the encoding, and that the server agrees on the encoding used. Otherwise, values will become corrupted. For example, since any set of bytes is considered a valid Latin1 sequence, a server replying with UTF-8 encoded header values might see its responses silently corrupted.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">An operation has already been started on the current instance.</exception>
         <exception cref="T:System.ObjectDisposedException">The current instance has been disposed.</exception>
       </Docs>
@@ -1199,7 +1212,20 @@ The timeout specified is greater than <see cref="F:System.Int32.MaxValue" /> mil
       <Docs>
         <summary>Gets or sets a callback that selects the <see cref="System.Text.Encoding" /> to decode response header values.</summary>
         <value>The header encoding selector callback that selects the <see cref="System.Text.Encoding" /> to decode the value for the specified response header name, or <see langword="null" /> to indicate the default behavior.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+When specifying an encoding, you're generally expected to use one of the following encoding schemes: <xref:System.Text.Encoding.ASCII>, <xref:System.Text.Encoding.Latin1>, or <xref:System.Text.Encoding.UTF8>. Other encoding schemes might be susceptible to request smuggling attacks.
+
+> [!CAUTION]
+> Fixed multi-byte encoding schemes in particular (for example, <xref:System.Text.Encoding.Unicode> or <xref:System.Text.Encoding.UTF32>) must never be used, as their binary representation is likely to be misinterpreted and break the protocol. For instance, part of `✊` might be interpreted as a new line (`\n`) that terminates the header value.
+
+When you specify an encoding, it's your responsibility to ensure that the values are representable via the encoding, and that the server agrees on the encoding used. Otherwise, values will become corrupted. For example, since any set of bytes is considered a valid Latin1 sequence, a server replying with UTF-8 encoded header values might see its responses silently corrupted.
+
+ ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">An operation has already been started on the current instance.</exception>
         <exception cref="T:System.ObjectDisposedException">The current instance has been disposed.</exception>
       </Docs>

xml/System/Uri.xml

@@ -2108,6 +2108,9 @@ If you used an escaped string to construct this instance (for example, `"http://
 
  The <xref:System.Uri.Fragment%2A> property is not considered in any <xref:System.Uri.Equals%2A> comparison.
 
+ > [!NOTE]
+ > The property includes the leading delimiter (`#`), whereas the URI specification (RFC 3986) recognizes the fragment as the portion of a URI without the delimiter.
+
 ## Examples
  The following example creates a <xref:System.Uri> instance and writes the fragment information to the console.
 
@@ -4218,6 +4221,9 @@ The following examples show a URI and the results of calling <xref:System.Uri.Ge
 
  For more information on IRI support, see the Remarks section for the <xref:System.Uri> class.
 
+ > [!NOTE]
+ > The property includes the leading delimiter (`?`), whereas the URI specification (RFC 3986) recognizes the query as the portion of a URI without the delimiter.
+
 ## Examples
  The following example writes the query `?date=today` to the console.