diff --git a/aspnetcore/diagnostics/asp0028.md b/aspnetcore/diagnostics/asp0028.md new file mode 100644 index 000000000000..e449db1b217b --- /dev/null +++ b/aspnetcore/diagnostics/asp0028.md @@ -0,0 +1,72 @@ +--- +title: "ASP0028: ## Analyzer to suggest using IPAddress.IPv6Any instead of IPAddress.Any if applicable" +ms.date: 11/11/2024 +description: "Learn about analysis rule ASP0028: Consider using IPAddress.IPv6Any instead of IPAddress.Any" +author: deaglegross +monikerRange: '>= aspnetcore-10.0' +ms.author: deaglegross +uid: diagnostics/asp0028 +--- +# ASP0028: Consider using `IPAddress.IPv6Any` instead of `IPAddress.Any` + +| | Value | +| - | - | +| **Rule ID** | ASP0028 | +| **Category** | Usage | +| **Fix is breaking or non-breaking** | Non-breaking | + +## Cause + +`IPv6Any` is preferred to `Any`, support IPv6 because `Any` is slower than `IPv6Any`. In some cases, `Any` may not work at all. `Any` has performance problems due to the [underlying System types implementation](https://github.com/dotnet/runtime/issues/82404). + +`127.0.0.1` is the IPv4 loopback address. `::1` is the IPv6 loopback address. `Any` is the wildcard address for both IPv4 and IPv6. `IPv6Any` is the wildcard address for IPv6 only. + +Currently, when using HTTP/1.x or HTTP/2.0: + +* `localhost` resolve tos `[::1]`. +* `[::1]` isn't accepted by the server, which forces a retry using `127.0.0.1`, and the cycle continues. + +Using `Any` with the preceding conditions is reported with a diagnostic message: + +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.Any, ...); +}) +``` + +## Rule description + +The recommended way is to setup Kestrel to listen on `IPv6Any`. + +## How to fix violations + +For the reported code +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.Any, ...); +}) +``` + +One can either explicitly change usage to `IPv6Any`: +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.IPv6Any, ...); +}) +``` + +or use another invocation - `options.ListenAnyIP()` without specifying any argument explicitly: +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.ListenAnyIP(...); +}) +``` + +## When to suppress warnings + +The severity level of this diagnostic is Information. You can suppress warnings if your intention is to disable `IPv6` usage completely on the server. + +You can disable IPv6 either system-wide, or for .NET only via the [AppCtx switch or environment variable](https://devblogs.microsoft.com/dotnet/dotnet-6-networking-improvements/#an-option-to-globally-disable-ipv6)