danielsword / reactiveui

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

ReactiveUI

Use the Reactive Extensions for .NET to create elegant, testable User Interfaces that run on any mobile or desktop platform. Supports Xamarin.iOS, Xamarin.Android, Xamarin.Mac, Xamarin Forms, WPF, Windows Forms, Windows Phone 8, Windows Store and Universal Windows Platform (UWP).

If you’re already familiar with functional reactive programming or what ReactiveUI is about, check out the documentation for more in-depth information about how it all works or our comprehensive collection of samples.

If you have a question, please see if any discussions in our GitHub issues or Stack Overflow have already answered it. If not, please feel free to file your own!

We have our very own Slack organization which contains some of the best user interface/reactive extension developers in the industry. All software engineers, young and old, regardless of experience are welcome to join our campfire but you'll need to send an email with the email address you'd like to be invited, and we'll send you an invite. Sit tight, it's worth it.

Table of Contents

• Introduction
• Fundamentals
• A Compelling Example
• Support
• Contribute
• Showcase
• Licensing
• Sponsorship

Introduction

ReactiveUI is inspired by functional reactive programming and is the father of the ReactiveCocoa (Cocoa/Swift) framework. Rather than using mutable variables which are replaced and modified in-place, ReactiveUI offers "event streams", represented by the IObserver and IObservable types, that send values over time.

If you are new to these concepts then we highly recommend watching the following videos before progressing too far:

• Rx Under the Hood (Video #1) by Erik Meijer (Inventor of Reactive Extensions/Microsoft Research)
• Rx Under the Hood (Video #2) by Erik Meijer (Inventor of Reactive Extensions/Microsoft Research)
• Controlling Time and Space: understanding the many formulations of FRP by Evan Czaplicki (Elm language designer/Prezi)
• FRP In Practice: Taking a look at Reactive[UI/Cocoa] by Paul Betts (Slack/GitHub)
• ReactiveUI - It's pretty neat by Brendan Forster (GitHub)
• ReactiveUI - Turning MVVM up to 11 by Brendan Forster (GitHub)
• Let Me Tell You About Our Lord And Saviour FRP by Brendan Forster (GitHub)

Fundamentals

One of the most confusing aspects of the Reactive Extensions is that of "hot" and "cold" observables (event streams). In short, given just a method or function declaration like this:

IObservable<string> Search(string query)

It is impossible to tell whether subscribing to (observing) that IObservable will involve side effects. If it does involve side effects, it’s also impossible to tell whether each subscription has a side effect, or if only the first one does. Whilst this example is contrived, it demonstrates a real, pervasive problem that makes it harder at first for newcomers to understand Rx code at first glance.

As such we also recommend watching this video, reading our documentation and playing with the marbles to familiarize yourself with the fundamentals.

A Compelling Example

Let’s say you have a text field, and whenever the user types something into it, you want to make a network request which searches for that query.

public interface ISearchViewModel
{
    ReactiveList<SearchResults> SearchResults { get; }
    string SearchQuery { get; }	 
    ReactiveCommand<string, List<SearchResults>> Search { get; }
    ISearchService SearchService { get; }
}

Define under what conditions a network request will be made

// Here we're describing here, in a *declarative way*, the conditions in
// which the Search command is enabled.  Now our Command IsEnabled is
// perfectly efficient, because we're only updating the UI in the scenario
// when it should change.
var canSearch = this.WhenAny(x => x.SearchQuery, x => !String.IsNullOrWhiteSpace(x.Value));

Make the network connection

// ReactiveCommand has built-in support for background operations and
// guarantees that this block will only run exactly once at a time, and
// that the CanExecute will auto-disable and that property IsExecuting will
// be set accordingly whilst it is running.
Search = ReactiveCommand.CreateFromTask<string, List<SearchResults>>(_ => 
        searchService.Search(this.SearchQuery), canSearch);

Update the user interface

// ReactiveCommands are themselves IObservables, whose value are the results
// from the async method, guaranteed to arrive on the UI thread. We're going
// to take the list of search results that the background operation loaded, 
// and them into our SearchResults.
Search.Subscribe(results => {
    SearchResults.Clear();
    SearchResults.AddRange(results);
});

Handling failures

// ThrownExceptions is any exception thrown from the CreateAsyncTask piped
// to this Observable. Subscribing to this allows you to handle errors on
// the UI thread. 
Search.ThrownExceptions
    .Subscribe(ex => {
        UserError.Throw("Potential Network Connectivity Error", ex);
    });

Throttling network requests and automatic search execution behaviour

// Whenever the Search query changes, we're going to wait for one second
// of "dead airtime", then automatically invoke the subscribe command.
this.WhenAnyValue(x => x.SearchQuery)
    .Throttle(TimeSpan.FromSeconds(1), RxApp.MainThreadScheduler)
    .InvokeCommand(Search);

Support

ReactiveUI is an open source project that is community supported by people just like you. We keep a bunch of curated tasks specifically for new contributors which are a great way to get started with open source. They also provide a fantastic avenue for getting to know the ReactiveUI maintainers.

If you have a question, please see if any discussions in our GitHub issues or Stack Overflow have already answered it. If not, please feel free to file your own!

Contribute

Here are some pointers for anyone looking for mini-features and work items that would make a positive contribution to ReactiveUI.

• Let us know if (and how) you are using ReactiveUI in production.
• We keep a bunch of curated tasks specifically for new contributors, which are a great way to get started with open source and provide a fantastic avenue for getting to know the ReactiveUI maintainers.
• Write a blog post about #ReactiveUI and then tweet the link to our twitter account. We will retweet you.
• Contribute a repro case or help resolve known issues.
• Help flesh out and improve our documentation by providing content writing, structure enforcement or editing services.

We try not to be too OCD about coding style wars, but we do have our own convention and best design practices documented - please respect them and your pull-request experience will be much smoother. If you are using Visual Studio, please install the rebracer plugin which will automatically apply the correct source formatting settings.

We're also looking for people to assist with code reviews of ReactiveUI contributions. If you're experienced with any of the below technologies, you can join the team and receive notifications:

• Android reviewers
• Core reviewers
• iOS reviewers
• Mac reviewers
• UWP reviewers
• WinForms reviewers
• WPF reviewers
• Xamarin Forms reviewers

Showcase

We encourage our community to showcase where and how they have used ReactiveUI in their applications, some members have even gone as far as open-sourcing their app and sharing their entire codebase. You are of course under no-obligation share these insights (or code) with us but it is greatly appreciated by the project maintainers and you'll usually get a retweet out of it.

Licensing

The ReactiveUI project is licensed under the MS-PL license.

Sponsorship

Through contributions, donations, and sponsorship, you allow ReactiveUI to thrive. Your donations directly support meetups, office hours, continued enhancements, and most importantly, great documentation and learning material!

Backers

[Become a backer]

Sponsors

[Become a sponsor]