GetObject (Función, Visual Basic)

Artículo
10/07/2008

Actualización: noviembre 2007

Devuelve una referencia a un objeto proporcionado por un componente COM.

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

Parámetros

Parámetro	Descripción
PathName	Opcional. String. Ruta de acceso completa y nombre del archivo que contiene el objeto que se va a recuperar. Si PathName se omite o es una cadena de longitud cero (""), se requiere Class.
Class	Obligatorio si no se proporciona PathName. String. Cadena que representa la clase del objeto. El argumento Class tiene la siguiente sintaxis y partes: appname.objecttype ParámetroDescripción appnameObligatorio. String. Nombre de la aplicación que proporciona el objeto. objecttypeObligatorio. String. Tipo o clase del objeto que se va a crear.

PathName

Opcional. String. Ruta de acceso completa y nombre del archivo que contiene el objeto que se va a recuperar. Si PathName se omite o es una cadena de longitud cero (""), se requiere Class.

Class

Obligatorio si no se proporciona PathName. String. Cadena que representa la clase del objeto. El argumento Class tiene la siguiente sintaxis y partes:

appname.objecttype

ParámetroDescripción

appnameObligatorio. String. Nombre de la aplicación que proporciona el objeto.

objecttypeObligatorio. String. Tipo o clase del objeto que se va a crear.

Excepciones

Tipo de excepción	Número de error	Condición
Exception	429	No existe ningún objeto del tipo de clase especificado.
FileNotFoundException	432	No existe ningún objeto con la ruta de acceso y el nombre de archivo especificados.

Consulte la columna "Número de error" si está actualizando aplicaciones de Visual Basic 6.0 que utilizan el control de errores no estructurado. (Se puede comparar el número de error con respecto a Number (Propiedad, objeto Err)). Sin embargo, siempre que sea posible, se debe considerar la sustitución de dicho control de errores por Información general sobre el control estructurado de excepciones de Visual Basic.

Comentarios

Utilice la función GetObject para cargar una instancia de un componente COM desde un archivo. Esto se ilustra en el siguiente ejemplo:

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

Cuando se ejecuta este código, la aplicación asociada con el argumento PathName especificado se inicia y se activa el objeto en el archivo especificado.

Casos predeterminados

Si PathName es una cadena de longitud cero (""), GetObject devuelve una nueva instancia de objeto del tipo de clase especificado. Si se omite el argumento PathName, GetObject devuelve un objeto actualmente activo del tipo de clase especificado en Class. Si no existe ningún objeto del tipo especificado, se produce un error.

Acceso a un subobjeto

Algunas aplicaciones permiten activar un subobjeto asociado a un archivo. Para ello, agregue un signo de exclamación (!) al final del nombre de archivo, seguido de una cadena que especifique la parte del archivo que desea activar. Para obtener información sobre cómo crear esta cadena, consulte la documentación de la aplicación que ha creado el objeto.

Por ejemplo, en una aplicación de dibujo, quizá tenga muchas capas para un dibujo almacenado en un archivo. Puede utilizar el código siguiente para activar una capa dentro de un dibujo denominado schema.cad.

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

Especificar un clase

Si no especifica la Class del objeto, la automatización determina la aplicación que se va a iniciar y el objeto que se va a activar, basándose en el nombre de archivo que se proporcione. Sin embargo, algunos archivos pueden admitir más de una clase de objeto. Por ejemplo, un dibujo puede ser compatible con tres tipos diferentes de objetos: un objeto Application, un objeto Drawing y un objeto Toolbar, que forman parte todos ellos del mismo archivo. Para especificar el objeto que desea activar en un archivo, utilice el argumento opcional Class. Esto se ilustra en el siguiente ejemplo:

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

En el ejemplo anterior, Figment es el nombre de una aplicación de dibujo y Drawing es uno de los tipos de objeto que admite.

Utilizar el objeto

Una vez que se activa un objeto, se hace referencia a él en el código mediante la variable de objeto que haya declarado. En el ejemplo anterior, se tiene acceso a las propiedades y métodos del nuevo objeto mediante la variable de objeto drawObj. Esto se ilustra en el siguiente ejemplo:

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

Nota:
Utilice la función GetObject cuando exista una instancia actual del objeto o cuando desee crear el objeto con un archivo cargado. Si no existe ninguna instancia actual y no desea que se inicie el objeto con un archivo cargado, utilice CreateObject (Función, Visual Basic). Si se ha registrado un objeto como objeto Active-X de una instancia, sólo se crea una instancia del objeto, independientemente del número de veces que se llame a CreateObject. Con un objeto de una sola instancia, la función GetObject devuelve siempre la misma instancia cuando se llama con sintaxis de cadena de longitud cero (""), y origina un error si se omite el argumento PathName. No se puede utilizar GetObject para obtener una referencia a una clase creada con Visual Basic.

Utilice la función GetObject cuando exista una instancia actual del objeto o cuando desee crear el objeto con un archivo cargado. Si no existe ninguna instancia actual y no desea que se inicie el objeto con un archivo cargado, utilice CreateObject (Función, Visual Basic).

Si se ha registrado un objeto como objeto Active-X de una instancia, sólo se crea una instancia del objeto, independientemente del número de veces que se llame a CreateObject. Con un objeto de una sola instancia, la función GetObject devuelve siempre la misma instancia cuando se llama con sintaxis de cadena de longitud cero (""), y origina un error si se omite el argumento PathName. No se puede utilizar GetObject para obtener una referencia a una clase creada con Visual Basic.

Nota de seguridad:
La función GetObject requiere un permiso de código no administrado que puede afectar a su ejecución en situaciones de confianza parcial. Para obtener más información, vea SecurityPermission y Permisos de acceso a código.

Al terminar de utilizar el objeto, establezca todas las referencias al objeto en Nothing. Esto permite al motor en tiempo de ejecución eliminar el componente COM.

Ejemplo

En el ejemplo siguiente se utiliza la función GetObject para determinar si Excel está ejecutándose.

' 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

En este ejemplo se utiliza la función GetObject para obtener una referencia a una hoja de cálculo de Microsoft Excel (excelObj) específica. La llamada a GetObject devuelve una referencia a la hoja de cálculo representada por el archivo especificado, test.xls. A continuación, el código de ejemplo hace que aparezcan Excel y la ventana que contiene la hoja de cálculo especificada.

En este ejemplo se requiere Option Strict Off porque utiliza enlace en tiempo de ejecución, en el que los objetos se asignan a variables de tipo Object. Puede especificar Option Strict On y puede declarar objetos de tipos de objeto concretos si agrega una referencia de proyecto a la biblioteca de tipos de Excel. Para ello, abra el cuadro de diálogo Agregar referencia en el menú Proyecto de Visual Studio y seleccione la biblioteca de tipos de Excel en la ficha 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