-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
Copy pathIObservable`1.xml
195 lines (165 loc) · 15.5 KB
/
IObservable`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
<Type Name="IObservable<T>" FullName="System.IObservable<T>">
<TypeSignature Language="C#" Value="public interface IObservable<out T>" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IObservable`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.IObservable`1" />
<TypeSignature Language="VB.NET" Value="Public Interface IObservable(Of Out T)" />
<TypeSignature Language="F#" Value="type IObservable<'T> = interface" />
<TypeSignature Language="C++ CLI" Value="generic <typename T>
public interface class IObservable" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IObservable`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>Covariant</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>Defines a provider for push-based notification.</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. In some push-based notifications, the <xref:System.IObserver%601> implementation and `T` can represent the same type.
The provider must implement a single method, <xref:System.IObservable%601.Subscribe%2A>, that indicates that an observer wants to receive push-based notifications. Callers to the method pass an instance of the observer. The method returns an <xref:System.IDisposable> implementation that enables observers to cancel notifications at any time before the provider has stopped sending them.
At any given time, a given provider may have zero, one, or multiple observers. The provider is responsible for storing references to observers and ensuring that they are valid before it sends notifications. The <xref:System.IObservable%601> interface does not make any assumptions about the number of observers or the order in which notifications are sent.
The provider sends the following three kinds of notifications to the observer by calling <xref:System.IObserver%601> methods:
- The current data. The provider can call the <xref:System.IObserver%601.OnNext%2A?displayProperty=nameWithType> method to pass the observer a `T` object that has current data, changed data, or fresh data.
- An error condition. The provider can call the <xref:System.IObserver%601.OnError%2A?displayProperty=nameWithType> method to notify the observer that some error condition has occurred.
- No further data. The provider can call the <xref:System.IObserver%601.OnCompleted%2A?displayProperty=nameWithType> method to notify the observer that it has finished sending notifications.
## 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 `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 `LocationUnknownException` 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 `LocationUnknownException` object. Note that `LocationUnknownException` 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 `LocationTracker` 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.
In this example, 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 enables 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 allows 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 that is 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 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.IObserver`1" />
<related type="Article" href="/dotnet/standard/events/observer-design-pattern">The Observer Design Pattern</related>
</Docs>
<Members>
<Member MemberName="Subscribe">
<MemberSignature Language="C#" Value="public IDisposable Subscribe (IObserver<out T> observer);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance class System.IDisposable Subscribe(class System.IObserver`1<!T> observer) cil managed" />
<MemberSignature Language="DocId" Value="M:System.IObservable`1.Subscribe(System.IObserver{`0})" />
<MemberSignature Language="VB.NET" Value="Public Function Subscribe (observer As IObserver(Of Out T)) As IDisposable" />
<MemberSignature Language="F#" Value="abstract member Subscribe : IObserver<'T> -> IDisposable" Usage="iObservable.Subscribe observer" />
<MemberSignature Language="C++ CLI" Value="public:
 IDisposable ^ Subscribe(IObserver<T> ^ observer);" />
<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.IDisposable</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="observer" Type="System.IObserver<T>" />
</Parameters>
<Docs>
<param name="observer">The object that is to receive notifications.</param>
<summary>Notifies the provider that an observer is to receive notifications.</summary>
<returns>A reference to an interface that allows observers to stop receiving notifications before the provider has finished sending them.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The <xref:System.IObservable%601.Subscribe%2A> method must be called to register an observer for push-based notifications. A typical implementation of the <xref:System.IObservable%601.Subscribe%2A> method does the following:
- It stores a reference to the observer in a collection object, such as a <xref:System.Collections.Generic.List%601> object.
- It returns a reference to an <xref:System.IDisposable> interface. This enables observers to unsubscribe (that is, to stop receiving notifications) before the provider has finished sending them and called the subscriber's <xref:System.IObserver%601.OnCompleted%2A> method.
At any given time, a particular instance of an <xref:System.IObservable%601> implementation is responsible for handling all subscriptions and notifying all subscribers. Unless the documentation for a particular <xref:System.IObservable%601> implementation indicates otherwise, observers should make no assumptions about the <xref:System.IObservable%601> implementation, such as the order of notifications that multiple observers will receive.
## Examples
The following example illustrates the <xref:System.IObservable%601.Subscribe%2A> method for an application that reports latitude and longitude information. It defines an <xref:System.Collections.Generic.IList%601> collection object that stores references to all observers. It also returns a private class named `Unsubscriber` that implements the <xref:System.IDisposable> interface and enables subscribers to stop receiving event notifications. See the Example section of the <xref:System.IObservable%601> topic for the complete example.
:::code language="csharp" source="~/snippets/csharp/System/IObservableT/Overview/provider.cs" id="Snippet13":::
:::code language="fsharp" source="~/snippets/fsharp/System/IObservableT/Overview/provider.fs" id="Snippet13":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.iobserver.class/vb/provider.vb" id="Snippet13":::
]]></format>
</remarks>
<altmember cref="T:System.IObserver`1" />
</Docs>
</Member>
</Members>
</Type>