diff --git a/aspnetcore/diagnostics/asp0028.md b/aspnetcore/diagnostics/asp0028.md new file mode 100644 index 000000000000..99a03bce9e8d --- /dev/null +++ b/aspnetcore/diagnostics/asp0028.md @@ -0,0 +1,66 @@ +--- +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 + +On the server machine that supports IPv6, listening to `Any`, rather than `IPv6Any` will either not work or be slower than necessary, because of the [underlying System types implementation](https://github.com/dotnet/runtime/issues/82404). + +At the moment of current article publishing, in case of HTTP/1.x or HTTP/2.0 a name like `localhost` will resolve to `[::1]`, which won't be accepted by the server, forcing a retry with `127.0.0.1` (i.e. failed attempt before each connection). + +This usage will be 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)