Skip to content

Document .NET 11 API breaking changes - #13119

Open
gewarren with Copilot wants to merge 4 commits into
mainfrom
copilot/630678-update-api-docs-dotnet-11
Open

Document .NET 11 API breaking changes#13119
gewarren with Copilot wants to merge 4 commits into
mainfrom
copilot/630678-update-api-docs-dotnet-11

Conversation

Copilot AI commented Sep 29, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Contributor

Update API reference documentation where .NET 11 breaking changes make existing descriptions inaccurate or leave new behavior undocumented.

  • Numeric APIs: Correct Math.Round/MathF.Round limits and rounding behavior; document updated Decimal, BigInteger, and Complex results.
  • Parsing and reflection: Document DateOnly/TimeOnly parsing exceptions, Type.GetNullableUnderlyingType, and Assembly.GetCallingAssembly behavior.
  • I/O and networking: Clarify ZIP and package stream behavior, async-handle semantics, and SendPacketsElement requirements.
  • Cryptography: Document HKDF input limits, DSA support on macOS, Composite ML-DSA support on Windows, and certificate-chain download behavior.

For example, .NET 11 correctly rounds the exact stored floating-point value:

Math.Round(655.925, 2, MidpointRounding.AwayFromZero); // 655.92

Internal previews

Toggle expand/collapse
File Preview link
xml/Microsoft.Win32.SafeHandles/SafeFileHandle.xml Learn preview
xml/System.IO.Compression/ZipArchive.xml Learn preview
xml/System.IO.Packaging/PackagePart.xml Learn preview
xml/System.IO/FileStream.xml Learn preview
xml/System.Net.Security/SslServerAuthenticationOptions.xml Learn preview
xml/System.Net.Sockets/SendPacketsElement.xml Learn preview
xml/System.Numerics/BigInteger.xml Learn preview
xml/System.Numerics/Complex.xml Learn preview
xml/System.Reflection/Assembly.xml Learn preview
xml/System.Security.Cryptography.X509Certificates/X509Chain.xml Learn preview
xml/System.Security.Cryptography/CompositeMLDsa.xml Learn preview
xml/System.Security.Cryptography/DSA.xml Learn preview
xml/System.Security.Cryptography/HKDF.xml Learn preview
xml/System/DateOnly.xml Learn preview
xml/System/Decimal.xml Learn preview
xml/System/Math.xml Learn preview
xml/System/MathF.xml Learn preview
xml/System/Nullable.xml Learn preview
xml/System/TimeOnly.xml Learn preview
xml/System/Type.xml Learn preview

Build report

Copilot AI linked an issue Sep 29, 2026 that may be closed by this pull request
Update API docs for .NET 11 breaking changes #12933
Open
Copilot AI and others added 2 commits September 29, 2026 03:38
@gewarren
Document .NET 11 parsing and numeric behavior
b134a36 
Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>
@gewarren
Document .NET 11 API behavior changes
e548535 
Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>
Copilot AI changed the title [WIP] Update API docs for .NET 11 breaking changes Document .NET 11 API breaking changes Sep 29, 2026
Copilot AI requested a review from gewarren September 29, 2026 03:43
gewarren
gewarren approved these changes Sep 29, 2026
View reviewed changes
Comment thread xml/System.Net.Sockets/SendPacketsElement.xml Outdated
Comment thread xml/System.Net.Sockets/SendPacketsElement.xml Outdated
Comment thread xml/System.Reflection/Assembly.xml
Comment thread xml/System.Security.Cryptography.X509Certificates/X509Chain.xml Outdated
Comment thread xml/System/Decimal.xml Outdated
@gewarren
Apply batched suggestions from code review
2a786f1 
Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com>
@gewarren
gewarren marked this pull request as ready for review September 29, 2026 04:00
Copilot AI balanced review requested due to automatic review settings September 29, 2026 04:00
@gewarren
gewarren requested review from a team as code owners September 29, 2026 04:00
Copilot AI reviewed Sep 29, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Several descriptions incorrectly generalize .NET 11 behavior, omit method-level exceptions, or retain contradictory example output.

Review effort: Balanced
Findings: 12 Low severity

Open (12)
What changed in this PR

Documents .NET 11 behavioral changes across core runtime APIs.

Changes:

  • Updates numeric conversion and rounding behavior.
  • Documents parsing, reflection, I/O, networking, and packaging changes.
  • Clarifies platform-specific cryptography behavior.
File Description
xml/​System/​Type.xml Documents nullable-type introspection.
xml/​System/​TimeOnly.xml Documents parsing exceptions.
xml/​System/​Nullable.xml Adds custom Type exception behavior.
xml/​System/​MathF.xml Updates rounding limits.
xml/​System/​Math.xml Updates exact-value rounding behavior.
xml/​System/​Decimal.xml Documents correctly rounded conversions.
xml/​System/​DateOnly.xml Documents parsing exceptions.
xml/​System.Security.Cryptography/​HKDF.xml Documents Windows input limits.
xml/​System.Security.Cryptography/​DSA.xml Notes removed macOS support.
xml/​System.Security.Cryptography/​CompositeMLDsa.xml Lists Windows-supported algorithms.
xml/​System.Security.Cryptography.X509Certificates/​X509Chain.xml Documents Linux AIA limits.
xml/​System.Reflection/​Assembly.xml Documents Native AOT behavior.
xml/​System.Numerics/​Complex.xml Notes C23 special-value behavior.
xml/​System.Numerics/​BigInteger.xml Documents floating-point conversions.
xml/​System.Net.Sockets/​SendPacketsElement.xml Clarifies platform-specific stream requirements.
xml/​System.Net.Security/​SslServerAuthenticationOptions.xml Documents AIA download defaults.
xml/​System.IO/​FileStream.xml Updates Unix asynchronous-handle semantics.
xml/​System.IO.Packaging/​PackagePart.xml Documents non-seekable streams.
xml/​System.IO.Compression/​ZipArchive.xml Documents eager asynchronous loading.
xml/​Microsoft.Win32.SafeHandles/​SafeFileHandle.xml Updates Unix IsAsync semantics.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread xml/Microsoft.Win32.SafeHandles/SafeFileHandle.xml
<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 or, in .NET 11 and later, has the <c>O_NONBLOCK</c> flag set on Unix; otherwise, <see langword="false" />.</value>
Comment thread xml/System.IO.Compression/ZipArchive.xml
</ul>
</li>
</dl>
<para>In .NET 11 and later, 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>
Comment thread xml/System.IO.Packaging/PackagePart.xml
## Remarks
This method opens the content stream with <xref:System.IO.FileMode> of <xref:System.IO.FileMode.OpenOrCreate> and <xref:System.IO.FileAccess> permissions that are the same as the parent <xref:System.IO.Packaging.Package>.

In .NET 11 and later, when a compressed part in a read/write package is opened for reading and hasn't been modified in the current session, the returned stream is non-seekable.
Comment thread xml/System.IO.Packaging/PackagePart.xml
<remarks>
<format type="text/markdown"><![CDATA[

In .NET 11 and later, when a compressed part in a read/write package is opened for reading and hasn't been modified in the current session, the returned stream is non-seekable.
Comment thread xml/System.IO/FileStream.xml
<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 or, in .NET 11 and later, has the <c>O_NONBLOCK</c> flag set on Unix; otherwise, <see langword="false" />.</value>
Comment thread xml/System/Math.xml
<paramref name="digits" /> is less than 0.</exception>
<block subset="none" type="usage">
<para>Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the <see cref="M:System.Math.Round(System.Double,System.Int32)" /> method may not appear to round midpoint values to the nearest even value in the <paramref name="digits" /> decimal position. This is illustrated in the following example, where 2.135 is rounded to 2.13 instead of 2.14. This occurs because internally the method multiplies <paramref name="value" /> by 10<sup>digits</sup>, and the multiplication operation in this case suffers from a loss of precision.
<para>Because most decimal fractions can't be represented exactly as floating-point values, rounding uses the exact value stored in <paramref name="value" />. For example, the stored value for 2.135 is slightly less than 2.135, so rounding it to two fractional digits produces 2.13.
Comment thread xml/System/Math.xml
<paramref name="mode" /> is not a valid value of <see cref="T:System.MidpointRounding" />.</exception>
<block subset="none" type="usage">
<para>Because of the loss of precision that can result from representing decimal values as floating-point numbers or performing arithmetic operations on floating-point values, in some cases the <see cref="M:System.Math.Round(System.Double,System.Int32,System.MidpointRounding)" /> method may not appear to round midpoint values as specified by the <paramref name="mode" /> parameter. This is illustrated in the following example, where 2.135 is rounded to 2.13 instead of 2.14. This occurs because internally the method multiplies <paramref name="value" /> by 10<sup>digits</sup>, and the multiplication operation in this case suffers from a loss of precision.
<para>Because most decimal fractions can't be represented exactly as floating-point values, rounding uses the exact value stored in <paramref name="value" />. For example, the stored value for 2.135 is slightly less than 2.135, so rounding it to two fractional digits produces 2.13.
Comment thread xml/System/MathF.xml
## Remarks

The value of the `digits` argument can range from 0 to 6. Note that 6 is the maximum number of integral and fractional digits supported by the <xref:System.Single> type.
The `digits` argument can be any non-negative value. Values of 9 or greater leave the <xref:System.Single> value unchanged.
Comment thread xml/System/Nullable.xml
</remarks>
<exception cref="T:System.ArgumentNullException">
<paramref name="nullableType" /> is <see langword="null" />.</exception>
<exception cref="T:System.NotSupportedException">The <paramref name="nullableType" /> is a custom <see cref="T:System.Type" /> subclass that doesn't override <see cref="M:System.Type.GetNullableUnderlyingType" />.</exception>
Comment thread xml/System/TimeOnly.xml
<remarks>
<format type="text/markdown"><![CDATA[

The `TryParse` and `TryParseExact` methods return `false` when the input doesn't match a valid format. In .NET 11 and later, they throw <xref:System.ArgumentException> when a supplied <xref:System.Globalization.DateTimeStyles> value or format specifier is invalid.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Balanced
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
+1 more reviewer
@gewarren gewarren gewarren approved these changes
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

@gewarren gewarren

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Update API docs for .NET 11 breaking changes

3 participants

@gewarren