DataObjectChangeEvents.StartEventGroup Method
Starts a group of events initiated by a call to the StartEventGroup method.
Namespace: Microsoft.VisualStudio.Data
Assembly: Microsoft.VisualStudio.Data (in Microsoft.VisualStudio.Data.dll)
Syntax
'Declaration
Public MustOverride Function StartEventGroup ( _
groupId As Integer _
) As Integer
public abstract int StartEventGroup(
int groupId
)
public:
virtual int StartEventGroup(
int groupId
) abstract
abstract StartEventGroup :
groupId:int -> int
public abstract function StartEventGroup(
groupId : int
) : int
Parameters
groupId
Type: System.Int32The parent group ID, if any; otherwise zero.
Return Value
Type: System.Int32
Returns the group ID of the parent group.
Exceptions
| Exception | Condition |
|---|---|
| ArgumentOutOfRangeException | The groupId parameter is less than or equal to zero or is greater than the current number of allocated groups. |
| ArgumentException | The groupId parameter is invalid. |
Remarks
Under some circumstances, multiple change events need to be grouped together and be treated as an atomic transaction.
Normally, an event listener reacts to event-group notifications by assembling a queue of events raised inside an event group; then, only after notification that the event group has ended, are the events processed in a transactional manner (that is, all events apply, or none of the events apply).
On the notification side, event grouping is implemented by enabling the specification of a hierarchy of event groups, each of them identified with a group ID. A notifier begins by calling StartEventGroup, which returns an ID for the group. Then the notifier calls the RaiseObjectAdded,RaiseObjectChanged, and RaiseObjectRemovedmethods, passing in the group ID. (Optionally, a notifier can start an embedded event group by calling StartEventGroup again, with the current group ID.)
Finally the notifier calls EndEventGroup using the group ID. Once the top-most group (the group created by calling StartEventGroup with a parameter of zero) has ended, all the events raised for that group are dispatched to listeners in a single event group.
.NET Framework Security
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.