Comportamento GetObject e CreateObject dos servidores de automatização do Office

Resumo

Este artigo aborda os diferentes comportamentos que ocorrem quando utiliza as funções GetObject e CreateObject com várias versões de aplicações do Microsoft Office.

GetObject e CreateObject são funções fornecidas pelo Microsoft Visual Basic e pelo Microsoft Visual Basic for Applications (VBA). No entanto, as informações também são aplicáveis ao Microsoft Visual C++ se tratar as referências a GetObject como chamadas à API GetActiveObject e referências a CreateObject como chamadas para a CoCreateInstanceAPI.

Mais Informações

GetObject

O GetObject é utilizado para anexar a uma instância em execução de um servidor de automatização. Existem algumas formas diferentes de chamar GetObject, mas a sintaxe recomendada para as aplicações do Microsoft Office é a seguinte:

set xlApp = GetObject(, "Excel.Application")

Se uma instância do Microsoft Excel estiver em execução quando este código é executado, terá acesso ao modelo de objetos da instância em execução através da variável xlApp. Se nenhuma instância estiver em execução, receberá a seguinte mensagem de erro de tempo de execução intercetável:

Run-time error '429':
ActiveX component can't create object  

Se estiverem a ser executadas várias instâncias do Microsoft Excel, o GetObject anexa-se à instância que é iniciada primeiro. Se, em seguida, fechar a primeira instância, outra chamada para GetObject é anexada à segunda instância que foi iniciada e assim sucessivamente.

Pode anexar a uma instância específica se souber o nome de um documento aberto nessa instância. Por exemplo, se uma instância do Excel estiver em execução com um livro aberto chamado Book2, o seguinte código é anexado com êxito a essa instância, mesmo que não seja a instância mais antiga que foi iniciada:

Set xlApp = GetObject("Book2").Application

CriarObjeto

O CreateObject é utilizado para iniciar uma nova instância de um servidor de Automatização. Por exemplo:

set xlApp = CreateObject("Excel.Application")

Dependendo se o servidor foi concebido como SingleUse ou MultiUse, outro processo de servidor pode ou não ser iniciado. Esta pode ser uma distinção importante para decidir se deve encerrar à força uma instância de Automatização. Por exemplo, com um servidor MultiUse, se uma instância já estiver em execução antes de a anexar, poderá querer evitar encerrar o servidor programaticamente quando terminar de automatizar o mesmo.

A tabela seguinte serve como uma referência útil ao implementar uma solução com o Microsoft Office. Apresenta uma lista de comportamentos e atributos das várias versões e aplicações do Microsoft Office, tais como se a predefinição do servidor é visível quando é iniciada, se for SingleUse ou MultiUse, se tiver uma propriedade UserControl, se tiver um método Quit e o nome da classe para a janela principal.

O nome da classe de janela principal é útil para chamar a API FindWindow quando quer descobrir convenientemente se alguma instância já está em execução. A propriedade UserControl é uma propriedade booleana que indica se a aplicação do servidor é encerrada automaticamente quando a última referência é lançada (definida como nada). O método Quit permite-lhe substituir a propriedade UserControl nos casos em que é necessário (por exemplo, quando uma instância não é encerrada após a última referência ser lançada).

Em geral, a Microsoft recomenda que utilize uma nova instância de uma aplicação do Office em vez de anexar a uma instância que o utilizador possa estar a utilizar. É melhor criar uma instância com o ProgID da Aplicação e, em seguida, abrir ou criar novos objetos a partir daí. Outros ProgIDs, como Excel.Sheet e Word. O documento, etc., destina-se a ser utilizado no OLE (Ligação de objetos e Incorporação) e pode fornecer resultados inconsistentes quando utilizado com CreateObject. Ao utilizar o ProgID da Aplicação, evita potenciais problemas ao iniciar explicitamente o servidor para Automatização (não incorporar).

Quando tiver terminado o servidor de Automatização, liberte todas as suas referências ao mesmo e chame o respetivo método Quit (se disponível) para que o servidor seja encerrado conforme esperado. Se quiser configurar uma instância através da Automatização e, em seguida, deixá-la aberta para o utilizador utilizar, tem de definir a propriedade UserControl como VERDADEIRO e, em seguida, libertar todas as suas referências. Em seguida, o servidor permanece em execução (porque a propriedade UserControl é TRUE) e encerra adequadamente quando o utilizador fecha a aplicação (porque não existem referências pendentes).

Nota Para Word, a propriedade UserControl é só de leitura. Não pode ser definido como Verdadeiro ou Falso. Word permanece sempre em execução quando a última referência é lançada.