Exposant les événements dans le Kit de développement logiciel de Visual StudioExposing Events in the Visual Studio SDK

Visual StudioVisual Studio permet à la source d’événements à l’aide d’automation. lets you source events by using automation. Il est recommandé que vous source d’événements pour les projets et éléments de projet.We recommend that you source events for projects and project items.

Les événements sont récupérés par les consommateurs d’automation à partir de la Events objet ou GetObject (« EventObjectName »).Events are retrieved by automation consumers from the Events object or GetObject ("EventObjectName"). L’environnement appelle IDispatch::Invoke à l’aide de la DISPATCH_METHOD ou DISPATCH_PROPERTYGET indicateurs pour retourner un événement.The environment calls IDispatch::Invoke by using the DISPATCH_METHOD or DISPATCH_PROPERTYGET flags to return an event.

La procédure suivante explique comment les événements de VSPackage spécifique sont retournés.The following process explains how VSPackage-specific events are returned.

  1. Démarrage de l’environnement.The environment starts.

  2. Il lit à partir du Registre de tous les noms de valeur sous les clés d’automatisation, AutomationEvents et AutomationProperties de tous les VSPackages et stocke ces noms dans une table.It reads from the registry all value names under the Automation, AutomationEvents and AutomationProperties keys of all VSPackages, and stores those names in a table.

  3. Un consommateur automation appelle, dans cet exemple, DTE.Events.AutomationProjectsEvents ou DTE.Events.AutomationProjectItemsEvents.An automation consumer calls, in this example, DTE.Events.AutomationProjectsEvents or DTE.Events.AutomationProjectItemsEvents.

  4. L’environnement de recherche le paramètre de chaîne de la table et charge le VSPackage correspondant.The environment finds the string parameter in the table and loads the corresponding VSPackage.

  5. L’environnement appelle le GetAutomationObject passés à la méthode en utilisant le nom de l’appel ; dans cet exemple, AutomationProjectsEvents ou AutomationProjectItemsEvents.The environment calls the GetAutomationObject method by using the name passed in the call; in this example, AutomationProjectsEvents or AutomationProjectItemsEvents.

  6. Le VSPackage crée un objet racine qui a des méthodes telles que get_AutomationProjectsEvents et get_AutomationProjectItemEvents , puis retourne un pointeur IDispatch pour l’objet.The VSPackage creates a root object that has methods such as get_AutomationProjectsEvents and get_AutomationProjectItemEvents and then returns an IDispatch pointer to the object.

  7. L’environnement appelle la méthode appropriée en fonction du nom passé dans l’appel d’automation.The environment calls the appropriate method based on the name passed into the automation call.

  8. Le get_ méthode crée un autre objet IDispatch d’événements qui implémente à la fois le IConnectionPointContainer interface et IConnectionPoint interface et retourne un IDispatchpointer à l’objet.The get_ method creates another IDispatch-based event object that implements both the IConnectionPointContainer interface and the IConnectionPoint interface and returns an IDispatchpointer to the object.

    Pour exposer un événement à l’aide d’automation, vous devez répondre à GetAutomationObject et de surveiller les chaînes que vous ajoutez au Registre.To expose an event by using automation, you must respond to GetAutomationObject and watch for the strings that you add to the registry. Dans l’exemple de projet de base, les chaînes sont « BscProjectsEvents » et « BscProjectItemsEvents ».In the Basic Project sample, the strings are "BscProjectsEvents" and "BscProjectItemsEvents".

Entrées de Registre de l’exemple de projet de baseRegistry Entries from the Basic Project Sample

Cette section montre où ajouter les valeurs d’événement automation dans le Registre.This section shows where to add automation event values to the registry.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\Packages\< PkgGUID>\AutomationEvents][HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\Packages\<PkgGUID>\AutomationEvents]

« AutomationProjectEvents « = » de retourne l’objet AutomationProjectEvents »"AutomationProjectEvents"="Returns the AutomationProjectEvents Object"

« AutomationProjectItemEvents « = » de retourne l’objet AutomationProjectItemsEvents »"AutomationProjectItemEvents"="Returns the AutomationProjectItemsEvents Object"

NameName TypeType RangeRange DescriptionDescription
Par défaut (@)Default (@) REG_SZREG_SZ Non utiliséUnused Non utilisé.Unused. Vous pouvez utiliser le champ de données pour la documentation.You can use the data field for documentation.
AutomationProjectsEventsAutomationProjectsEvents REG_SZREG_SZ Nom de votre objet d’événement.Name of your event object. Il concerne uniquement le nom de clé.Only the key name is relevant. Vous pouvez utiliser le champ de données pour la documentation.You can use the data field for documentation.

Cet exemple provient de l’exemple de projet de base.This example comes from the Basic Project sample.
AutomationProjectItemEventsAutomationProjectItemEvents REG_SZREG_SZ Nom de votre objet d’événementName of your event object Il concerne uniquement le nom de clé.Only the key name is relevant. Vous pouvez utiliser le champ de données pour la documentation.You can use the data field for documentation.

Cet exemple provient de l’exemple de projet de base.This example comes from the Basic Project sample.

Lorsqu’un de vos objets d’événement sont demandé par un consommateur d’automation, créer un objet racine qui a des méthodes pour tout événement qui prend en charge de votre VSPackage.When any of your event objects are requested by an automation consumer, create a root object that has methods for any event that your VSPackage supports. L’environnement appelle approprié get_ méthode sur cet objet.The environment calls the appropriate get_ method on this object. Par exemple, si DTE.Events.AutomationProjectsEvents est appelée, la get_AutomationProjectsEvents méthode est appelée sur l’objet racine.For example, if DTE.Events.AutomationProjectsEvents is called, the get_AutomationProjectsEvents method on the root object is invoked.

Événements de projet Visual StudioVisual Studio Project Events
Modèle Automation pour les événementsAutomation model for events

La classe CProjectEventsContainer représente l’objet source pour BscProjectsEvents, tandis que CProjectItemsEventsContainer représente l’objet source pour BscProjectItemsEvents.The class CProjectEventsContainer represents the source object for BscProjectsEvents, while CProjectItemsEventsContainer represents the source object for BscProjectItemsEvents.

Dans la plupart des cas, vous devez retourner un objet pour chaque demande de l’événement étant donné que la plupart des objets d’événements prennent un objet de filtre.In most cases, you must return a new object for every event request because most event objects take a filter object. Lorsque vous déclenchez l’événement, vérifiez ce filtre pour vérifier que le Gestionnaire d’événements est appelé.When you fire your event, check this filter to verify that the event handler is being called.

AutomationEvents.h et AutomationEvents.cpp contiennent les déclarations et des implémentations des classes dans le tableau suivant.AutomationEvents.h and AutomationEvents.cpp contain declarations and implementations of the classes in the following table.

ClasseClass DescriptionDescription
CAutomationEvents Implémente un objet racine d’événement, extrait du DTE.Events objet.Implements an event root object, retrieved from the DTE.Events object.
CProjectsEventsContainer et CProjectItemsEventsContainerCProjectsEventsContainer and CProjectItemsEventsContainer Implémenter les objets de source d’événements qui déclenchent les événements correspondants.Implement the event source objects that fire the corresponding events.

L’exemple de code suivant montre comment répondre à une demande pour un objet d’événement.The following code example shows how to respond to a request for an event object.

STDMETHODIMP CVsPackage::GetAutomationObject(  
    /* [in]  */ LPCOLESTR       pszPropName,   
    /* [out] */ IDispatch **    ppIDispatch)  
{  
    ExpectedPtrRet(ppIDispatch);  
    *ppIDispatch = NULL;  

    if (_wcsicmp(pszPropName, g_wszAutomationProjects) == 0)   
        //Is the requested name our Projects object?  
    {  
        return GetAutomationProjects(ppIDispatch);  
        // Gets our Projects object.  
    }  
    else if (_wcsicmp(pszPropName, g_wszAutomationProjectsEvents) == 0)  
        //Is the requested name our ProjectsEvents object?  
    {  
        return CAutomationEvents::GetAutomationEvents(ppIDispatch);  
          // Gets our ProjectEvents object.  
    }  
    else if (_wcsicmp(pszPropName, g_wszAutomationProjectItemsEvents) == 0)  //Is the requested name our ProjectsItemsEvents object?  
    {  
        return CAutomationEvents::GetAutomationEvents(ppIDispatch);  
          // Gets our ProjectItemsEvents object.  
    }  
    return E_INVALIDARG;  
}  

Dans le code ci-dessus, g_wszAutomationProjects est le nom de votre collection de projets (« FigProjects »), g_wszAutomationProjectsEvents (« FigProjectsEvents ») et g_wszAutomationProjectItemsEvents (« FigProjectItemEvents ») sont les noms des événements dans les projets et éléments de projet des événements qui sont générés à partir de votre Implémentation du VSPackage.In the code above, g_wszAutomationProjects is the name of your project collection ("FigProjects"), g_wszAutomationProjectsEvents ("FigProjectsEvents") and g_wszAutomationProjectItemsEvents ("FigProjectItemEvents") are the names of project events and project items events that are sourced from your VSPackage implementation.

Objets d’événements sont récupérés à l’emplacement central, le DTE.Events objet.Event objects are retrieved from the same central location, the DTE.Events object. De cette manière, tous les objets événements sont regroupés afin qu’un utilisateur final n’a pas à parcourir le modèle d’objet complet pour rechercher un événement spécifique.This way, all event objects are grouped together so that an end user does not have to browse the entire object model to find a specific event. Cela vous permet également de fournir vos objets VSPackage spécifiques, au lieu de vous demander d’implémenter votre propre code pour des événements système.This also lets you provide your specific VSPackage objects, instead of requiring you to implement your own code for system-wide events. Toutefois, pour l’utilisateur final, qui doit rechercher un événement pour votre ProjectItem interface, il n’est pas immédiatement clair à partir duquel cet objet d’événement est récupéré.However, for the end user,who must find an event for your ProjectItem interface, it is not immediately clear from where that event object is retrieved.

Voir aussiSee Also

GetAutomationObject
Exemples d’extensibilité Visual StudioVSSDK Samples