diff --git a/aspnetcore/diagnostics/asp0028.md b/aspnetcore/diagnostics/asp0028.md index 99a03bce9e8d..26370fb0a938 100644 --- a/aspnetcore/diagnostics/asp0028.md +++ b/aspnetcore/diagnostics/asp0028.md @@ -1,10 +1,10 @@ --- 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" +description: "Consider using IPAddress.IPv6Any instead of IPAddress.Any" author: deaglegross monikerRange: '>= aspnetcore-10.0' -ms.author: deaglegross +ms.author: dmkorolev uid: diagnostics/asp0028 --- # ASP0028: Consider using `IPAddress.IPv6Any` instead of `IPAddress.Any` @@ -17,11 +17,17 @@ uid: diagnostics/asp0028 ## 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). +On the server machine that supports `IPv6`, [IPv6Any](/dotnet/api/system.net.ipaddress.ipv6any) is preferred to [Any](/dotnet/api/system.net.ipaddress.any) because `Any` can be slower than `IPv6Any`. In some cases, `Any` may not work at all. `Any` can be slower due to 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). +`127.0.0.1` is the IPv4 loopback address. `::1` is the IPv6 loopback address. `Any` is the wildcard address for IPv4. `IPv6Any` is the wildcard address for IPv6. + +Current behavior with with IPv6 when using HTTP/1.x or HTTP/2.0: + +* `localhost` resolves to `[::1]`. +* `[::1]` isn't accepted by the server, which forces a retry using `127.0.0.1`, creating a repeated cycle. + +Using `Any` with the preceding conditions causes the `ASP0028` diagnostic message. Here's an example of the code that can result in these conditions: -This usage will be reported with a diagnostic message: ```csharp .UseKestrel().ConfigureKestrel(options => { @@ -31,36 +37,34 @@ This usage will be reported with a diagnostic message: ## Rule description -The recommended way is to setup Kestrel to listen on `IPv6Any`. +The recommended way to configure Kestrel to listen for incoming connections on all available `IPv6` network interfaces is with `IPv6Any`. ## How to fix violations -For the reported code -```csharp -.UseKestrel().ConfigureKestrel(options => -{ - options.Listen(IPAddress.Any, ...); -}) -``` +For the problematic code, replace `Any` with `IPv6Any`. -One can either explicitly change usage to `IPv6Any`: -```csharp +Use the method without specifying any arguments: + +```diff .UseKestrel().ConfigureKestrel(options => { - options.Listen(IPAddress.IPv6Any, ...); +- options.Listen(IPAddress.Any, ...); ++ options.ListenAnyIP(...); }) ``` -or use another invocation - `options.ListenAnyIP()` without specifying any argument explicitly: -```csharp +Or use the field: + +```diff .UseKestrel().ConfigureKestrel(options => { - options.ListenAnyIP(...); +- options.Listen(IPAddress.Any, ...); ++ options.Listen(IPAddress.IPv6Any, ...); }) ``` ## 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. +The `ASP0028` diagnostic has [Information](/dotnet/api/microsoft.extensions.logging.loglevel) level severity. Suppress this warning if your intention is to disable `IPv6` usage completely on the server, although doing so risks the performance problems mentioned in this article. -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) +`IPv6` can be disabled 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) diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 5c8c55da4d3d..56cd71380a83 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -1301,6 +1301,8 @@ items: uid: diagnostics/asp0025 - name: ASP0026 uid: diagnostics/asp0026 + - name: ASP0028 + uid: diagnostics/asp0028 - name: BL0001 uid: diagnostics/bl0001 - name: BL0002