References.Add, méthode

Article
08/10/2011

Ajoute une nouvelle référence au projet.

Espace de noms : VSLangProj
Assembly : VSLangProj (dans VSLangProj.dll)

Syntaxe

'Déclaration
Function Add ( _
    bstrPath As String _
) As Reference

Reference Add(
    string bstrPath
)

Reference^ Add(
    [InAttribute] String^ bstrPath
)

abstract Add : 
        bstrPath:string -> Reference

function Add(
    bstrPath : String
) : Reference

Paramètres

bstrPath
Type : System.String
Obligatoire.Chemin d'accès d'une référence COM ou .NET Framework.
Ce paramètre peut prendre trois formes :
Nom d'objet .NET Framework simple, tel que "System".
Nom de fichier .NET Framework (fichier .tlb, .dll ou .ocx).
Fichier bibliothèque COM (fichier .tlb, .dll, .ocx ou .exe).Pour les objets COM, le chemin d'accès doit être constitué d'un chemin complet et d'un nom de fichier, par exemple "D:\Application\App.dll".Consultez la section "Références COM", plus loin dans cette rubrique, pour connaître les restrictions à l'ajout de références à un fichier .exe COM.

Valeur de retour

Type : VSLangProj.Reference
Retourne un objet Reference.

Notes

Une erreur est générée si aucune bibliothèque de types ne se trouve dans le fichier indiqué par le paramètre bstrPath ou si la référence n'a pas pu être résolue (consultez la section Résolution de référence).

Cette méthode ne génère pas d'erreur s'il existe dans le projet une référence dotée des mêmes propriétés Identity, Culture, MajorVersion, MinorVersion, BuildNumber et RevisionNumber que celles de la nouvelle référence. Cette condition indiquerait que la référence désignée par le paramètre bstrPath a déjà été ajoutée au projet. Dans ce cas, le ProjectItem de la référence déjà présente dans le projet est retourné.

Si une référence dotée de la même propriété Identity mais de propriétés MajorVersion, MinorVersion, BuildNumber, RevisionNumber ou Culture différentes est trouvée dans le projet, la méthode génère une erreur.

Pour supprimer une référence, utilisez le Remove.

Références COM

Cette méthode retourne l'objet Reference de la première bibliothèque de types présente dans le fichier référencé.

Elle ajoute tous les objets trouvés dans le fichier bibliothèque de types ainsi que toutes les dépendances de ces objets. Un seul appel à cette méthode peut donc avoir pour résultat l'ajout de plusieurs références à la collection References.

Les fichiers .exe COM peuvent être ajoutés en tant que références s'ils contiennent des bibliothèques de types. Dans ce cas, les références à toutes les bibliothèques de types inscrites contenues dans le fichier .exe sont ajoutées.

Références .NET Framework

Cette méthode retourne l'objet Reference de l'assembly référencé.

Ces références n'ayant pas de fichier bibliothèque de types, aucun assembly dépendant n'est ajouté au projet en tant que référence.

Si la référence est un assembly qui contient aussi des bibliothèques de types incorporées, seule une référence à cet assembly est ajoutée.

Les références aux fichiers .exe .NET Framework sont autorisées.

Résolution de référence

Lorsque le fichier projet est enregistré, les chemins d'accès des références ne sont pas enregistrés avec le projet. Le fichier projet peut ainsi être partagé plus facilement entre plusieurs ordinateurs. Par exemple, System.dll peut être stocké dans C:\Bigfolder sur l'ordinateur A, et il peut être stocké dans D:\Smallfolder sur l'ordinateur B. Pour les références de .NET Framework, seul le nom d'assembly de référence est rendu persistant. Ainsi, pour System.dll, seul "System" est persistant.

Les compilateurs acceptent uniquement des références sous la forme d'un chemin d'accès complet, plus le nom de fichier, par exemple C:\Bigfolder\system.dll. Par conséquent, il doit y avoir une méthode cohérente pour localiser les assemblys au moment de la conception. Un assembly est résolu si son chemin d'accès complet peut être retrouvé. Le chemin d'accès résolu est le chemin d'accès complet à la référence. Pour continuer avec l'exemple System, si System.dll se trouve sous "C:\Bigfolder", son chemin d'accès, après résolution, est "C:\Bigfolder\System.dll".

Pour résoudre une référence, l'environnement de développement crée pour elle un nom dont il se sert pour la rechercher. Ce nom inclut l'extension .dll parce que le nom enregistré pour une référence peut inclure ou non cette extension. Les deux références, "ReferenceOne" et "ReferenceTwo.dll", prennent respectivement les noms "ReferenceOne.dll" et "ReferenceTwo.dll".

L'environnement de développement recherche le nom dans l'ordre suivant et s'arrête dès qu'il rencontre une correspondance :

Dans la hiérarchie du projet.
Dans le chemin de recherche des références (paramètre de niveau projet). Pour plus d'informations, consultez ReferencePath.
Dans l'ensemble de répertoires utilisé par le sélecteur de composants pour l'énumération des références. Cet ensemble de répertoires est enregistré dans le Registre durant l'installation.

Chaque référence est résolue lors du chargement d'un projet. Pour une nouvelle référence, la résolution est également effectuée lorsque le paramètre bstrPath de la méthode Add contient autre chose qu'un chemin d'accès complet.

Si une référence ne peut pas être résolue, une erreur est générée. Les références COM sont toujours résolues parce que le chemin d'accès complet est exigé par le paramètre bstrPath. Si le paramètre bstrPath est le nom .NET Framework (par exemple, "SomeObject") ou le nom de fichier .NET Framework sans chemin d'accès (par exemple, "SomeObject.dll"), il est possible que la référence ne soit pas résolue, auquel cas une erreur est générée.

Exemples

' Macro Editor
Imports VSLangProj
Sub AddExample()
   ' This example assumes that the first project in the solution is 
   ' either a Visual Basic or C# project.
   Dim aVSProject As VSProject = _
      CType(DTE.Solution.Projects.Item(1).Object, VSProject)
        
   Dim refs As References = aVSProject.References
   ' Adds a reference to a compiled .NET project.
   refs.Add("C:\path\program.dll")
   ' Adds a reference to an installed ActiveX control.
   refs.Add("C:\WINNT\system32\msmask32.ocx")
   ' Adds a reference to System.dll as an example of adding a
   ' reference using just the simple name.
   refs.Add("System")
End Sub

Sécurité .NET Framework

Confiance totale accordée à l'appelant immédiat. Ce membre ne peut pas être utilisé par du code d'un niveau de confiance partiel. Pour plus d'informations, consultez Utilisation de bibliothèques à partir de code d'un niveau de confiance partiel.

Voir aussi

Référence

References Interface

VSLangProj, espace de noms

Partager via