mvvm-toolkit

CommunityToolkit.Mvvm (core)

Use this skill when authoring or reviewing ViewModels, properties, commands, or validation in apps that use CommunityToolkit.Mvvm 8.x.

Companion skills. If available from the same trusted catalog as this skill, load mvvm-toolkit-messenger for IMessenger pub/sub patterns and mvvm-toolkit-di for Microsoft.Extensions.DependencyInjection integration.

Quick recap. [ObservableProperty] on private fields in partial classes; [RelayCommand] on instance methods; inherit from ObservableObject (or ObservableValidator for input forms, ObservableRecipient when using IMessenger).

Partial properties. Newer 8.x releases also accept [ObservableProperty] on a partial property. That form needs a recent C# language version; the field form stays valid for older language versions.

Package & setup

<ItemGroup>
  <PackageReference Include="CommunityToolkit.Mvvm" Version="8.*" />
</ItemGroup>

For production projects, pin an exact, reviewed 8.x release instead of a floating range (or use a NuGet lock file), and raise the pin deliberately, because the package runs source generators inside the compiler.

Targets: netstandard2.0, netstandard2.1, net6.0+. Works on .NET, .NET Framework, Mono. Source generators ship in the same NuGet — no extra analyzer reference required.

Namespaces:

using CommunityToolkit.Mvvm.ComponentModel;   // ObservableObject, [ObservableProperty]
using CommunityToolkit.Mvvm.Input;             // [RelayCommand], RelayCommand, AsyncRelayCommand

Universal rule. Every type that uses [ObservableProperty] or [RelayCommand] — and every enclosing type, if nested — must be declared partial. Without it, the build fails with compiler errors.

Source generators cheat sheet

Naming. Field name / _name / m_name → Name. Method LoadAsync → LoadCommand (the Async suffix is stripped; a leading On is also stripped).

See references/source-generators.md for the full attribute reference with generated-code samples.

ViewModel patterns

Simple observable property

public partial class ContactViewModel : ObservableObject
{
    [ObservableProperty]
    private string? name;
}

Hooks: OnXxxChanging / OnXxxChanged

[ObservableProperty]
private string? name;

partial void OnNameChanged(string? value) =>
    Logger.LogInformation("Name changed to {Name}", value);

Both single-arg (value) and two-arg (oldValue, newValue) overloads are available. Implement only the ones you need; unimplemented hooks are elided by the compiler (zero runtime cost).

Dependent properties + dependent commands

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FullName))]
[NotifyCanExecuteChangedFor(nameof(SaveCommand))]
private string? firstName;

[ObservableProperty]
[NotifyPropertyChangedFor(nameof(FullName))]
[NotifyCanExecuteChangedFor(nameof(SaveCommand))]
private string? lastName;

public string FullName => $"{FirstName} {LastName}".Trim();

Wrapping a non-observable model

public sealed class ObservableUser(User user) : ObservableObject
{
    public string Name
    {
        get => user.Name;
        set => SetProperty(user.Name, value, user, static (u, n) => u.Name = n);
    }
}

Pass a static lambda (no captured state) to keep the call allocation-free.

Commands

[RelayCommand]
private void Refresh() => Items.Reset();

[RelayCommand]
private async Task LoadAsync()
{
    foreach (var item in await service.GetItemsAsync())
        Items.Add(item);
}

[RelayCommand(IncludeCancelCommand = true)]
private async Task DownloadAsync(CancellationToken token)
{
    await using var stream = await http.GetStreamAsync(url, token);
    // ...
}

[RelayCommand(CanExecute = nameof(CanSave))]
private Task SaveAsync() => repo.SaveAsync(Name!);

private bool CanSave() => !string.IsNullOrWhiteSpace(Name);

Reach for manual RelayCommand / AsyncRelayCommand constructors only when you must own the command's lifetime explicitly or compose it from non-trivial sources. The attribute style covers ~95% of cases.

See references/relaycommand-cookbook.md for sync / async / cancellable / concurrency / error-surfacing recipes.

Base class selection

C# is single-inheritance: ObservableValidator and ObservableRecipient both extend ObservableObject, so combining them requires composition (e.g., inject IMessenger into an ObservableValidator).

Validation

using System.ComponentModel.DataAnnotations;

public sealed partial class RegistrationViewModel : ObservableValidator
{
    [ObservableProperty]
    [NotifyDataErrorInfo]
    [Required, MinLength(2), MaxLength(100)]
    private string? name;

    [ObservableProperty]
    [NotifyDataErrorInfo]
    [Required, EmailAddress]
    private string? email;

    [RelayCommand]
    private void Submit()
    {
        ValidateAllProperties();
        if (HasErrors) return;
        // submit...
    }
}

Other entry points: TrySetProperty, ValidateProperty(value, name), ClearAllErrors(), GetErrors(propertyName). Custom rules support [CustomValidation] methods and custom ValidationAttribute subclasses.

See references/validation.md for the full validator surface area.

Top pitfalls

1. Forgetting partial. Class (and every enclosing type) must be partial, or the build fails with compiler errors.
2. PascalCase field name. [ObservableProperty] private string Name; collides with the generated property. Use name, _name, or m_name.
3. async void on [RelayCommand]. The generator only wraps Task-returning methods as IAsyncRelayCommand. async void becomes a sync RelayCommand and exceptions are unobserved. The toolkit also reports an analyzer diagnostic for this pattern. Always return Task.
4. Forgetting [NotifyCanExecuteChangedFor]. The Save button stays disabled even though CanSave() would now return true.
5. Mutating the same reference held by an [ObservableProperty] field. EqualityComparer<T>.Default returns true, no notification fires. Replace the instance instead of mutating it.

For the full diagnostic table (MVVMTK0xxx) and more pitfalls, see references/troubleshooting.md.

End-to-end mini walkthrough

A two-pane Notes app demonstrating generators + commands + [NotifyCanExecuteChangedFor]:

public sealed partial class NoteViewModel(INotesService notes,
    IMessenger messenger) : ObservableRecipient(messenger)
{
    [ObservableProperty]
    [NotifyCanExecuteChangedFor(nameof(SaveCommand))]
    [NotifyCanExecuteChangedFor(nameof(DeleteCommand))]
    private string? filename;

    [ObservableProperty]
    [NotifyCanExecuteChangedFor(nameof(SaveCommand))]
    private string? text;

    [RelayCommand(CanExecute = nameof(CanSave))]
    private async Task SaveAsync()
    {
        await notes.SaveAsync(Filename!, Text!);
        Messenger.Send(new NoteSavedMessage(Filename!));
    }

    [RelayCommand(CanExecute = nameof(CanDelete))]
    private Task DeleteAsync() => notes.DeleteAsync(Filename!);

    private bool CanSave() =>
        !string.IsNullOrWhiteSpace(Filename) && !string.IsNullOrEmpty(Text);
    private bool CanDelete() => !string.IsNullOrWhiteSpace(Filename);
}

For the full sample (DI wiring, View code-behind, XAML, unit tests), see references/end-to-end-walkthrough.md.

References & companion skills

External sources:

• Toolkit overview: https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/
• WinUI MVVM Toolkit tutorial: https://learn.microsoft.com/en-us/windows/apps/tutorials/winui-mvvm-toolkit/intro
• Source: https://github.com/CommunityToolkit/dotnet
• Samples: https://github.com/CommunityToolkit/MVVM-Samples