-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
Copy pathIObserver`1.xml
303 lines (265 loc) · 20.1 KB
/
IObserver`1.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
<Type Name="IObserver<T>" FullName="System.IObserver<T>">
<TypeSignature Language="C#" Value="public interface IObserver<in T>" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IObserver`1<- T>" FrameworkAlternate="dotnet-uwp-10.0;net-5.0;net-6.0;net-7.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.IObserver`1" />
<TypeSignature Language="VB.NET" Value="Public Interface IObserver(Of In T)" />
<TypeSignature Language="F#" Value="type IObserver<'T> = interface" />
<TypeSignature Language="C++ CLI" Value="generic <typename T>
public interface class IObserver" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IObserver`1<- T>" FrameworkAlternate="net-8.0;net-9.0" />
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
<AssemblyVersion>4.2.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<TypeForwardingChain>
<TypeForwarding From="mscorlib" FromVersion="4.0.0.0" To="System.Runtime" ToVersion="0.0.0.0" FrameworkAlternate="dotnet-uwp-10.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Runtime" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
<TypeForwarding From="System.Runtime" FromVersion="4.1.1.1" To="mscorlib" ToVersion="4.0.0.0" FrameworkAlternate="netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1" />
</TypeForwardingChain>
<TypeParameters>
<TypeParameter Name="T">
<Constraints>
<ParameterAttribute>Contravariant</ParameterAttribute>
</Constraints>
<Attributes>
<Attribute FrameworkAlternate="net-8.0;net-9.0">
<AttributeName Language="C#">[System.Runtime.CompilerServices.Nullable(2)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.CompilerServices.Nullable(2)>]</AttributeName>
</Attribute>
</Attributes>
</TypeParameter>
</TypeParameters>
<Interfaces />
<Attributes>
<Attribute FrameworkAlternate="net-8.0;net-9.0">
<AttributeName Language="C#">[System.Runtime.CompilerServices.NullableContext(1)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.CompilerServices.NullableContext(1)>]</AttributeName>
</Attribute>
</Attributes>
<Docs>
<typeparam name="T">The object that provides notification information.</typeparam>
<summary>Provides a mechanism for receiving push-based notifications.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.IObserver%601> and <xref:System.IObservable%601> interfaces provide a generalized mechanism for push-based notification, also known as the observer design pattern. The <xref:System.IObservable%601> interface represents the class that sends notifications (the provider); the <xref:System.IObserver%601> interface represents the class that receives them (the observer). `T` represents the class that provides the notification information.
An <xref:System.IObserver%601> implementation arranges to receive notifications from a provider (an <xref:System.IObservable%601> implementation) by passing an instance of itself to the provider's <xref:System.IObservable%601.Subscribe%2A?displayProperty=nameWithType> method. This method returns an <xref:System.IDisposable> object that can be used to unsubscribe the observer before the provider finishes sending notifications.
The <xref:System.IObserver%601> interface defines the following three methods that the observer must implement:
- The <xref:System.IObserver%601.OnNext%2A> method, which is typically called by the provider to supply the observer with new data or state information.
- The <xref:System.IObserver%601.OnError%2A> method, which is typically called by the provider to indicate that data is unavailable, inaccessible, or corrupted, or that the provider has experienced some other error condition.
- The <xref:System.IObserver%601.OnCompleted%2A> method, which is typically called by the provider to indicate that it has finished sending notifications to observers.
## Examples
The following example illustrates the observer design pattern. It defines a `Location` class that contains latitude and longitude information.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/provider.cs" id="Snippet5":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/provider.fs" id="Snippet5":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/provider.vb" id="Snippet5":::
The `LocationReporter` class provides the <xref:System.IObserver%601> implementation. It displays information about the current location to the console. Its constructor includes a `name` parameter, which allows the `LocationReporter` instance to identify itself in its string output. It also includes a `Subscribe` method, which wraps a call to the provider's <xref:System.IObservable%601.Subscribe%2A> method. This enables the method to assign the returned <xref:System.IDisposable> reference to a private variable. The `LocationReporter` class also includes an `Unsubscribe` method, which calls the <xref:System.IDisposable.Dispose%2A?displayProperty=nameWithType> method of the object returned by the <xref:System.IObservable%601.Subscribe%2A?displayProperty=nameWithType> method. The following code defines the `LocationReporter` class.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/observer.cs" id="Snippet8":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/observer.fs" id="Snippet8":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/observer.vb" id="Snippet8":::
The `LocationTracker` class provides the <xref:System.IObservable%601> implementation. Its `TrackLocation` method is passed a nullable `Location` object that contains the latitude and longitude data. If the `Location` value is not `null`, the `TrackLocation` method calls the <xref:System.IObserver%601.OnNext%2A> method of each observer.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/provider.cs" id="Snippet6":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/provider.fs" id="Snippet6":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/provider.vb" id="Snippet6":::
If the `Location` value is `null`, the `TrackLocation` method instantiates a `LocationNotFoundException` object, which is shown in the following example. It then calls each observer's <xref:System.IObserver%601.OnError%2A> method and passes it the `LocationNotFoundException` object. Note that `LocationNotFoundException` derives from <xref:System.Exception> but does not add any new members.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/provider.cs" id="Snippet7":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/provider.fs" id="Snippet7":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/provider.vb" id="Snippet7":::
Observers register to receive notifications from a `TrackLocation` object by calling its <xref:System.IObservable%601.Subscribe%2A?displayProperty=nameWithType> method, which assigns a reference to the observer object to a private generic <xref:System.Collections.Generic.List%601> object. The method returns an `Unsubscriber` object, which is an <xref:System.IDisposable> implementation that enables observers to stop receiving notifications. The `LocationTracker` class also includes an `EndTransmission` method. When no further location data is available, the method calls each observer's <xref:System.IObserver%601.OnCompleted%2A> method and then clears the internal list of observers.
The following code then instantiates the provider and the observer.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/program.cs" id="Snippet9":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/program.fs" id="Snippet9":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/module1.vb" id="Snippet9":::
]]></format>
</remarks>
<altmember cref="T:System.IObservable`1" />
</Docs>
<Members>
<Member MemberName="OnCompleted">
<MemberSignature Language="C#" Value="public void OnCompleted ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void OnCompleted() cil managed" />
<MemberSignature Language="DocId" Value="M:System.IObserver`1.OnCompleted" />
<MemberSignature Language="VB.NET" Value="Public Sub OnCompleted ()" />
<MemberSignature Language="F#" Value="abstract member OnCompleted : unit -> unit" Usage="iObserver.OnCompleted " />
<MemberSignature Language="C++ CLI" Value="public:
 void OnCompleted();" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
<AssemblyVersion>4.2.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Notifies the observer that the provider has finished sending push-based notifications.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
When the observer's <xref:System.IObserver%601.OnCompleted%2A> implementation is called, the <xref:System.IObserver%601.OnCompleted%2A> method can optionally call the <xref:System.IDisposable.Dispose%2A> method of the <xref:System.IDisposable> object that was returned to the observer when it called the <xref:System.IObservable%601.Subscribe%2A?displayProperty=nameWithType> method.
## Examples
The following example provides an implementation of the <xref:System.IObserver%601.OnCompleted%2A> method in a latitude/longitude tracking application. The method simply reports that no further data is available and calls the provider's <xref:System.IDisposable.Dispose%2A?displayProperty=nameWithType> implementation. See the Example section of the <xref:System.IObserver%601> topic for the complete example.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/observer.cs" id="Snippet11":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/observer.fs" id="Snippet11":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/observer.vb" id="Snippet11":::
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="OnError">
<MemberSignature Language="C#" Value="public void OnError (Exception error);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void OnError(class System.Exception error) cil managed" />
<MemberSignature Language="DocId" Value="M:System.IObserver`1.OnError(System.Exception)" />
<MemberSignature Language="VB.NET" Value="Public Sub OnError (error As Exception)" />
<MemberSignature Language="F#" Value="abstract member OnError : Exception -> unit" Usage="iObserver.OnError error" />
<MemberSignature Language="C++ CLI" Value="public:
 void OnError(Exception ^ error);" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
<AssemblyVersion>4.2.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="error" Type="System.Exception" />
</Parameters>
<Docs>
<param name="error">An object that provides additional information about the error.</param>
<summary>Notifies the observer that the provider has experienced an error condition.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
Although `error` is an object that is derived from <xref:System.Exception?displayProperty=nameWithType>, it does not necessarily represent an exception that is thrown by the provider. It can also represent a routine or expected error condition, such as data that is missing or unavailable. The <xref:System.IObserver%601.OnError%2A> method should be seen as informational, and the provider should not expect the observer to provide error handling.
## Examples
The following example provides an implementation of the <xref:System.IObserver%601.OnError%2A> method in a latitude/longitude tracking application. The method simply reports that data is currently unavailable; it does not make use of the <xref:System.Exception> object passed to it as a parameter. See the Example section of the <xref:System.IObserver%601> topic for the complete example.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/observer.cs" id="Snippet10":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/observer.fs" id="Snippet10":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/observer.vb" id="Snippet10":::
]]></format>
</remarks>
<related type="Article" href="/dotnet/standard/events/observer-design-pattern-best-practices">Observer Design Pattern Best Practices</related>
</Docs>
</Member>
<Member MemberName="OnNext">
<MemberSignature Language="C#" Value="public void OnNext (T value);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void OnNext(!T value) cil managed" />
<MemberSignature Language="DocId" Value="M:System.IObserver`1.OnNext(`0)" />
<MemberSignature Language="VB.NET" Value="Public Sub OnNext (value As T)" />
<MemberSignature Language="F#" Value="abstract member OnNext : 'T -> unit" Usage="iObserver.OnNext value" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Runtime</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.0.20.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.2.0.0</AssemblyVersion>
<AssemblyVersion>4.2.1.0</AssemblyVersion>
<AssemblyVersion>4.2.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="value" Type="T" />
</Parameters>
<Docs>
<param name="value">The current notification information.</param>
<summary>Provides the observer with new data.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
After an observer has called a provider's <xref:System.IObservable%601.Subscribe%2A?displayProperty=nameWithType> method, the provider calls the observer's <xref:System.IObserver%601.OnNext%2A> method to provide notifications.
## Examples
The following example provides an implementation of the <xref:System.IObserver%601.OnNext%2A> method in a latitude/longitude tracking application. See the Example section of the <xref:System.IObserver%601> topic for the complete example.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/observer.cs" id="Snippet12":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/observer.fs" id="Snippet12":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/observer.vb" id="Snippet12":::
]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>