feat: ASP0028 diagnostic docs (#34084)

Author: DeagleGross

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)