ReactiveUI Documentation

Technical Documentation: reactiveui/ReactiveUI

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

What is ReactiveUI?

ReactiveUI is a composable, cross-platform model-view-viewmodel framework for all .NET
platforms that is inspired by functional reactive programming, which is a paradigm that allows you
to abstract mutable state away from your user interfaces and express the idea around a feature in one readable place
and improve the testability of your application.

🔨 Get Started 🛍 Install Packages 🎞 Watch Videos 🎓 View Samples 🎤 Discuss ReactiveUI

Your first view model Copy Chapter

A view shows data that changes, so it needs to know when a value changes. Written by hand, each property needs a
field and a setter that raises a change notification. Each command needs a property that wraps a method. ReactiveUI
writes that code for you while your project builds.

A source generator is a compiler add-on that writes C# code during the build. The ReactiveUI packages bring two
of them.
ReactiveUI.SourceGenerators writes reactive properties
and commands. ReactiveUI.Binding writes the code behind
WhenAnyValue, ToProperty and the view bindings. You install neither yourself.

1. Install the ReactiveUI package for your UI framework. A class library that holds only view models installs
ReactiveUI.

dotnet add package ReactiveUI.WPF

2. Declare the view model as a partial class and mark its members.

using ReactiveUI;
using ReactiveUI.SourceGenerators;

public partial class LoginViewModel : ReactiveObject
{
    private readonly IObservable<bool> _canLogIn;

    public LoginViewModel()
    {
        _canLogIn = this.WhenAnyValue(
            static x => x.UserName,
            static x => x.Password,
            static (userName, password) => userName.Length > 0 && password.Length > 0);

        _isValidHelper = _canLogIn.ToProperty(this, static x => x.IsValid);
    }

    [Reactive]
    public partial string UserName { get; set; } = string.Empty;

    [Reactive]
    public partial string Password { get; set; } = string.Empty;

    [ObservableAsProperty]
    public partial bool IsValid { get; }

    [ReactiveCommand(CanExecute = nameof(_canLogIn))]
    private async Task<bool> LogInAsync(CancellationToken cancellationToken)
    {
        await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
        return Password == "secret";
    }
}

WhenAnyValue returns a stream, an IObservable<T> that emits a new value each time either property changes.

3. Build. The generators write the rest of the class:

• The bodies of UserName and Password. Setting either one raises the change notification.
• The body of IsValid and its _isValidHelper field. ToProperty keeps IsValid equal to the latest value of
  _canLogIn.
• A LogInCommand property. It holds a command, an ICommand that also reports each result as a stream. The
  command runs LogInAsync, and it is enabled only while _canLogIn emits true. The generator drops the Async
  suffix from the name.

Next, bind the properties and the command to your view with Bind and BindCommand. The
ReactiveUI.Binding documentation shows how. The
source generators documentation lists every attribute
and option.

Partial properties with an initial value need C# 14, the default language version for .NET 10.

How the packages fit together Copy Chapter

ReactiveUI is a set of packages. You install the package for your UI framework, and it brings the rest.

The ReactiveUI documentation covers the core package, and the
installation guide shows which
package to install for each platform.

Pick a flavour Copy Section

ReactiveUI comes in two flavours with the same API. They differ only in the reactive types that appear in that API.

ReactiveUI.Primitives is ReactiveUI's own library of streams,
operators and schedulers. Both flavours run on it. The default flavour does not depend on System.Reactive, so your app
ships fewer assemblies.

The System.Reactive flavour puts its own types in the ReactiveUI.Reactive namespace. A file that uses
ReactiveObject or ReactiveCommand from it adds using ReactiveUI.Reactive;.

Bindings come from ReactiveUI.Binding Copy Section

ReactiveUI runs WhenAnyValue, Bind, OneWayBind, BindCommand, ToProperty and view location on
ReactiveUI.Binding. Its source generator writes the code for each
binding while your project builds. Nothing looks up a property by name at run time, so bindings are safe to trim and
to publish with Native AOT.

The ReactiveUI package imports the ReactiveUI.Binding namespace into your project, so binding calls need no using.
Moving from an earlier version? The
migration guide covers
the calls that need an Unsafe twin and the behavior that changed.

Source generators come with ReactiveUI.Core Copy Section

ReactiveUI.Core references
ReactiveUI.SourceGenerators and passes its generators
on. Every project that installs a ReactiveUI package can use [Reactive], [ReactiveCommand] and the other
attributes. Add using ReactiveUI.SourceGenerators; to each file that uses them. The generators check which flavour
your project references and write code for that flavour.

• Remove your own reference to ReactiveUI.SourceGenerators, or set it to the version ReactiveUI brings or later.
  An older version fails to restore with error NU1605.

Analyzers Copy Section

An analyzer checks your code as you type and reports problems as warnings or errors. ReactiveUI.Binding and
ReactiveUI.SourceGenerators run their analyzers in your project. They report binding calls and attributes that the
generators cannot handle. Diagnostic RXUIBIND021 flags a binding call with no generated binding behind it, such as
one that targets a member another source generator adds or a stored lambda; that call throws at run time, so treat
the warning as a bug to fix rather than suppress.

The analyzers inside ReactiveUI.Primitives stay out of your project. ReactiveUI references ReactiveUI.Primitives with
ExcludeAssets="analyzers". To use them, reference ReactiveUI.Primitives directly:

<PackageReference Include="ReactiveUI.Primitives" Version="x.y.z" />

Routing Copy Section

Routing (RoutingState and IScreen) is part of the ReactiveUI package. The WPF, WinUI and MAUI packages add a
RoutedViewHost control that shows the current view, and Windows Forms adds RoutedControlHost. RoutingState reports
navigation as streams. CurrentViewModel emits the view model on top of the stack. NavigationStackChanged emits a
read-only copy of the whole stack after each change. CanNavigateBack emits whether there is a view model to go back
to. The routing migration guide
covers moving from the ReactiveUI.Routing package.

Platform packages Copy Section

Install the package for your UI framework. Each one brings ReactiveUI. Each one except ReactiveUI.Uno has a
.Reactive twin for the System.Reactive flavour.

Platform	Package	NuGet
Class libraries	ReactiveUI
WPF	ReactiveUI.WPF
WinUI	ReactiveUI.WinUI
MAUI	ReactiveUI.Maui
Windows Forms	ReactiveUI.WinForms
Android (AndroidX)	ReactiveUI.AndroidX
Blazor	ReactiveUI.Blazor
Avalonia	ReactiveUI.Avalonia
Uno Platform	ReactiveUI.Uno
Unit tests	ReactiveUI.Testing

ReactiveUI.Avalonia and ReactiveUI.Uno live in their own repositories.

ReactiveUI.Validation adds validation rules for view models. It lives in its own repository.

Documentation Copy Chapter

• RxSchedulers - Using ReactiveUI schedulers without RequiresUnreferencedCode attributes

Book Copy Chapter

There has been an excellent book written by our Alumni maintainer
Kent Boogart.

Sponsors Copy Chapter

JetBrains gives ReactiveUI's maintainers licences for its tools through its
open source support programme.
Anthropic supports them with Claude through
Claude for Open Source.
OpenAI supports them with Codex through
Codex for Open Source.

See our sponsors for more information.
JetBrains, Claude, Anthropic, OpenAI and Codex names and logos are trademarks of their respective owners.

Sponsorship Copy Chapter

The core team members, ReactiveUI contributors and contributors in the ecosystem do this open-source work in their free
time. If you use ReactiveUI, a serious task, and you'd like us to invest more time on it, please donate. This project
increases your income/productivity too. It makes development and applications faster and it reduces the required
bandwidth.

Become a sponsor.

Migration from Xamarin and .NET 8 MAUI Copy Chapter

Xamarin Users Copy Section

As of May 2024, Microsoft ended support for Xamarin per
their support policy. ReactiveUI has removed
support for legacy Xamarin platforms in favor of modern .NET MAUI. For Xamarin projects:

• Xamarin.Forms → Migrate to MAUI and use ReactiveUI.Maui
• Xamarin.Android → Migrate to MAUI Android or use ReactiveUI.AndroidX for native Android
• Xamarin.iOS/Mac → Migrate to MAUI iOS/Mac Catalyst

For guidance on migrating from Xamarin to MAUI, see
the official migration documentation.

MAUI Users Copy Section

ReactiveUI supports .NET 9 and .NET 10 for MAUI platforms:

• net10.0-android / net9.0-android
• net10.0-ios / net9.0-ios
• net10.0-maccatalyst / net9.0-maccatalyst
• net10.0-windows10.0.19041.0 / net9.0-windows10.0.19041.0

Non-MAUI net8.0 library targets remain fully supported.

Examples Copy Chapter

Platform-specific sample applications are included in src/examples/:

All samples target .NET 10, use RxAppBuilder for initialization, and demonstrate WhenActivated, Bind/
BindCommand, and proper subscription disposal.

This is how we use the donations:

• Allow the core team to work on ReactiveUI
• Thank contributors if they invested a large amount of time in contributing
• Support projects in the ecosystem

Support Copy Chapter

If you have a question, please see if any discussions in
our GitHub issues
or Stack Overflow have already answered it.

If you want to discuss something or just need help, here is our Slack room, where there
are always individuals looking to help out!

Please do not open GitHub issues for support requests.

Contribute Copy Chapter

ReactiveUI is developed under an OSI-approved open source license, making it freely usable and distributable, even for
commercial use.

If you want to submit pull requests please first open
a GitHub issue to discuss. We are first time PR
contributors friendly.

See Contribution Guidelines for further information how to contribute changes.

Core Team Copy Chapter

| Glenn Watson
Melbourne, Australia | Chris Pulman
United Kingdom |

| --- | --- |

Alumni Core Team Copy Chapter

The following have been core team members in the past.

| Geoffrey Huntley
Sydney, Australia | Kent Boogaart
Brisbane, Australia | Olly Levett
London, United Kingdom |

| --- | --- | --- |
| Anaïs Betts
San Francisco, USA | Brendan Forster
Melbourne, Australia | Claire Novotny
New York, USA |
| Artyom Gorchakov
Moscow, Russia | Rodney Littles II
Texas, USA | Colt Bauman
South Korea |

.NET Foundation Copy Chapter

ReactiveUI is part of the .NET Foundation. Other projects that are associated with
the foundation include the Microsoft .NET Compiler Platform ("Roslyn") as well as the Microsoft ASP.NET family of
projects, and Microsoft .NET Core.

Overview (`src/examples/README.md`) Copy Section

Examples

Every documentation project runs. Each example prints what it does, and the // Output: comment under it shows what it
prints, so you can compare the two:

dotnet run --project src/examples/Documentation/Pages/commands

Property observation and binding Copy Chapter

WhenAnyValue, ObservableForProperty, Bind, OneWayBind, BindTo, BindCommand, BindInteraction and the view
locator come from ReactiveUI.Binding. Its source
generator writes each binding and view lookup at compile time, so they need no reflection and are safe to trim. The
ReactiveUI package imports the ReactiveUI.Binding namespaces for you, so these calls need no using directive.

The documentation projects reference the ReactiveUI project, which does not import those namespaces the way the package
does, so Documentation/Directory.Build.props imports them for each page.

Overview (`src/tests/ReactiveUI.Device.Tests/README.md`) Copy Section

ReactiveUI.Device.Tests

This app runs ReactiveUI's Android and iOS platform code on a real emulator or simulator. The other test projects run
on the build machine, where that code cannot load.

The app has two heads:

• Android (net11.0-android37). An instrumentation runs every test in the app. dotnet test --device starts it,
  streams each result back and writes a TRX report on the host.
• iOS (net11.0-ios). When UIKit connects the app's scene, the app runs every test, writes a TRX report and an
  exit-code file, and exits. It builds on Windows and macOS. It runs only on a macOS simulator.

The tests use TUnit on Microsoft.Testing.Platform, like the rest of the repository.

Run the tests Copy Chapter

The device-tests.cs script in reactiveui/actions-common
does the whole run: it boots the emulator or simulator, builds and runs the app, collects the logs and shuts the
device down. CI runs the same script through .github/workflows/device-tests.yml.

1. Clone reactiveui/actions-common next to this repository.

2. From the repository root, run the leg you want:

   bash Copy

   # Android: Linux, macOS or Windows with the Android SDK (ANDROID_HOME) and hardware virtualization
   dotnet run --file ../actions-common/scripts/device-tests.cs -- android --project src/tests/ReactiveUI.Device.Tests/ReactiveUI.Device.Tests.csproj
   
   # iOS: macOS with Xcode and an iOS simulator runtime
   dotnet run --file ../actions-common/scripts/device-tests.cs -- ios --project src/tests/ReactiveUI.Device.Tests/ReactiveUI.Device.Tests.csproj

3. Read the results in device-test-results/: the TRX report, logcat.txt or console.log, and the
   emulator or simulator log.

The script exits with 0 when every test passes. The header of device-tests.cs lists every option and exit code.

With an emulator already running, you can also run the Android head directly from src:

dotnet test --project tests/ReactiveUI.Device.Tests/ReactiveUI.Device.Tests.csproj -f net11.0-android37 --device emulator-5554 --report-trx

What the tests cover Copy Chapter

Why the normal CI legs skip it Copy Chapter

The solution builds this project on every leg, so a compile break shows up in the normal build. The test step leaves
it out with !tests/ReactiveUI.Device.Tests/** in testProjects, because it needs a device to run.

RxSchedulers (`docs/RxSchedulers.md`) Copy Section

RxSchedulers: Consuming ReactiveUI Schedulers Without RequiresUnreferencedCode

Problem Copy Chapter

When using RxApp.MainThreadScheduler or RxApp.TaskpoolScheduler in your code, since the entire RxApp class triggers initialization that is marked with RequiresUnreferencedCode attributes, any code that consumes these schedulers must also be marked with the same attributes.

This is particularly problematic when creating observables in ViewModels, Repositories, or other deeper code that is consumed by multiple sources, as it forces all consumers to add RequiresUnreferencedCode attributes.

Solution Copy Chapter

The new RxSchedulers static class provides access to the same scheduler functionality without requiring unreferenced code attributes. This class contains only the scheduler properties and doesn't trigger the Splat dependency injection initialization that requires reflection.

Usage Examples Copy Chapter

Basic Usage Copy Section

// Old way - requires RequiresUnreferencedCode attribute
[RequiresUnreferencedCode("Uses RxApp which may require unreferenced code")]
public IObservable<string> GetDataOld()
{
    return Observable.Return("data")
        .ObserveOn(RxApp.MainThreadScheduler);  // Triggers RequiresUnreferencedCode
}

// New way - no attributes required
public IObservable<string> GetDataNew()
{
    return Observable.Return("data")
        .ObserveOn(RxSchedulers.MainThreadScheduler);  // No attributes needed!
}

ViewModel Example Copy Section

public class MyViewModel : ReactiveObject
{
    private readonly ObservableAsPropertyHelper<string> _greeting;

    public MyViewModel()
    {
        // Using RxSchedulers avoids RequiresUnreferencedCode
        _greeting = this.WhenAnyValue(x => x.Name)
            .Select(name => $"Hello, {name ?? "World"}!")
            .ObserveOn(RxSchedulers.MainThreadScheduler)  // No attributes needed!
            .ToProperty(this, nameof(Greeting), scheduler: RxSchedulers.MainThreadScheduler);
    }

    public string? Name { get; set; }
    public string Greeting => _greeting.Value;
}

Repository Pattern Copy Section

public class DataRepository
{
    public IObservable<string> GetProcessedData()
    {
        // Using RxSchedulers in repository code doesn't force consumers 
        // to add RequiresUnreferencedCode attributes
        return GetRawData()
            .ObserveOn(RxSchedulers.TaskpoolScheduler)  // Background processing
            .Select(ProcessData)
            .ObserveOn(RxSchedulers.MainThreadScheduler);  // UI updates
    }
}

ReactiveProperty Factory Methods Copy Section

// New factory methods that use RxSchedulers internally
var property1 = ReactiveProperty<string>.Create();  // No attributes required
var property2 = ReactiveProperty<string>.Create("initial value");
var property3 = ReactiveProperty<int>.Create(42, skipCurrentValueOnSubscribe: false, allowDuplicateValues: true);

API Reference Copy Chapter

RxSchedulers Properties Copy Section

• RxSchedulers.MainThreadScheduler - Scheduler for UI thread operations (no unit test detection)
• RxSchedulers.TaskpoolScheduler - Scheduler for background operations (no unit test detection)

ReactiveProperty Factory Methods Copy Section

• ReactiveProperty<T>.Create() - Creates with default scheduler
• ReactiveProperty<T>.Create(T initialValue) - Creates with initial value
• ReactiveProperty<T>.Create(T initialValue, bool skipCurrentValueOnSubscribe, bool allowDuplicateValues) - Full configuration
• ReactiveProperty<T>.Create(T initialValue, IScheduler scheduler, bool skipCurrentValueOnSubscribe, bool allowDuplicateValues) - Custom scheduler

Compatibility Copy Chapter

• RxApp schedulers still work as before - no breaking changes
• RxApp and RxSchedulers are kept synchronized when schedulers are set
• For code that needs unit test detection, continue using RxApp schedulers
• For new code that doesn't need unit test detection, prefer RxSchedulers

When to Use Each Copy Chapter

Use `RxSchedulers` when: Copy Section

• Creating library code that shouldn't require RequiresUnreferencedCode attributes
• Building ViewModels, repositories, or services consumed by multiple sources
• You don't need automatic unit test scheduler detection
• You want to avoid triggering ReactiveUI's dependency injection initialization

Use `RxApp` schedulers when: Copy Section

• You need automatic unit test scheduler detection
• You're already using other RxApp features
• Existing code that's already marked with RequiresUnreferencedCode
• You need the full ReactiveUI initialization sequence

Migration Guide Copy Chapter

To migrate existing code from RxApp to RxSchedulers:

1. Replace RxApp.MainThreadScheduler with RxSchedulers.MainThreadScheduler
2. Replace RxApp.TaskpoolScheduler with RxSchedulers.TaskpoolScheduler
3. Remove RequiresUnreferencedCode and RequiresDynamicCode attributes if they were only needed for scheduler access
4. Use ReactiveProperty<T>.Create() factory methods instead of constructors
5. Test that unit tests still work (you may need to manually set test schedulers if you relied on automatic detection)

Notes Copy Chapter

• RxSchedulers provides a simplified version without unit test detection
• In unit test environments, you may need to manually set the schedulers if you were relying on automatic detection
• The schedulers default to DefaultScheduler.Instance for main thread and TaskPoolScheduler.Default for background
• This solution maintains full backwards compatibility with existing code

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~8162 tokens
• Canonical Reference: https://codewiki.google/github.com/reactiveui/ReactiveUI