This documentation is archived and is not being maintained.

GetObject Function

Returns a reference to an object provided by a COM component.

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


Optional; String. The full path and name of the file containing the object to retrieve. If pathname is omitted, class is required.
Optional; String. A string representing the class of the object.

The Class argument has the following syntax and parts:


Class Parameters

Required; String. The name of the application providing the object.
Required; String. The type or class of object to create.


Exception type Error number Condition
Exception 429 No object with the specified pathname exists.
FileNotFoundException 432 No object of the specified type exists.


Use the GetObject function to load an instance of a COM component from a file. For example:

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

When this code is executed, the application associated with the specified pathname is started and the object in the specified file is activated.

If PathName is a zero-length string (""), GetObject returns a new object instance of the specified type. If the PathName argument is omitted, GetObject returns a currently active object of the specified type. If no object of the specified type exists, an error occurs.

Some applications allow you to activate a sub-object associated with a file. Add an exclamation point (!) to the end of the file name and follow it with a string that identifies the part of the file you want to activate. For information on how to create this string, see the documentation for the application that created the object.

For example, in a drawing application you might have multiple layers to a drawing stored in a file. You could use the following code to activate a layer within a drawing called SCHEMA.CAD:

LayerObject = GetObject("C:\CAD\SCHEMA.CAD!Layer3")

If you don't specify the object's Class, Automation determines the application to start and the object to activate, based on the file name you provide. Some files, however, may support more than one class of object. For example, a drawing might support three different types of objects: an Application object, a Drawing object, and a Toolbar object, all of which are part of the same file. To specify which object in a file you want to activate, use the optional Class argument. For example:

Dim MyObject As Object

In the example, FIGMENT is the name of a drawing application and DRAWING is one of the object types it supports.

Once an object is activated, you reference it in code using the object variable you defined. In the preceding example, you access properties and methods of the new object using the object variable MyObject. For example:

MyObject.Line (9, 90)
MyObject.InsertText (9, 100, "Hello, world.")
Note   Use the GetObject function when there is a current instance of the object or if you want to create the object with a file already loaded. If there is no current instance, and you do not want the object started with a file loaded, use the CreateObject function. If an object has registered itself as an Active-X single-instance object, only one instance of the object is created, no matter how many times CreateObject is executed. With a single-instance object, GetObject always returns the same instance when called with the zero-length string ("") syntax, and it causes an error if the PathName argument is omitted. You cannot use GetObject to obtain a reference to a class created with Visual Basic.


This example uses the GetObject function to get a reference to a specific Microsoft Excel worksheet (MyXL). It uses the worksheet's Application property to make Microsoft Excel visible, to close it, and so on. Using two API calls, the DetectExcel sub procedure looks for Microsoft Excel, and if it is running, enters it in the running object table. The first call to GetObject causes an error if Microsoft Excel isn't already running. In the example, the error causes the ExcelWasNotRunning flag to be set to True. The second call to GetObject specifies a file to open. If Microsoft Excel isn't already running, the second call starts it and returns a reference to the worksheet represented by the specified file, test.xls. The file must exist in the specified location; otherwise, the Visual Basic error Automation error is generated. Next the example code makes both Microsoft Excel and the window containing the specified worksheet visible.

Option Strict Off is required because this example uses late binding, where objects are assigned to generic object variables. You can specify Option Strict On and declare objects of specific object types if you add a reference to the Excel type library from the COM tab of the Add Reference dialog box of the Project menu in Visual Studio .NET.

' Add Option Strict Off to the top of your program.
Option Strict Off
 ' Declare necessary API routines:
   Declare Function FindWindow Lib "user32" Alias _
      "FindWindowA" (ByVal lpClassName As String, _
      ByVal lpWindowName As Long) As Long

   Declare Function SendMessage Lib "user32" Alias _
   "SendMessageA" (ByVal hWnd As Long, ByVal wMsg As Long, _
      ByVal wParam As Long, ByVal lParam As Long) As Long

Sub GetExcel()
   Dim MyXL As Object   ' Variable to hold reference
   ' to Microsoft Excel.
   Dim ExcelWasNotRunning As Boolean   ' Flag for final release.

   ' Test to see if there is a copy of Microsoft Excel already running.
   On Error Resume Next   ' Defer error trapping.
   ' Getobject function called without the first argument returns a
   ' reference to an instance of the application. 
   ' If the application is not running, an error occurs.
   MyXL = GetObject(, "Excel.Application")
   If Err().Number <> 0 Then ExcelWasNotRunning = True
   Err().Clear() ' Clear Err object in case error occurred.

   ' Check for Microsoft Excel. If Microsoft Excel is running,
   ' enter it into the Running Object table.

   ' Set the object variable to reference the file you want to see.
   MyXL = GetObject("c:\vb\TEST.XLS")

   ' Show Microsoft Excel through its Application property. Then
   ' show the actual window containing the file using the Windows
   ' collection of the MyXL object reference.
   MyXL.Application.Visible = True
   MyXL.Parent.Windows(1).Visible = True
   '  Do manipulations of your  file here.
End Sub

Sub DetectExcel()
   ' Procedure dectects a running Excel and registers it.
   Const WM_USER = 1024
   Dim hWnd As Long
   ' If Excel is running this API call returns its handle.
   hWnd = FindWindow("XLMAIN", 0)
   If hWnd = 0 Then   ' 0 means Excel not running.
      Exit Sub
      ' Excel is running so use the SendMessage API
      ' function to enter it in the Running Object Table.
      SendMessage(hWnd, WM_USER + 18, 0, 0)
   End If
End Sub

When you call the GetExcel function, a check is made to see if Excel is already running. If it is not, then an instance of Excel is created.

Smart Device Developer Notes

This function is not supported.


Namespace: Microsoft.VisualBasic

Module: Interaction

Assembly: Microsoft Visual Basic .NET Runtime (in Microsoft.VisualBasic.dll)

See Also

CreateObject Function | Declare Statement | Exception Class | FileNotFoundException Class