Philiprehberger.Polling 0.2.5

Philiprehberger.Polling

Poll any async operation until a condition is met with configurable intervals, timeouts, and backoff strategies.

Installation

dotnet add package Philiprehberger.Polling

Usage

using Philiprehberger.Polling;

// Poll an API until the order status is "completed"
var result = await Poll
    .Until(
        async () => await client.GetOrderStatusAsync(orderId),
        status => status == "completed")
    .Every(TimeSpan.FromSeconds(2))
    .WithTimeout(TimeSpan.FromMinutes(5))
    .WithBackoff(BackoffStrategy.Exponential)
    .ExecuteAsync();

if (result.Succeeded)
    Console.WriteLine($"Order completed after {result.Attempts} attempts");

Side-effect polling

Poll an operation that throws until it succeeds:

var result = await Poll
    .Until(async () => await db.PingAsync())
    .Every(TimeSpan.FromSeconds(1))
    .WithTimeout(TimeSpan.FromSeconds(30))
    .ExecuteAsync();

Backoff strategies

// Constant (default) — same interval every attempt
.WithBackoff(BackoffStrategy.Constant)

// Linear — interval grows by base each attempt (500ms, 1s, 1.5s, ...)
.WithBackoff(BackoffStrategy.Linear)

// Exponential — interval doubles each attempt (500ms, 1s, 2s, 4s, ...)
.WithBackoff(BackoffStrategy.Exponential)

// Exponential with jitter — exponential + random jitter to avoid thundering herd
.WithBackoff(BackoffStrategy.ExponentialWithJitter)

Max Attempts

Limit polling to a fixed number of attempts, independent of timeout:

var result = await Poll
    .Until(
        async () => await client.GetJobStatusAsync(jobId),
        status => status == "done")
    .Every(TimeSpan.FromSeconds(1))
    .WithMaxAttempts(10)
    .ExecuteAsync();

if (!result.Succeeded)
    Console.WriteLine($"Gave up after {result.Attempts} attempts");

Polling Context

Use a context-aware predicate to access attempt metadata:

var result = await Poll
    .Until(
        async () => await GetValueAsync(),
        (value, context) =>
        {
            Console.WriteLine($"Attempt {context.AttemptNumber}, elapsed {context.Elapsed}");
            return value > 100;
        })
    .Every(TimeSpan.FromSeconds(1))
    .ExecuteAsync();

The PollContext provides AttemptNumber (1-based), Elapsed time, and LastException.

Exception Filtering

Only retry on specific exception types; other exceptions propagate immediately:

var result = await Poll
    .Until(async () => await db.PingAsync())
    .Every(TimeSpan.FromSeconds(1))
    .OnlyRetryOn<TimeoutException>()
    .WithTimeout(TimeSpan.FromSeconds(30))
    .ExecuteAsync();

Observability

var result = await Poll
    .Until(
        async () => await service.GetHealthAsync(),
        health => health.IsHealthy)
    .Every(TimeSpan.FromSeconds(1))
    .OnAttempt((value, attempt) =>
        Console.WriteLine($"Attempt {attempt}: healthy={value.IsHealthy}"))
    .ExecuteAsync();

Cancellation

using var cts = new CancellationTokenSource();

var result = await Poll
    .Until(
        async () => await GetValueAsync(),
        v => v > 100)
    .Every(TimeSpan.FromMilliseconds(200))
    .WithCancellation(cts.Token)
    .ExecuteAsync();

API

Poll

PollBuilder<T> / PollBuilder

PollContext

PollResult<T>

BackoffStrategy

Development

dotnet build src/Philiprehberger.Polling.csproj --configuration Release

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT