Table of Contents

Class ObservableObject

Namespace
CommunityToolkit.Mvvm.ComponentModel
Assembly
CommunityToolkit.Mvvm.dll

A base class for objects of which the properties must be observable.

public abstract class ObservableObject : INotifyPropertyChanged, INotifyPropertyChanging
Inheritance
ObservableObject
Implements
Derived
Inherited Members

Constructors

ObservableObject() 

protected ObservableObject()

Methods

OnPropertyChanged(PropertyChangedEventArgs)

Raises the PropertyChanged event.

protected virtual void OnPropertyChanged(PropertyChangedEventArgs e)

Parameters

e PropertyChangedEventArgs

The input PropertyChangedEventArgs instance.

Exceptions

ArgumentNullException

Thrown if e is null.

OnPropertyChanged(string?)

Raises the PropertyChanged event.

protected void OnPropertyChanged(string? propertyName = null)

Parameters

propertyName string

(optional) The name of the property that changed.

OnPropertyChanging(PropertyChangingEventArgs)

Raises the PropertyChanging event.

protected virtual void OnPropertyChanging(PropertyChangingEventArgs e)

Parameters

e PropertyChangingEventArgs

The input PropertyChangingEventArgs instance.

Exceptions

ArgumentNullException

Thrown if e is null.

OnPropertyChanging(string?)

Raises the PropertyChanging event.

protected void OnPropertyChanging(string? propertyName = null)

Parameters

propertyName string

(optional) The name of the property that changed.

SetPropertyAndNotifyOnCompletion(ref 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(ref 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.

protected bool SetPropertyAndNotifyOnCompletion(ref ObservableObject.TaskNotifier? taskNotifier, Task? newValue, Action<Task?> callback, string? propertyName = null)

Parameters

taskNotifier ObservableObject.TaskNotifier

The field notifier to modify.

newValue Task

The property's value after the change occurred.

callback Action<Task>

A callback to invoke to update the property value.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

Exceptions

ArgumentNullException

Thrown if callback is null.

SetPropertyAndNotifyOnCompletion(ref 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>(ref 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);
}
protected bool SetPropertyAndNotifyOnCompletion(ref ObservableObject.TaskNotifier? taskNotifier, Task? newValue, string? propertyName = null)

Parameters

taskNotifier ObservableObject.TaskNotifier

The field notifier to modify.

newValue Task

The property's value after the change occurred.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same. The return value being true only indicates that the new value being assigned to taskNotifier is different than the previous one, and it does not mean the new Task instance passed as argument is in any particular state.

SetPropertyAndNotifyOnCompletion<T>(ref TaskNotifier<T>?, 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>(ref TaskNotifier<T>?, 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.

protected bool SetPropertyAndNotifyOnCompletion<T>(ref ObservableObject.TaskNotifier<T>? taskNotifier, Task<T>? newValue, Action<Task<T>?> callback, string? propertyName = null)

Parameters

taskNotifier ObservableObject.TaskNotifier<T>

The field notifier to modify.

newValue Task<T>

The property's value after the change occurred.

callback Action<Task<T>>

A callback to invoke to update the property value.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of result for the Task<TResult> to set and monitor.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

Exceptions

ArgumentNullException

Thrown if callback is null.

SetPropertyAndNotifyOnCompletion<T>(ref TaskNotifier<T>?, 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>(ref 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);
}
protected bool SetPropertyAndNotifyOnCompletion<T>(ref ObservableObject.TaskNotifier<T>? taskNotifier, Task<T>? newValue, string? propertyName = null)

Parameters

taskNotifier ObservableObject.TaskNotifier<T>

The field notifier to modify.

newValue Task<T>

The property's value after the change occurred.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of result for the Task<TResult> to set and monitor.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same. The return value being true only indicates that the new value being assigned to taskNotifier is different than the previous one, and it does not mean the new Task<TResult> instance passed as argument is in any particular state.

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>(ref 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.

protected bool SetProperty<T>(T oldValue, T newValue, Action<T> callback, string? propertyName = null)

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

callback Action<T>

A callback to invoke to update the property value.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

Exceptions

ArgumentNullException

Thrown if callback is null.

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?).

protected bool SetProperty<T>(T oldValue, T newValue, IEqualityComparer<T> comparer, Action<T> callback, string? propertyName = null)

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

comparer IEqualityComparer<T>

The IEqualityComparer<T> instance to use to compare the input values.

callback Action<T>

A callback to invoke to update the property value.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Exceptions

ArgumentNullException

Thrown if comparer or callback are null.

SetProperty<T>(ref 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>(ref T, T, string?).

protected bool SetProperty<T>(ref T field, T newValue, IEqualityComparer<T> comparer, string? propertyName = null)

Parameters

field T

The field storing the property's value.

newValue T

The property's value after the change occurred.

comparer IEqualityComparer<T>

The IEqualityComparer<T> instance to use to compare the input values.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Exceptions

ArgumentNullException

Thrown if comparer is null.

SetProperty<T>(ref 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.

protected bool SetProperty<T>(ref T field, T newValue, string? propertyName = null)

Parameters

field T

The field storing the property's value.

newValue T

The property's value after the change occurred.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

T

The type of the property that changed.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

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>(ref 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?).

protected bool SetProperty<TModel, T>(T oldValue, T newValue, IEqualityComparer<T> comparer, TModel model, Action<TModel, T> callback, string? propertyName = null) where TModel : class

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

comparer IEqualityComparer<T>

The IEqualityComparer<T> instance to use to compare the input values.

model TModel

The model containing the property being updated.

callback Action<TModel, T>

The callback to invoke to set the target property value, if a change has occurred.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

TModel

The type of model whose property (or field) to set.

T

The type of property (or field) to set.

Exceptions

ArgumentNullException

Thrown if comparer, model or callback are null.

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>(ref 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>(ref 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.

protected bool SetProperty<TModel, T>(T oldValue, T newValue, TModel model, Action<TModel, T> callback, string? propertyName = null) where TModel : class

Parameters

oldValue T

The current property value.

newValue T

The property's value after the change occurred.

model TModel

The model containing the property being updated.

callback Action<TModel, T>

The callback to invoke to set the target property value, if a change has occurred.

propertyName string

(optional) The name of the property that changed.

Returns

bool

true if the property was changed, false otherwise.

Type Parameters

TModel

The type of model whose property (or field) to set.

T

The type of property (or field) to set.

Remarks

The PropertyChanging and PropertyChanged events are not raised if the current and new value for the target property are the same.

Exceptions

ArgumentNullException

Thrown if model or callback are null.

Events

PropertyChanged 

public event PropertyChangedEventHandler? PropertyChanged

Event Type

PropertyChangedEventHandler

PropertyChanging 

public event PropertyChangingEventHandler? PropertyChanging

Event Type

PropertyChangingEventHandler