-
Notifications
You must be signed in to change notification settings - Fork 6
/
IMessenger.xml
363 lines (363 loc) · 21.7 KB
/
IMessenger.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
<Type Name="IMessenger" FullName="Microsoft.Toolkit.Mvvm.Messaging.IMessenger">
<TypeSignature Language="C#" Value="public interface IMessenger" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IMessenger" />
<TypeSignature Language="DocId" Value="T:Microsoft.Toolkit.Mvvm.Messaging.IMessenger" />
<TypeSignature Language="VB.NET" Value="Public Interface IMessenger" />
<TypeSignature Language="F#" Value="type IMessenger = interface" />
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<Interfaces />
<Docs>
<summary>
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 <see cref="T:Microsoft.Toolkit.Mvvm.Messaging.IMessenger" /> functionalities, first define a message type, like so:
<code>
public sealed class LoginCompletedMessage { }
</code>
Then, register your a recipient for this message:
<code>
Messenger.Default.Register<MyRecipientType, LoginCompletedMessage>(this, (r, m) =>
{
// Handle the message here...
});
</code>
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:
<code>
Messenger.Default.Send<LoginCompletedMessage>();
</code>
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:
<code>
private static void Receive(MyRecipientType recipient, LoginCompletedMessage message)
{
// Handle the message there
}
</code>
The registration can then be performed in a single line like so:
<code>
Messenger.Default.Register(this, Receive);
</code>
The C# compiler will automatically convert that expression to a <see cref="T:Microsoft.Toolkit.Mvvm.Messaging.MessageHandler`2" /> instance
compatible with <see cref="M:Microsoft.Toolkit.Mvvm.Messaging.IMessengerExtensions.Register``2(Microsoft.Toolkit.Mvvm.Messaging.IMessenger,``0,Microsoft.Toolkit.Mvvm.Messaging.MessageHandler{``0,``1})" />.
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 <see cref="T:Microsoft.Toolkit.Mvvm.Messaging.IRecipient`1" /> interface.
To do so, the recipient just needs to implement the interface and then call the
<see cref="M:Microsoft.Toolkit.Mvvm.Messaging.IMessengerExtensions.RegisterAll(Microsoft.Toolkit.Mvvm.Messaging.IMessenger,System.Object)" /> extension, which will automatically register
all the handlers that are declared by the recipient type. Registration for individual handlers is supported as well.
</summary>
<remarks>To be added.</remarks>
</Docs>
<Members>
<Member MemberName="Cleanup">
<MemberSignature Language="C#" Value="public void Cleanup ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Cleanup() cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.Cleanup" />
<MemberSignature Language="VB.NET" Value="Public Sub Cleanup ()" />
<MemberSignature Language="F#" Value="abstract member Cleanup : unit -> unit" Usage="iMessenger.Cleanup " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>
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.
</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="IsRegistered<TMessage,TToken>">
<MemberSignature Language="C#" Value="public bool IsRegistered<TMessage,TToken> (object recipient, TToken token) where TMessage : class where TToken : IEquatable<TToken>;" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance bool IsRegistered<class TMessage, (class System.IEquatable`1<!!TToken>) TToken>(object recipient, !!TToken token) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.IsRegistered``2(System.Object,``1)" />
<MemberSignature Language="VB.NET" Value="Public Function IsRegistered(Of TMessage As Class, TToken As Class) (recipient As Object, token As TToken) As Boolean" />
<MemberSignature Language="F#" Value="abstract member IsRegistered : obj * 'oken -> bool (requires 'Message : null and 'oken :> IEquatable<'oken>)" Usage="iMessenger.IsRegistered (recipient, token)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<TypeParameters>
<TypeParameter Name="TMessage">
<Constraints>
<ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
</Constraints>
</TypeParameter>
<TypeParameter Name="TToken">
<Constraints>
<InterfaceName>System.IEquatable<TToken></InterfaceName>
</Constraints>
</TypeParameter>
</TypeParameters>
<Parameters>
<Parameter Name="recipient" Type="System.Object" />
<Parameter Name="token" Type="TToken" />
</Parameters>
<Docs>
<typeparam name="TMessage">The type of message to check for the given recipient.</typeparam>
<typeparam name="TToken">The type of token to check the channel for.</typeparam>
<param name="recipient">The target recipient to check the registration for.</param>
<param name="token">The token used to identify the target channel to check.</param>
<summary>
Checks whether or not a given recipient has already been registered for a message.
</summary>
<returns>Whether or not <paramref name="recipient" /> has already been registered for the specified message.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Register<TRecipient,TMessage,TToken>">
<MemberSignature Language="C#" Value="public void Register<TRecipient,TMessage,TToken> (TRecipient recipient, TToken token, Microsoft.Toolkit.Mvvm.Messaging.MessageHandler<TRecipient,TMessage> handler) where TRecipient : class where TMessage : class where TToken : IEquatable<TToken>;" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Register<class TRecipient, class TMessage, (class System.IEquatable`1<!!TToken>) TToken>(!!TRecipient recipient, !!TToken token, class Microsoft.Toolkit.Mvvm.Messaging.MessageHandler`2<!!TRecipient, !!TMessage> handler) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.Register``3(``0,``2,Microsoft.Toolkit.Mvvm.Messaging.MessageHandler{``0,``1})" />
<MemberSignature Language="VB.NET" Value="Public Sub Register(Of TRecipient As Class, TMessage As Class, TToken As Class) (recipient As TRecipient, token As TToken, handler As MessageHandler(Of TRecipient, TMessage))" />
<MemberSignature Language="F#" Value="abstract member Register : 'Recipient * 'oken * Microsoft.Toolkit.Mvvm.Messaging.MessageHandler<'Recipient, 'Message (requires 'Recipient : null and 'Message : null)> -> unit (requires 'Recipient : null and 'Message : null and 'oken :> IEquatable<'oken>)" Usage="iMessenger.Register (recipient, token, handler)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<TypeParameters>
<TypeParameter Name="TRecipient">
<Constraints>
<ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
</Constraints>
</TypeParameter>
<TypeParameter Name="TMessage">
<Constraints>
<ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
</Constraints>
</TypeParameter>
<TypeParameter Name="TToken">
<Constraints>
<InterfaceName>System.IEquatable<TToken></InterfaceName>
</Constraints>
</TypeParameter>
</TypeParameters>
<Parameters>
<Parameter Name="recipient" Type="TRecipient" />
<Parameter Name="token" Type="TToken" />
<Parameter Name="handler" Type="Microsoft.Toolkit.Mvvm.Messaging.MessageHandler<TRecipient,TMessage>" />
</Parameters>
<Docs>
<typeparam name="TRecipient">The type of recipient for the message.</typeparam>
<typeparam name="TMessage">The type of message to receive.</typeparam>
<typeparam name="TToken">The type of token to use to pick the messages to receive.</typeparam>
<param name="recipient">The recipient that will receive the messages.</param>
<param name="token">A token used to determine the receiving channel to use.</param>
<param name="handler">The <see cref="T:Microsoft.Toolkit.Mvvm.Messaging.MessageHandler`2" /> to invoke when a message is received.</param>
<summary>
Registers a recipient for a given type of message.
</summary>
<remarks>To be added.</remarks>
<exception cref="T:System.InvalidOperationException">Thrown when trying to register the same message twice.</exception>
</Docs>
</Member>
<Member MemberName="Reset">
<MemberSignature Language="C#" Value="public void Reset ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Reset() cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.Reset" />
<MemberSignature Language="VB.NET" Value="Public Sub Reset ()" />
<MemberSignature Language="F#" Value="abstract member Reset : unit -> unit" Usage="iMessenger.Reset " />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>
Resets the <see cref="T:Microsoft.Toolkit.Mvvm.Messaging.IMessenger" /> instance and unregisters all the existing recipients.
</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Send<TMessage,TToken>">
<MemberSignature Language="C#" Value="public TMessage Send<TMessage,TToken> (TMessage message, TToken token) where TMessage : class where TToken : IEquatable<TToken>;" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance !!TMessage Send<class TMessage, (class System.IEquatable`1<!!TToken>) TToken>(!!TMessage message, !!TToken token) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.Send``2(``0,``1)" />
<MemberSignature Language="VB.NET" Value="Public Function Send(Of TMessage As Class, TToken As Class) (message As TMessage, token As TToken) As TMessage" />
<MemberSignature Language="F#" Value="abstract member Send : 'Message * 'oken -> 'Message (requires 'Message : null and 'oken :> IEquatable<'oken>)" Usage="iMessenger.Send (message, token)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>TMessage</ReturnType>
</ReturnValue>
<TypeParameters>
<TypeParameter Name="TMessage">
<Constraints>
<ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
</Constraints>
</TypeParameter>
<TypeParameter Name="TToken">
<Constraints>
<InterfaceName>System.IEquatable<TToken></InterfaceName>
</Constraints>
</TypeParameter>
</TypeParameters>
<Parameters>
<Parameter Name="message" Type="TMessage" />
<Parameter Name="token" Type="TToken" />
</Parameters>
<Docs>
<typeparam name="TMessage">The type of message to send.</typeparam>
<typeparam name="TToken">The type of token to identify what channel to use to send the message.</typeparam>
<param name="message">The message to send.</param>
<param name="token">The token indicating what channel to use.</param>
<summary>
Sends a message of the specified type to all registered recipients.
</summary>
<returns>The message that was sent (ie. <paramref name="message" />).</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Unregister<TMessage,TToken>">
<MemberSignature Language="C#" Value="public void Unregister<TMessage,TToken> (object recipient, TToken token) where TMessage : class where TToken : IEquatable<TToken>;" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Unregister<class TMessage, (class System.IEquatable`1<!!TToken>) TToken>(object recipient, !!TToken token) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.Unregister``2(System.Object,``1)" />
<MemberSignature Language="VB.NET" Value="Public Sub Unregister(Of TMessage As Class, TToken As Class) (recipient As Object, token As TToken)" />
<MemberSignature Language="F#" Value="abstract member Unregister : obj * 'oken -> unit (requires 'Message : null and 'oken :> IEquatable<'oken>)" Usage="iMessenger.Unregister (recipient, token)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<TypeParameters>
<TypeParameter Name="TMessage">
<Constraints>
<ParameterAttribute>ReferenceTypeConstraint</ParameterAttribute>
</Constraints>
</TypeParameter>
<TypeParameter Name="TToken">
<Constraints>
<InterfaceName>System.IEquatable<TToken></InterfaceName>
</Constraints>
</TypeParameter>
</TypeParameters>
<Parameters>
<Parameter Name="recipient" Type="System.Object" />
<Parameter Name="token" Type="TToken" />
</Parameters>
<Docs>
<typeparam name="TMessage">The type of message to stop receiving.</typeparam>
<typeparam name="TToken">The type of token to identify what channel to unregister from.</typeparam>
<param name="recipient">The recipient to unregister.</param>
<param name="token">The token to use to identify which handlers to unregister.</param>
<summary>
Unregisters a recipient from messages of a given type.
</summary>
<remarks>If the recipient has no registered handler, this method does nothing.</remarks>
</Docs>
</Member>
<Member MemberName="UnregisterAll">
<MemberSignature Language="C#" Value="public void UnregisterAll (object recipient);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void UnregisterAll(object recipient) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.UnregisterAll(System.Object)" />
<MemberSignature Language="VB.NET" Value="Public Sub UnregisterAll (recipient As Object)" />
<MemberSignature Language="F#" Value="abstract member UnregisterAll : obj -> unit" Usage="iMessenger.UnregisterAll recipient" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="recipient" Type="System.Object" />
</Parameters>
<Docs>
<param name="recipient">The recipient to unregister.</param>
<summary>
Unregisters a recipient from all registered messages.
</summary>
<remarks>
This method will unregister the target recipient across all channels.
Use this method as an easy way to lose all references to a target recipient.
If the recipient has no registered handler, this method does nothing.
</remarks>
</Docs>
</Member>
<Member MemberName="UnregisterAll<TToken>">
<MemberSignature Language="C#" Value="public void UnregisterAll<TToken> (object recipient, TToken token) where TToken : IEquatable<TToken>;" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void UnregisterAll<(class System.IEquatable`1<!!TToken>) TToken>(object recipient, !!TToken token) cil managed" />
<MemberSignature Language="DocId" Value="M:Microsoft.Toolkit.Mvvm.Messaging.IMessenger.UnregisterAll``1(System.Object,``0)" />
<MemberSignature Language="VB.NET" Value="Public Sub UnregisterAll(Of TToken As IEquatable(Of TToken)) (recipient As Object, token As TToken)" />
<MemberSignature Language="F#" Value="abstract member UnregisterAll : obj * 'oken -> unit (requires 'oken :> IEquatable<'oken>)" Usage="iMessenger.UnregisterAll (recipient, token)" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>Microsoft.Toolkit.Mvvm</AssemblyName>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>7.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<TypeParameters>
<TypeParameter Name="TToken">
<Constraints>
<InterfaceName>System.IEquatable<TToken></InterfaceName>
</Constraints>
</TypeParameter>
</TypeParameters>
<Parameters>
<Parameter Name="recipient" Type="System.Object" />
<Parameter Name="token" Type="TToken" />
</Parameters>
<Docs>
<typeparam name="TToken">The type of token to identify what channel to unregister from.</typeparam>
<param name="recipient">The recipient to unregister.</param>
<param name="token">The token to use to identify which handlers to unregister.</param>
<summary>
Unregisters a recipient from all messages on a specific channel.
</summary>
<remarks>If the recipient has no registered handler, this method does nothing.</remarks>
</Docs>
</Member>
</Members>
</Type>