DataObjectChangeEvents.StartEventGroup Method

Article
10/02/2013

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.Int32

The 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.

Share via