ObservableRecipient Class

Definition

A base class for observable objects that also acts as recipients for messages. This class is an extension of ObservableObject which also provides built-in support to use the IMessenger type.

public abstract class ObservableRecipient : Microsoft.Toolkit.Mvvm.ComponentModel.ObservableObject
type ObservableRecipient = class
    inherit ObservableObject
Public MustInherit Class ObservableRecipient
Inherits ObservableObject
Inheritance
ObservableRecipient

Constructors

ObservableRecipient()

Initializes a new instance of the ObservableRecipient class.

ObservableRecipient(IMessenger)

Initializes a new instance of the ObservableRecipient class.

Properties

IsActive

Gets or sets a value indicating whether the current view model is currently active.

Messenger

Gets the IMessenger instance in use.

Methods

Broadcast<T>(T, T, String)

Broadcasts a PropertyChangedMessage<T> with the specified parameters, without using any particular token (so using the default channel).

OnActivated()

Raised whenever the IsActive property is set to true. Use this method to register to messages and do other initialization for this instance.

OnDeactivated()

Raised whenever the IsActive property is set to false. Use this method to unregister from messages and do general cleanup for this instance.

OnPropertyChanged(PropertyChangedEventArgs)

Raises the PropertyChanged event.

(Inherited from ObservableObject)
OnPropertyChanged(String)

Raises the PropertyChanged event.

(Inherited from ObservableObject)
OnPropertyChanging(PropertyChangingEventArgs)

Raises the PropertyChanging event.

(Inherited from ObservableObject)
OnPropertyChanging(String)

Raises the PropertyChanging event.

(Inherited from ObservableObject)
SetProperty<T>(T, T, Action<T>, Boolean, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. Similarly to the SetProperty<T>(T, T, Action<T>, String) method, this overload should only be used when SetProperty<T>(T, T, String) can't be used directly.

SetProperty<T>(T, T, Action<T>, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. This overload is much less efficient than SetProperty<T>(T, T, String) and it should only be used when the former is not viable (eg. when the target property being updated does not directly expose a backing field that can be passed by reference). For performance reasons, it is recommended to use a stateful callback if possible through the SetProperty<TModel,T>(T, T, TModel, Action<TModel,T>, String) whenever possible instead of this overload, as that will allow the C# compiler to cache the input callback and reduce the memory allocations. More info on that overload are available in the related XML docs. This overload is here for completeness and in cases where that is not applicable.

(Inherited from ObservableObject)
SetProperty<T>(T, T, Boolean, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event.

SetProperty<T>(T, T, IEqualityComparer<T>, Action<T>, Boolean, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. See additional notes about this overload in SetProperty<T>(T, T, Action<T>, Boolean, String).

SetProperty<T>(T, T, IEqualityComparer<T>, Action<T>, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. See additional notes about this overload in SetProperty<T>(T, T, Action<T>, String).

(Inherited from ObservableObject)
SetProperty<T>(T, T, IEqualityComparer<T>, Boolean, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. See additional notes about this overload in SetProperty<T>(T, T, Boolean, String).

SetProperty<T>(T, T, IEqualityComparer<T>, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event. See additional notes about this overload in SetProperty<T>(T, T, String).

(Inherited from ObservableObject)
SetProperty<T>(T, T, String)

Compares the current and new values for a given property. If the value has changed, raises the PropertyChanging event, updates the property with the new value, then raises the PropertyChanged event.

(Inherited from ObservableObject)
SetProperty<TModel,T>(T, T, IEqualityComparer<T>, TModel, Action<TModel,T>, Boolean, String)

Compares the current and new values for a given nested property. If the value has changed, raises the PropertyChanging event, updates the property and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<TModel,T>(T, T, IEqualityComparer<T>, TModel, Action<TModel,T>, String), with the difference being that this method is used to relay properties from a wrapped model in the current instance. For more info, see the docs for SetProperty<TModel,T>(T, T, IEqualityComparer<T>, TModel, Action<TModel,T>, String).

SetProperty<TModel,T>(T, T, IEqualityComparer<T>, TModel, Action<TModel,T>, String)

Compares the current and new values for a given nested property. If the value has changed, raises the PropertyChanging event, updates the property and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<T>(T, T, String), with the difference being that this method is used to relay properties from a wrapped model in the current instance. See additional notes about this overload in SetProperty<TModel,T>(T, T, TModel, Action<TModel,T>, String).

(Inherited from ObservableObject)
SetProperty<TModel,T>(T, T, TModel, Action<TModel,T>, Boolean, String)

Compares the current and new values for a given nested property. If the value has changed, raises the PropertyChanging event, updates the property and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<TModel,T>(T, T, TModel, Action<TModel,T>, String), with the difference being that this method is used to relay properties from a wrapped model in the current instance. For more info, see the docs for SetProperty<TModel,T>(T, T, TModel, Action<TModel,T>, String).

SetProperty<TModel,T>(T, T, TModel, Action<TModel,T>, String)

Compares the current and new values for a given nested property. If the value has changed, raises the PropertyChanging event, updates the property and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<T>(T, T, String), with the difference being that this method is used to relay properties from a wrapped model in the current instance. This type is useful when creating wrapping, bindable objects that operate over models that lack support for notification (eg. for CRUD operations). Suppose we have this model (eg. for a database row in a table):

public class Person
{
    public string Name { get; set; }
}

We can then use a property to wrap instances of this type into our observable model (which supports notifications), injecting the notification to the properties of that model, like so:

public class BindablePerson : ObservableObject
{
    public Model { get; }

    public BindablePerson(Person model)
    {
        Model = model;
    }

    public string Name
    {
        get => Model.Name;
        set => Set(Model.Name, value, Model, (model, name) => model.Name = name);
    }
}

This way we can then use the wrapping object in our application, and all those "proxy" properties will also raise notifications when changed. Note that this method is not meant to be a replacement for SetProperty<T>(T, T, String), and it should only be used when relaying properties to a model that doesn't support notifications, and only if you can't implement notifications to that model directly (eg. by having it inherit from ObservableObject). The syntax relies on passing the target model and a stateless callback to allow the C# compiler to cache the function, which results in much better performance and no memory usage.

(Inherited from ObservableObject)
SetPropertyAndNotifyOnCompletion(ObservableObject+TaskNotifier, Task, Action<Task>, String)

Compares the current and new values for a given field (which should be the backing field for a property). If the value has changed, raises the PropertyChanging event, updates the field and then raises the PropertyChanged event. This method is just like SetPropertyAndNotifyOnCompletion(ObservableObject+TaskNotifier, Task, String), with the difference being an extra Action<T> parameter with a callback being invoked either immediately, if the new task has already completed or is null, or upon completion.

(Inherited from ObservableObject)
SetPropertyAndNotifyOnCompletion(ObservableObject+TaskNotifier, Task, String)

Compares the current and new values for a given field (which should be the backing field for a property). If the value has changed, raises the PropertyChanging event, updates the field and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<T>(T, T, String), with the difference being that this method will also monitor the new value of the property (a generic Task) and will also raise the PropertyChanged again for the target property when it completes. This can be used to update bindings observing that Task or any of its properties. This method and its overload specifically rely on the ObservableObject.TaskNotifier type, which needs to be used in the backing field for the target Task property. The field doesn't need to be initialized, as this method will take care of doing that automatically. The ObservableObject.TaskNotifier type also includes an implicit operator, so it can be assigned to any Task instance directly. Here is a sample property declaration using this method:

private TaskNotifier myTask;

public Task MyTask
{
    get => myTask;
    private set => SetAndNotifyOnCompletion(ref myTask, value);
}
(Inherited from ObservableObject)
SetPropertyAndNotifyOnCompletion<T>(ObservableObject.TaskNotifier, Task<T>, Action<Task<T>>, String)

Compares the current and new values for a given field (which should be the backing field for a property). If the value has changed, raises the PropertyChanging event, updates the field and then raises the PropertyChanged event. This method is just like SetPropertyAndNotifyOnCompletion<T>(ObservableObject.TaskNotifier, Task<T>, String), with the difference being an extra Action<T> parameter with a callback being invoked either immediately, if the new task has already completed or is null, or upon completion.

(Inherited from ObservableObject)
SetPropertyAndNotifyOnCompletion<T>(ObservableObject.TaskNotifier, Task<T>, String)

Compares the current and new values for a given field (which should be the backing field for a property). If the value has changed, raises the PropertyChanging event, updates the field and then raises the PropertyChanged event. The behavior mirrors that of SetProperty<T>(T, T, String), with the difference being that this method will also monitor the new value of the property (a generic Task) and will also raise the PropertyChanged again for the target property when it completes. This can be used to update bindings observing that Task or any of its properties. This method and its overload specifically rely on the ObservableObject.TaskNotifier<T> type, which needs to be used in the backing field for the target Task property. The field doesn't need to be initialized, as this method will take care of doing that automatically. The ObservableObject.TaskNotifier<T> type also includes an implicit operator, so it can be assigned to any Task instance directly. Here is a sample property declaration using this method:

private TaskNotifier<int> myTask;

public Task<int> MyTask
{
    get => myTask;
    private set => SetAndNotifyOnCompletion(ref myTask, value);
}
(Inherited from ObservableObject)

Events

PropertyChanged (Inherited from ObservableObject)
PropertyChanging (Inherited from ObservableObject)

Applies to