Messenger Class

Implements the IMessenger interface and allows you to exchange messages between application modules.

Namespace: DevExpress.Mvvm

Assembly: DevExpress.WinUI.Mvvm.v23.2.dll

NuGet Package: DevExpress.WinUI

Declaration

C#

public class Messenger :
    IMessenger

VB.NET

Public Class Messenger
    Implements IMessenger

Remarks

Run Demo: Messenger Module in the WinUI MVVM Demo

The following example demonstrates how to exchange messages between application modules:

XAML

 <UserControl ...
    xmlns:dx="using:DevExpress.WinUI.Core"
    xmlns:ViewModel="using:WinUIApp.ViewModel" ...>

    <StackPanel Orientation="Vertical">
        <!--A Grid bound to the SenderViewModel--> 
        <Grid>
            <Grid.DataContext>
                <ViewModel:SenderViewModel/>
            </Grid.DataContext>
            <!--Click the button to send a message-->
            <Button Content="Send Message" Command="{x:Bind SendMessageCommand}"/>
        </Grid>
        <!--A Grid bound to the ReceiverViewModel--> 
        <Grid>
            <Grid.DataContext>
                <ViewModel:ReceiverViewModel/>
            </Grid.DataContext>
            <TextBlock Text="{x:Bind ReceivedMessage, Mode=OneWay}" />
        </Grid>
    </StackPanel>
</UserControl>

C#

using DevExpress.Mvvm;

namespace MVVMDemo.ViewModelsInteraction {
    // Sender ViewModel
    public class SenderViewModel : BindableBase {
        public DelegateCommand SendMessageCommand { get; }
        public SenderViewModel() {
            SendMessageCommand = new DelegateCommand(() => SendMessage());
        }
        public void SendMessage() {
            Messenger.Default.Send("Hello world!");
        }
    }
    // Receiver ViewModel
    public class ReceiverViewModel : BindableBase {
        public string ReceivedMessage { get => GetValue<string>(); set => SetValue(value); }
        public ReceiverViewModel() {
            Messenger.Default.Register<string>(this, OnMessage);
        }
        void OnMessage(string message) {
            ReceivedMessage = "Received: " + message;
        }
    }
} 

VB.NET

Imports DevExpress.Mvvm

Namespace MVVMDemo.ViewModelsInteraction
    ' Sender ViewModel
    Public Class SenderViewModel
        Inherits BindableBase

        Private privateSendMessageCommand As DelegateCommand
        Public Property SendMessageCommand() As DelegateCommand
            Get
                Return privateSendMessageCommand
            End Get
            Private Set(ByVal value As DelegateCommand)
                privateSendMessageCommand = value
            End Set
        End Property
        Public Sub New()
            SendMessageCommand = New DelegateCommand(Sub() SendMessage())
        End Sub
        Public Sub SendMessage()
            Messenger.Default.Send("Hello world!")
        End Sub
    End Class
    ' Receiver ViewModel
    Public Class ReceiverViewModel
        Inherits BindableBase

        Public Property ReceivedMessage() As String
            Get
                Return GetValue(Of String)()
            End Get
            Set(ByVal value As String)
                SetValue(value)
            End Set
        End Property
        Public Sub New()
            Messenger.Default.Register(Of String)(Me, AddressOf OnMessage)
        End Sub
        Private Sub OnMessage(ByVal message As String)
            ReceivedMessage = "Received: " & message
        End Sub
    End Class
End Namespace

Default Messenger

The static Messenger.Default property returns a default Messenger instance. The default messenger is not multi-thread safe and stores weak references.

Change the Default Messenger

To change the default messenger, create a new Messenger instance and pass it to the static Messenger.Default property.

The following code sample replaces the default Messenger with a multi-thread safe Messenger instance:

C#

public partial class App : Application {
    public App() {
        Messenger.Default = new Messenger(isMultiThreadSafe: true, actionReferenceType: ActionReferenceType.WeakReference);
    }
}

VB.NET

Public Partial Class App
    Inherits Application
    Public Sub New()
        Messenger.[Default] = New Messenger(isMultiThreadSafe := True, actionReferenceType := ActionReferenceType.WeakReference)
    End Sub
End Class

Send and Receive Messages

Call the Register and Send methods to recieve and send messages.

C#

public static void Register<TMessage>(this IMessenger messenger, object recipient, Action<TMessage> action);
public static void Send<TMessage>(this IMessenger messenger, TMessage message);

VB.NET

<System.Runtime.CompilerServices.Extension> _
Public Shared Sub Register(Of TMessage)(messenger As IMessenger, recipient As Object, action As Action(Of TMessage))
<System.Runtime.CompilerServices.Extension> _
Public Shared Sub Send(Of TMessage)(messenger As IMessenger, message As TMessage)

The following code sample sends and receives messages with different types:

C#

public class MyMessage {
    //...
}
public class Recipient {
    public Recipient() {
        // Receives messages of the `string` type.
        Messenger.Default.Register<string>(this, OnMessage1);
        // Receives messages of a custom `MyMessage` type.
        Messenger.Default.Register<MyMessage>(this, OnMessage2);
    }
    void SendMessages() {
        // Sends messages of the `string` type.
        Messenger.Default.Send("test");
        // Sends messages of a custom `MyMessage` type.
        Messenger.Default.Send(new MyMessage());
    }
    void OnMessage1(string message) {
        //...
    }
    void OnMessage2(MyMessage message) {
        //...
    }
}

VB.NET

Public Class MyMessage
    '...
End Class
Public Class Recipient
    Public Sub New()
        ' Receives messages of the `string` type.
        Messenger.[Default].Register(Of String)(Me, AddressOf OnMessage1)
        ' Receives messages of a custom `MyMessage` type.
        Messenger.[Default].Register(Of MyMessage)(Me, AddressOf OnMessage2)
    End Sub
    Private Sub SendMessages()
        ' Sends messages of the `string` type.
        Messenger.[Default].Send("test")
        '  Sends messages of a custom `MyMessage` type.
        Messenger.[Default].Send(New MyMessage())
    End Sub
    Private Sub OnMessage1(message As String)
        '...
    End Sub
    Private Sub OnMessage2(message As MyMessage)
        '...
    End Sub
End Class

Send and Receive Message Descendants

When you subscribe to a message with a custom type, you can invoke your handler if a message descendant is received.

Use the following methods to work with the messages with custom inherited types:

C#

public static void Register<TMessage>(this IMessenger messenger, object recipient, bool receiveInheritedMessagesToo, Action<TMessage> action);
public static void Send<TMessage>(this IMessenger messenger, TMessage message);

VB.NET

<System.Runtime.CompilerServices.Extension> _
Public Shared Sub Register(Of TMessage)(messenger As IMessenger, recipient As Object, receiveInheritedMessagesToo As Boolean, action As Action(Of TMessage))
<System.Runtime.CompilerServices.Extension> _
Public Shared Sub Send(Of TMessage)(messenger As IMessenger, message As TMessage)

The code sample below invokes a handler when a message descendant is received:

C#

public class InheritedMessage : MyMessage {
    // ...
}
public class Recipient {
    public Recipient() {
        // Inherited messages are not processed with this subscription
        Messenger.Default.Register<MyMessage>(
            recipient: this, 
            action: OnMessage);
        // Inherited messages are processed with this subscription
        Messenger.Default.Register<MyMessage>(
            recipient: this, 
            receiveInheritedMessagesToo: true,
            action: OnMessage);
    }
    void SendMessages() {
        Messenger.Default.Send(new MyMessage());
        Messenger.Default.Send(new InheritedMessage());
    }
    void OnMessage(MyMessage message) {
        // ...
    }
}

VB.NET

Public Class InheritedMessage
    Inherits MyMessage
    ' ...
End Class
Public Class Recipient
    Public Sub New()
        ' Inherited messages are not processed with this subscription
        Messenger.[Default].Register(Of MyMessage)(recipient := Me, action := AddressOf OnMessage)
        ' Inherited messages are processed with this subscription
        Messenger.[Default].Register(Of MyMessage)(recipient := Me, receiveInheritedMessagesToo := True, action := AddressOf OnMessage)
    End Sub
    Private Sub SendMessages()
        Messenger.[Default].Send(New MyMessage())
        Messenger.[Default].Send(New InheritedMessage())
    End Sub
    Private Sub OnMessage(message As MyMessage)
        ' ...
    End Sub
End Class

Messages With Tokens

You can invoke message handlers when a message with a particular token is received. Use the following methods to work with messages with tokens:

C#

public static void Register<TMessage>(this IMessenger messenger, object recipient, object token, Action<TMessage> action);
public static void Send<TMessage>(this IMessenger messenger, TMessage message, object token);

VB.NET

<System.Runtime.CompilerServices.Extension> _
Public Shared Sub Register(Of TMessage)(messenger As IMessenger, recipient As Object, token As Object, action As Action(Of TMessage))
<System.Runtime.CompilerServices.Extension> _
Public Shared Sub Send(Of TMessage)(messenger As IMessenger, message As TMessage, token As Object)

The code sample below invokes handlers when a message with a specified token is received:

C#

public enum MessageToken { Type1, Type2 }
public class Recipient {
    public Recipient() {
        Messenger.Default.Register<MyMessage>(
            recipient: this, 
            token: MessageToken.Type1,
            action: OnMessage1);
        Messenger.Default.Register<MyMessage>(
            recipient: this, 
            token: MessageToken.Type2,
            action: OnMessage2);
    }
    void SendMessages() {
        Messenger.Default.Send(message: new MyMessage(), token: MessageToken.Type1);
        Messenger.Default.Send(message: new MyMessage(), token: MessageToken.Type2);
    }
    void OnMessage1(MyMessage message) {
        //...
    }
    void OnMessage2(MyMessage message) {
        //...
    }
}

VB.NET

Public Enum MessageToken
    Type1
    Type2
End Enum
Public Class Recipient
    Public Sub New()
        Messenger.[Default].Register(Of MyMessage)(recipient := Me, token := MessageToken.Type1, action := AddressOf OnMessage1)
        Messenger.[Default].Register(Of MyMessage)(recipient := Me, token := MessageToken.Type2, action := AddressOf OnMessage2)
    End Sub
    Private Sub SendMessages()
        Messenger.[Default].Send(message := New MyMessage(), token := MessageToken.Type1)
        Messenger.[Default].Send(message := New MyMessage(), token := MessageToken.Type2)
    End Sub
    Private Sub OnMessage1(message As MyMessage)
        '...
    End Sub
    Private Sub OnMessage2(message As MyMessage)
        '...
    End Sub
End Class

Unregister Message Handlers

A Messenger With Weak References

If you use a Messenger with weak references (the Default Messenger), you do not need to unregister message handlers. When you subscribe to messengers with weak references, it does not cause memory leaks.

A Messenger With Strong References

You can use a Messenger instance that works with strong references:

C#

Messenger messenger = new Messenger(isMultiThreadSafe: false, actionReferenceType: ActionReferenceType.StrongReference);

VB.NET

Dim messenger As New Messenger(isMultiThreadSafe := False, actionReferenceType := ActionReferenceType.StrongReference)

To avoid memory leaks, unregister message handlers with any of the following methods:

C#

// Unsubscribe from a specific message
void IMessenger.Unregister<TMessage>(object recipient, object token, Action<TMessage> action);
// Unsubscribe a recipient from all messages
void IMessenger.Unregister(object recipient);

VB.NET

' Unsubscribe from a specific message
Sub Unregister(recipient As Object, token As Object, action As Action(Of TMessage)) Implements IMessenger(Of TMessage).Unregister
' Unsubscribe a recipient from all messages
Sub Unregister(recipient As Object) Implements IMessenger(Of TMessage).Unregister

Closures in Message Handlers

The weak reference messenger (like the default messenger) imposes a limitation for lambda expressions with outer variables (closures).

The weak reference messenger refers to a lambda expression with a weak reference. If the garbage collector collects the lambda expression object, the message handler is not invoked.

In the code below, the lambda method refers to the text variable that is defined outside the lambda. In this case, this lambda can be collected and never called.

C#

public class Recipient {
    public Recipient(string text) {
        // WARNING!
        // The lambda may be collected and never called.
        Messenger.Default.Register<Message>(this, x => {
            var str = text;
            //...
        });
    }
}

VB.NET

Public Class Recipient
    Public Sub New(text As String)
        ' WARNING!
        ' The lambda may be collected and never called.
        Messenger.[Default].Register(Of Message)(Me, 
            Function(x) 
                Dim str = text
                '...
            End Function)
    End Sub
End Class

To prevent a lambda expression object from being collected, declare the text variable as a property at the subscriber object level:

C#

public class Recipient {
    string MyProperty {get; set;}
    public Recipient(string text) {
        MyProperty = text;
        Messenger.Default.Register<Message>(this, x => {
            var str = MyProperty;
            //...
        });
    }
}

VB.NET

Public Class Recipient
    Private MyProperty As String
    Public Sub New(text As String)
        MyProperty = text
        Messenger.[Default].Register(Of Message)(Me, 
            Function(x) 
                Dim str = MyProperty
                '...
            End Function)
    End Sub
End Class

You can also store the message handler:

C#

public class Recipient {
    Action<Message> messageHandler;
    public Recipient(string text) {
        messageHandler = x => {
            var str = text;
            //...
        };
        Messenger.Default.Register<Message>(this, messageHandler);
    }
}

VB.NET

Public Class Recipient
    Private messageHandler As Action(Of Message)
    Public Sub New(text As String)
        messageHandler = Function(x) 
            Dim str = text
            '...
        End Function
        Messenger.[Default].Register(Of Message)(Me, messageHandler)
    End Sub
End Class

If your lambda expression does not use outer variables, your message handler is invoked without any limitations.

Implements

IMessenger

Inheritance

Object

Messenger

Extension Methods

Register<TMessage>(Object, Action<TMessage>)

Register<TMessage>(Object, Boolean, Action<TMessage>)

Register<TMessage>(Object, Object, Action<TMessage>)

Send<TMessage>(TMessage)

Send<TMessage, TTarget>(TMessage)

Send<TMessage>(TMessage, Object)

Unregister<TMessage>(Object)

Unregister<TMessage>(Object, Object)

Unregister<TMessage>(Object, Action<TMessage>)