|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here.|
GetObject Function (Visual Basic)
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 or is a zero-length string (""), Class is required.
Required if PathName is not supplied. String. A string representing the class of the object. The Class argument has the following syntax and parts:
appname . objecttype
|Exception type||Error number||Condition|
No object of the specified class type exists.
No object with the specified path and file name exists.
See the "Error number" column if you are upgrading Visual Basic 6.0 applications that use unstructured error handling. (You can compare the error number against the.) However, when possible, you should consider replacing such error control with .
Use the GetObject function to load an instance of a COM component from a file. The following example illustrates this.
Dim CADObject As Object CADObject = GetObject("C:\CAD\schema.cad")
When this code runs, 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 class type. If the PathName argument is omitted, GetObject returns a currently active object of the class type specified in Class. If no object of the specified type exists, an error occurs.
Accessing a Subobject
Some applications allow you to activate a subobject associated with a file. To do this, 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")
Specifying a Class
If you do not 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, can 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. The following example illustrates this.
Dim drawObj As Object drawObj = GetObject("C:\Drawings\sample.drw", "Figment.Drawing")
In the preceding example, Figment is the name of a drawing application and Drawing is one of the object types it supports.
Using the Object
Once an object is activated, you refer to it in code using the object variable you declared. In the preceding example, you access properties and methods of the new object using the object variable drawObj. The following example illustrates this.
drawObj.Line(9, 90) drawObj.InsertText(9, 100, "Hello, world.") drawObj.SaveAs("C:\Drawings\sample.drw")
Use the GetObject function when there is a current instance of the object or if you want to create the object with a file loaded. If there is no current instance, and you do not want the object started with a file loaded, use the.
If an object has registered itself as an ActiveX single-instance object, only one instance of the object is created, no matter how many times CreateObject is called. 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.
The GetObject function requires unmanaged code permission, which might affect its execution in partial-trust situations. For more information, seeand .
When you are finished using the object, set all references to the object to Nothing. This allows the runtime to dispose of the COM component.
The following example uses the GetObject function to determine whether Excel is running.
' 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
The following example uses the GetObject function to obtain a reference to a specific Microsoft Excel worksheet (excelObj). The call to GetObject returns a reference to the worksheet represented by the specified file, test.xls. Next, the example code makes both Excel and the window containing the specified worksheet visible.
This example requires Option Strict Off because it uses late binding, where objects are assigned to variables of type Object. You can specify Option Strict On and declare objects of specific object types if you add a project reference to the Excel type library. To do so, open the Add Reference dialog box from the Project menu in Visual Studio and select the Excel type library on the COM tab.
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
Assembly: Visual Basic Runtime Library (in Microsoft.VisualBasic.dll)