Generating Visual Studio Analyzer Events

You can generate either system-defined or custom events from any place in your code. You must register any event you plan to generate. If you generate an unregistered event, or an event from an unregistered source, the event will be correctly passed and recorded. However, there is no guarantee that users will be able to create or edit filters based on an unregistered event or event source. Make sure all events and event sources are registered. (For more information on how to use filters, see Understanding Filters.)

The following lists the steps you must take with code in your component in order to generate events:

  1. Create an instance of the in-process event creator object.

    How you do this depends on the language in which your event source is written, as shown in the following table:

    Language Code to Create an Inprocess Event Creator Instance
    Visual Basic, Visual J++ 
    Dim MyIEC As _ MSVSAInprocEventCreator
    Set MyIEC = New _ MSVSAInprocEventCreator
    Visual C++ 
    HRESULT hr = CoCreateInstance(CLSID_VSA_IEC, NULL, CLSCTX_INPROC_SERVER, IID_ISystemDebugEventFire,
 (void **)&pEvent);

  2. Call the BeginSession method of the in-process event creator object.

    The BeginSession method allows you to uniquely identify this particular session of your component. The unique identifier is important because your component might be running on several machines at the same time. If each component is generating Visual Studio Analyzer events, a unique identifier is necessary to distinguish between events generated by each instance of the component.

  3. Call the FireEvent method of the in-process event creator object each time you want to generate an event.

    The FireEvent method allows you to pass the name of the event and the corresponding event data.

  4. Call the EndSession method of the in-process event creator object and then destroy the in-process event creator instance.

Passing Event Data

You can pass event data in an array with the FireEvent method. This data provides detailed information to the Visual Studio Analyzer user, helping them understand a distributed application, determine performance problems, and isolate faults. See VSAStandardParameter for a list of the parameters you can pass for event data.

Among the many possible event parameters, some of the most important are the machine, process, process name, thread, component, session, and handle for both the source and the target component. The source component is the component that generates the event; the target component is the called function, database, or transaction. You can pass default values for these parameters; see Determining Source and Target Values for Events for more information on when to pass default values and when it is better to explicitly provide source and target values.

It is also important to show how events relate to one another. The CorrelationID and CausalityID event parameters provide a way for you to ensure that related events, such as the call to and return from a function, appear related to the Visual Studio Analyzer user. See Determining the Relationships Between Events for more information on showing client and server interaction with these relationships.