Compartilhar via


Eventos em projetos do Office

Cada modelo de projeto do Office gera automaticamente vários manipuladores de eventos. Os manipuladores de eventos para personalizações em nível de documento são ligeiramente diferentes dos manipuladores de eventos para suplementos VSTO.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento e projetos de suplemento VSTO. Consulte Recursos disponíveis por aplicativo e tipo de projeto do Office.

Projetos em nível de documento

O Visual Studio fornece código gerado por trás de documentos ou planilhas novos ou existentes em personalizações em nível de documento. Esse código gera dois eventos diferentes: inicialização e desligamento.

Evento de inicialização

O evento Startup é gerado para cada um dos itens de host (documento, pasta de trabalho ou planilha) depois que o documento está em execução e todo o código de inicialização no assembly foi executado. É a última coisa a ser executada no construtor da classe em que seu código está sendo executado. Para obter mais informações sobre itens de host, consulte Visão geral sobre itens de host e controles de host.

Quando você cria um projeto de nível de documento, o Visual Studio cria manipuladores de eventos para o evento Startup nos arquivos de código gerados:

  • Para projetos do Microsoft Office Word, o manipulador de eventos é chamado ThisDocument_Startup.

  • Para projetos do Microsoft Office Excel, os manipuladores de eventos têm os seguintes nomes:

    • Sheet1_Startup

    • Sheet2_Startup

    • Sheet3_Startup

    • ThisWorkbook_Startup

Evento de encerramento

O evento Shutdown é gerado para cada um dos itens do host (documento ou planilha) quando o domínio do aplicativo no qual o código é carregado está prestes a ser descarregado. É a última coisa a ser chamada na classe à medida que descarrega.

Quando você cria um projeto de nível de documento, o Visual Studio cria manipuladores de eventos para o evento Shutdown nos arquivos de código gerados:

  • Para projetos do Microsoft Office Word, o manipulador de eventos é chamado ThisDocument_Shutdown.

  • Para projetos do Microsoft Office Excel, os manipuladores de eventos têm os seguintes nomes:

    • Sheet1_Shutdown

    • Sheet2_Shutdown

    • Sheet3_Shutdown

    • ThisWorkbook_Shutdown

Observação

Não remova controles programaticamente durante o manipulador de eventos Shutdown do documento. Os elementos da interface do usuário do documento não estarão mais disponíveis quando o evento Shutdown ocorrer. Se você quiser remover controles antes que o aplicativo feche, adicione seu código a outro manipulador de eventos, como BeforeClose ou BeforeSave.

Declarações de método do manipulador de eventos

Cada declaração de método do manipulador de eventos tem os mesmos argumentos passados para ela: sender e e. No Excel, o argumento remetente refere-se à planilha, como Sheet1 ou Sheet2; no Word, o argumento remetente refere-se ao documento. O argumento e refere-se aos argumentos padrão para um evento, que não são usados neste caso.

O exemplo de código a seguir mostra os manipuladores de eventos padrão em projetos de nível de documento para o Word.

private void ThisDocument_Startup(object sender, System.EventArgs e)
{
}

private void ThisDocument_Shutdown(object sender, System.EventArgs e)
{
}

O exemplo de código a seguir mostra os manipuladores de eventos padrão em projetos de nível de documento para Excel.

Observação

O exemplo de código a seguir mostra os manipuladores de eventos na Sheet1 classe. Os nomes dos manipuladores de eventos em outras classes de item de host correspondem ao nome da classe. Por exemplo, na Sheet2 classe, o manipulador de eventos Startup é chamado Sheet2_Startup. Na classe, o ThisWorkbook manipulador de eventos Startup é chamado ThisWorkbook_Startup.

private void Sheet1_Startup(object sender, System.EventArgs e)
{
}

private void Sheet1_Shutdown(object sender, System.EventArgs e)
{
}

Ordem de eventos em projetos do Excel em nível de documento

Os manipuladores de eventos de inicialização em projetos do Excel são chamados nesta ordem:

  1. ThisWorkbook_Startup.

  2. Sheet1_Startup.

  3. Sheet2_Startup.

  4. Sheet3_Startup.

  5. Outras folhas em ordem.

    Os manipuladores de eventos Shutdown em uma solução de pasta de trabalho são chamados nesta ordem:

  6. ThisWorkbook_Shutdown.

  7. Sheet1_Shutdown.

  8. Sheet2_Shutdown.

  9. Sheet3_Shutdown.

  10. Outras folhas em ordem.

    A ordem é determinada quando o projeto é compilado. Se o usuário reorganizar as planilhas em tempo de execução, ele não alterará a ordem em que os eventos serão gerados na próxima vez que a pasta de trabalho for aberta ou fechada.

Projetos de suplemento VSTO

Visual Studio fornece código gerado em suplementos VSTO. Esse código gera dois eventos diferentes: Startup e Shutdown.

Evento de inicialização

O Startup evento é gerado depois que o suplemento VSTO é carregado e todo o código de inicialização no assembly foi executado. Esse evento é manipulado ThisAddIn_Startup pelo método no arquivo de código gerado.

O código no ThisAddIn_Startup manipulador de eventos é o primeiro código de usuário a ser executado, a menos que o suplemento VSTO substitua o RequestComAddInAutomationService método. Nesse caso, o ThisAddIn_Startup manipulador de eventos é chamado após RequestComAddInAutomationService.

Não adicione código no ThisAdd-In_Startup manipulador de eventos se o código exigir que um documento esteja aberto. Em vez disso, adicione esse código a um evento que o aplicativo do Office gera quando um usuário cria ou abre um documento. Para obter mais informações, consulte Acessar um documento quando o aplicativo do Office é iniciado.

Para obter mais informações sobre a sequência de inicialização de suplementos VSTO, consulte Arquitetura de suplementos VSTO.

Evento de encerramento

O Shutdown evento é gerado quando o domínio do aplicativo no qual seu código é carregado está prestes a ser descarregado. Esse evento é manipulado ThisAddIn_Shutdown pelo método no arquivo de código gerado. Esse manipulador de eventos é o último código de usuário a ser executado quando o suplemento VSTO é descarregado.

Evento de desligamento nos suplementos VSTO do Outlook

O Shutdown evento é gerado somente quando o usuário desabilita o suplemento VSTO usando a caixa de diálogo Suplementos COM no Outlook. Ele não é gerado quando o Outlook sai. Se você tiver código que deve ser executado quando o Outlook é encerrado, manipule um dos seguintes eventos:

Observação

Você pode forçar o Outlook a gerar o evento quando ele for encerrado modificando o Shutdown registro. No entanto, se um administrador reverter essa configuração, qualquer código adicionado ao método não será mais executado quando o ThisAddIn_Shutdown Outlook for encerrado. Para obter mais informações, consulte Alterações de desligamento para o Outlook 2010.