Building Component Libraries

One of the advertised benefits of using components is code reuse. You write a method once, and then you never need to write the same method ever again.

One problem with the components that have been created to this point is that they have all been application specific. In other words, you cannot reuse the components across multiple websites without copying all the source code from one App_Code folder to another.

If you want to share components among multiple websites, then you can no longer take advantage of dynamic compilation. To share components, you need to compile the components explicitly in a separate assembly.

Compiling Component Libraries

You can use a number of methods to compile a set of components into an assembly:

• Use the command-line compiler

• Use Visual Basic Express

• Use Visual Studio .NET 2005

These options are explored in turn.

Using the Visual Basic .NET Command-Line Compiler

You can use the Visual Basic command-line compiler to compile a source code file, or set of source code files, into an assembly. The Visual Basic command-line compiler is located at the following path:

C:\WINDOWS\Microsoft.NET\Framework\[version]\vbc.exe 

Note

If you have installed the .NET Framework 2.0 SDK, then you can open the SDK Command Prompt from the Microsoft .NET Framework SDK v2.0 program group. When the command prompt opens, the path to the Visual Basic .NET compiler is added to the environment automatically.

You can use the vbc.exe tool to compile any Visual Basic source file like this:

vbc /t:library SomeFile.vb 

The /t (target) option causes the compiler to create a component library and not a Console or Windows application. When you execute this command, a new file named SomeFile.dll is created, which is the compiled assembly.

As an alternative to compiling a single file, you can compile all the source code files in a folder (and every subfolder) like this:

vbc /t:library /recurse:*.vb /out:MyLibrary.dll 

The /recurse option causes the compiler to compile the contents of all the subfolders. The /out option provides a name for the resulting assembly.

You need to know about two other compiler options:

• /imports Enables you to provide a comma-delimited list of namespaces to import.

• /reference Enables you to provide a comma-delimited list of assemblies to reference.

When the source code files are compiled dynamically in the App_Code folder, several imports and references are used by default. For example, the System.Collections, System.Web, and System.Web.UI.WebControls namespaces are imported automatically. When compiling from the command line, you need to either add Imports statements to your source code files or list these namespaces, using the /imports compiler option.

Furthermore, several assembly references are added automatically during dynamic compilation, including System.Web.dll and System.Data.dll. When compiling from the command line, you need to add these references explicitly if you are using a class from one of these assemblies.

Note

You can determine the assembly and namespace associated with any class in the .NET Framework by looking up the main entry for the class in the .NET Framework SDK Documentation.

Visual Web Developer Tip

You can add the vbc command-line compiler as an external tool to Visual Web Developer. That way, you can simply select a menu option to compile the contents of the App_Code folder automatically into an assembly. To add a new external tool, select the menu option Tools, External Tools (see Figure 14.7).

Figure 14.7. Adding the Visual Basic Compiler to External Tools.

Using Visual Basic .NET Express

You can download a trial edition of Visual Basic .NET Express from the MSDN website (http://msdn.microsoft.com). Visual Basic .NET Express enables you to build Windows applications, Console applications, and class libraries.

To create a class library that you can use with an ASP.NET application, you create a Class Library project in Visual Basic .NET Express (see Figure 14.8). When you build the project, a new assembly is created.

Figure 14.8. Creating a Class Library in Visual Basic .NET Express.

If you need to use ASP.NET classes in your class library, such as the HttpContext class, then you need to add a reference to the System.Web.dll assembly to your Class Library project. Select the menu option Project, Add Reference and add the System.Web.dll from beneath the .NET tab (see Figure 14.9).

Figure 14.9. Adding a reference to System.Web.dll.

Note

If you are a C# developer, then you can download Visual C# Express from the MSDN Website (http://msdn.microsoft.com).

Using Visual Studio .NET 2005

The easiest way to create a class library that you can share among multiple ASP.NET applications is to use Visual Studio .NET 2005 instead of Visual Web Developer. Visual Studio .NET 2005 was designed to enable you to easily build enterprise applications. Building class libraries is one of the features you get in Visual Studio .NET 2005 that you don't get in Visual Web Developer Express.

Visual Studio .NET 2005 enables you to add multiple projects to a single solution. For example, you can add both an ASP.NET project and a Class Library project to the same solution. When you update the Class Library project, the ASP.NET project is updated automatically (see Figure 14.10).

Figure 14.10. A solution that contains multiple projects.

Adding a Reference to a Class Library

Now that you understand how you can create a class library in a separate assembly, you need to know how you can use this class library in another project. In other words, how do you use the components contained in an assembly within an ASP.NET page?

There are two ways to make an assembly available to an ASP.NET application. You can add the assembly to the application's /Bin folder or you can add the assembly to the Global Assembly Cache.

Adding an Assembly to the Bin Folder

In general, the best way to use an assembly in an ASP.NET application is to add the assembly to the application's root Bin folder. There is nothing magical about this folder. The ASP.NET Framework automatically checks this folder for any assemblies. If the folder contains an assembly, the assembly is referenced automatically by the ASP.NET application when it is compiled dynamically.

If you are using Visual Web Developer, then you can select the menu option Website, Add Reference to add a new assembly to your application's Bin folder (see Figure 14.11). Alternatively, you can simply copy an assembly into this folder. (If the folder doesn't exist, just create it.)

Figure 14.11. Adding an assembly reference with Visual Web Developer.

When you add an assembly to an ASP.NET application's Bin folder, the assembly is scoped to the application. This means that you can add different versions of the same assembly to different applications without worrying about any conflicts.

Furthermore, if you add an assembly to the Bin folder, then you can take advantage of XCopy deployment. In other words, if you need to move your website to a new server, then you can simply copy all the files in your website from one server to another. As long as you copy your Bin folder, the assembly is available at the new location.

Adding an Assembly to the Global Assembly Cache

All the assemblies that make up the .NET Framework class library are contained in the Global Assembly Cache. For example, the Random class is located in the System.dll assembly, and the System.dll assembly is contained in the Global Assembly Cache. Any assembly located in the Global Assembly Cache can be referenced by any application running on a server.

The Global Assembly Cache's physical location is at the following path:

C:\WINDOWS\assembly 

Before you can add an assembly to the Global Assembly Cache, you must add a strong name to the assembly. A strong name is similar to a GUID. You use a strong name to provide your assembly with a universally unique identifier.

Note

Technically, a strong name consists of the name, version number, and culture of the assembly. The strong name also includes the public key from a public/private key pair. Finally, the strong name includes a hash of the assembly's contents so that you know whether the assembly has been modified.

You can generate a strong name by using the sn.exe command-line tool like this:

sn.exe -k KeyPair.snk 

Executing this command creates a new file named KeyPair.snk, which includes a new random public/private key pair.

Warning

Protect your key file. You should not reveal the private key to anyone.

You can compile an assembly that includes a strong name by executing the Visual Basic .NET command-line compiler like this:

vbc /t:library /keyfile:KeyPair.snk /recurse:*.vb /out:MyLibrary.dll 

The resulting assembly is strongly named with the public key from the KeyPair.snk file. The /keyfile option associates the key file with the assembly. In this case, the name of the resulting assembly is MyLibrary.dll.

An alternative method of associating a strong name with an assembly is to use the <Assembly: AssemblyKeyFile> attribute. You can add this attribute to any of the source files that get compiled into the assembly. For example, you can drop the file in Listing 14.23 into the folder that you are compiling and it associates the public key from the KeyPair.snk file with the compiled assembly.

Listing 14.23. AssemblyInfo.vb

Imports System.Reflection <Assembly: AssemblyKeyFile("KeyPair.snk")> <Assembly: AssemblyVersion("0.0.0.0")>

The file in Listing 14.23 actually includes two attributes. The first attribute associates the KeyPair.snk public key with the assembly. The second attribute associates a version number with the assembly. The version number consists of four sets of numbers: the major version, minor version, build number, and the revision number.

After you add the file in Listing 14.23 to a folder that contains the source code for your components, use the following command to compile the folder:

vbc /t:library /recurse:*.vb /out:MyLibrary.dll 

After you associate a strong name with an assembly, you can use the GacUtil.exe command-line tool to add the assembly to the Global Assembly Cache. Executing the following statement from a command prompt adds the MyLibrary.dll assembly to the Global Assembly Cache:

GacUtil.exe /i MyLibrary.dll 

You can verify that the MyLibrary.dll assembly has been added successfully to the Global Assembly Cache by opening your Global Assembly Cache folder located at the following path:

C:\WINDOWS\assembly 

You should see the MyLibrary.dll assembly listed in the Assembly Name column (see Figure 14.12). Note the Version and the PublicKeyToken columns. You need to know the values of these columns to use the assembly in an application.

Figure 14.12. Viewing the Global Assembly Cache.

After you install an assembly in the Global Assembly Cache, you can use the assembly in your ASP.NET Pages and App_Code components by adding a reference to the assembly in your web configuration file. The web configuration file in Listing 14.24 adds the MyLibrary.dll assembly to your application.

Listing 14.24. Web.Config

<?xml version="1.0"?> <configuration>   <system.web>     <compilation>       <assemblies>         <add assembly="MyLibrary,Version=0.0.0.0,Culture=neutral,           PublicKeyToken=250c66fc9dd31989"/>       </assemblies>     </compilation>   </system.web> </configuration>

The web configuration file in Listing 14.24 adds the MyLibrary assembly. Notice that you must supply the Version, Culture, and PublicKeyToken associated with the assembly. You need to substitute the correct values for these properties in Listing 14.24 before you use the file with an assembly that you have compiled. (Remember that you can get these values by opening the c:\WINDOWS\assembly folder.)

Note

When using Visual Basic Express or Visual Studio .NET 2005, you can create a strong name automatically and associate the strong name with an assembly. Right-click the name of your project in the Solution Explorer window and select Properties. Next, select the tab labeled Signing.

In general, you should avoid adding your assemblies to the Global Assembly Cache because using the Global Assembly Cache defeats XCopy deployment. Using the Global Assembly Cache makes it more difficult to back up an application. It also makes it more difficult to move an application from one server to another.