References.Add(String) Method

Definition

Namespace:

VSLangProj

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

Adds a new reference to the project.

public:
 VSLangProj::Reference ^ Add(System::String ^ bstrPath);

public:
 VSLangProj::Reference ^ Add(Platform::String ^ bstrPath);

VSLangProj::Reference Add(std::wstring const & bstrPath);

[System.Runtime.InteropServices.DispId(6)]
public VSLangProj.Reference Add (string bstrPath);

[<System.Runtime.InteropServices.DispId(6)>]
abstract member Add : string -> VSLangProj.Reference

Public Function Add (bstrPath As String) As Reference

Parameters

bstrPath

String

Required. The path of a COM or .NET Framework reference. This parameter may take three forms:A simple .NET Framework object name, such as "System". A .NET Framework file name (.tlb, .dll, or .ocx file).A COM library file (.tlb, .dll, .ocx, or .exe file). For COM objects, the path needs to include a full path and file name, such as, "D:\SomeApplication\SomeApp.dll". See restrictions in the "COM References" section below on adding COM .exe file references.

Returns

Reference

Returns a Reference object.

Attributes

DispIdAttribute

Examples

' 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  

Remarks

An error is generated if there are no type libraries in the file indicated by the bstrPath parameter, or the reference cannot be resolved (see Reference Resolution section).

This method does not generate an error if a reference exists in the project with the same Identity, Culture, MajorVersion, MinorVersion, BuildNumber, and RevisionNumber as the new reference. That condition would indicate that the reference indicated by the bstrPath parameter has already been added to the project. Instead, the ProjectItem for the matching reference already in the project is returned.

If a reference with the same Identity but differing MajorVersion, MinorVersion, BuildNumber, RevisionNumber, or Culture is found in the project, the method generates an error.

To remove a reference, use the Remove.

COM References

This method returns the Reference object for the first type library in the file being referenced.

This method adds all objects found in the type library file and any dependencies of those objects. Therefore, a single call to this method may result in more than one reference being added to the References collection.

COM .exe files may be added as references, if they contain type libraries. In such a case, references to all registered type libraries contained in the .exe file are added.

.NET Framework References

This method returns the Reference object for the assembly being reference.

These references do not have a type library file, so no dependent assemblies are added as references to the project.

If the reference is an assembly that also has embedded type libraries, only a reference to the assembly is added.

References to .NET Framework .exe files are allowed.

Reference Resolution

When the project file is saved, the paths for references are not saved as part of the project. This allows the project file to be shared between computers more easily. For example, System.dll might be stored in C:\Bigfolder on computer A, and it might be stored in D:\Smallfolder on computer B. For .NET Framework references, only the reference assembly name is persisted. So, for System.dll, "System" is persisted.

Compilers only accept references in the form of full path plus file name, for example, C:\Bigfolder\system.dll. So, there must be some consistent way of locating assemblies at design-time. An assembly is resolved if the full path to the assembly can be located. The resolved path is the full path to the reference. Continuing with the System example, if System.dll is found in C:\Bigfolder, then when System.dll is resolved, its resolved path is C:\Bigfolder\System.dll.

To resolve a reference, the development environment creates a search name from the reference and searches for the reference. The search name is created so that it includes the .dll extension, since the saved name for a reference may or may not include the .dll extension. The two references, ReferenceOne and ReferenceTwo.dll, will have the names, ReferenceOne.dll and ReferenceTwo.dll, respectively.

The development environment searches for the name in the following order, stopping as soon as a match is found:

1. In the project hierarchy.

2. In the references search path, which is a project-level setting. For more information, see ReferencePath.

3. In the set of directories the component picker uses when enumerating references. This set of directories is stored in the registry during installation.

Each reference is resolved when a project is loaded. Resolution also occurs on a new reference when the bstrPath parameter to the Add method is something other than a full path.

If a reference cannot be resolved, an error is generated. COM references will always be resolved, because the full path name is required in the bstrPath parameter. If the bstrPath parameter is the .NET Framework name (for example, SomeObject) or the .NET Framework file name without path (for example, SomeObject.dll), then it is possible that the reference may not be resolved, and an error is generated.