References.Add (Método)
Agrega una nueva referencia al proyecto.
Espacio de nombres: VSLangProj
Ensamblado: VSLangProj (en VSLangProj.dll)
Sintaxis
'Declaración
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
Parámetros
- bstrPath
Tipo: System.String
Obligatorio.Ruta de acceso de una referencia COM o .NET Framework.
Este parámetro puede tomar tres formas:
Un nombre de objeto sencillo de .NET Framework, como "System".
Un nombre de archivo de .NET Framework (archivo .tlb, .dll u .ocx).
Un archivo de biblioteca COM (archivo .tlb, .dll, .ocx o .exe).Para los objetos COM, esta ruta de acceso debe incluir la ruta y el nombre de archivo completos, como "D:\SomeApplication\SomeApp.dll".Vea las restricciones existentes en la sección "Referencias COM" más adelante, que indica cómo agregar referencias de archivo .exe de COM.
Valor devuelto
Tipo: VSLangProj.Reference
Devuelve un objeto Reference.
Comentarios
Se genera un error si no hay bibliotecas de tipos en el archivo indicado por el parámetro bstrPath o no se puede resolver la referencia (vea la sección Resolución de referencias).
Este método no genera un error si existe una referencia en el proyecto con las mismas propiedades Identity, Culture, MajorVersion, MinorVersion, BuildNumber y RevisionNumber que tendría la nueva referencia. En tal caso, ello indicaría que la referencia señalada en el parámetro bstrPath ya se había agregado al proyecto. En su lugar, se devuelve el objeto ProjectItem de la referencia coincidente que ya existe en el proyecto.
Si se encuentra en el proyecto una referencia con la misma propiedad Identity pero con distinta propiedad MajorVersion, MinorVersion, BuildNumber, RevisionNumber o Culture, el método genera un error.
Para quitar una referencia, utilice el método Remove.
Referencias COM
Este método devuelve el objeto Reference de la primera biblioteca de tipos del archivo al que se hace referencia.
Este método agrega todos los objetos hallados en el archivo de biblioteca de tipos y todas sus respectivas dependencias. Por tanto, una única llamada a este método puede hacer que se agregue más de una referencia a la colección References.
Pueden agregarse archivos .exe de COM como referencias si contienen bibliotecas de tipos. En tal caso, se agregan referencias a todas las bibliotecas de tipos registradas contenidas en el archivo .exe.
Referencias de .NET Framework
Este método devuelve el objeto Reference del ensamblado al que se hace referencia.
Estas referencias no tienen un archivo de biblioteca de tipos, por lo que no se agregan ensamblados dependientes como referencias al proyecto.
Si la referencia es un ensamblado, pero también contiene bibliotecas de tipos incrustadas, solo se agrega una referencia al mismo.
Las referencias a archivos .exe de .NET Framework están permitidas.
Resolución de referencias
Cuando se guarda el archivo de proyecto, no se guardan las rutas de acceso a las referencias como parte del proyecto. Ello permite compartir el archivo de proyecto entre varios equipos con mayor facilidad. Por ejemplo, System.dll podría almacenarse en C:\Bigfolder en el equipo A y en D:\Smallfolder en el equipo B. Para las referencias de NET Framework, solo se conserva el nombre del ensamblado de referencia. Así, para System.dll, persiste "System".
Los compiladores solo aceptan referencias con el formato de ruta de acceso completa más nombre de archivo, por ejemplo, C:\Micarpeta\system.dll. Por tanto, debe haber alguna forma coherente de localizar ensamblados en tiempo de diseño. Un ensamblado se resuelve si se encuentra la ruta de acceso completa al mismo. La ruta resuelta es la ruta de acceso completa a la referencia. Continuando con el ejemplo de System, si System.dll se encuentra en C:\Micarpeta, al resolver System.dll, su ruta resuelta será C:\Micarpeta\System.dll.
Para resolver una referencia, el entorno de desarrollo crea un nombre de búsqueda a partir de la referencia y busca la referencia. El nombre de búsqueda se crea para que incluya la extensión .dll, ya que el nombre guardado de una referencia puede o no incluir esta extensión. Las dos referencias, ReferenceOne y ReferenceTwo.dll, tendrán los nombres ReferenceOne.dll y ReferenceTwo.dll, respectivamente.
El entorno de desarrollo busca el nombre en el orden siguiente, deteniéndose en cuanto se encuentra una coincidencia:
En la jerarquía de proyectos.
En la ruta de búsqueda de referencias, que es un valor de nivel de proyecto. Para obtener más información, vea ReferencePath.
En el conjunto de directorios que utiliza el selector de componentes al enumerar las referencias. Este conjunto de directorios se almacena en el Registro durante la instalación.
Cada una de las referencias se resuelve al cargar un proyecto. La resolución también tiene lugar en una nueva referencia cuando el parámetro bstrPath del método Add no es una ruta de acceso completa.
Si no es posible resolver una referencia, se genera un error. Las referencias COM siempre se resuelven, ya que se requiere la ruta de acceso completa en el parámetro bstrPath. Si el parámetro bstrPath es el nombre de .NET Framework (por ejemplo, SomeObject) o el nombre de archivo de .NET Framework sin la ruta de acceso (por ejemplo, SomeObject.dll), es posible que no se resuelva la referencia y se genere un error.
Ejemplos
' 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
Seguridad de .NET Framework
- Plena confianza para el llamador inmediato. Un código de confianza parcial no puede utilizar este miembro. Para obtener más información, vea Utilizar bibliotecas de código que no es de plena confianza.