Referencing Assemblies

Each project contains a References folder for identifying the physical assemblies that code in that project can use. The reason that library assemblies must be referenced is that the project that needs the reference must know where to find the referenced assembly. When the project is compiled, all references to other assemblies are stored in the compiled assembly's metadata. This all relates back to the self-describing behavior of assemblies discussed in Chapter 1. For security, type safety, and versioning, an assembly must know which assemblies it references.

This reference is not the same as the using declaration at the top of a code file. The using declaration tells the code that it can reference types in an assembly in an unqualified manner. Without the using statement, each reference to a type must be fully qualified, which means that it must be used with the entire namespace name and type name. For example, System.Console.WriteLine("Welcome!") is fully qualified, but if a using System declaration is at the top of the file, the statement would only need to be written as Console.WriteLine("Welcome!"), without the namespace portion. For a using statement to be correct, the assembly containing the code with the using statement must have a reference to the assembly that holds the type referenced by the using statement.

There was an explanation in Chapter 3 in the section titled "Encapsulation" of how to add a reference to a project. The situation was that there was a main executable program (refer to Listing 3.8) that needed to use functionality in a library (refer to Listing 3.9). The scenario is the same for connecting all references to projects within the same project group.

Many times, assemblies that a project needs to reference are third-party components or parts of the .NET Framework Base Class Library (BCL). For BCL libraries, select Add Reference from the context menu of the project the reference will be added to. The Add Reference dialog opens initially with the .NET Assemblies tab selected, as shown in Figure 5.10. Because of the volume of assemblies to load in the list, this dialog may take a couple of seconds to initialize. The documentation for a given type will identify its containing assembly, which must be added to the reference folder to use that type.

Figure 5.10. The Add Reference dialog.

For third-party components, click the Browse button and find the assemblies in the file system to add to the list.

Normally, an assembly reference will list a typical .NET assembly. However, referencing a COM object with an embedded COM Type Library will automatically generate a .NET proxy that can be used to communicate with that COM object. If you select the COM Imports tab of the Add Reference dialog, you can select any of the COM objects and a proxy will be generated for using that COM object. Refer to the documentation for using individual COM objects.

HANDLING OPTIONAL PARAMETERS WITH COM INTEROP CALLS

Although communicating with COM objects is beyond the scope of this book, here's one tip that will save you time. Often the documentation for a COM object has examples in Visual Basic (VBA or VB6.0), and method calls have optional parameters. In C#, you can't ignore optional parameters, but must replace those parameters with System.Reflection.Missing.Value. The .NET Framework SDK, included with C#Builder, contains sample applications that show how to write programs that use COM Interop.

A helpful tool is the class browser for references. Just double-click on any assembly in the References list and a class browser will display in the work area. This is a quick way to see the contents of assemblies you are referencing.