GetObject, fonction (Visual Basic)

Article
09/12/2008

Mise à jour : novembre 2007

Retourne une référence à un objet fourni par un composant COM.

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

Paramètres

Paramètre	Description
PathName	Facultatif. String. Chemin d'accès complet et nom du fichier contenant l'objet à récupérer. Si PathName est omis ou constitue une chaîne de longueur nulle (""), Class est obligatoire.
Class	Requis si PathName n'est pas fourni. String. Chaîne représentant la classe de l'objet. L'argument Class emploie la syntaxe et les paramètres suivants : appname.objecttype ParamètresDescription appnameRequis. String. Nom de l'application fournissant l'objet. objecttypeRequis. String. Type ou classe de l'objet à créer.

PathName

Facultatif. String. Chemin d'accès complet et nom du fichier contenant l'objet à récupérer. Si PathName est omis ou constitue une chaîne de longueur nulle (""), Class est obligatoire.

Class

Requis si PathName n'est pas fourni. String. Chaîne représentant la classe de l'objet. L'argument Class emploie la syntaxe et les paramètres suivants :

appname.objecttype

ParamètresDescription

appnameRequis. String. Nom de l'application fournissant l'objet.

objecttypeRequis. String. Type ou classe de l'objet à créer.

Exceptions

Type d'exception	Numéro de l'erreur	Condition
Exception	429	Aucun objet du type spécifié n'existe.
FileNotFoundException	432	Aucun objet avec le chemin d'accès spécifié et le nom de fichier n'existe.

Consultez la colonne « Numéro d'erreur » si vous mettez à niveau des applications Visual Basic 6.0 qui utilisent la gestion des erreurs non structurée. (Vous pouvez comparer le numéro d'erreur par rapport à Number, propriété (objet Err).) Toutefois, lorsque cela est possible, vous devez envisager de remplacer un tel contrôle d'erreur par Vue d'ensemble de la gestion structurée des exceptions pour Visual Basic.

Notes

Utilisez la fonction GetObject pour charger une instance d'un composant COM à partir d'un fichier. L'exemple suivant illustre ce comportement :

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

Lorsque ce code est exécuté, l'application associée au PathName spécifié démarre et l'objet dans le fichier spécifié est activé.

Cas par défaut

Si PathName est une chaîne de longueur nulle (""), GetObject retourne une nouvelle instance d'objet du type de classe spécifié. Si l'argument PathName est omis, GetObject retourne un objet actuellement actif du type de classe spécifié dans Class. S'il n'existe aucun objet du type spécifié, une erreur se produit.

Accès à un sous-objet

Certaines applications vous permettent d'activer un sous-objet associé à un fichier. Pour ce faire, ajoutez un point d'exclamation (!) à la fin du nom du fichier et faites suivre ce dernier d'une chaîne identifiant la partie du fichier à activer. Pour plus d'informations sur la façon de créer cette chaîne, consultez la documentation de l'application qui a créé l'objet.

Dans une application de dessin, par exemple, un fichier peut contenir un dessin constitué de plusieurs couches. Le code suivant vous permet d'activer une couche d'un dessin nommé schema.cad.

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

Spécification d'une classe

Si vous ne spécifiez pas la Class de l'objet, Automation détermine l'application à démarrer et l'objet à activer, en fonction du nom de fichier que vous fournissez. Cependant, certains fichiers peuvent prendre en charge plusieurs classes d'objets. Par exemple, un dessin peut prendre en charge trois types d'objets différents : un objet Application, un objet Drawing et un objet Toolbar, chacun faisant partie du même fichier. Pour spécifier l'objet à activer dans un fichier, utilisez l'argument Class facultatif. L'exemple suivant illustre ce comportement :

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

Dans l'exemple précédent, Figment est le nom d'une application de dessin et Drawing est un des types d'objets qu'elle prend en charge.

Utilisation de l'objet

Une fois un objet activé, vous y faites référence dans le code à l'aide de la variable objet que vous avez déclarée. Dans l'exemple précédent, vous accédez aux propriétés et aux méthodes du nouvel objet en utilisant la variable objet drawObj. L'exemple suivant illustre ce comportement :

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

Remarque :
Utilisez la fonction GetObject s'il existe une instance actuelle de l'objet, ou lorsque vous souhaitez créer l'objet avec un fichier chargé. S'il n'existe aucune instance actuelle et si vous ne souhaitez pas démarrer l'objet avec un fichier chargé, utilisez CreateObject, fonction (Visual Basic). Si un objet s'est inscrit comme objet à instance unique Active-X, une seule instance de l'objet est créée quel que soit le nombre d'appels à CreateObject. Avec un objet à instance unique, GetObject retourne toujours la même instance lorsqu'elle est appelée à l'aide de la syntaxe de chaîne de longueur nulle (""). En outre, elle produit une erreur si l'argument PathName est omis. Vous ne pouvez pas utiliser GetObject pour obtenir une référence à une classe créée à l'aide de Visual Basic.

Utilisez la fonction GetObject s'il existe une instance actuelle de l'objet, ou lorsque vous souhaitez créer l'objet avec un fichier chargé. S'il n'existe aucune instance actuelle et si vous ne souhaitez pas démarrer l'objet avec un fichier chargé, utilisez CreateObject, fonction (Visual Basic).

Si un objet s'est inscrit comme objet à instance unique Active-X, une seule instance de l'objet est créée quel que soit le nombre d'appels à CreateObject. Avec un objet à instance unique, GetObject retourne toujours la même instance lorsqu'elle est appelée à l'aide de la syntaxe de chaîne de longueur nulle (""). En outre, elle produit une erreur si l'argument PathName est omis. Vous ne pouvez pas utiliser GetObject pour obtenir une référence à une classe créée à l'aide de Visual Basic.

Note de sécurité :
La fonction GetObject nécessite une permission de code non managée, qui peut affecter son exécution dans les situations de confiance partielle. Pour plus d'informations, consultez SecurityPermission et Autorisations d'accès du code.

Lorsque vous avez fini d'utiliser l'objet, définissez toutes les références à l'objet avec la valeur Nothing. Cela permet au runtime de disposer du composant COM.

Exemple

L'exemple suivant utilise la fonction GetObject pour déterminer si Excel est en cours d'exécution.

' 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

Cet exemple utilise la fonction GetObject pour obtenir une référence à une feuille de calcul Microsoft Excel spécifique (excelObj). L'appel à GetObject retourne une référence à la feuille de calcul représentée par le fichier spécifié, test.xls. L'exemple de code rend ensuite Excel et la fenêtre contenant la feuille de calcul spécifiée visibles.

Cet exemple requiert Option Strict Off parce qu'il utilise la liaison tardive, où les objets sont assignés aux variables de type Object. Vous pouvez spécifier Option Strict On et déclarer des objets de types d'objets spécifiques si vous ajoutez une référence de projet à la bibliothèque de types Excel. À cette fin, ouvrez la boîte de dialogue Ajouter une référence à partir du menu Projet de Visual Studio et sélectionnez la bibliothèque de types Excel sur l'onglet 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