ReactiveUI.Validation
4.1.1
Prefix Reserved
dotnet add package ReactiveUI.Validation --version 4.1.1
NuGet\Install-Package ReactiveUI.Validation -Version 4.1.1
<PackageReference Include="ReactiveUI.Validation" Version="4.1.1" />
paket add ReactiveUI.Validation --version 4.1.1
#r "nuget: ReactiveUI.Validation, 4.1.1"
// Install ReactiveUI.Validation as a Cake Addin #addin nuget:?package=ReactiveUI.Validation&version=4.1.1 // Install ReactiveUI.Validation as a Cake Tool #tool nuget:?package=ReactiveUI.Validation&version=4.1.1
<a href="https://github.com/reactiveui/ReactiveUI.Validation"> <img width="140" heigth="140" src="https://github.com/reactiveui/ReactiveUI.Validation/blob/main/media/logo.png"> </a>
ReactiveUI.Validation
Validation for ReactiveUI based solutions, functioning in a reactive way. ReactiveUI.Validation
was originally developed by @jcmm33 as Vistian.Reactive.Validation, and then refactored and updated by Àlex Martínez Morón and the ReactiveUI Core Team. ReactiveUI.Validation
supports all platforms, including .NET Framework, .NET Standard, .NET Core, Maui.
NuGet Packages
Install the following package into your class library and into a platform-specific project.
Platform | ReactiveUI Package | NuGet |
---|---|---|
Any Platform | ReactiveUI.Validation | |
AndroidX (Maui, Xamarin) | ReactiveUI.Validation.AndroidX | |
Xamarin.Android | ReactiveUI.Validation.AndroidSupport |
How to Use
- For ViewModels which need validation, implement
IValidatableViewModel
. - Add validation rules to the ViewModel using the
ValidationRule
extension methods. - Bind to the validation rules in the View via
BindValidation
orINotifyDataErrorInfo
.
Example
- Decorate existing ViewModel with
IValidatableViewModel
, which has a single member,ValidationContext
. The ValidationContext contains all of the functionality surrounding the validation of the ViewModel. Most access to the specification of validation rules is performed through extension methods on theIValidatableViewModel
interface. Then, add validation to the ViewModel.
using ReactiveUI.Validation.Extensions;
public class SampleViewModel : ReactiveObject, IValidatableViewModel
{
public SampleViewModel()
{
// Creates the validation for the Name property.
this.ValidationRule(
viewModel => viewModel.Name,
name => !string.IsNullOrWhiteSpace(name),
"You must specify a valid name");
}
public ValidationContext ValidationContext { get; } = new ValidationContext();
private string _name;
public string Name
{
get => _name;
set => this.RaiseAndSetIfChanged(ref _name, value);
}
}
For more complex validation scenarios there are several more overloads of the ValidationRule
extension method that accept observables. These allow validation to occur asynchronously, and allows complex chains of observables to be combined to produce validation results.
The simplest accepts an IObservable<bool>
where the observed boolean indicates whether the ValidationRule
is valid or not. The overload accepts a message which is used when the observable produces a false
(invalid) result.
IObservable<bool> passwordsObservable =
this.WhenAnyValue(
x => x.Password,
x => x.ConfirmPassword,
(password, confirmation) => password == confirmation);
this.ValidationRule(
vm => vm.ConfirmPassword,
passwordsObservable,
"Passwords must match.");
Any existing observables can be used to drive a ValidationRule
using the extension method overload that accepts an arbitrary IObservable<TState>
streams of events. The overload accepts a custom validation function that is supplied with the latest TState
, and a custom error message function, responsible for formatting the latest TState
object. The syntax for this looks as follows:
// IObservable<{ Password, Confirmation }>
var passwordsObservable =
this.WhenAnyValue(
x => x.Password,
x => x.ConfirmPassword,
(password, confirmation) =>
new { Password = password, Confirmation = confirmation });
this.ValidationRule(
vm => vm.ConfirmPassword,
passwordsObservable,
state => state.Password == state.Confirmation,
state => $"Passwords must match: {state.Password} != {state.Confirmation}");
Note The function to extract a message (
messageFunc
) is only invoked if the function to establish validity (isValidFunc
) returnsfalse
, otherwise the message is set tostring.Empty
.
Finally, you can directly supply an observable that streams any object (or struct) that implements IValidationState
; or you can use the ValidationState
base class which already implements the interface. As the resulting object is stored directly against the context without further transformation, this can be the most performant approach:
IObservable<IValidationState> usernameNotEmpty =
this.WhenAnyValue(x => x.UserName)
.Select(name => string.IsNullOrEmpty(name)
? new ValidationState(false, "The username must not be empty")
: ValidationState.Valid);
this.ValidationRule(vm => vm.UserName, usernameNotEmpty);
Note As a valid
ValidationState
does not really require a message, there is a singletonValidationState.Valid
property that you are encouraged to use to indicate a valid state whenever possible, to reduce memory allocations.
- Add validation presentation to the View.
using ReactiveUI.Validation.Extensions;
public class SampleView : ReactiveContentPage<SampleViewModel>
{
public SampleView()
{
InitializeComponent();
this.WhenActivated(disposables =>
{
this.Bind(ViewModel, vm => vm.Name, view => view.Name.Text)
.DisposeWith(disposables);
// Bind any validations that reference the Name property
// to the text of the NameError UI control.
this.BindValidation(ViewModel, vm => vm.Name, view => view.NameError.Text)
.DisposeWith(disposables);
// Bind any validations attached to this particular view model
// to the text of the FormErrors UI control.
this.BindValidation(ViewModel, view => view.FormErrors.Text)
.DisposeWith(disposables);
});
}
}
Note
Name
is an<Entry />
,NameError
is a<Label />
, andFormErrors
is a<Label />
as well. All these controls are from the Xamarin.Forms library.
Example with Android Extensions
There are extensions methods for Xamarin.Android and its Material design control TextInputLayout
. These extensions use internally the Error
property from the TextInputLayout
control, allowing you to implement a fully native behavior to showing validation errors. To use these extensions you must import ReactiveUI.Validation.Extensions
and install either ReactiveUI.Validation.AndroidSupport
or ReactiveUI.Validation.AndroidX
:
dotnet add package ReactiveUI.Validation.AndroidX
Note In ReactiveUI.Validation 1.7 and lower, the Android-specific extensions are available in the main package targeting
MonoAndroid90
, and you don't need to installReactiveUI.Validation.AndroidSupport
. In ReactiveUI.Validation 1.7 and lower, addusing ReactiveUI.Validation.Platforms.Android
instead ofusing ReactiveUI.Validation.Extensions
.
<img src="https://user-images.githubusercontent.com/6759207/96716730-15729480-13ae-11eb-928e-7e408b7ffac4.png" width="400" />
// This using directive makes Android-specific extensions available.
// Make sure to install either the ReactiveUI.Validation.AndroidSupport
// package or the ReactiveUI.Validation.AndroidX package.
using ReactiveUI.Validation.Extensions;
public class SignUpActivity : ReactiveAppCompatActivity<SignUpViewModel>
{
// The Android native text boxes declared in an .axml file.
public TextInputEditText Password { get; set; }
public TextInputEditText ConfirmPassword { get; set; }
// The layouts wrapping the text boxes declared in an .axml file.
public TextInputLayout PasswordField { get; set; }
public TextInputLayout ConfirmPasswordField { get; set; }
protected override void OnCreate (Bundle bundle)
{
base.OnCreate(bundle);
SetContentView(Resource.Layout.Main);
// The WireUpControls method is a magic ReactiveUI utility method for Android, see:
// https://www.reactiveui.net/docs/handbook/data-binding/xamarin-android/wire-up-controls
this.WireUpControls();
this.Bind(ViewModel, x => x.Password, x => x.Password.Text);
this.Bind(ViewModel, x => x.ConfirmPassword, x => x.ConfirmPassword.Text);
// Bind any validations which reference the Password property
// to the Error property of the TextInputLayout control.
this.BindValidation(ViewModel, x => x.Password, PasswordField);
this.BindValidation(ViewModel, x => x.ConfirmPassword, ConfirmPasswordField);
}
}
INotifyDataErrorInfo
Support
For those platforms that support the INotifyDataErrorInfo
interface, ReactiveUI.Validation provides a helper base class named ReactiveValidationObject
. The helper class implements both the IValidatableViewModel
interface and the INotifyDataErrorInfo
interface. It listens to any changes in the ValidationContext
and invokes INotifyDataErrorInfo
events.
<img width="400" src="https://user-images.githubusercontent.com/6759207/96717163-bbbe9a00-13ae-11eb-8c54-89cd339cbd5c.png">
using ReactiveUI.Validation.Extensions;
public class SampleViewModel : ReactiveValidationObject
{
public SampleViewModel()
{
this.ValidationRule(
viewModel => viewModel.Name,
name => !string.IsNullOrWhiteSpace(name),
"Name shouldn't be null or white space.");
}
private string _name = string.Empty;
public string Name
{
get => _name;
set => this.RaiseAndSetIfChanged(ref _name, value);
}
}
Note Keep in mind that
INotifyDataErrorInfo
is only supported via XAML binding. ReactiveUI binding doesn't use the inbuilt classes of WPF.
When using a ValidationRule
overload that accepts an observable, please remember to supply the property which the validation rule is targeting as the first argument. Otherwise it is not possible for INotifyDataErrorInfo
to conclude which property the error message is for.
this.ValidationRule(
vm => vm.ConfirmPassword,
passwordsObservable,
"Passwords must match.");
Custom Formatters
You can pass an instance of IValidationTextFormatter<T>
to a call to BindValidation
if you'd like to override the default SingleLineFormatter
used in the validation library. The SingleLineFormatter
accepts a separator char and uses whitespace by default, so the code snippet below shows how to use a non-default separator char:
// This formatter is based on the default SingleLineFormatter but uses a custom separator char.
var formatter = new SingleLineFormatter(Environment.NewLine);
this.BindValidation(ViewModel, x => x.ErrorLabel.Text, formatter)
.DisposeWith(disposables);
The simplest possible custom IValidationTextFormatter<TOut>
implementation may look like this one.
private class ConstFormatter : IValidationTextFormatter<string>
{
private readonly string _text;
public ConstFormatter(string text = "The input is invalid.") => _text = text;
public string Format(ValidationText validationText) => _text;
}
// This formatter is based on a custom IValidationTextFormatter implementation.
var formatter = new ConstFormatter("The input is invalid.");
this.BindValidation(ViewModel, x => x.ErrorLabel.Text, formatter)
.DisposeWith(disposables);
If you'd like to override the IValidationTextFormatter<string>
used in ReactiveUI.Validation by default, register an instance of IValidationTextFormatter<string>
into Locator.CurrentMutable
before your app starts. This could be useful in cases when your app needs localization and you wish to pass message keys instead of messages to ValidationRule
calls.
// Register a singleton instance of IValidationTextFormatter<string> into Splat.Locator.
Locator.CurrentMutable.RegisterConstant(new CustomFormatter(), typeof(IValidationTextFormatter<string>));
Capabilities
In essence, ReactiveUI.Validation is a relatively simple model of the ValidationContext
containing a list of IValidationComponent
instances. An IValidationComponent
provides an observable of IValidationState
. Whenever validation state changes (either a transition of validity) or ValidationText
changes, then a new value is pushed out.
- Rules can be composed of single or multiple properties along with more generic Observables.
- Validation text can encapsulate both valid and invalid states.
- Binding can occur to either a View or an action.
- Validation text can reference either the ViewModel or properties which comprise the validation rule e.g. include text entered as part of validation message.
- Validation text output can be adjusted using custom formatters, not only allowing for single & multiline output but also for platforms like Android it should be possible to achieve richer renderings i.e. Bold/italics.
Feedback
Please use GitHub issues for questions, comments, or bug reports.
Contribute
ReactiveUI.Validation is developed under an OSI-approved open source license, making it freely usable and distributable, even for commercial use. We ❤ the people who are involved in this project, and we’d love to have you on board, especially if you are just getting started or have never contributed to open-source before.
So here's to you, lovely person who wants to join us — this is how you can support us:
- Responding to questions on StackOverflow
- Passing on knowledge and teaching the next generation of developers
- Submitting documentation updates where you see fit or lacking.
- Making contributions to the code base.
Copyright and License
Code released under the MIT license.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net6.0-windows10.0.17763 is compatible. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-android34.0 is compatible. net8.0-browser was computed. net8.0-ios was computed. net8.0-ios17.5 is compatible. net8.0-maccatalyst was computed. net8.0-maccatalyst17.5 is compatible. net8.0-macos was computed. net8.0-macos14.5 is compatible. net8.0-tvos was computed. net8.0-tvos17.5 is compatible. net8.0-windows was computed. net8.0-windows10.0.17763 is compatible. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 is compatible. net463 was computed. net47 was computed. net471 was computed. net472 is compatible. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETFramework 4.6.2
- ReactiveUI (>= 20.1.63)
- System.Collections.Immutable (>= 8.0.0)
-
.NETFramework 4.7.2
- ReactiveUI (>= 20.1.63)
- System.Collections.Immutable (>= 8.0.0)
-
.NETStandard 2.0
- ReactiveUI (>= 20.1.63)
- System.Collections.Immutable (>= 8.0.0)
-
net6.0
- ReactiveUI (>= 20.1.63)
-
net6.0-windows10.0.17763
- ReactiveUI (>= 20.1.63)
-
net8.0
- ReactiveUI (>= 20.1.63)
-
net8.0-android34.0
- ReactiveUI (>= 20.1.63)
-
net8.0-ios17.5
- ReactiveUI (>= 20.1.63)
-
net8.0-maccatalyst17.5
- ReactiveUI (>= 20.1.63)
-
net8.0-macos14.5
- ReactiveUI (>= 20.1.63)
-
net8.0-tvos17.5
- ReactiveUI (>= 20.1.63)
-
net8.0-windows10.0.17763
- ReactiveUI (>= 20.1.63)
NuGet packages (12)
Showing the top 5 NuGet packages that depend on ReactiveUI.Validation:
Package | Downloads |
---|---|
Zafiro.UI
The Cross-platform Crema for .NET Devs |
|
Zafiro.Avalonia.FileExplorer
Package Description |
|
ArtemisRGB.UI.Shared
Package Description |
|
KH.UIBase
InstrumentBaseLib |
|
Acorisoft.Island
Island 设计语言(预览版) |
GitHub repositories (15)
Showing the top 5 popular GitHub repositories that depend on ReactiveUI.Validation:
Repository | Stars |
---|---|
shadowsocks/shadowsocks-windows
A C# port of shadowsocks
|
|
AvaloniaUI/Avalonia
Develop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The most popular .NET UI client technology
|
|
2dust/clashN
A clash client for Windows, support Mihomo
|
|
Artemis-RGB/Artemis
Provides advanced unified lighting across many different brands RGB peripherals
|
|
database64128/youtube-dl-wpf
A simple GUI wrapper for youtube-dl and yt-dlp.
|
Version | Downloads | Last updated |
---|---|---|
4.1.1 | 5,026 | 9/25/2024 |
4.0.9 | 19,155 | 5/11/2024 |
4.0.6 | 492 | 5/7/2024 |
3.1.7 | 111,883 | 2/1/2023 |
3.0.22 | 56,976 | 11/25/2022 |
3.0.1 | 31,470 | 6/28/2022 |
2.2.1 | 64,622 | 9/29/2021 |
2.1.1 | 55,596 | 1/22/2021 |
2.0.1 | 4,456 | 12/13/2020 |
1.8.6 | 12,467 | 10/22/2020 |
1.8.1 | 1,120 | 10/19/2020 |
1.7.1 | 1,771 | 10/15/2020 |
1.6.4 | 1,122 | 10/12/2020 |
1.5.5 | 6,400 | 7/28/2020 |
1.5.3 | 1,144 | 7/26/2020 |
1.4.15 | 15,427 | 5/7/2020 |
1.4.13 | 4,935 | 4/1/2020 |
1.4.10 | 9,120 | 1/31/2020 |
1.4.8 | 1,068 | 1/31/2020 |
1.4.7 | 2,174 | 1/14/2020 |
1.4.6 | 1,693 | 12/26/2019 |
1.4.1 | 11,958 | 9/21/2019 |
1.3.1 | 993 | 9/21/2019 |
1.2.1 | 8,389 | 5/13/2019 |
1.1.1 | 13,788 | 5/7/2019 |
1.0.13 | 1,243 | 4/1/2019 |
1.0.3 | 1,315 | 2/26/2019 |
1.0.2 | 1,020 | 2/26/2019 |
1.0.0 | 1,458 | 7/26/2020 |