-
Notifications
You must be signed in to change notification settings - Fork 1.5k
/
IEnlistmentNotification.xml
302 lines (273 loc) · 23.5 KB
/
IEnlistmentNotification.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
<Type Name="IEnlistmentNotification" FullName="System.Transactions.IEnlistmentNotification">
<TypeSignature Language="C#" Value="public interface IEnlistmentNotification" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract IEnlistmentNotification" FrameworkAlternate="net-5.0;net-6.0;net-7.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;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-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Transactions.IEnlistmentNotification" />
<TypeSignature Language="VB.NET" Value="Public Interface IEnlistmentNotification" />
<TypeSignature Language="F#" Value="type IEnlistmentNotification = interface" />
<TypeSignature Language="C++ CLI" Value="public interface class IEnlistmentNotification" />
<TypeSignature Language="ILAsm" Value=".class public interface auto ansi abstract beforefieldinit IEnlistmentNotification" FrameworkAlternate="net-8.0;net-9.0" />
<AssemblyInfo>
<AssemblyName>System.Transactions</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<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>
<AssemblyInfo>
<AssemblyName>System.Transactions.Local</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.1.0</AssemblyVersion>
<AssemblyVersion>4.0.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>
<TypeForwardingChain>
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Transactions.Local" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Transactions.Local" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Transactions.Local" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Transactions.Local" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Transactions.Local" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
</TypeForwardingChain>
<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>
<summary>Describes an interface that a resource manager should implement to provide two phase commit notification callbacks for the transaction manager upon enlisting for participation.</summary>
<remarks>
<format type="text/markdown">< and [Committing a Transaction in Single-Phase and Multi-Phase](/dotnet/framework/data/transactions/committing-a-transaction-in-single-phase-and-multi-phase) respectively.
The transaction manager notifies the enlisted object at different phases of the Two Phase Commit Protocol by the following methods.
|Method|Description|
|------------|-----------------|
|<xref:System.Transactions.IEnlistmentNotification.Prepare%2A>|This method of an enlisted object is used as a callback by the Transaction Manager during the first phase of a transaction, when the transaction manager asks participants whether they can commit the transaction.|
|<xref:System.Transactions.IEnlistmentNotification.Commit%2A>|This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is committed.|
|<xref:System.Transactions.IEnlistmentNotification.Rollback%2A>|This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is aborted (that is, rolled back).|
|<xref:System.Transactions.IEnlistmentNotification.InDoubt%2A>|This method of an enlisted object is used as a callback by the Transaction Manager during the second phase of a transaction if the transaction is in doubt.|
> [!NOTE]
> You should be aware that notifications might not be sent sequentially, or in a particular order.
## Examples
The following example shows an implementation of this interface, as well as enlisting the object as a participant in a transaction using the <xref:System.Transactions.Transaction.EnlistVolatile%2A> method.
:::code language="csharp" source="~/snippets/csharp/VS_Snippets_CFX/tx_enlist/cs/enlist.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CFX/tx_enlist/vb/enlist.vb" id="Snippet1":::
]]></format>
</remarks>
<altmember cref="T:System.Transactions.ISinglePhaseNotification" />
<related type="Article" href="/dotnet/framework/data/transactions/enlisting-resources-as-participants-in-a-transaction">Enlisting Resources as Participants in a Transaction</related>
<related type="Article" href="/dotnet/framework/data/transactions/committing-a-transaction-in-single-phase-and-multi-phase">Committing a Transaction in Single-Phase and Multi-Phase</related>
</Docs>
<Members>
<Member MemberName="Commit">
<MemberSignature Language="C#" Value="public void Commit (System.Transactions.Enlistment enlistment);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Commit(class System.Transactions.Enlistment enlistment) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Transactions.IEnlistmentNotification.Commit(System.Transactions.Enlistment)" />
<MemberSignature Language="VB.NET" Value="Public Sub Commit (enlistment As Enlistment)" />
<MemberSignature Language="F#" Value="abstract member Commit : System.Transactions.Enlistment -> unit" Usage="iEnlistmentNotification.Commit enlistment" />
<MemberSignature Language="C++ CLI" Value="public:
 void Commit(System::Transactions::Enlistment ^ enlistment);" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Transactions</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<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>
<AssemblyInfo>
<AssemblyName>System.Transactions.Local</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.1.0</AssemblyVersion>
<AssemblyVersion>4.0.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>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="enlistment" Type="System.Transactions.Enlistment" />
</Parameters>
<Docs>
<param name="enlistment">An <see cref="T:System.Transactions.Enlistment" /> object used to send a response to the transaction manager.</param>
<summary>Notifies an enlisted object that a transaction is being committed.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The transaction manager calls this method of an enlisted object during the second phase of a commitment, when it instructs all participants to commit the transaction.
The resource manager should perform any work necessary to finish the transaction and then inform the TM that it has finished by calling the <xref:System.Transactions.Enlistment.Done%2A> method on the `enlistment` parameter.
If the resource manager has enlisted durably, but does not respond by calling <xref:System.Transactions.Enlistment.Done%2A> method, the transaction manager is unsure that the resource manager has received the <xref:System.Transactions.IEnlistmentNotification.Commit%2A> call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If <xref:System.Transactions.Enlistment.Done%2A> is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by <xref:System.Transactions>, this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the <xref:System.Transactions.Enlistment.Done%2A> method once your resource manager is done with your prepare work.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="InDoubt">
<MemberSignature Language="C#" Value="public void InDoubt (System.Transactions.Enlistment enlistment);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void InDoubt(class System.Transactions.Enlistment enlistment) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Transactions.IEnlistmentNotification.InDoubt(System.Transactions.Enlistment)" />
<MemberSignature Language="VB.NET" Value="Public Sub InDoubt (enlistment As Enlistment)" />
<MemberSignature Language="F#" Value="abstract member InDoubt : System.Transactions.Enlistment -> unit" Usage="iEnlistmentNotification.InDoubt enlistment" />
<MemberSignature Language="C++ CLI" Value="public:
 void InDoubt(System::Transactions::Enlistment ^ enlistment);" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Transactions</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<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>
<AssemblyInfo>
<AssemblyName>System.Transactions.Local</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.1.0</AssemblyVersion>
<AssemblyVersion>4.0.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>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="enlistment" Type="System.Transactions.Enlistment" />
</Parameters>
<Docs>
<param name="enlistment">An <see cref="T:System.Transactions.Enlistment" /> object used to send a response to the transaction manager.</param>
<summary>Notifies an enlisted object that the status of a transaction is in doubt.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
This method is called for volatile resources when the transaction manager has invoked a single phase commit operation to a single durable resource, and then connection to the durable resource was lost prior to getting the transaction result. At that point, the transaction outcome cannot be safely determined.
As <xref:System.Transactions.IEnlistmentNotification.InDoubt%2A> is considered to be a final state for a transaction, you should not call <xref:System.Transactions.IEnlistmentNotification.Commit%2A> or <xref:System.Transactions.IEnlistmentNotification.Rollback%2A> after calling <xref:System.Transactions.IEnlistmentNotification.InDoubt%2A>.
> [!NOTE]
> Your implementation of this method for the volatile resource should perform whatever recovery or containment operation it understands on the affected data. It must also call the <xref:System.Transactions.Enlistment.Done%2A> method on the on the `enlistment` parameter when it has finished its work.
If the resource manager has enlisted durably, but does not respond by calling <xref:System.Transactions.Enlistment.Done%2A> method, the transaction manager is unsure that the resource manager has received the <xref:System.Transactions.IEnlistmentNotification.InDoubt%2A> call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If <xref:System.Transactions.Enlistment.Done%2A> is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by <xref:System.Transactions>, this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the <xref:System.Transactions.Enlistment.Done%2A> method once your resource manager is done with your prepare work.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Prepare">
<MemberSignature Language="C#" Value="public void Prepare (System.Transactions.PreparingEnlistment preparingEnlistment);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Prepare(class System.Transactions.PreparingEnlistment preparingEnlistment) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Transactions.IEnlistmentNotification.Prepare(System.Transactions.PreparingEnlistment)" />
<MemberSignature Language="VB.NET" Value="Public Sub Prepare (preparingEnlistment As PreparingEnlistment)" />
<MemberSignature Language="F#" Value="abstract member Prepare : System.Transactions.PreparingEnlistment -> unit" Usage="iEnlistmentNotification.Prepare preparingEnlistment" />
<MemberSignature Language="C++ CLI" Value="public:
 void Prepare(System::Transactions::PreparingEnlistment ^ preparingEnlistment);" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Transactions</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<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>
<AssemblyInfo>
<AssemblyName>System.Transactions.Local</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.1.0</AssemblyVersion>
<AssemblyVersion>4.0.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>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="preparingEnlistment" Type="System.Transactions.PreparingEnlistment" />
</Parameters>
<Docs>
<param name="preparingEnlistment">A <see cref="T:System.Transactions.PreparingEnlistment" /> object used to send a response to the transaction manager.</param>
<summary>Notifies an enlisted object that a transaction is being prepared for commitment.</summary>
<remarks>
<format type="text/markdown"><.
Your resource manager should complete all work that must be finished before calling the <xref:System.Transactions.PreparingEnlistment.Prepared%2A> method of the `preparingEnlistment` parameter to indicate its vote for commitment. You should make sure that this is accomplished before receiving any phase 2 notification such as commit, rollback or in doubt. This is because phase 2 notifications can happen inline on the same thread that called the <xref:System.Transactions.PreparingEnlistment.Prepared%2A> method in phase 1. As such, you should not do any work after the <xref:System.Transactions.PreparingEnlistment.Prepared%2A> call (for example, releasing locks) that you would expect to have completed before receiving the phase 2 notifications.
You can also call the method of the `preparingEnlistment` parameter to indicate a vote for rollback.
If you want the object to merely observe and react to the progress of the transaction, without participating in it, your implementation of this method should call the <xref:System.Transactions.Enlistment.Done%2A> method of the `preparingEnlistment` parameter when it has finished its work. By doing so, your resource manager would not receive any phase 2 notification.
]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="Rollback">
<MemberSignature Language="C#" Value="public void Rollback (System.Transactions.Enlistment enlistment);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig newslot virtual instance void Rollback(class System.Transactions.Enlistment enlistment) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Transactions.IEnlistmentNotification.Rollback(System.Transactions.Enlistment)" />
<MemberSignature Language="VB.NET" Value="Public Sub Rollback (enlistment As Enlistment)" />
<MemberSignature Language="F#" Value="abstract member Rollback : System.Transactions.Enlistment -> unit" Usage="iEnlistmentNotification.Rollback enlistment" />
<MemberSignature Language="C++ CLI" Value="public:
 void Rollback(System::Transactions::Enlistment ^ enlistment);" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Transactions</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<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>
<AssemblyInfo>
<AssemblyName>System.Transactions.Local</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.1.0</AssemblyVersion>
<AssemblyVersion>4.0.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>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="enlistment" Type="System.Transactions.Enlistment" />
</Parameters>
<Docs>
<param name="enlistment">A <see cref="T:System.Transactions.Enlistment" /> object used to send a response to the transaction manager.</param>
<summary>Notifies an enlisted object that a transaction is being rolled back (aborted).</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
The transaction manager calls this method of an enlisted object when the transaction is being rolled back (aborted) due to the inability of one or more transaction participants to commit the transaction.
The resource manager should perform any work necessary to finish the transaction and then inform the TM that it has finished by calling the <xref:System.Transactions.Enlistment.Done%2A> method on the `enlistment` parameter.
If the resource manager has enlisted durably, but does not respond by calling <xref:System.Transactions.Enlistment.Done%2A> method, the transaction manager is unsure that the resource manager has received the <xref:System.Transactions.IEnlistmentNotification.Rollback%2A> call. As such, the transaction manager keeps waiting for a response, and maintains information relevant to this transaction. If <xref:System.Transactions.Enlistment.Done%2A> is never called, this piece of information is kept around indefinitely in memory or in a system-wide resource. This results in resources not being able to be reclaimed. In the case of a distributed transaction, this could eventually fill the MSDTC log which halts the MSDTC process. In the case of a transaction managed by <xref:System.Transactions>, this results in a gradual and continual increase in the memory consumption of the resource manager's process. Therefore, it is crucial that you call the <xref:System.Transactions.Enlistment.Done%2A> method once your resource manager is done with your prepare work.
]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>