R a/asp028

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)