AGENT SKILL

r3-reactive-extensions

Build reactive/event-driven C# with R3 (Cysharp's modern reimplementation of Reactive Extensions). Covers the Observable<T>/Observer<T> model, the OnErrorResume error contract, async dispatch with AwaitOperation, Task/IAsyncEnumerable integration, TimeProvider/FrameProvider scheduling, the concurrency contract, and how R3 differs from System.Reactive (Rx.NET).

License 许可
MIT
最近更新
2026-11-13
Stars
★ 1
Forks
0

01 前言 Front Matter

name
r3-reactive-extensions
description
Build reactive/event-driven C# with R3 (Cysharp's modern reimplementation of Reactive Extensions). Covers the Observable<T>/Observer<T> model, the OnErrorResume error contract, async dispatch with AwaitOperation, Task/IAsyncEnumerable integration, TimeProvider/FrameProvider scheduling, the concurrency contract, and how R3 differs from System.Reactive (Rx.NET).
user-invocable
false

02 资源文件 3

03 SKILL.md 正文

R3: Modern Reactive Extensions for .NET

R3 is Cysharp's ground-up reimplementation of Reactive Extensions — "the new future of dotnet/reactive and UniRx." It keeps the LINQ-over-events programming model but rebuilds the core types, error contract, and scheduler to fix long-standing problems in System.Reactive (Rx.NET). Use this skill when composing event streams, UI input, timers, or push-based pipelines in C#.

Canonical sources (link to these from code and docs):

When to Use This Skill

Use this skill when:

  • Composing events over time — UI input, sensor/feed updates, websocket messages, domain events
  • You need operators like debounce, throttle, merge, combine-latest, distinct-until-changed
  • Building MVVM state with ReactiveProperty / BindableReactiveProperty
  • Bridging push-based streams with Task / async and IAsyncEnumerable
  • Migrating from System.Reactive, UniRx, or IObservable<T> code
  • You hit Rx pain points: subscriptions dying on exceptions, scheduler overhead, or leak hunting

Not the right tool for: request/response I/O (use async/await), bounded producer/consumer with backpressure (use System.Threading.Channels), or server-side stream processing with batching/backpressure (use Akka.NET Streams). R3, like all Rx, is push-based with no backpressure. See the csharp-concurrency-patterns skill for choosing between these.

Reference Files

  • rx-net-differences.md: Every meaningful difference vs System.Reactive (Rx.NET) — the new core types, the error model, operator renames, dropped APIs, the scheduler swap, and a migration checklist.
  • async-and-integration-patterns.md: Common patterns — async dispatch with AwaitOperation, Task integration, IAsyncEnumerable round-tripping, ReactiveProperty/MVVM, subjects, and subscription lifecycle.
  • scheduling-and-concurrency.md: How R3 handles concurrent updates (the threading contract, Synchronize, ObserveOn), TimeProvider vs FrameProvider, when each is necessary, and deterministic testing with fake providers.

Everything in this skill was validated empirically against R3 1.3.1. Captured output appears in the reference files as evidence.


Why R3 Exists (the "why use it")

The author (neuecc) built R3 to fix concrete defects in System.Reactive:

  1. Exceptions silently kill subscriptions. In Rx, one exception in the pipeline calls OnError and unsubscribes forever — "a billion-dollar mistake" for long-lived event streams (a single bad UI event tears down the whole subscription). R3 routes errors to OnErrorResume and keeps the subscription alive by default.
  2. IScheduler is heavy and confusing. ImmediateScheduler/Merge were measured causing real server memory/CPU bloat. R3 deletes IScheduler and uses .NET 8's TimeProvider (wall-clock) plus a new FrameProvider (frame-clock).
  3. Subscription leaks are hard to find. R3 makes every Observable<T> an abstract class so all subscriptions funnel through one place, enabling ObservableTracker to list every live subscription with stack traces.
  4. Rx and async were awkwardly fused. R3 treats Rx as event-first and adds explicit bridges (AwaitOperation, FromAsync, ToAsyncEnumerable) instead of pretending events are pull-based sequences.
  5. One library, every UI. A platform-neutral core plus thin provider packages for Unity, Godot, WPF, WinForms, Avalonia, WinUI3, MAUI, Stride, MonoGame, and Blazor.

Install

dotnet add package R3
# Platform glue (pick what applies): R3.WPF, R3.Avalonia, R3.WinForms, R3.Unity (UPM),
# R3.Godot, ObservableCollections.R3, etc. See the repo README for the full list.
using R3;

The Mental Model

R3 replaces Rx's interfaces with abstract classes, and replaces Rx's two-method error contract with a single completion that carries a result.

public abstract class Observable<T>
{
    public IDisposable Subscribe(Observer<T> observer);     // tracked centrally
    protected abstract IDisposable SubscribeCore(Observer<T> observer);
}

public abstract class Observer<T> : IDisposable               // the observer IS the subscription
{
    public void OnNext(T value);
    public void OnErrorResume(Exception error);               // error WITHOUT unsubscribing
    public void OnCompleted(Result result);                   // success OR failure terminates
}

The grammar is (OnNext | OnErrorResume)* OnCompleted(Result)?. Note the difference from Rx's OnNext* (OnError | OnCompleted)?: errors and termination are decoupled. An error is just a notification; only OnCompleted ends the stream, and it carries a Result that is either Result.Success or Result.Failure(exception).

Quick start

using R3;

var subscription = Observable
    .EveryValueChanged(model, m => m.SearchText)   // emits when the property changes
    .Debounce(TimeSpan.FromMilliseconds(300))      // Rx called this "Throttle" (see differences)
    .DistinctUntilChanged()
    .SubscribeAwait(async (text, ct) =>
    {
        var results = await _api.SearchAsync(text, ct);
        Render(results);
    }, AwaitOperation.Switch);                      // cancel the in-flight search on a new keystroke

// Dispose to unsubscribe; or route into a DisposableBag / AddTo(token).
subscription.Dispose();

Core Behavior, Verified

Errors do not terminate by default

var subject = new Subject<int>();
subject.Select(x => 100 / x).Subscribe(
    onNext:        x => Console.WriteLine($"next {x}"),
    onErrorResume: e => Console.WriteLine($"errorResume {e.GetType().Name}"),
    onCompleted:   (Result r) => Console.WriteLine($"completed IsSuccess={r.IsSuccess}"));

subject.OnNext(2);   // next 50
subject.OnNext(0);   // errorResume DivideByZeroException   <-- NOT terminated
subject.OnNext(5);   // next 20                             <-- subscription is still alive!
subject.OnCompleted(); // completed IsSuccess=True

This is the single biggest behavioral change from Rx. To opt back into classic "an error terminates the sequence" behavior, insert .OnErrorResumeAsFailure() — the error then flows to OnCompleted(Result.Failure(e)) and downstream OnNexts stop. Recover with Catch. Full captured runs and the (deliberately absent) Retry story are in rx-net-differences.md.

Async dispatch is explicit

R3's async operators (SubscribeAwait, SelectAwait, WhereAwait, …) take an AwaitOperation that decides what happens when values arrive faster than the async work completes:

AwaitOperation Overlap behavior Typical use
Sequential (default) Queue values, run one at a time Ordered processing
Drop Ignore new values while one is running Debounced submit / cooldown
Switch Cancel the running one, start the new Search-as-you-type, latest-wins
Parallel Run all concurrently Independent fan-out
SequentialParallel Run concurrently, emit results in order Parallel map, ordered output
ThrottleFirstLast Run first + last of a burst Leading/trailing sampling

These were verified to behave exactly as described (including Switch cancelling the superseded operation's CancellationToken). See async-and-integration-patterns.md.

Task and IAsyncEnumerable bridges

// Task -> Observable
await Observable.FromAsync(async ct => await LoadAsync(ct)).FirstAsync();

// Observable -> Task (terminal operators return Task<T>)
List<int> all = await source.ToListAsync();
int last      = await source.LastAsync();

// IAsyncEnumerable -> Observable, and back
await asyncEnumerable.ToObservable().ForEachAsync(Handle);
await foreach (var x in source.ToAsyncEnumerable()) { /* ... */ }

All verified working. Details and the full terminal-operator list are in async-and-integration-patterns.md.


How R3 Handles Concurrent Updates

R3 does not serialize concurrent producers. Like Rx, it assumes the Rx grammar: OnNext must not be called concurrently or re-entrantly from multiple threads. Operators (Where, Select, Subject, …) are not internally locked. Pushing OnNext from many threads at once into a stateful downstream corrupts state — in testing, 20,000 concurrent OnNext calls into a List<T> subscriber lost ~half the items and threw inside the operator chain.

The fix is to make the boundary explicit:

// Multiple producer threads -> one serialized consumer
subject.Synchronize()                  // lock-based gate; delivery becomes single-threaded
       .Where(x => x.IsValid)
       .Subscribe(Handle);             // verified: 10000/10000 items, no corruption

// Or marshal onto a context/threadpool, which also serializes delivery:
source.ObserveOnThreadPool().Subscribe(Handle);

// For shared MVVM state written from many threads:
var counter = new SynchronizedReactiveProperty<int>(0);   // thread-safe writes

Practical rule: if more than one thread can publish into a stream, put Synchronize() (or an ObserveOn*) immediately after the source, or use SynchronizedReactiveProperty. Full race reproductions and outputs are in scheduling-and-concurrency.md.


Time vs Frames: TimeProvider and FrameProvider

R3 has two notions of "when," and both are abstractions you can fake in tests:

  • TimeProvider (the .NET 8 BCL type) = wall-clock time. Used by Delay, Debounce, Interval, Timer, Timeout. This is what server/business code uses.
  • FrameProvider (R3-specific) = a frame clock. Used by EveryUpdate, DelayFrame(n), IntervalFrame(n), etc.

When is a FrameProvider necessary? Whenever "progress" is measured in render/update ticks instead of elapsed time:

  • Game engines (Unity, Godot, Stride, MonoGame) — logic ticks with the engine's update loop, so it respects pause and time-scale and stays in lockstep with rendering.
  • UI render loops (WPF/Avalonia/WinUI composition frames) — react per frame.
  • Deterministic tests — FakeFrameProvider.Advance(n) drives frames with zero real time, exactly as FakeTimeProvider.Advance(timeSpan) drives the clock.

Plain server/business code virtually never needs FrameProvider — that's TimeProvider territory. Both fakes make time-dependent pipelines fully deterministic; examples in scheduling-and-concurrency.md.


Best Practices Summary

DO

  • Treat OnErrorResume as the default: design streams that survive individual bad events.
  • Add .OnErrorResumeAsFailure() when you genuinely want an error to terminate the stream.
  • Choose an AwaitOperation deliberately for every async operator (Switch for latest-wins, Sequential for ordering, Drop for cooldowns).
  • Put Synchronize() / ObserveOn* after any source that multiple threads publish into.
  • Pass a TimeProvider to time operators and a FrameProvider to frame operators so tests can use FakeTimeProvider / FakeFrameProvider.
  • Manage lifetime: route subscriptions into a DisposableBag, CompositeDisposable, or .AddTo(cancellationToken); turn on ObservableTracker in dev to catch leaks.
  • Use ReactiveProperty for de-duplicated observable state; BindableReactiveProperty for XAML-bound state.

DON'T

  • Don't assume an exception ends the stream (that's Rx, not R3).
  • Don't reach for Rx names that R3 renamed: it's Debounce (not Throttle), ThrottleLast (not Sample), Chunk (not Buffer). Retry, GroupBy, Finally, and plain Buffer are absent in 1.3.1 — see the differences file for replacements.
  • Don't call OnNext concurrently/re-entrantly from multiple threads without Synchronize().
  • Don't use R3 for backpressured throughput pipelines — use Channels or Akka.NET Streams.
  • Don't block on terminal operators (.Result/.Wait()); they return Task<T> — await them.

Additional Resources

04 同仓库更多 Skills

Blind-Striker
Blind-Striker/agent-skills-and-plugins

writing-tunit-tests

Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

dotnet-walls

Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

csharp-15

Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

verified-waves

Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

harness

The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

delegating-to-worker-models

Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.

★ 1