IMessenger Interface

Definition

Namespace:

Microsoft.Toolkit.Mvvm.Messaging

Assembly:

Microsoft.Toolkit.Mvvm.dll

Package:

Microsoft.Toolkit.Mvvm v7.1.2

An interface for a type providing the ability to exchange messages between different objects. This can be useful to decouple different modules of an application without having to keep strong references to types being referenced. It is also possible to send messages to specific channels, uniquely identified by a token, and to have different messengers in different sections of an applications. In order to use the IMessenger functionalities, first define a message type, like so:

public sealed class LoginCompletedMessage { }

Then, register your a recipient for this message:

Messenger.Default.Register<MyRecipientType, LoginCompletedMessage>(this, (r, m) =>
{
    // Handle the message here...
});

The message handler here is a lambda expression taking two parameters: the recipient and the message. This is done to avoid the allocations for the closures that would've been generated if the expression had captured the current instance. The recipient type parameter is used so that the recipient can be directly accessed within the handler without the need to manually perform type casts. This allows the code to be less verbose and more reliable, as all the checks are done just at build time. If the handler is defined within the same type as the recipient, it is also possible to directly access private members. This allows the message handler to be a static method, which enables the C# compiler to perform a number of additional memory optimizations (such as caching the delegate, avoiding unnecessary memory allocations). Finally, send a message when needed, like so:

Messenger.Default.Send<LoginCompletedMessage>();

Additionally, the method group syntax can also be used to specify the message handler to invoke when receiving a message, if a method with the right signature is available in the current scope. This is helpful to keep the registration and handling logic separate. Following up from the previous example, consider a class having this method:

private static void Receive(MyRecipientType recipient, LoginCompletedMessage message)
{
    // Handle the message there
}

The registration can then be performed in a single line like so:

Messenger.Default.Register(this, Receive);

The C# compiler will automatically convert that expression to a MessageHandler<TRecipient,TMessage> instance compatible with Register<TRecipient,TMessage>(IMessenger, TRecipient, MessageHandler<TRecipient,TMessage>). This will also work if multiple overloads of that method are available, each handling a different message type: the C# compiler will automatically pick the right one for the current message type. It is also possible to register message handlers explicitly using the IRecipient<TMessage> interface. To do so, the recipient just needs to implement the interface and then call the RegisterAll(IMessenger, Object) extension, which will automatically register all the handlers that are declared by the recipient type. Registration for individual handlers is supported as well.

public interface IMessenger

type IMessenger = interface

Public Interface IMessenger

Derived

Microsoft.Toolkit.Mvvm.Messaging.StrongReferenceMessenger

Microsoft.Toolkit.Mvvm.Messaging.WeakReferenceMessenger

Methods

Cleanup()	Performs a cleanup on the current messenger. Invoking this method does not unregister any of the currently registered recipient, and it can be used to perform cleanup operations such as trimming the internal data structures of a messenger implementation.
IsRegistered<TMessage,TToken>(Object, TToken)	Checks whether or not a given recipient has already been registered for a message.
Register<TRecipient,TMessage,TToken>(TRecipient, TToken, MessageHandler<TRecipient,TMessage>)	Registers a recipient for a given type of message.
Reset()	Resets the IMessenger instance and unregisters all the existing recipients.
Send<TMessage,TToken>(TMessage, TToken)	Sends a message of the specified type to all registered recipients.
Unregister<TMessage,TToken>(Object, TToken)	Unregisters a recipient from messages of a given type.
UnregisterAll(Object)	Unregisters a recipient from all registered messages.
UnregisterAll<TToken>(Object, TToken)	Unregisters a recipient from all messages on a specific channel.

Extension Methods

IsRegistered<TMessage>(IMessenger, Object)	Checks whether or not a given recipient has already been registered for a message.
Register<TMessage>(IMessenger, IRecipient<TMessage>)	Registers a recipient for a given type of message.
Register<TMessage>(IMessenger, Object, MessageHandler<Object,TMessage>)	Registers a recipient for a given type of message.
Register<TRecipient,TMessage>(IMessenger, TRecipient, MessageHandler<TRecipient,TMessage>)	Registers a recipient for a given type of message.
Register<TMessage,TToken>(IMessenger, IRecipient<TMessage>, TToken)	Registers a recipient for a given type of message.
Register<TMessage,TToken>(IMessenger, Object, TToken, MessageHandler<Object,TMessage>)	Registers a recipient for a given type of message.
RegisterAll(IMessenger, Object)	Registers all declared message handlers for a given recipient, using the default channel.
RegisterAll<TToken>(IMessenger, Object, TToken)	Registers all declared message handlers for a given recipient.
Send<TMessage>(IMessenger, TMessage)	Sends a message of the specified type to all registered recipients.
Send<TMessage>(IMessenger)	Sends a message of the specified type to all registered recipients.
Send<TMessage,TToken>(IMessenger, TToken)	Sends a message of the specified type to all registered recipients.
Unregister<TMessage>(IMessenger, Object)	Unregisters a recipient from messages of a given type.