Document IPNetwork and ForwardedHeadersOptions.KnownNetworks obsolescence for .NET 10 (#47899)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -24,6 +24,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [Exception diagnostics suppressed when TryHandleAsync returns true](aspnet-core/10/exception-handler-diagnostics-suppressed.md) | Behavioral change | Preview 7 |
 | [IActionContextAccessor and ActionContextAccessor are obsolete](aspnet-core/10/iactioncontextaccessor-obsolete.md) | Source incompatible/behavioral change | Preview 7 |
 | [IncludeOpenAPIAnalyzers property and MVC API analyzers are deprecated](aspnet-core/10/openapi-analyzers-deprecated.md) | Source incompatible | Preview 7 |
+| [IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete](aspnet-core/10/ipnetwork-knownnetworks-obsolete.md) | Source incompatible | Preview 7 |
 | [Microsoft.Extensions.ApiDescription.Client package deprecated](aspnet-core/10/apidescription-client-deprecated.md) | Source incompatible | Preview 7 |
 | [Razor run-time compilation is obsolete](aspnet-core/10/razor-runtime-compilation-obsolete.md) | Source incompatible | Preview 7 |
 

docs/core/compatibility/aspnet-core/10/ipnetwork-knownnetworks-obsolete.md

@@ -0,0 +1,50 @@
+---
+title: "Breaking change: IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete"
+description: Learn about the breaking change in ASP.NET Core 10.0 where IPNetwork and ForwardedHeadersOptions.KnownNetworks have been obsoleted in favor of System.Net.IPNetwork and KnownIPNetworks.
+ms.date: 08/08/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/aspnet/Announcements/issues/523
+---
+# IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete
+
+<xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName> and <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks> have been marked as obsolete in favor of using <xref:System.Net.IPNetwork?displayProperty=fullName> and `KnownIPNetworks`.
+
+## Version introduced
+
+.NET 10 Preview 7
+
+## Previous behavior
+
+Previously, you could use <xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName> and <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks> to configure known networks for the forwarded headers middleware:
+
+```csharp
+app.UseForwardedHeaders(new ForwardedHeadersOptions
+{
+    KnownNetworks.Add(new(IPAddress.Loopback, 8))
+});
+```
+
+## New behavior
+
+Starting in .NET 10, if you use [the obsolete APIs](#affected-apis) in your code, you'll get warning `ASPDEPR005` at compile time:
+
+> warning ASPDEPR005: Please use KnownIPNetworks instead. For more information, visit <https://aka.ms/aspnet/deprecate/005>.
+
+Use the <xref:System.Net.IPNetwork?displayProperty=fullName> type and `KnownIPNetworks` property instead.
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+<xref:System.Net.IPNetwork?displayProperty=fullName> has replaced the <xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName> type that was implemented for <xref:Microsoft.AspNetCore.HttpOverrides.ForwardedHeadersMiddleware>.
+
+## Recommended action
+
+Change to using <xref:System.Net.IPNetwork?displayProperty=fullName> and `KnownIPNetworks`.
+
+## Affected APIs
+
+- <xref:Microsoft.AspNetCore.HttpOverrides.IPNetwork?displayProperty=fullName>
+- <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -20,6 +20,8 @@ items:
                 href: aspnet-core/10/iactioncontextaccessor-obsolete.md
               - name: IncludeOpenAPIAnalyzers property and MVC API analyzers are deprecated
                 href: aspnet-core/10/openapi-analyzers-deprecated.md
+              - name: IPNetwork and ForwardedHeadersOptions.KnownNetworks are obsolete
+                href: aspnet-core/10/ipnetwork-knownnetworks-obsolete.md
               - name: Microsoft.Extensions.ApiDescription.Client package deprecated
                 href: aspnet-core/10/apidescription-client-deprecated.md
               - name: Razor run-time compilation is obsolete