Expor eventos no SDK do Visual Studio

O Visual Studio permite que você origine eventos usando automação. Recomendamos que você origine eventos para projetos e itens de projeto.

Os eventos são recuperados por consumidores de automação do objeto Events ou GetObject (por exemplo, GetObject("EventObjectName")). O ambiente chama IDispatch::Invoke usando os sinalizadores DISPATCH_METHOD ou DISPATCH_PROPERTYGET para retornar um evento.

O processo a seguir explica como os eventos específicos do VSPackage são retornados.

1. O estado do ambiente.

2. Ele lê do Registro todos os nomes de valor sob as chaves Automation, AutomationEvents e AutomationProperties de todos os VSPackages e armazena esses nomes em uma tabela.

3. Um consumidor de automação chama, neste exemplo, DTE.Events.AutomationProjectsEvents ou DTE.Events.AutomationProjectItemsEvents.

4. O ambiente localiza o parâmetro de sequência na tabela e carrega o VSPackage correspondente.

5. O ambiente chama o método GetAutomationObject usando o nome informado na chamada; neste exemplo, AutomationProjectsEvents ou AutomationProjectItemsEvents.

6. O VSPackage cria um objeto raiz que tem métodos como get_AutomationProjectsEvents e get_AutomationProjectItemEvents e, em seguida, retorna um ponteiro IDispatch para o objeto.

7. O ambiente chama o método apropriado com base no nome informado na chamada de automação.

8. O método get_ cria outro objeto de evento baseado no IDispatch que implementa as interfaces IConnectionPointContainer e IConnectionPoint e retorna um IDispatchpointer para o objeto.

   Para expor um evento usando automação, você deve responder a GetAutomationObject e observar as sequências adicionadas ao Registro. Na amostra de projeto básico, as sequências são BscProjectsEvents e BscProjectItemsEvents.

Entradas do Registro da amostra de projeto básico

Esta seção mostra onde adicionar valores de evento de automação ao Registro.

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

AutomationProjectEvents = Retorna o objeto AutomationProjectEvents.

AutomationProjectItemEvents = Retorna o objeto AutomationProjectItemsEvents.

Nome	Tipo	Intervalo	Descrição
Padrão (@)	REG_SZ	Não usado	Não utilizado. Você pode usar o campo de dados para documentação.
AutomationProjectsEvents	REG_SZ	Nome do objeto de evento.	Apenas o nome da chave é relevante. Você pode usar o campo de dados para documentação. Este exemplo vem da amostra de projeto básico.
AutomationProjectItemEvents	REG_SZ	Nome do objeto de evento	Apenas o nome da chave é relevante. Você pode usar o campo de dados para documentação. Este exemplo vem da amostra de projeto básico.

Quando qualquer objeto de evento for solicitado por um consumidor de automação, crie um objeto raiz que tenha métodos para qualquer evento que o VSPackage suporte. O ambiente chama o método apropriado get_ neste objeto. Por exemplo, se DTE.Events.AutomationProjectsEvents for chamado, o método get_AutomationProjectsEvents no objeto raiz será invocado.

Modelo de automação para eventos

A classe CProjectEventsContainer representa o objeto de origem para BscProjectsEvents e CProjectItemsEventsContainer representa o objeto de origem para BscProjectItemsEvents.

Na maioria dos casos, você deve retornar um novo objeto para cada solicitação de evento porque a maioria dos objetos de evento usa um objeto de filtro. Ao disparar o evento, verifique esse filtro para confirmar se o manipulador de eventos está sendo chamado.

AutomationEvents.h e AutomationEvents.cpp contêm declarações e implementações das classes na tabela a seguir.

Classe	Descrição
CAutomationEvents	Implementa um objeto raiz de evento, recuperado do objeto DTE.Events.
CProjectsEventsContainer e CProjectItemsEventsContainer	Implemente os objetos de origem de evento que disparam os eventos correspondentes.

O exemplo de código a seguir mostra como responder a uma solicitação de um objeto de evento.

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;
}

No código acima, g_wszAutomationProjects é o nome da sua coleção de projetos (FigProjects), g_wszAutomationProjectsEvents (FigProjectsEvents) e g_wszAutomationProjectItemsEvents (FigProjectItemEvents) são os nomes de eventos de projeto e eventos de itens de projeto que são originados da implementação do VSPackage.

Os objetos de evento são recuperados da mesma localização central, o objeto DTE.Events. Dessa forma, todos os objetos de evento são agrupados para que um usuário final não precise procurar o modelo de objeto inteiro para localizar um evento específico. Isso também permite que você forneça seus objetos do VSPackage específicos, em vez de exigir que você implemente seu próprio código para eventos de todo o sistema. No entanto, para o usuário final, que deve localizar um evento para a interface ProjectItem, não está imediatamente claro de onde esse objeto de evento é recuperado.

Conteúdo relacionado

• GetAutomationObject