Skip to content

feat: ASP0028 diagnostic docs #34084

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 12, 2024
Merged

feat: ASP0028 diagnostic docs #34084

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions aspnetcore/diagnostics/asp0028.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Comment on lines +20 to +66
Copy link
Contributor

@Rick-Anderson Rick-Anderson Nov 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)
`IPv6Any` is preferred to `Any` 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 IPv4. `IPv6Any` is the wildcard address for IPv6.
Currently, when using HTTP/1.x or HTTP/2.0:
* `localhost` resolve to `[::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 to configure Kestrel to listen for incoming connections on all available IPv6 network interfaces is with IPv6Any.

How to fix violations

For the problematic code, replace Any with IPv6Any:

.UseKestrel().ConfigureKestrel(options =>
{ 
-   options.Listen(IPAddress.Any, ...);
+   options.Listen(IPAddress.IPv6Any, ...);
})

Alternatively, use the ListenAnyIP method without specifying any argument:

.UseKestrel().ConfigureKestrel(options =>
{ 
-   options.Listen(IPAddress.Any, ...);
+   options.ListenAnyIP(...);
})

When to suppress warnings

The ASP0028 diagnostic has a Information level severity. Suppress warnings if your intention is to disable IPv6 usage completely on the server, although this comes with the risk of the performance problems mentions in this article

IPv6 can be disabled either system-wide, or for .NET only via the AppCtx switch or environment variable

Loading