[✨ Triage] dotnet/runtime#120499 by ericstj - System.Net docs for .NET 10.0 APIs

[MihuBot]

Triage for dotnet/runtime#120499.
Repo filter: All networking issues.
MihuBot version: 554101.
Ping MihaZupan for any issues.

This is a test triage report generated by AI, aimed at helping the triage team quickly identify past issues/PRs that may be related.
Take any conclusions with a large grain of salt.

Tool logs

dotnet/runtime#120499: System.Net docs for .NET 10.0 APIs by ericstj
[Tool] Searching for System.Net docs for .NET 10.0 APIs, System.Net documentation .NET 10.0, IPAddress.IsValid documentation, IPAddress.IsValidUtf8 documentation, IPNetwork.TryParse documentation, IUtf8SpanParsable System.Net (IncludeOpen=True, IncludeClosed=True, IncludeIssues=True, IncludePullRequests=True, Repository=dotnet/runtime)
[Tool] Found 55 issues, 286 comments, 40 returned results (24195 ms)

Here is a thorough triage of issue #120499 ("System.Net docs for .NET 10.0 APIs") and a summary of all related discussions and issues:

---

Issue Summary

This issue tracks the porting of documentation for 4 new APIs in the System.Net namespace added in .NET 10.0:

IPAddress

• IsValid(ReadOnlySpan<char>)
• IsValidUtf8(ReadOnlySpan<byte>)
• IUtf8SpanParsable<IPAddress>.TryParse(ReadOnlySpan<byte>, IFormatProvider, out IPAddress)

IPNetwork

• IUtf8SpanParsable<IPNetwork>.TryParse(ReadOnlySpan<byte>, IFormatProvider, out IPNetwork)

---

Related Issues and Discussions

1. API Approval and Implementation

API Proposal: IPAddress.IsValid (Jan 2025)

• Motivation: Provide a cheaper way to validate IP addresses without parsing.
• API Review: Approved, but the UTF-8 variant was renamed to IsValidUtf8 to avoid confusion with binary overloads.
• Usage: IPAddress.IsValid(span) and IPAddress.IsValidUtf8(utf8Span).

PR: Add IPAddress.IsValid (Jan 2025)

• Implements both IsValid(ReadOnlySpan<char>) and IsValidUtf8(ReadOnlySpan<byte>).
• Discussion clarified naming and parameter conventions.

API Proposal: Implement IUtf8SpanParsable on IPAddress & IPNetwork (June 2024)

• Motivation: Expand UTF-8 support to IPAddress and IPNetwork.
• API Review: Explicit implementation recommended for methods that ignore IFormatProvider.
• Decision: Feature moved to .NET 10 due to missed deadlines.

PR: Implement IUtf8SpanParsable on IPAddress and IPNetwork (May–Oct 2024)

• Implements IUtf8SpanParsable for both types.
• Extensive review and benchmarking, with performance optimizations and generic parsing logic.
• Discussion on generic helper methods, marshalling, and performance tradeoffs.
• Final consensus: API and implementation are correct and performant.

2. Usability and Behavior of IPNetwork

System.Net.IPNetwork - not working (Nov 2023)

• Users confused by exceptions when parsing addresses like 192.168.1.1/24.
• Explanation: System.Net.IPNetwork requires the base address to have zero bits after the prefix (e.g., 192.168.1.0/24).

System.Net.IPNetwork parse CIDR issue (Dec 2023)

• Similar confusion for IPv6 CIDR parsing.
• Clarification: The last bits after the prefix must be zero.

System.Net.IPNetwork not behave as Microsoft.AspNetCore.HttpOverrides.IPNetwork (June 2025)

• Users expect IPNetwork.TryParse("127.0.0.1/8", out _) to succeed, but it fails due to the same restriction.
• Team consensus: This restriction is a usability issue and will be removed in .NET 10.

3. UTF-8 Validation APIs

API proposal: Utf8.IsValid(bytes) (Dec 2019–Jun 2023)

• Motivation: Expose a public API to validate UTF-8 byte spans.
• Approved and implemented as Utf8.IsValid(ReadOnlySpan<byte>).

PR: Added Utf8.IsValid(bytes) (Jun 2023)

• Implementation details and suggestions for usage in other libraries.

API Proposal: Indexed version of Utf8.IsValid (Jul–Aug 2025)

• Adds Utf8.IndexOfInvalidSubsequence and similar for Utf16.
• Naming and design discussed and approved.

API Proposal: UTF-16 version of Utf8.IsValid (Jul–Aug 2025)

• Adds Utf16.IsValid(ReadOnlySpan<char>).
• Naming debated; settled on IsValid for consistency.

PR: Utf16.IsValid and Utf8/16.IndexOfInvalidSubsequence (Oct 2025)

• Implements the above APIs.

4. General IPAddress and IPNetwork API Evolution

IUtf8SpanFormattable and IUtf8SpanParsable (Feb 2023–Jul 2024)

• Tracks the introduction and implementation of UTF-8 parsing/formatting interfaces across .NET types.
• IPAddress and IPNetwork were added in .NET 10.

API Proposal: IPAddress should implement ISpanFormattable/Parsable (Mar 2023)

• Motivated the addition of span-based parsing/formatting interfaces.

PR: Implement IUtf8SpanFormattable on IPAddress and IPNetwork (Apr 2023)

• Implements UTF-8 formatting for both types.

5. Edge Cases and Validation

IPAddress.TryParse(ROS<byte>) accepts invalid UTF-8 (Jan 2025)

• Discussion on whether parsing APIs should reject invalid UTF-8.
• Other UTF-8 parsing APIs do fail as expected; IPAddress may accept some invalid cases due to spec ambiguity.

IPAddress.TryParse return wrong result for 192.168.1 (Feb 2025)

• Clarifies that dotted IP notation with fewer than 4 parts is valid per spec and widely accepted.
• IPAddress.IsValid will help users who want stricter validation.

IPNetwork.Contains for IPv4 networks should match IPv4-Mapped IPv6 Addresses (Feb 2024)

• Suggests changing IPNetwork.Contains to treat IPv4-mapped IPv6 addresses as IPv4 for usability.
• Team leans toward making this breaking change in .NET 10.

---

Documentation Porting History

• Previous documentation porting issues for System.Net APIs:
  • .NET 6
  • .NET 8
  • .NET 9

---

Conclusion

All four APIs listed in issue #120499 are newly added in .NET 10 and have gone through full API review and implementation.

• The IsValid and IsValidUtf8 methods on IPAddress are approved and implemented.
• IUtf8SpanParsable is now implemented for both IPAddress and IPNetwork, with explicit interface implementations as recommended.
• The usability restriction on IPNetwork requiring zero bits after the prefix is being removed in .NET 10 due to repeated user confusion.
• UTF-8 validation APIs are now standardized and available for use in documentation and code samples.

For documentation writers: See the main tracking issue (#120483) for instructions. The APIs are stable, and their behavior is well-documented in both code and discussion.

---

Most Relevant Issues/PRs

• Issue #111282 (Jan 2025) – API Proposal: IPAddress.IsValid
• PR #111433 (Jan 2025) – Add IPAddress.IsValid
• Issue #103111 (Jun 2024) – API Proposal: Implement IUtf8SpanParsable on IPAddress & IPNetwork
• PR #102144 (May–Oct 2024) – Implement IUtf8SpanParsable on IPAddress and IPNetwork
• Issue #117114 (Jun 2025) – System.Net.IPNetwork usability restriction
• Issue #95321 (Nov 2023) – System.Net.IPNetwork - not working
• Issue #81500 (Feb 2023) – IUtf8SpanFormattable and IUtf8SpanParsable
• Issue #111288 (Jan 2025) – IPAddress.TryParse(ROS) accepts invalid UTF-8
• Issue #98427 (Feb 2024) – IPNetwork.Contains for IPv4 networks should match IPv4-Mapped IPv6 Addresses

---

If you need more details on any specific API or discussion, let me know!