Exposer des événements dans le SDK Visual StudioExpose events in the Visual Studio SDK

Visual StudioVisual Studio vous permet de la source d’événements à l’aide d’automation. lets you source events by using automation. Nous recommandons 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 (par exemple, GetObject("EventObjectName")).Events are retrieved by automation consumers from the Events object or GetObject (for example, 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.

Le processus suivant explique la façon dont les événements spécifiques au VSPackage 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 dans le Automation, AutomationEvents, et AutomationProperties clés de tous les VSPackages et stocke ces noms dans un 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 utilisateur d’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 recherche le paramètre de chaîne dans 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 méthode en utilisant le nom passé dans 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 package Visual Studio crée un objet racine qui possède 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 le 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 à partir de l’exemple de projet de baseRegistry entries from the Basic Project sample

Cette section indique 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 = retourne le AutomationProjectEvents objet.AutomationProjectEvents = Returns the AutomationProjectEvents object.

AutomationProjectItemEvents = retourne le AutomationProjectItemsEvents objet.AutomationProjectItemEvents = Returns the AutomationProjectItemsEvents object.

NameName TypeType RangeRange DescriptionDescription
Par défaut (@)Default (@) REG_SZREG_SZ inutilisé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.

Quand un de vos objets d’événement sont demandé par un utilisateur d’automation, créer un objet racine qui a des méthodes pour n’importe quel événement prenant en charge 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, le 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, et CProjectItemsEventsContainer représente l’objet source pour BscProjectItemsEvents.The class CProjectEventsContainer represents the source object for BscProjectsEvents, and CProjectItemsEventsContainer represents the source object for BscProjectItemsEvents.

Dans la plupart des cas, vous devez retourner un nouvel objet pour chaque requête d’événement, car la plupart des objets événement 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 votre é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 des 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énement qui se 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 de projet et les événements qui sont générés à partir de votre implémentation VSPackage d’éléments de projet.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 façon, tous les objets événements sont regroupés afin qu’un utilisateur final n’a pas à parcourir l’intégralité du modèle objet 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 obliger à implémenter votre propre code pour les événements de l’échelle du 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 event 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