Mvvm-Toolkit-Messenger

# CommunityToolkit.Mvvm Messenger

Pub/sub messaging for ViewModels (or any objects) without forcing a shared

reference graph. Part of `CommunityToolkit.Mvvm` 8.x.

> **TL;DR.** Default to `WeakReferenceMessenger.Default`. Register handlers

> with the `(recipient, message)` lambda and the `static` modifier so you

> never capture `this`. Inherit from `ObservableRecipient` and toggle

> `IsActive` at activation/deactivation to get automatic register/unregister.

---

When to use this skill

- Two or more ViewModels need to react to an event (login, theme change,

save, navigation) without holding references to each other

- A ViewModel needs to ask another VM for a value (request/reply)

- You're scoping events to a sub-system or window with channel tokens

- Diagnosing "my handler never fires" or weak-reference recipient lifetime

problems

For source generators, base classes, and commands see the **`mvvm-toolkit`**

skill. For DI wiring (registering an `IMessenger` instance), see

**`mvvm-toolkit-di`**.

---

Choose an implementation

| Type | When |

|------|------|

| `WeakReferenceMessenger.Default` | **Default.** Recipients held weakly — eligible for GC even while registered. Internal trimming runs during full GCs; no manual `Cleanup()` needed. |

| `StrongReferenceMessenger.Default` | Profiler shows the messenger is hot and allocation matters. Recipients are pinned until you `Unregister`. Forgetting unregistration leaks them. |

| Custom `IMessenger` instance | Per-window/per-scope (e.g., one messenger per app window). Construct directly, inject via DI. |

`ObservableRecipient`'s parameterless constructor uses

`WeakReferenceMessenger.Default`. Pass a different `IMessenger` to its

constructor to override.

---

Define a message

The toolkit ships base classes; any class works.

using CommunityToolkit.Mvvm.Messaging.Messages;

// Single-payload broadcast
public sealed class LoggedInUserChangedMessage(User user)
    : ValueChangedMessage<User>(user);

// Custom shape (records are great for this)
public sealed record ThemeChangedMessage(AppTheme NewTheme);

// Empty signal
public sealed record RefreshRequestedMessage;

---

Register a recipient

Lambda style (recommended)

WeakReferenceMessenger.Default.Register<MyViewModel, ThemeChangedMessage>(
    this,
    static (recipient, message) => recipient.OnThemeChanged(message.NewTheme));

The `static` modifier prevents accidental closure allocation and keeps

`this` out of the lambda — use the `recipient` parameter instead.

`IRecipient<TMessage>` interface style

public sealed class MyViewModel : ObservableRecipient,
    IRecipient<ThemeChangedMessage>,
    IRecipient<RefreshRequestedMessage>
{
    public void Receive(ThemeChangedMessage message) { /* ... */ }
    public void Receive(RefreshRequestedMessage message) { /* ... */ }
}

`ObservableRecipient.OnActivated()` calls `Messenger.RegisterAll(this)`,

which subscribes every `IRecipient<T>` interface implemented by the type.

If you're not using `ObservableRecipient`, register manually:

WeakReferenceMessenger.Default.RegisterAll(this);

---

Send a message

WeakReferenceMessenger.Default.Send(new ThemeChangedMessage(AppTheme.Dark));

// Empty payloads use the parameterless overload:
WeakReferenceMessenger.Default.Send<RefreshRequestedMessage>();

---

Channels (tokens)

Scope messages to a sub-system or window with a token (any equatable

value — `int`, `string`, `Guid`):

const int LeftPaneChannel = 1;

WeakReferenceMessenger.Default.Register<MyViewModel, RefreshRequestedMessage, int>(
    this, LeftPaneChannel,
    static (r, _) => r.RefreshLeft());

WeakReferenceMessenger.Default.Send(new RefreshRequestedMessage(), LeftPaneChannel);

Messages sent without a token use the default shared channel — they are

**not** delivered to channel-scoped recipients.

---

Request / reply

For ask-style scenarios where a recipient provid