Document .NET 11 API breaking changes

snippets/csharp/System/Math/Round/round3.cs

@@ -10,11 +10,18 @@ public static void Run()
             Console.WriteLine($"{value} --> {Math.Round(value, 2)}");
     }
 }
-// The example displays the following output:
+// The example displays the following output on .NET 10 and earlier:
 //       2.125 --> 2.12
 //       2.135 --> 2.13
 //       2.145 --> 2.14
 //       3.125 --> 3.12
 //       3.135 --> 3.14
 //       3.145 --> 3.14
+// On .NET 11 and later:
+//       2.125 --> 2.12
+//       2.135 --> 2.13
+//       2.145 --> 2.15
+//       3.125 --> 3.12
+//       3.135 --> 3.13
+//       3.145 --> 3.15
 // </Snippet2>

snippets/csharp/System/Math/Round/round4.cs

@@ -9,13 +9,20 @@ public static void Run()
         foreach (double value in values)
             Console.WriteLine($"{value} --> {Math.Round(value, 2, MidpointRounding.AwayFromZero)}");
 
-        // The example displays the following output:
+        // The example displays the following output on .NET 10 and earlier:
         //       2.125 --> 2.13
         //       2.135 --> 2.13
         //       2.145 --> 2.15
         //       3.125 --> 3.13
         //       3.135 --> 3.14
         //       3.145 --> 3.15
+        // On .NET 11 and later:
+        //       2.125 --> 2.13
+        //       2.135 --> 2.13
+        //       2.145 --> 2.15
+        //       3.125 --> 3.13
+        //       3.135 --> 3.13
+        //       3.145 --> 3.15
         // </Snippet3>
     }
 }

snippets/fsharp/System/Math/Round/round3.fs

@@ -6,11 +6,18 @@ open System
 let values = [| 2.125; 2.135; 2.145; 3.125; 3.135; 3.145 |]
 for value in values do
     printfn $"{value} --> {Math.Round(value, 2)}"
-// The example displays the following output:
+// The example displays the following output on .NET 10 and earlier:
 //       2.125 --> 2.12
 //       2.135 --> 2.13
 //       2.145 --> 2.14
 //       3.125 --> 3.12
 //       3.135 --> 3.14
 //       3.145 --> 3.14
+// On .NET 11 and later:
+//       2.125 --> 2.12
+//       2.135 --> 2.13
+//       2.145 --> 2.15
+//       3.125 --> 3.12
+//       3.135 --> 3.13
+//       3.145 --> 3.15
 // </Snippet2>

snippets/fsharp/System/Math/Round/round4.fs

@@ -6,11 +6,18 @@ open System
 let values = [| 2.125; 2.135; 2.145; 3.125; 3.135; 3.145 |]
 for value in values do
     printfn $"{value} --> {Math.Round(value, 2, MidpointRounding.AwayFromZero)}"
-// The example displays the following output:
+// The example displays the following output on .NET 10 and earlier:
 //       2.125 --> 2.13
 //       2.135 --> 2.13
 //       2.145 --> 2.15
 //       3.125 --> 3.13
 //       3.135 --> 3.14
 //       3.145 --> 3.15
+// On .NET 11 and later:
+//       2.125 --> 2.13
+//       2.135 --> 2.13
+//       2.145 --> 2.15
+//       3.125 --> 3.13
+//       3.135 --> 3.13
+//       3.145 --> 3.15
 // </Snippet3>

snippets/visualbasic/System/Math/Round/round3.vb

@@ -1,3 +1,3 @@
 ' Visual Basic .NET Document
 Option Strict On
 
@@ -10,12 +10,18 @@
       Next
    End Sub
 End Module
-' The example displays the following output:
+' The example displays the following output on .NET 10 and earlier:
 '       2.125 --> 2.12
 '       2.135 --> 2.13
 '       2.145 --> 2.14
 '       3.125 --> 3.12
 '       3.135 --> 3.14
 '       3.145 --> 3.14
+' On .NET 11 and later:
+'       2.125 --> 2.12
+'       2.135 --> 2.13
+'       2.145 --> 2.15
+'       3.125 --> 3.12
+'       3.135 --> 3.13
+'       3.145 --> 3.15
 ' </Snippet2>
-

snippets/visualbasic/System/Math/Round/round4.vb

@@ -1,3 +1,3 @@
 ' Visual Basic .NET Document
 Option Strict On
 
@@ -11,12 +11,18 @@
       Next
    End Sub
 End Module
-' The example displays the following output:
+' The example displays the following output on .NET 10 and earlier:
 '       2.125 --> 2.13
 '       2.135 --> 2.13
 '       2.145 --> 2.15
 '       3.125 --> 3.13
 '       3.135 --> 3.14
 '       3.145 --> 3.15
+' On .NET 11 and later:
+'       2.125 --> 2.13
+'       2.135 --> 2.13
+'       2.145 --> 2.15
+'       3.125 --> 3.13
+'       3.135 --> 3.13
+'       3.145 --> 3.15
 ' </Snippet3>
-

xml/Microsoft.Win32.SafeHandles/SafeFileHandle.xml

@@ -237,10 +237,10 @@
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets a value that determines if the handle is asynchronous or not.</summary>
+        <summary>Gets a value that indicates whether the handle is configured for asynchronous I/O.</summary>
         <value>
-          <see langword="true" /> if the handle is asynchronous; <see langword="false" /> otherwise.</value>
-        <remarks>To be added.</remarks>
+          <see langword="true" /> if the handle is configured for overlapped I/O on Windows. On Unix, <see langword="true" /> if the handle was configured as asynchronous in .NET 10 and earlier or has the <c>O_NONBLOCK</c> flag set in .NET 11 and later; otherwise, <see langword="false" />.</value>
+        <remarks>On Unix, starting in .NET 11, this property reflects whether the file descriptor has the <c>O_NONBLOCK</c> flag set. Regular files return <see langword="false" />, even if opened with <see cref="T:System.IO.FileOptions" />.<see cref="F:System.IO.FileOptions.Asynchronous" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="IsInvalid">

xml/System.IO.Compression/ZipArchive.xml

@@ -429,6 +429,7 @@ If the comment byte length is larger than <xref:System.UInt16.MaxValue>, it will
               </ul>
             </li>
           </dl>
+          <para>In .NET 11 and later, when <paramref name="mode" /> is <see cref="F:System.IO.Compression.ZipArchiveMode.Read" />, this method reads the archive's central directory and loads its entries asynchronously before it completes. Errors caused by malformed entries are reported by this method; accessing the <see cref="P:System.IO.Compression.ZipArchive.Entries" /> property afterward doesn't read from the stream.</para>
         </remarks>
         <exception cref="T:System.ArgumentException">
           <para>The stream is already closed.</para>
@@ -445,6 +446,9 @@ If the comment byte length is larger than <xref:System.UInt16.MaxValue>, it will
           <para>
             <paramref name="mode" /> is Update and an entry is missing from the archive or is corrupt and cannot be read.</para>
           <para>-or-</para>
+          <para>
+            In .NET 11 and later, <paramref name="mode" /> is Read and an archive entry is malformed.</para>
+          <para>-or-</para>
           <para>
             <paramref name="mode" /> is Update and an entry is too large to fit into memory.</para>
         </exception>

xml/System.IO.Packaging/PackagePart.xml

@@ -1094,7 +1094,13 @@ A part-level relationship defines an association between this part and a target
         <param name="access">The access permissions to use in opening the content stream.</param>
         <summary>Returns the part content stream opened with a specified <see cref="T:System.IO.FileMode" /> and <see cref="T:System.IO.FileAccess" />.</summary>
         <returns>The content stream for the part.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+In .NET 11 and later, when a compressed part in a read/write package is opened with <xref:System.IO.FileMode.Open> and <xref:System.IO.FileAccess.Read> and hasn't been modified in the current session, the returned stream is non-seekable.
+
+          ]]></format>
+        </remarks>
         <exception cref="T:System.InvalidOperationException">The part has been deleted.
 
  -or-

xml/System.IO/FileStream.xml

@@ -65,7 +65,7 @@ Use the <xref:System.IO.FileStream> class to read from, write to, open, and clos
 > [!IMPORTANT]
 > This type implements the <xref:System.IDisposable> interface. When you've finished using the type, you should dispose of it either directly (by calling its `Dispose` method) or indirectly (with a language construct such as `using` in C#). For more information, see [Use an object that implements IDisposable](xref:System.IDisposable#use-an-object-that-implements-idisposable).
 
-The <xref:System.IO.FileStream.IsAsync> property detects whether the file handle was opened asynchronously. You specify this value when you create an instance of the <xref:System.IO.FileStream> class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the <xref:System.IO.FileStream.IsAsync> property does not have to be `true` to call the <xref:System.IO.FileStream.ReadAsync*>, <xref:System.IO.FileStream.WriteAsync*>, or <xref:System.IO.Stream.CopyToAsync*> method. When the <xref:System.IO.FileStream.IsAsync> property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously.
+The <xref:System.IO.FileStream.IsAsync> property indicates whether the underlying handle is configured for asynchronous I/O. On Windows, this means the handle was opened for overlapped I/O. On Unix, starting in .NET 11, the property is `true` only when the file descriptor has the `O_NONBLOCK` flag set; regular files return `false` even when opened with <xref:System.IO.FileOptions.Asynchronous>. You can call asynchronous methods such as <xref:System.IO.FileStream.ReadAsync*> and <xref:System.IO.FileStream.WriteAsync*> when the property is `false`, but the I/O is performed synchronously.
 
 The <xref:System.IO.FileStream.Seek*> method supports random access to files. <xref:System.IO.FileStream.Seek*> allows the read/write position to be moved to any position within the file. This is done with byte offset reference point parameters. The byte offset is relative to the seek reference point, which can be the beginning, the current position, or the end of the underlying file, as represented by the three members of the <xref:System.IO.SeekOrigin> enumeration.
 
@@ -2288,16 +2288,16 @@ This method flushes the .NET stream buffers to the file, but does not flush inte
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets a value that indicates whether the <see langword="FileStream" /> was opened asynchronously or synchronously.</summary>
+        <summary>Gets a value that indicates whether the underlying handle is configured for asynchronous I/O.</summary>
         <value>
-          <see langword="true" /> if the <see langword="FileStream" /> was opened asynchronously; otherwise, <see langword="false" />.</value>
+          <see langword="true" /> if the handle was opened for overlapped I/O on Windows. On Unix, <see langword="true" /> if the stream was opened for asynchronous I/O in .NET 10 and earlier or the file descriptor has the <c>O_NONBLOCK</c> flag set in .NET 11 and later; otherwise, <see langword="false" />.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The `IsAsync` property detects whether the `FileStream` handle was opened asynchronously, enabling your code to use the <xref:System.IO.FileStream.Handle> property correctly. In Win32, `IsAsync` being true means the handle was opened for overlapped I/O, and thus requires different parameters to `ReadFile` and `WriteFile`.
+ The `IsAsync` property indicates whether the `FileStream` handle is configured for asynchronous I/O, enabling your code to use the <xref:System.IO.FileStream.Handle> property correctly. In Win32, `IsAsync` being true means the handle was opened for overlapped I/O, and thus requires different parameters to `ReadFile` and `WriteFile`. On Unix, starting in .NET 11, it reflects whether the file descriptor has the `O_NONBLOCK` flag set.
 
- You specify this value when you create an instance of the <xref:System.IO.FileStream> class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. When the property is `true`, the stream utilizes overlapped I/O to perform file operations asynchronously. However, the <xref:System.IO.FileStream.IsAsync> property does not have to be `true` to call the <xref:System.IO.FileStream.ReadAsync*>, <xref:System.IO.FileStream.WriteAsync*>, or <xref:System.IO.Stream.CopyToAsync*> method. When the <xref:System.IO.FileStream.IsAsync> property is `false` and you call the asynchronous read and write operations, the UI thread is still not blocked, but the actual I/O operation is performed synchronously.
+ You specify this value when you create an instance of the <xref:System.IO.FileStream> class using a constructor that has an `isAsync`, `useAsync`, or `options` parameter. The property doesn't have to be `true` to call the <xref:System.IO.FileStream.ReadAsync*>, <xref:System.IO.FileStream.WriteAsync*>, or <xref:System.IO.Stream.CopyToAsync*> method. When the property is `false` and you call an asynchronous read or write method, the UI thread isn't blocked, but the I/O is performed synchronously.
 
 
 

xml/System.Net.Security/SslServerAuthenticationOptions.xml

@@ -259,6 +259,8 @@ When this property isn't `null`, certain properties on `SslServerAuthenticationO
 
 - <xref:System.Net.Security.SslServerAuthenticationOptions.CertificateRevocationCheckMode> is superseded by <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.RevocationMode>.
 - Any <xref:System.Net.Security.SslCertificateTrust> associated with <xref:System.Net.Security.SslServerAuthenticationOptions.ServerCertificateContext> is superseded by <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.TrustMode> and <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.CustomTrustStore>. However, the trust list from `SslCertificateTrust` is still sent in the handshake when configured.
+
+When validating client certificates on the server, .NET 11 and later disable AIA certificate downloads by default if this property is `null`. If you supply a chain policy, its <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy.DisableCertificateDownloads> value is used.
 ]]></format>
         </remarks>
       </Docs>

xml/System.Net.Sockets/SendPacketsElement.xml

@@ -358,7 +358,7 @@
 
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentException">The <paramref name="fileStream" /> parameter must have been opened for asynchronous reading and writing.</exception>
+        <exception cref="T:System.ArgumentException">On Windows, the <paramref name="fileStream" /> parameter must have been opened for asynchronous reading and writing. In .NET 10 and earlier, this requirement also applies on non-Windows platforms.</exception>
         <exception cref="T:System.ArgumentNullException">The <paramref name="fileStream" /> parameter cannot be <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="offset" /> and <paramref name="count" /> parameters must be greater than or equal to zero.</exception>
       </Docs>
@@ -553,7 +553,7 @@
 
  ]]></format>
         </remarks>
-        <exception cref="T:System.ArgumentException">The <paramref name="fileStream" /> parameter must have been opened for asynchronous reading and writing.</exception>
+        <exception cref="T:System.ArgumentException">On Windows, the <paramref name="fileStream" /> parameter must have been opened for asynchronous reading and writing. In .NET 10 and earlier, this requirement also applies on non-Windows platforms.</exception>
         <exception cref="T:System.ArgumentNullException">The <paramref name="fileStream" /> parameter cannot be <see langword="null" />.</exception>
         <exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="offset" /> and <paramref name="count" /> parameters must be greater than or equal to zero.</exception>
       </Docs>

xml/System.Numerics/BigInteger.xml

@@ -214,6 +214,8 @@
 
 The <xref:System.Numerics.BigInteger> type is an immutable type that represents an arbitrarily large integer whose value in theory has no upper or lower bounds. The members of the <xref:System.Numerics.BigInteger> type closely parallel those of other integral types (the <xref:System.Byte>, <xref:System.Int16>, <xref:System.Int32>, <xref:System.Int64>, <xref:System.SByte>, <xref:System.UInt16>, <xref:System.UInt32>, and <xref:System.UInt64> types). This type differs from the other integral types in .NET, which have a range indicated by their `MinValue` and `MaxValue` properties.
 
+In .NET 11 and later, conversions from <xref:System.Numerics.BigInteger> to binary floating-point types round the exact integer value once to the nearest representable result.
+
 > [!NOTE]
 > Because the <xref:System.Numerics.BigInteger> type is immutable (see [Mutability](#mutability)) and because it has no upper or lower bounds, an <xref:System.OutOfMemoryException> can be thrown for any operation that causes a <xref:System.Numerics.BigInteger> value to grow too large.
 

xml/System.Numerics/Complex.xml

@@ -204,6 +204,8 @@ Note that, because the <xref:System.Numerics.Complex.Real> and  <xref:System.Num
 
 The real and imaginary parts of a complex number are represented by two double-precision floating-point values. This means that <xref:System.Numerics.Complex> values, like double-precision floating-point values, can lose precision as a result of numerical operations. This means that strict comparisons for equality of two <xref:System.Numerics.Complex> values may fail, even if the difference between the two values is due to a loss of precision. For more information, see <xref:System.Double>.
 
+In .NET 11 and later, the arithmetic operators and mathematical functions follow C23 Annex G for results involving infinities, NaNs, and signed zeros.
+
 For example, performing exponentiation on the logarithm of a number should return the original number. However, in some cases, the loss of precision of floating-point values can cause slight differences between the two values, as the following example illustrates.
 
 :::code language="csharp" source="~/snippets/csharp/System.Numerics/Complex/Overview/precision1.cs" id="Snippet5":::

xml/System.Reflection/Assembly.xml

@@ -1044,7 +1044,7 @@ Many members of the <xref:System.Reflection.Assembly> class provide information
 
  This effect also occurs when `M1` executes as a tail call from `M2`, or when `M2` executes as a tail call from `M3`. You can prevent the JIT compiler from inlining the method that calls <xref:System.Reflection.Assembly.GetCallingAssembly*>, by applying the <xref:System.Runtime.CompilerServices.MethodImplAttribute> attribute with the <xref:System.Runtime.CompilerServices.MethodImplOptions.NoInlining?displayProperty=nameWithType> flag, but there is no similar mechanism for preventing tail calls.
 
-
+Starting in .NET 11, this method supports Native AOT and uses stack trace data to identify the caller. If the `StackTraceSupport` feature switch is set to `false`, the method throws <xref:System.NotSupportedException>.
 
 ## Examples
  The following example gets the calling assembly of the current method.
@@ -1054,6 +1054,7 @@ Many members of the <xref:System.Reflection.Assembly> class provide information
 
  ]]></format>
         </remarks>
+        <exception cref="T:System.NotSupportedException">In .NET 11 and later, stack trace support is disabled.</exception>
       </Docs>
     </Member>
     <MemberGroup MemberName="GetCustomAttributes">

xml/System.Security.Cryptography.X509Certificates/X509Chain.xml

@@ -318,7 +318,7 @@
 ## Remarks
  Note that a valid X.509 certificate from a trusted issuer is valid only for the use specified in the <xref:System.Security.Cryptography.X509Certificates.X509ChainPolicy> object. Certificates that meet these chain policy rules might still be invalid for specific uses with such features as Security/MIME (SMIME), Authenticode, or Secure Sockets Layer (SSL). If further processing is required to determine whether the certificate is valid for a specific policy, derive a class from <xref:System.Security.Cryptography.X509Certificates.X509Chain> and override the <xref:System.Security.Cryptography.X509Certificates.X509Chain.Build*> method so that it calls the base class `Build` method first, and then does the additional processing.
 
-
+On Linux and other OpenSSL-based platforms, .NET 11 and later versions limit AIA certificate downloads to two per chain build. A chain that requires more than two AIA downloads can't be completed using those downloads alone.
 
 ## Examples
  The following code example opens the current user's personal certificate store, allows you to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate you select.