Referencing an Assembly from Global Assembly Cache

To use an assembly, add a reference to it, as described in Adding and Removing References. Next, use the Imports statement to choose the namespace of the items to be use, as described in References and the Imports Statement Once an assembly is referenced and imported, all the accessible classes, properties, methods, and other members of its namespaces are available to the application as if their code were part of your source file. A single assembly can contain multiple namespaces, and each namespace can contain a different grouping of items, including other namespaces.

Adding and Removing References

In order to use a component in the application, first add a reference to it. Visual Studio .NET provides three options on the Add Reference dialog box:

• .NET - Lists all .NET Framework components available for referencing.
• COM - Lists all COM components available for referencing.
• Projects - Lists all reusable components created in local projects.

Web references can also be added in the Add Web Reference dialog box.

Note Avoid adding file references to outputs of another project in the same solution, because doing so may cause compilation errors. Instead, use the Projects tab of the Add References dialog box to create project-to-project references. This makes team development easier, by allowing for better management of the class libraries you create in your projects.

To add a reference

• In Solution Explorer, expand the project node to which a reference is to be added.
• Right-click the References node for the project and select Add Reference from the shortcut menu.
• To add a reference to a component or components, do the following:
• In the Add Reference dialog box, select the tab indicating the type of component to be referenced.
• In the top pane, select the component to be referenced, and then click the Select button.

Tip If the component you are looking for is not in the list, you may locate it using the Browse button.

The component referenced appears in the SelectedComponents pane of the dialog box.

• Repeat Step b for each additional component added.
• Click OK when references are all added.

Selected references will appear under the References node of the project.

To remove a reference

• In Solution Explorer, right-click the reference in the References node, and select Remove from the shortcut menu.
• By default, the Add References dialog box only lists assemblies that are in the Public Assemblies folder (Program Files\Microsoft Visual Studio .NET\Common7\IDE\Public Assemblies) or in the Global Assembly cache. You can add your own assemblies to the list by adding a registry key to specify their location.

To add assemblies to the Add References dialog box

• In Windows, click the Start button, click Run, then type regedit, to open the Registry Editor.
• Select the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\7.0\AssemblyFolders
• On the Edit menu, point to New, then, click Key.
• Enter a name for the key (for example, MyAssemblies).
• Select the (Default) value for the key that you just added.
• On the Edit menu, choose Modify.
• In the Edit String dialog box, select the Value data field and enter the full path to the folder where your assemblies are located.

Note Only the specified folder will be searched each time the Add References dialog box is opened; subfolders will not be searched. Separate keys must be added for each subdirectory to be searched.

External objects can be made available to the project by choosing the Add Reference command from the Project menu. References in Visual Basic .NET can point to assemblies, which are like type libraries but contain more information. Assemblies include one or more namespaces. When a reference is added to an assembly, an Imports statement can also be added to a module that controls the visibility of that assembly's namespaces within the module. The Imports statement provides a scoping context that lets only the portion of the namespace necessary to be used to supply a unique reference.

The Imports statement has the following syntax

Imports [| aliasname =] Namespace

Aliasname refers to a short name you can use within code to refer to an imported namespace. Namespace is a namespace available through either a project reference, through a definition within the project, or through a previous Imports statement.

A module may contain any number of Imports statements. They must appear after any Option statements, if present, but before any other code.

Note Do not confuse project references with the Imports statement or the Declare statement. Project references make external objects, such as objects in assemblies, available to Visual Basic .NET projects. The Imports statement is used to simplify access to project references, but does not provide access to these objects. The Declare statement is used to declare a reference to an external procedure in a dynamic-link library (DLL).

How the Runtime Locates Assemblies

To successfully deploy the .NET Framework application, the developer must understand how the common language runtime locates and binds to the assemblies that make up the application. By default, the runtime attempts to bind with the exact version of an assembly that the application was built with. This default behavior can be overridden by configuration file settings.

The common language runtime performs a number of steps when attempting to locate an assembly and resolve an assembly reference. Each step is explained in the following sections. The term probing is often used when describing how the runtime locates assemblies; it refers to the set of heuristics used to locate the assembly based on its name and culture.

Note Binding information can be viewed in the log file using the Assembly Binding Log Viewer (Fuslogvw.exe), which is included in the .NET Framework SDK.

Initiating the Bind

The process of locating and binding to an assembly begins when the runtime attempts to resolve a reference to another assembly. This reference can be either static or dynamic. The compiler records static references in the assembly manifest's metadata at build time. Dynamic references are constructed on the fly as a result of calling various methods, such as System.Reflection.Assembly.Load. The preferred way to reference an assembly is to use a full reference, including the assembly name, version, culture, and public key token (if one exists). The runtime uses this information to locate the assembly. The runtime uses the same resolution process regardless of whether the reference is for a static or dynamic assembly.

Dynamic reference can reference an assembly by providing the calling method with only partial information about the assembly, such as specifying only the assembly name. In this case, only the application directory is searched for the assembly, and no other checking occurs. A partial reference using any of the various methods for loading assemblies such as System.Reflection.Assembly.Load or AppDomain.Load can be made. If the global assembly cache and the application directory is to be checked for a referenced assembly, you can specify a partial reference using the System.Reflection.Assembly.LoadWithPartialName method. Finally, a dynamic reference can be made using a method such as System.Reflection.Assembly.Load and provide only partial information. This can then be used to qualify the reference using the element in the application configuration file. This element allows the developer to provide the full reference information (name, version, culture and, if applicable, the public key token) in your application configuration file instead of in your code. This technique can be used if a reference is to be fully qualified to an assembly outside the application directory, or if an assembly is to be referenced in the global assembly cache with the convenience of specifying the full reference in the configuration file instead of in the code.

Note: This type of partial reference should not be used with assemblies that are shared among several applications. Because configuration settings are applied per application and not per assembly, a shared assembly using this type of partial reference would require each application using the shared assembly to have the qualifying information in its configuration file.

The runtime uses the following steps to resolve an assembly reference:

1. Determines the correct assembly version by examining applicable configuration files, including the application configuration file, publisher policy file, and machine configuration file. If the configuration file is located on a remote machine, the runtime must locate and download the application configuration file first.

2. Checks whether the assembly name has been bound to before and, if that is so, it uses the previously loaded assembly.

3. Checks the global assembly cache If the assembly is found there, the runtime uses this assembly.

4. Probes for the assembly using the following steps:

• If configuration and publisher policy do not affect the original reference and if the bind request was created using the Assembly.LoadFrom method, the runtime checks for location hints.
• If a codebase is found in the configuration files, the runtime checks only this location. If this probe fails, the runtime determines that the binding request failed and no other probing occurs.
• Probes for the assembly using the heuristics described in the probing section If the assembly is not found after probing, the runtime requests the Windows Installer to provide the assembly. This acts as an install-on-demand feature.

Note There is no version checking for assemblies without strong names, nor does the runtime check in the global assembly cache for assemblies without strong names.