Class ReactiveCommandBase<TParam, TResult>
- Namespace
- ReactiveUI
- Assembly
- ReactiveUI.dll
A base class for generic reactive commands.
public abstract class ReactiveCommandBase<TParam, TResult> : IReactiveCommand<TParam, TResult>, IObservable<TResult>, IReactiveCommand, IDisposable, IHandleObservableErrors, ICommand
Type Parameters
TParam
The type of parameter values passed in during command execution.
TResult
The type of the values that are the result of command execution.
- Inheritance
-
ReactiveCommandBase<TParam, TResult>
- Implements
-
IReactiveCommand<TParam, TResult>IObservable<TResult>
- Derived
- Extension Methods
Remarks
This class extends ReactiveCommand and adds generic type parameters for the parameter values passed into command execution, and the return values of command execution.
Because the result type is known by this class, it can implement IObservable<T>. However, the implementation is defined as abstract, so subclasses must provide it.
Reactive commands encapsulate the behavior of running some execution logic and then surfacing the results on the UI
thread. Importantly, no scheduling is performed against input observables (the canExecute
and execution pipelines).
To create an instance of ReactiveCommand
, call one of the static creation methods defined by this class.
Create(Action, IObservable<bool>?, IScheduler?) can be used when your execution logic is synchronous.
ReactiveCommand.CreateFromObservable and
ReactiveCommand.CreateFromTask (and overloads) can be used for asynchronous
execution logic. Optionally, you can provide an observable that governs the availability of the command for execution,
as well as a scheduler to which events will be delivered.
The CanExecute property provides an observable that can be used to determine whether the command is
eligible for execution. The value of this observable is determined by both the canExecute
observable provided
during command creation, and the current execution status of the command. A command that is already executing will
yield false
from its CanExecute observable regardless of the canExecute
observable provided
during command creation.
The IsExecuting property provides an observable whose value indicates whether the command is currently executing. This can be a useful means of triggering UI, such as displaying an activity indicator whilst a command is executing.
As discussed above, you are under no obligation to somehow incorporate this into your canExecute
observable
because that is taken care of for you. That is, if the value of IsExecuting
is true
, the value of
CanExecute
will be false
. However, if the value of CanExecute
is false
, that does not imply
the value of IsExecuting
is true
.
Any errors in your command's execution logic (including any canExecute
observable you choose to provide) will be
surfaced via the ThrownExceptions observable. This gives you the opportunity to handle the error before
it triggers a default handler that tears down the application. For example, you might use this as a means of alerting
the user that something has gone wrong executing the command.
For the sake of convenience, all ReactiveCommand
instances are also implementations of ICommand.
This allows you to easily integrate instances of ReactiveCommand
into platforms that understands ICommand
natively (such as WPF and UWP).
Constructors
ReactiveCommandBase()
protected ReactiveCommandBase()
Properties
CanExecute
Gets an observable whose value indicates whether the command can currently execute.
public abstract IObservable<bool> CanExecute { get; }
Property Value
- IObservable<bool>
The can execute.
Remarks
The value provided by this observable is governed both by any canExecute
observable provided during
command creation, as well as the current execution status of the command. A command that is currently executing
will always yield false
from this observable, even if the canExecute
pipeline is currently true
.
IsExecuting
Gets an observable whose value indicates whether the command is currently executing.
public abstract IObservable<bool> IsExecuting { get; }
Property Value
- IObservable<bool>
The is executing.
Remarks
This observable can be particularly useful for updating UI, such as showing an activity indicator whilst a command is executing.
ThrownExceptions
Gets a observable which will fire whenever an exception would normally terminate ReactiveUI internal state.
public abstract IObservable<Exception> ThrownExceptions { get; }
Property Value
Methods
Dispose()
public void Dispose()
Dispose(bool)
Disposes of the managed resources.
protected abstract void Dispose(bool disposing)
Parameters
disposing
boolIf its getting called by the Dispose() method.
Execute()
Gets an observable that, when subscribed, executes this command.
public abstract IObservable<TResult> Execute()
Returns
- IObservable<TResult>
An observable that will tick the single result value if and when it becomes available.
Remarks
Invoking this method will return a cold (lazy) observable that, when subscribed, will execute the logic
encapsulated by the command. It is worth restating that the returned observable is lazy. Nothing will
happen if you call Execute
and neglect to subscribe (directly or indirectly) to the returned observable.
If no parameter value is provided, a default value of type TParam
will be passed into
the execution logic.
Any number of subscribers can subscribe to a given execution observable and the execution logic will only run once. That is, the result is broadcast to those subscribers.
In those cases where execution fails, there will be no result value. Instead, the failure will tick through the ThrownExceptions observable.
Execute(TParam)
Gets an observable that, when subscribed, executes this command.
public abstract IObservable<TResult> Execute(TParam parameter)
Parameters
parameter
TParamThe parameter to pass into command execution.
Returns
- IObservable<TResult>
An observable that will tick the single result value if and when it becomes available.
Remarks
Invoking this method will return a cold (lazy) observable that, when subscribed, will execute the logic
encapsulated by the command. It is worth restating that the returned observable is lazy. Nothing will
happen if you call Execute
and neglect to subscribe (directly or indirectly) to the returned observable.
If no parameter value is provided, a default value of type TParam
will be passed into
the execution logic.
Any number of subscribers can subscribe to a given execution observable and the execution logic will only run once. That is, the result is broadcast to those subscribers.
In those cases where execution fails, there will be no result value. Instead, the failure will tick through the ThrownExceptions observable.
ICommandCanExecute(object?)
Will be called by the methods from the ICommand interface. This method is called when the Command should evaluate if it can execute.
protected virtual bool ICommandCanExecute(object? parameter)
Parameters
parameter
objectThe parameter being passed to the ICommand.
Returns
- bool
If the command can be executed.
ICommandExecute(object?)
Will be called by the methods from the ICommand interface. This method is called when the Command should execute.
protected virtual void ICommandExecute(object? parameter)
Parameters
parameter
objectThe parameter being passed to the ICommand.
OnCanExecuteChanged(bool)
Will trigger a event when the CanExecute condition has changed.
protected void OnCanExecuteChanged(bool newValue)
Parameters
newValue
boolThe new value of the execute.
Subscribe(IObserver<TResult>)
Subscribes to execution results from this command.
public abstract IDisposable Subscribe(IObserver<TResult> observer)
Parameters
observer
IObserver<TResult>The observer.
Returns
- IDisposable
An IDisposable that, when disposed, will unsubscribe the observer.