Função GetObject (Visual Basic)

Artigo
08/25/2010

Retorna uma referência a um objeto fornecido por um componente COM.

Public Function GetObject( _
    Optional ByVal PathName As String = Nothing, _
    Optional ByVal [Class] As String = Nothing _
) As Object

Parâmetros

Parâmetro	Descrição
PathName	Opcional.String.O caminho completo e nome do arquivo que contém o objeto para recuperar.Se PathName for omitido ou for uma string de comprimento nulo (""), Class será necessária.
Class	Necessário se PathName não for fornecido.String.Uma seqüência de caracteres que representa a classe do objeto.O argumento Class possui a seguinte sintaxe e partes: appname.objecttype Parâmetro Descrição appnameObrigatório.String.O nome do aplicativo fornecendo o objeto. objecttypeObrigatório.String.O tipo ou classe de objeto para criar.

PathName

Opcional.String.O caminho completo e nome do arquivo que contém o objeto para recuperar.Se PathName for omitido ou for uma string de comprimento nulo (""), Class será necessária.

Class

Necessário se PathName não for fornecido.String.Uma seqüência de caracteres que representa a classe do objeto.O argumento Class possui a seguinte sintaxe e partes:

appname.objecttype

Parâmetro Descrição

appnameObrigatório.String.O nome do aplicativo fornecendo o objeto.

objecttypeObrigatório.String.O tipo ou classe de objeto para criar.

Exceções

Tipo de exceção	Número de erro	Condição
Exception	429	Nenhum objeto do tipo de classe especificado existe.
FileNotFoundException	432	Não existe nenhum objeto com o caminho e nome de arquivo especificados.

Ver a coluna " número de erro " se você estiver atualizando aplicativos Visual Basic 6.0 que usam manipulação de erros não estruturada.(Você pode comparar o número do erro com a Propriedade do Número (Erro de objeto).) Entretanto, quando for possivel, você pode considerar substituir tal controle de erro por Visão Geral sobre a Manipulação Estruturada de Exceções para o Visual Basic.

Comentários

Use a função GetObject para carregar uma instância de um componente COM a partir de um arquivo.O exemplo a seguir ilustra isto:

Dim CADObject As Object
CADObject = GetObject("C:\CAD\schema.cad")

Quando esse código é executado, o aplicativo associado com o PathName especificado é iniciado e o objeto no arquivo especificado é ativado.

Casos padrão

Se PathName for uma string de comprimento nulo (""), GetObject retornará uma nova instância do tipo de classe especificado.Se o argumento PathName for omitido, GetObject retorna um objeto do tipo de classe especificado em Class que esteja ativo no momento.Se nenhum objeto do tipo especificado existir, ocorrerá um erro.

Acessando um Subobjeto

Alguns aplicativos permitem que você ative um subobjeto associado a um arquivo.Para fazer isso, adicione um ponto de exclamação (!) ao final do nome de arquivo e depois coloque uma sequência de caracteres que identifique a parte do arquivo que você deseja ativar.Para obter informações sobre como criar essa sequência de caracteres, consulte a documentação do aplicativo que criou o objeto.

Por exemplo, em um aplicativo de desenho, você pode ter várias camadas para um desenho armazenado em um arquivoVocê pode usar o código a seguir para ativar uma camada em um desenho chamado schema.cad.

layerObject = GetObject("C:\CAD\schema.cad!Layer3")

Especificando uma classe

Se você não especificar a Classdo objeto, a automação determina que o aplicativo inicie e o objeto fique ativo, com base no nome de arquivo que você fornecer.Alguns arquivos, no entanto, podem suportar mais de uma classe de objeto.Por exemplo, um desenho pode oferecer suporte a três tipos diferentes de objetos: an Application objeto, um Drawing objeto e um Toolbar objeto, todos os que fazem parte do mesmo arquivo. Para especificar qual objeto em um arquivo que você deseja ativar, use o argumento opcional Class.O exemplo a seguir ilustra isto:

Dim drawObj As Object
drawObj = GetObject("C:\Drawings\sample.drw", "Figment.Drawing")

No exemplo anterior, Figment é o nome de um aplicativo de desenho e Drawing é um dos tipos de objeto suportados.

Usando o objeto

Depois que um objeto for ativado, você faz referência a ele no código usando a variável de objeto que você declarou.No exemplo anterior, você acessa propriedades e métodos do objeto novo usando a variável de objeto drawObj.O exemplo a seguir ilustra isto:

drawObj.Line(9, 90)
drawObj.InsertText(9, 100, "Hello, world.")
drawObj.SaveAs("C:\Drawings\sample.drw")

Observação:
Use o GetObject função quando há uma instância corrente do objeto ou se você deseja criar o objeto com um arquivo carregado. Se não houver nenhuma instância atual, e você não deseja o objeto iniciado com um arquivo carregado, use a CreateObject função (Visual Basic). Se um objeto tiver se auto-registrado sistema autônomo um objeto de instância única do ActiveX, apenas uma instância do objeto será criada, não importa quantas vezes CreateObject é chamado.Com um objeto de instância única GetObject sempre retorna a mesma instância quando chamado com o (cadeia de comprimento zero "" ) sintaxe e causa um erro se o PathName argumento é omitido.Não é possível usar GetObject Para obter uma referência a uma classe criada com o Visual Basic.

Use o GetObject função quando há uma instância corrente do objeto ou se você deseja criar o objeto com um arquivo carregado. Se não houver nenhuma instância atual, e você não deseja o objeto iniciado com um arquivo carregado, use a CreateObject função (Visual Basic).

Se um objeto tiver se auto-registrado sistema autônomo um objeto de instância única do ActiveX, apenas uma instância do objeto será criada, não importa quantas vezes CreateObject é chamado.Com um objeto de instância única GetObject sempre retorna a mesma instância quando chamado com o (cadeia de comprimento zero "" ) sintaxe e causa um erro se o PathName argumento é omitido.Não é possível usar GetObject Para obter uma referência a uma classe criada com o Visual Basic.

Observação de segurança:
O GetObject função requer permissão do código não gerenciado, que poderá afetar sua execução em situações de confiança parcial. Para obter mais informações, consulte SecurityPermission e Permissões de acesso a código .

Quando tiver terminado de usar o objeto, definia todas as referências para o objeto como Nothing.Isso permite que o tempo de execução descarte o componente COM.

Exemplo

O exemplo a seguir usa a função GetObject para determinar se o Excel está em execução.

' Test to see if a copy of Excel is already running.
Private Sub testExcelRunning()
    On Error Resume Next
    ' GetObject called without the first argument returns a
    ' reference to an instance of the application. If the
    ' application is not already running, an error occurs.
    Dim excelObj As Object = GetObject(, "Excel.Application")
    If Err.Number = 0 Then
        MsgBox("Excel is running")
    Else
        MsgBox("Excel is not running")
    End If
    Err.Clear()
    excelObj = Nothing
End Sub

O exemplo a seguir usa a função GetObject para obter uma referência a uma planilha do Microsoft Excel (excelObj)específica.A chamada para GetObject retorna uma referência à planilha representada pelo arquivo especificado, test.xls.Em seguida, o código de exemplo torna o Excel e a janela que contém a planilha especificada visíveis.

Esse exemplo requer Option Strict Off porque ele usa ligação tardia, onde os objetos são atribuídos a variáveis do tipo Object.Você pode especificar Option Strict On e declarar objetos dos tipos de objeto específicos se você adicionar um referência de projeto à biblioteca de tipos do Excel.Para fazer isso, abra a caixa de diálogo Adicionar Referência no menu Projeto no Visual Studio e selecione a biblioteca de tipos do Excel na aba COM.

' Add Option Strict Off to the top of your program.
Option Strict Off

Private Sub getExcel()
    Dim fileName As String = "c:\vb\test.xls"

    If Not My.Computer.FileSystem.FileExists(fileName) Then
        MsgBox(fileName & " does not exist")
        Exit Sub
    End If

    ' Set the object variable to refer to the file you want to use.
    Dim excelObj As Object = GetObject(fileName)
    ' Show Excel through its Application property. 
    excelObj.Application.Visible = True
    ' Show the window containing the file.
    Dim winCount As Integer = excelObj.Parent.Windows.Count()
    excelObj.Parent.Windows(winCount).Visible = True

    ' Insert additional code to manipulate the test.xls file here.
    ' ...

    excelObj = Nothing
End Sub