IsOnline.NET 1.0.1

IsOnline.NET

Why?

NetworkInterface.GetIsNetworkAvailable() and Ping only tell you if there's a local connection — not whether the internet is actually reachable. Behind a captive portal (hotel, airport Wi-Fi), your device has an IP address but can't reach anything until you log in. IsOnline.NET detects this correctly.

Install

dotnet add package IsOnline.NET

Targets: netstandard2.1 · net8.0

Quick Start

using IsOnline;

Console.WriteLine(await IsOnlineChecker.CheckAsync());
// => true

Usage Examples

With timeout

bool online = await IsOnlineChecker.CheckAsync(new IsOnlineOptions
{
    Timeout = 10_000, // 10 seconds
});

With cancellation

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(3));

bool online = await IsOnlineChecker.CheckAsync(new IsOnlineOptions
{
    CancellationToken = cts.Token,
});
// => false (if cancelled before any check succeeds)

With fallback URLs

bool online = await IsOnlineChecker.CheckAsync(new IsOnlineOptions
{
    FallbackUrls = ["https://www.google.com", "https://www.github.com"],
});

With IPv6

bool online = await IsOnlineChecker.CheckAsync(new IsOnlineOptions
{
    IpVersion = 6,
});

All options combined

bool online = await IsOnlineChecker.CheckAsync(new IsOnlineOptions
{
    Timeout           = 8_000,
    IpVersion         = 4,
    CancellationToken = cts.Token,
    FallbackUrls      = ["https://your-api.example.com/health"],
});

API

IsOnlineChecker.CheckAsync(IsOnlineOptions? options = null)

Returns Task<bool> — true if online, false otherwise.

• Never throws on network failure (always returns false).
• Throws ArgumentOutOfRangeException if IpVersion is not 4 or 6, or Timeout is ≤ 0.

IsOnlineOptions

IsOnlineChecker.CheckFailed event

Subscribe to receive diagnostics when individual check URLs fail:

IsOnlineChecker.CheckFailed += (_, e) =>
{
    Console.WriteLine($"[{e.Timestamp:HH:mm:ss}] {e.Url} — {e.ErrorMessage}");
};

Each event provides:

• Timestamp (DateTimeOffset) — when the failure occurred
• Url (string) — the URL that failed
• ErrorMessage (string) — human-readable error
• Exception (Exception?) — the original exception

How It Works

Four checker groups run in parallel. The first success wins — CheckAsync returns true immediately without waiting for the others.

🌐 Public IP Check

🍎 Apple Captive Portal (iOS / macOS / iPadOS)

User-Agent: CaptiveNetworkSupport/1.0 wispr

If behind a captive portal, these URLs are redirected to a login page → body won't contain "Success" → correctly returns false.

🤖 Google Connectivity Check (Android / ChromeOS)

A redirect or any other status code → captive portal suspected → false.

🪟 Microsoft NCSI (Windows)

Fallback URLs

If all four checker groups fail and FallbackUrls is provided, those are checked sequentially:

• HEAD request first (minimal data transfer)
• Falls back to GET on HTTP 405 Method Not Allowed
• Success = any 2xx or 3xx response

Architecture

IsOnlineChecker.CheckAsync()
     │
     ├── 1. All NICs internal? → false
     ├── 2. CancellationToken cancelled? → false
     │
     └── 3. Run in parallel (first true wins):
           ├── PublicIpChecker       (2 URLs)
           ├── ApplePortalChecker    (3 URLs)
           ├── GooglePortalChecker   (5 URLs)
           └── MicrosoftPortalChecker(3 URLs)
                     │
                     └── All failed? → try FallbackUrls sequentially
                               │
                               └── All failed? → false

Key design decisions:

• Shared static HttpClient — avoids socket exhaustion
• AllowAutoRedirect = false — detects captive portals via redirect
• ConfigureAwait(false) — safe for ASP.NET, WPF, WinForms contexts
• Diagnostics never throw — CheckFailed event errors are swallowed

Proxy Support

To use through a proxy, configure HttpClient.DefaultProxy before calling CheckAsync:

HttpClient.DefaultProxy = new WebProxy("http://proxy.example.com:8080");

Requirements

• .NET Standard 2.1+ or .NET 8.0+
• No external NuGet dependencies

License

MIT — Created by Ishwar Datt Mishra.