See Also Tasks Example Applies To
Starts a Visual Studio Analyzer session with the calling component. You assign a unique identifier to the session. Events that are generated during this session are stamped with the session identifier, which helps you identify the true source of an event, particularly in cases where multiple copies of the component are running at the same time.
Syntax
| Visual Basic | object.BeginSession(guidSourceID As String, strSessionName As String) |
| Visual C++ | HRESULT BeginSession( REFGUID guidSourceID, LPCOLESTR strSessionName); |
| Visual J++ | object.BeginSession(String guidSourceID, String strSessionName); |
Parameters
object
A unique instance of the event creator object. The event creator object generates Visual Studio Analyzer events for the calling component. Each instance of a component has its own event creator object.
guidSourceID
A unique identifier for the calling component. Multiple sessions from this component can exist at the same time on the same machine. This ID is defined in the call to the RegisterSource method of ISystemDebugEventInstall, which registers components with the Visual Studio Analyzer framework.
Visual C++: [in]
strSessionName
A session identifier, which must be unique among all instances of this component until the machine where the component resides is restarted.
Visual C++: [in]
Remarks
Before you can call BeginSession, you must register the calling component with the Visual Studio Analyzer framework by calling the RegisterSource method of ISystemDebugEventInstall.
Each event creator object can accept only one call to BeginSession at a time. If your application supports multiple simultaneous sessions, such as a Web server running on more than one port, you can choose to create multiple in-process event creator objects.
You can make repeated calls to BeginSession on the same object, as long as you have a matching EndSession call for each BeginSession call. You cannot nest calls, as the following table illustrates:
| Accepted | Not Accepted |
| BeginSession | BeginSession |
| EndSession | BeginSession |
| BeginSession | EndSession |
| EndSession | EndSession |
The code does not validate whether strSessionName is unique. If the session identifier is not unique, the user might be unable to distinguish between events from multiple sessions of the same component. However, this lack of checking allows for two servers that represent one conceptual session to coexist and operate correctly.
This function will fail if guidSourceID is not properly registered.
You can use the default user component, DEBUG_EVENT_SOURCE_USER, which is already registered, if you want a quick way to generate events without a lot of overhead. The default user component is registered automatically when you install Visual Studio Analyzer.