Class IMessengerExtensions

Namespace

CommunityToolkit.Mvvm.Messaging

Assembly

CommunityToolkit.Mvvm.dll

Extensions for the IMessenger type.

public static class IMessengerExtensions

Inheritance

object

IMessengerExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

CreateObservable<TMessage>(IMessenger)

Creates an IObservable<T> instance that can be used to be notified whenever a message of a given type is broadcast by a messenger.

public static IObservable<TMessage> CreateObservable<TMessage>(this IMessenger messenger) where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

Returns

IObservable<TMessage>

An IObservable<T> instance to receive notifications for TMessage messages being broadcast.

Type Parameters

TMessage

The type of message to use to receive notification for through the resulting IObservable<T> instance.

Exceptions

ArgumentNullException

Thrown if messenger is null.

CreateObservable<TMessage, TToken>(IMessenger, TToken)

Creates an IObservable<T> instance that can be used to be notified whenever a message of a given type is broadcast by a messenger.

public static IObservable<TMessage> CreateObservable<TMessage, TToken>(this IMessenger messenger, TToken token) where TMessage : class where TToken : IEquatable<TToken>

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

token TToken

A token used to determine the receiving channel to use.

Returns

IObservable<TMessage>

An IObservable<T> instance to receive notifications for TMessage messages being broadcast.

Type Parameters

TMessage

The type of message to use to receive notification for through the resulting IObservable<T> instance.

TToken

The type of token to identify what channel to use to receive messages.

Exceptions

ArgumentNullException

Thrown if messenger or token are null.

IsRegistered<TMessage>(IMessenger, object)

Checks whether or not a given recipient has already been registered for a message.

public static bool IsRegistered<TMessage>(this IMessenger messenger, object recipient) where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to check the registration.

recipient object

The target recipient to check the registration for.

Returns

bool

Whether or not recipient has already been registered for the specified message.

Type Parameters

TMessage

The type of message to check for the given recipient.

Remarks

This method will use the default channel to check for the requested registration.

Exceptions

ArgumentNullException

Thrown if messenger or recipient are null.

RegisterAll(IMessenger, object)

Registers all declared message handlers for a given recipient, using the default channel.

public static void RegisterAll(this IMessenger messenger, object recipient)

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient object

The recipient that will receive the messages.

Remarks

See notes for RegisterAll<TToken>(IMessenger, object, TToken) for more info.

Exceptions

ArgumentNullException

Thrown if messenger or recipient are null.

RegisterAll<TToken>(IMessenger, object, TToken)

Registers all declared message handlers for a given recipient.

public static void RegisterAll<TToken>(this IMessenger messenger, object recipient, TToken token) where TToken : IEquatable<TToken>

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient object

The recipient that will receive the messages.

token TToken

The token indicating what channel to use.

Type Parameters

TToken

The type of token to identify what channel to use to receive messages.

Remarks

This method will register all messages corresponding to the IRecipient<TMessage> interfaces being implemented by recipient. If none are present, this method will do nothing. Note that unlike all other extensions, this method will use reflection to find the handlers to register. Once the registration is complete though, the performance will be exactly the same as with handlers registered directly through any of the other generic extensions for the IMessenger interface.

Exceptions

ArgumentNullException

Thrown if messenger, recipient or token are null.

Register<TMessage>(IMessenger, IRecipient<TMessage>)

Registers a recipient for a given type of message.

public static void Register<TMessage>(this IMessenger messenger, IRecipient<TMessage> recipient) where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient IRecipient<TMessage>

The recipient that will receive the messages.

Type Parameters

TMessage

The type of message to receive.

Remarks

This method will use the default channel to perform the requested registration.

Exceptions

InvalidOperationException

Thrown when trying to register the same message twice.

ArgumentNullException

Thrown if messenger or recipient are null.

Register<TMessage>(IMessenger, object, MessageHandler<object, TMessage>)

Registers a recipient for a given type of message.

public static void Register<TMessage>(this IMessenger messenger, object recipient, MessageHandler<object, TMessage> handler) where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient object

The recipient that will receive the messages.

handler MessageHandler<object, TMessage>

The MessageHandler<TRecipient, TMessage> to invoke when a message is received.

Type Parameters

TMessage

The type of message to receive.

Remarks

This method will use the default channel to perform the requested registration.

Exceptions

InvalidOperationException

Thrown when trying to register the same message twice.

ArgumentNullException

Thrown if messenger, recipient or handler are null.

Register<TMessage, TToken>(IMessenger, IRecipient<TMessage>, TToken)

Registers a recipient for a given type of message.

public static void Register<TMessage, TToken>(this IMessenger messenger, IRecipient<TMessage> recipient, TToken token) where TMessage : class where TToken : IEquatable<TToken>

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient IRecipient<TMessage>

The recipient that will receive the messages.

token TToken

The token indicating what channel to use.

Type Parameters

TMessage

The type of message to receive.

TToken

The type of token to identify what channel to use to receive messages.

Remarks

This method will use the default channel to perform the requested registration.

Exceptions

InvalidOperationException

Thrown when trying to register the same message twice.

ArgumentNullException

Thrown if messenger, recipient or token are null.

Register<TMessage, TToken>(IMessenger, object, TToken, MessageHandler<object, TMessage>)

Registers a recipient for a given type of message.

public static void Register<TMessage, TToken>(this IMessenger messenger, object recipient, TToken token, MessageHandler<object, TMessage> handler) where TMessage : class where TToken : IEquatable<TToken>

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient object

The recipient that will receive the messages.

token TToken

A token used to determine the receiving channel to use.

handler MessageHandler<object, TMessage>

The MessageHandler<TRecipient, TMessage> to invoke when a message is received.

Type Parameters

TMessage

The type of message to receive.

TToken

The type of token to use to pick the messages to receive.

Exceptions

InvalidOperationException

Thrown when trying to register the same message twice.

ArgumentNullException

Thrown if messenger, recipient or handler are null.

Register<TRecipient, TMessage>(IMessenger, TRecipient, MessageHandler<TRecipient, TMessage>)

Registers a recipient for a given type of message.

public static void Register<TRecipient, TMessage>(this IMessenger messenger, TRecipient recipient, MessageHandler<TRecipient, TMessage> handler) where TRecipient : class where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to register the recipient.

recipient TRecipient

The recipient that will receive the messages.

handler MessageHandler<TRecipient, TMessage>

The MessageHandler<TRecipient, TMessage> to invoke when a message is received.

Type Parameters

TRecipient

The type of recipient for the message.

TMessage

The type of message to receive.

Remarks

This method will use the default channel to perform the requested registration.

Exceptions

InvalidOperationException

Thrown when trying to register the same message twice.

ArgumentNullException

Thrown if messenger, recipient or handler are null.

Send<TMessage>(IMessenger)

Sends a message of the specified type to all registered recipients.

public static TMessage Send<TMessage>(this IMessenger messenger) where TMessage : class, new()

Parameters

messenger IMessenger

The IMessenger instance to use to send the message.

Returns

TMessage

The message that has been sent.

Type Parameters

TMessage

The type of message to send.

Remarks

This method is a shorthand for Send<TMessage>(IMessenger, TMessage) when the message type exposes a parameterless constructor: it will automatically create a new TMessage instance and send that to its recipients.

Exceptions

ArgumentNullException

Thrown if messenger is null.

Send<TMessage>(IMessenger, TMessage)

Sends a message of the specified type to all registered recipients.

public static TMessage Send<TMessage>(this IMessenger messenger, TMessage message) where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to send the message.

message TMessage

The message to send.

Returns

TMessage

The message that was sent (ie. message).

Type Parameters

TMessage

The type of message to send.

Exceptions

ArgumentNullException

Thrown if messenger or message are null.

Send<TMessage, TToken>(IMessenger, TToken)

Sends a message of the specified type to all registered recipients.

public static TMessage Send<TMessage, TToken>(this IMessenger messenger, TToken token) where TMessage : class, new() where TToken : IEquatable<TToken>

Parameters

messenger IMessenger

The IMessenger instance to use to send the message.

token TToken

The token indicating what channel to use.

Returns

TMessage

The message that has been sen.

Type Parameters

TMessage

The type of message to send.

TToken

The type of token to identify what channel to use to send the message.

Remarks

This method will automatically create a new TMessage instance just like Send<TMessage>(IMessenger), and then send it to the right recipients.

Exceptions

ArgumentNullException

Thrown if messenger or token are null.

Unregister<TMessage>(IMessenger, object)

Unregisters a recipient from messages of a given type.

public static void Unregister<TMessage>(this IMessenger messenger, object recipient) where TMessage : class

Parameters

messenger IMessenger

The IMessenger instance to use to unregister the recipient.

recipient object

The recipient to unregister.

Type Parameters

TMessage

The type of message to stop receiving.

Remarks

This method will unregister the target recipient only from the default channel. If the recipient has no registered handler, this method does nothing.

Exceptions

ArgumentNullException

Thrown if messenger or recipient are null.