Como utilizar o Visual C# para automatizar uma instância em execução de um programa do Office

Resumo

Este artigo passo a passo mostra-lhe como criar um cliente do Microsoft Visual C# 2005 ou Microsoft Visual C# .NET que obteva uma Referência de Automatização para uma instância em execução de um programa do Office.

Criar uma Aplicação Visual C# 2005 ou Visual C# .NET que Automatiza uma Instância Em Execução de um Programa do Office

Os programas de cliente que automatizam o Office podem criar uma nova instância do programa do Office ou obter uma referência à instância que já está em execução. A Microsoft recomenda geralmente que crie uma nova instância em vez de anexar a uma instância em execução. No entanto, em alguns cenários, o programa cliente tem de automatizar uma instância já em execução de um programa do Office. Neste caso, o cliente de automatização obtere a referência ao objeto COMPONENT Object Model (COM) do servidor de automatização a partir da Tabela de Objetos Em Execução (ROT).

Se o servidor de automatização se registou na Tabela de Objetos Em Execução, um cliente .NET pode obter uma referência para a instância em execução, chamando o seguinte:

System.Runtime.InteropServices.Marshall.GetActiveObject

-ou-

System.Runtime.InteropServices.Marshall.BindToMoniker

Código de Exemplo

1. Inicia o Microsoft Visual Studio 2005 ou o Microsoft Visual Studio .NET. No menu Ficheiro, clique em Novo e, em seguida, clique em Projeto. Em Tipos de projeto, clique em Projetos Visuais C# e, em seguida, em Modelos, clique em Aplicação do Windows. O formulário1 é criado por predefinição.

   Nota No Visual C# 2005, clique em Visual C# em vez de Projetos Visuais C#.

2. Adicione uma referência à Biblioteca de Objetos do Microsoft Excel e à Biblioteca de Objetos do Microsoft Word. Para tal, siga estes passos:

   1. No menu Projeto, clique em Adicionar Referência.

   2. No separador COM, localize a Biblioteca de Objetos doMicrosoft Excel e, em seguida, clique em Selecionar.

      Nota No Visual C# 2005, não tem de clicar em Selecionar.

      Nota O Microsoft Office 2003 inclui Conjuntos de Interojuntas Principais (PIAs). O Microsoft Office XP não inclui PIAs, mas estes poderão ser transferidos.

   3. Localize a Biblioteca de Objetos do Microsoft Word e, em seguida, clique em Selecionar.

      Nota No Visual C# 2005, não tem de clicar em Selecionar.

   4. Na caixa de diálogo Adicionar Referências, clique em OK para aceitar as suas seleções.

3. No menu Ver, clique em Caixa de Ferramentas para apresentar a caixa de ferramentas. Adicione três botões e uma caixa de texto ao Formulário1. Escreva o texto destes controlos da seguinte forma:

   ID	Text
   botão1	Obter a Referência de Automatização para executar a Instância do Excel
   botão2	Obter a Referência de Automatização para o Excel utilizando File Moniker
   botão3	Shell Word e Obter Referência de Automatização para o mesmo
   textBox1	Introduza o nome do ficheiro xls guardado

4. Configurar os controladores de eventos Click dos controlos de botão, da seguinte forma:

   1. Faça duplo clique no botão1 e, em seguida, clique em Estruturador no menu Ver.
   2. Faça duplo clique no botão2 e, em seguida, clique em Estruturador no menu Ver.
   3. Faça duplo clique no botão3.

5. Adicione o seguinte código ao topo do Form1.cs, a seguir ao outro utilizando instruções:

   using Excel = Microsoft.Office.Interop.Excel;
   using Word = Microsoft.Office.Interop.Word;
   

6. Adicione o seguinte código aos organizadores de eventos:

   private void button1_Click(object sender, System.EventArgs e)
   {
   
   //Excel Application Object
   Excel.Application oExcelApp;
   
   this.Activate();
   
   //Get reference to Excel.Application from the ROT.
   oExcelApp =  (Excel.Application)System.Runtime.InteropServices.Marshal.GetActiveObject("Excel.Application");
   
   //Display the name of the object.
   MessageBox.Show(oExcelApp.ActiveWorkbook.Name);
   
   //Release the reference.
   oExcelApp = null;
   }
   
   private void button2_Click(object sender, System.EventArgs e)
   {
   Excel.Workbook  xlwkbook;
   Excel.Worksheet xlsheet;
   
   //Get a reference to the Workbook object by using a file moniker.
   //The xls was saved earlier with this file name.
   xlwkbook = (Excel.Workbook)  System.Runtime.InteropServices.Marshal.BindToMoniker(textBox1.Text); 
   
   string sFile = textBox1.Text.Substring(textBox1.Text.LastIndexOf("\\")+1);
   xlwkbook.Application.Windows[sFile].Visible = true;
   xlwkbook.Application.Visible = true;
   xlsheet = (Excel.Worksheet) xlwkbook.ActiveSheet;
   xlsheet.Visible = Excel.XlSheetVisibility.xlSheetVisible;
   xlsheet.Cells[1,1] = 100;
   
   //Release the reference.
   xlwkbook = null;
   xlsheet = null;
   }
   
   private void button3_Click(object sender, System.EventArgs e)
   {
   Word.Application wdapp;
   
   //Shell Word
   System.Diagnostics.Process.Start("<Path to WINWORD.EXE>");
   
   this.Activate();
   
   //Word and other Office applications register themselves in 
   //ROT when their top-level window loses focus. Having a MessageBox 
   //forces Word to lose focus and then register itself in the ROT.
   
   MessageBox.Show("Launched Word");
   
   //Get the reference to Word.Application from the ROT.
   wdapp = (Word.Application)System.Runtime.InteropServices.Marshal.GetActiveObject("Word.Application");
   
   //Display the name.
   MessageBox.Show(wdapp.Name);
   
   //Release the reference.
   wdapp = null;
   }
   
   

   Nota Em button3_click(), substitua Caminho para Winword.exe pelo caminho correto para Winword.exe. A localização predefinida do Microsoft Word é C:\Program Files\Microsoft Office\Office\Winword.exe.

7. No menu Criar, selecione Construir Solução para criar a aplicação.

Testar a Aplicação

1. Prima F5 para criar e executar a sua aplicação.
2. Esmaeça todas as instâncias em execução do Excel.
3. Comece o Excel com um novo livro.
4. Clique no botão Obter Referência de Automatização para executar a Instância do Excel .
5. A aplicação obtete a referência de automatização à instância existente do Excel. A referência de automatização é armazenada na variável local oExcelApp para button1_Click. Uma caixa de mensagem apresenta o nome do livro ativo.
6. Guarde o livro no disco local. Deixe o livro aberto no Excel.
7. Escreva o caminho completo e o nome de ficheiro do livro que guardou no passo anterior na caixa de texto Caixa1.
8. Clique no botão Obter Referência de Automatização para o Excel através do botão File Moniker .
9. A aplicação recebe uma referência de automatização para a instância em execução do Excel. A Referência de Automatização é armazenada na variável local xlwkbookpara button2_Click. É introduzido um valor de 100 na primeira linha e na primeira coluna da folha ativa.
10. Saia do Excel sem guardar as alterações feitas ao livro.
11. Clique no botão Obter Referência de Automatização para o Excel através do botão File Moniker .
12. É criada uma nova instância do Excel e o livro guardado anteriormente é aberto. A aplicação obtete uma referência de automatização a esta instância do Excel. A Referência de Automatização é armazenada no xlwkbook da variável local para button2_Click. É introduzido um valor de 100 na primeira linha e na primeira coluna da folha ativa.
13. Feche o Excel.
14. Clique no botão Shell Word e Obter Referência de Automatização para a mesma.
15. O Word é iniciado, tal como se o iniciasse a partir de uma mensagem de comando e a caixa de mensagem Iniciado do Word fosse apresentada. A apresentação de uma caixa de mensagem força a WM_SETFOCUS mensagem a ser enviada para a janela do programa do Word. Isto permite ao Word registar-se na Tabela de Objetos Em Execução (ROT).
16. Feche a caixa de mensagem. O programa recebe uma referência de automatização para a nova instância iniciada do Word. A referência de automatização é armazenada no wdapp de variável local para button3_Click. É apresentada uma caixa de mensagem que mostra o nome do objeto Word.Application.

Notas Adicionais

Os servidores COM podem ser classificados como Múltiplas (Instância Única) ou Utilização Única (Múltiplas Instâncias), dependendo do número de instâncias do servidor que podem ser executados em simultâneo num único computador.

Quando um pedido de um novo objeto COM chega a um servidor COM de Várias Utilizações (Instância Única), o servidor utiliza apenas uma instância do ficheiro .exe para criar esse objeto. Independentemente de quantos clientes pedirem um novo objeto COM, só haverá um servidor .exe processo. No servidor de Utilização Única (Múltiplas Instâncias), cada pedido de um novo objeto COM inicia uma instância separada do ficheiro de servidor .exe ficheiro. Assim, mais do que uma instância do servidor pode ser executado no mesmo computador.

Várias instâncias do Word (Winword.exe), Excel (Excel.exe) e Microsoft Access (MSAccess.exe) podem ser executados em simultâneo. Por conseguinte, estes servidores são definidos como servidores de Utilização Única (Múltiplas Instâncias). Apenas uma instância do PowerPoint (Powerpnt.exe) pode ser executada a qualquer altura. Portanto, o PowerPoint é um servidor de Várias Utilização (Instância Única).

Se um servidor COM for de Utilização Única (Múltiplas Instâncias) ou Múltiplas Instâncias (Instância Única) poderá afetar a sua decisão de utilizar GetActiveObject para obter referência a esse servidor. Como é possível que mais do que uma instância do Word, Excel ou Microsoft Access possa estar em execução, a funcionalidade GetActiveObject num servidor específico poderá devolver uma instância que não esperava. A instância que é registada pela primeira vez no ROT é, normalmente, a instância que é devolvida pela GetActiveObject. Se quiser obter uma Referência de Automatização para uma instância de execução específica do Word, Excel ou Microsoft Access, utilize BindToMoniker com o nome do ficheiro aberto na instância. Para um servidor multiutilizador (Instância Única), como o PowerPoint, não é importante, porque a referência de automatização aponta para a mesma instância em execução.

Espera-se que os servidores COM se registem na Tabela de Objetos Em Execução após o arranque. Os programas do Office registam-se quando perdem o foco. Se um programa tentar anexar a uma instância em execução antes de o programa perder o foco, poderá receber uma mensagem de erro.

Referências

Para obter informações adicionais sobre os diferentes comportamentos dos programas do Office quando utiliza a funcionalidade GetActiveObject, clique no número de artigo abaixo para ver o artigo na Base de Dados de Conhecimento Microsoft:

288902 informações: Comportamento da GetObject e CreateObject dos Servidores de Automatização do Office Para obter mais informações, consulte o seguinte site do Microsoft Developer Network (MSDN):

Desenvolvimento do Microsoft Office com Visual Studio