MVVM with CommunityToolkit.Mvvm

Why use a toolkit?

In the last two lessons you wrote MVVM by hand: a ViewModelBase with SetProperty, a RelayCommand, and setters that call RaiseCanExecuteChanged. Doing it once is the best way to understand MVVM. Doing it in every app is boring, and every line of boilerplate is a place for a bug.

CommunityToolkit.Mvvm (often called the MVVM Toolkit) is a free, open source library from Microsoft and the .NET community that does this work for you. It gives you:

• ObservableObject: a ready made base class with INotifyPropertyChanged and SetProperty.
• [ObservableProperty]: an attribute that writes the property and its change notification for you.
• [RelayCommand]: an attribute that turns a method into a command property.
• RelayCommand, AsyncRelayCommand and their generic versions, for when you want to create commands yourself.
• A messenger for talking between view models, covered in Messaging Between ViewModels.

The attributes work through source generators: compiler add-ons that write extra C# code while your project builds. You never see that code in your files, but it is compiled into your app. The C# course has a whole lesson on source generators if you are curious how they work.

From this lesson onward, every CoinJar view model uses the toolkit.

Install the package

From the project folder:

dotnet add package CommunityToolkit.Mvvm

In Visual Studio you can also right click the project, choose Manage NuGet Packages, and search for CommunityToolkit.Mvvm. Your .csproj gets a line like this:

<PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.2" />

ObservableObject and [ObservableProperty]

Here is one property written by hand, the way you did it before:

private string _newTitle = "";

public string NewTitle
{
    get => _newTitle;
    set => SetProperty(ref _newTitle, value);
}

With the toolkit it becomes one line:

using CommunityToolkit.Mvvm.ComponentModel;

namespace CoinJar.ViewModels;

public partial class ExpenseListViewModel : ObservableObject
{
    [ObservableProperty]
    public partial string NewTitle { get; set; } = "";
}

Three things matter here:

1. The class inherits from ObservableObject.
2. The class is partial. The generator writes the other half of the class in a hidden file, and C# joins the two halves.
3. The property is a partial property: you declare it, and the generator writes the body that stores the value and raises PropertyChanged.

Partial properties need C# 13 or newer. A .NET 10 project uses C# 14 by default, so this just works.

The older field form

Many tutorials (and older projects) put the attribute on a private field instead:

[ObservableProperty]
private string newTitle = "";   // generates a public NewTitle property

This still works, and the generator turns newTitle (or _newTitle) into a property called NewTitle. The partial property form is the newer, recommended style: you see the real property name in your code and it works better with other C# features. This course uses partial properties.

Reacting when a property changes

Sometimes setting one property should do something else. The toolkit generates partial methods you can fill in. For a property called NewTitle you get OnNewTitleChanging and OnNewTitleChanged:

partial void OnNewTitleChanged(string value)
{
    // Runs after NewTitle got a new value
    StatusText = value.Length > 40 ? "That title is quite long" : "";
}

You only write the ones you need. If you do not write them, they cost nothing.

Dependent properties

When another property depends on this one, add [NotifyPropertyChangedFor]. The generator then raises PropertyChanged for both:

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FormIsValid))]
public partial decimal NewAmount { get; set; }

public bool FormIsValid => !string.IsNullOrWhiteSpace(NewTitle) && NewAmount > 0;

[RelayCommand]: commands from methods

Put [RelayCommand] on a method and the toolkit creates a command property for it. The name is the method name plus Command:

using CommunityToolkit.Mvvm.Input;

[RelayCommand]
private void Delete(Expense? expense)    // generates DeleteCommand
{
    if (expense is not null) Expenses.Remove(expense);
}

The method has a parameter, so DeleteCommand is an IRelayCommand<Expense> and the CommandParameter from the view arrives as expense. The XAML does not change at all:

<Button Content="Delete"
        Command="{Binding DataContext.DeleteCommand, RelativeSource={RelativeSource AncestorType=Window}}"
        CommandParameter="{Binding}" />

CanExecute

To add a “can it run?” check, name a method or property with CanExecute:

[RelayCommand(CanExecute = nameof(CanAdd))]
private void Add()
{
    Expenses.Add(new Expense { Title = NewTitle.Trim(), Amount = NewAmount, Category = NewCategory });
    NewTitle = "";
    NewAmount = 0;
}

private bool CanAdd() => !string.IsNullOrWhiteSpace(NewTitle) && NewAmount > 0;

Remember the bug from Commands and ICommand: the button needs to be told when CanAdd might change. Instead of writing setters, add [NotifyCanExecuteChangedFor] to each input property:

[ObservableProperty]
[NotifyCanExecuteChangedFor(nameof(AddCommand))]
public partial string NewTitle { get; set; } = "";

[ObservableProperty]
[NotifyCanExecuteChangedFor(nameof(AddCommand))]
public partial decimal NewAmount { get; set; }

Now every time NewTitle or NewAmount changes, AddCommand raises CanExecuteChanged and the button updates.

Async commands

If the method returns a Task, the toolkit makes an async command (IAsyncRelayCommand). A trailing Async in the method name is dropped, so LoadAsync becomes LoadCommand:

[RelayCommand]
private async Task LoadAsync()
{
    await Task.Delay(1000); // pretend to read from disk or the web
    Expenses.Add(new Expense { Title = "Cinema", Amount = 11m, Category = "Fun" });
}

An async command is much safer than async void:

• While the task runs, LoadCommand.IsRunning is true, so you can show a spinner.
• By default the command cannot run again until the first run finishes, so a double click does not load twice. Set AllowConcurrentExecutions = true if you want to allow it.
• With a CancellationToken parameter and IncludeCancelCommand = true, you also get a LoadCancelCommand for a Cancel button.

<Button Content="Load sample data" Command="{Binding LoadCommand}" />
<TextBlock Text="Loading..."
           Visibility="{Binding LoadCommand.IsRunning, Converter={StaticResource BoolToVisibility}}" />

BoolToVisibility is a BooleanToVisibilityConverter declared in resources, as in Value Converters. More on keeping the UI smooth in Async, Await and a Responsive UI and the C# lesson on async and await.

The model becomes observable too

Until now, editing an expense in place (for example in a DataGrid) did not update the total, because Expense did not raise PropertyChanged. Make it an ObservableObject as well:

public partial class Expense : ObservableObject
{
    public int Id { get; set; }

    [ObservableProperty]
    public partial string Title { get; set; } = "";

    [ObservableProperty]
    public partial decimal Amount { get; set; }

    [ObservableProperty]
    public partial string Category { get; set; } = "Other";

    [ObservableProperty]
    public partial DateTime Date { get; set; } = DateTime.Today;
}

Now the view model can listen to each expense’s PropertyChanged and refresh Total when an amount is edited. The full version in the code panel does this.

Before and after

You can now delete ViewModelBase.cs and RelayCommand.cs from CoinJar.

Common mistakes

• Forgetting partial. Both the class and the property must be partial, or you get a compile error such as “partial property must have an implementation part”.
• Binding to the method name. [RelayCommand] on Add() creates AddCommand. Bind to AddCommand, not Add.
• Writing to a backing field directly. If you set a field yourself, no notification is raised. Always set the property.
• Mixing old and new styles by accident. It is fine to use the field form in old code, but do not put [ObservableProperty] on both a field and a property with the same name.
• Inheriting from ObservableObject twice. If your class already has a base class, use the [ObservableObject] or [INotifyPropertyChanged] class attributes instead. Prefer the base class when you can.

Quick recap

• Install CommunityToolkit.Mvvm and inherit view models from ObservableObject.
• [ObservableProperty] public partial string Title { get; set; } writes the notifying property for you, in a partial class.
• Fill in partial void OnTitleChanged(...) to react to changes, and use [NotifyPropertyChangedFor] for dependent properties.
• [RelayCommand] turns a method into NameCommand. Use CanExecute = nameof(...) and [NotifyCanExecuteChangedFor] to enable and disable it.
• Methods that return Task become async commands with IsRunning and protection against double runs.
• Next, in Dependency Injection with the Generic Host, you stop creating view models with new.