DotNetQuery.Blazor 1.0.0-beta.2

DotNet Query

A TanStack Query-inspired async data fetching and state management library for .NET and Blazor.

DotNet Query brings the battle-tested data-fetching patterns of TanStack Query to the .NET ecosystem. It gives you predictable loading, error, and success states out of the box — powered by Rx.NET observables, so everything is composable, lazy, and reactive by default.

Features

• Queries — fetch async data with automatic caching, background refetching, and stale-while-revalidate semantics
• Mutations — execute data-modifying operations with lifecycle callbacks and automatic cache invalidation on success
• Reactive state — built on Rx.NET, every query and mutation exposes IObservable streams for composable async pipelines
• Smart caching — configurable stale time and cache time control when data is re-fetched and when it is evicted
• Query deduplication — identical keys share a single cached query instance; no redundant requests
• Retry logic — exponential backoff out of the box; plug in your own strategy via IRetryHandler
• Blazor components — <Suspense> and <Transition> components for declarative query rendering
• CSR / SSR support — QueryExecutionMode controls Singleton (WebAssembly) vs Scoped (Server-Side Rendering) DI lifetime
• DI integration — first-class support for Microsoft.Extensions.DependencyInjection

Installation

# Core library — always required
dotnet add package DotNetQuery.Core

# DI integration
dotnet add package DotNetQuery.Extensions.DependencyInjection

# Blazor components
dotnet add package DotNetQuery.Blazor

Quick Start

// Program.cs
builder.Services.AddDotNetQuery(options =>
{
    options.StaleTime = TimeSpan.FromMinutes(1);
});

// Create a query
var query = queryClient.CreateQuery(new QueryOptions<int, UserDto>
{
    KeyFactory = id => QueryKey.From("users", id),
    Fetcher    = (id, ct) => userService.GetByIdAsync(id, ct),
});

query.Args.OnNext(42);

query.Success.Subscribe(user => Console.WriteLine($"Hello, {user.Name}!"));
query.Failure.Subscribe(error => Console.WriteLine($"Oops: {error.Message}"));

// Create a mutation
var mutation = queryClient.CreateMutation(new MutationOptions<CreateUserRequest, UserDto>
{
    Mutator        = (req, ct) => userService.CreateAsync(req, ct),
    InvalidateKeys = [QueryKey.From("users")],
    OnSuccess      = (_, user) => Console.WriteLine($"Created {user.Name}"),
});

mutation.Execute(new CreateUserRequest { Name = "Alice" });

<Suspense Query="_userQuery">
    <Content Context="user"><p>Hello, @user.Name!</p></Content>
    <Loading><p>Loading...</p></Loading>
    <Failure Context="error"><p>Error: @error.Message</p></Failure>
</Suspense>

Documentation

Full guides, examples, and API reference are available at https://psachmann.github.io/dotnet-query/.

• Introduction — core concepts and motivation
• Getting Started — install and write your first query
• Guides — queries, mutations, caching, Blazor, retries, and SSR
• API Reference — full generated API docs

Contributing

Contributions are welcome! Please see the Contributing guide for setup instructions, coding conventions, and the PR workflow. For bugs and feature requests, open an issue.

License

MIT — Copyright (c) 2026 Patrick Sachmann