Compiling and Deploying a Server Control


For a custom control to be usable on a page, the control must be compiled into an assembly and made accessible to the ASP.NET runtime. If you are not familiar with the concept of assembly, think of it as a dynamic-link library (DLL) implemented in managed code.

In this book's sample files, we have provided batch files for building from the command line and provided a Visual Studio .NET solution file (BookCodeCS.sln for C#) for opening the project in Visual Studio .NET. We will discuss the command-line procedure in this section, and we'll show how to use a custom control in Visual Studio .NET in the section "Custom Controls in Visual Studio .NET."

The batch files in the book's sample files contain commands that will compile all the control samples in this book. If you want to get a feel for building a server control assembly, follow the instructions in the next paragraph. However, before executing the commands, copy the source files for the control samples in this chapter to a directory other than the one in which you installed the source code so that you don't overwrite the installed files.

To compile the control shown in Listing 5-1, navigate to the directory that contains the source file for SimpleControl (for example, C:\MyBookCodeCS\MyServerControls) and execute the following command:

 csc/t:library/out:MSPress.ServerControls.dll/r:System.dll /r:System.Web.dllSimpleControl.cs 

The csc command invokes the C# compiler. The /t option tells the compiler that the target assembly is a library. The /out option provides the name of the output file. The /r option provides the names of the assemblies whose metadata is referenced by the classes being compiled. At this point, we need to reference only two assemblies: System and System.Web . When you execute the compiler command, it will generate a library assembly named MSPress.ServerControls in the file MSPress.ServerControls.dll.

Each ASP.NET application has a special location from which it can access private assemblies. (We'll explain what private means shortly.) That location is the bin directory immediately under the virtual root representing an Internet Information Services (IIS) Web application. If your Web application's virtual root is named BookWeb and maps to a path such as C:\BookWebDir, the directory C:\BookWebDir\bin should hold assemblies referenced by pages in the BookWeb Web directory. Binaries that are needed by pages in subdirectories must also be placed in the bin directory directly under the virtual root. For example, the bin directory for pages in C:\BookWebDir\Chapter5 is also C:\BookWebDir\bin. If you ran the setup program included with the book's sample files, the BookWeb Web application and its bin directory are already created for you.

If you want to follow the instructions in this chapter to understand the mechanics of the process, create an IIS virtual root different from the BookWeb application that was created for you when you installed the samples. If you have not created an IIS virtual root before, see the Introduction of this book for instructions. It is important that you create a new Web application (such as MyBookWeb) so that you don't overwrite the pages and binaries that are part of the BookWeb application. You must also create a directory named bin under the virtual root.

Next copy the MSPress.ServerControls.dll file that you created earlier to the bin directory of your Web application. Here's an example:

 copyMSPress.ServerControls.dll<  pathtotherootofyourWebapplication  >\bin 

The assembly that you created and copied into the application's bin directory is known as a private assembly because only pages in your Web application can reference it. In Chapter 17, we will show you how to create an assembly that can be deployed in the global assembly cache (GAC) and thus shared by multiple applications.

Our first custom control is now ready to be used by any page in your Web application. We'll show you next how to use SimpleControl on a page.

Using a Custom Control on a Page

Using a custom control on a page is similar to using a server control that ships with the SDK, with one difference. The page developer must register a tag prefix (analogous to the asp tag prefix used for standard ASP.NET controls) for your control by using a Register directive at the top of the page, as shown in the following example:

 <%@RegisterTagPrefix="msp" Namespace="MSPress.ServerControls"  Assembly="MSPress.ServerControls" %> 

The TagPrefix attribute creates an alias that maps to a custom control's namespace and assembly. A page developer can specify any name for the tag prefix (other than asp ) as long as it does not conflict with the name of another tag prefix specified on the page. The Namespace attribute specifies the namespace in which the custom control is declared. The Assembly attribute specifies the assembly into which the control is compiled. Do not use the .dll file extension when specifying the assembly attribute because the file extension is not part of the assembly name. Listing 5-2 shows you a page that uses our first custom control.

Listing 5-2 SimpleControlTest.aspx
 <%@PageLanguage="C#"%> <%@RegisterTagPrefix="msp"NameSpace="MSPress.ServerControls" Assembly="MSPress.ServerControls"%> <html> <body> <br> Hereistheoutputfromourfirstcustomcontrol. <br> <msp:SimpleControlid="simple1"runat="server"/> <br> </body> </html> 

We mentioned earlier that you must declare your control in a namespace. You can now see why that is needed. A namespace allows a control to be used declaratively on a page because the tag prefix in the Register directive maps to the namespace in which the control is declared.

To test the page, save it with an .aspx extension, copy it to your Web application, and open it in your browser. If you ran the setup program included with the book's sample files, you will find SimpleControlTest.aspx in the Chapter5 directory of your BookWeb application. Enter the following URL in your browser's address bar:

 http://localhost/BookWeb/Chapter5/SimpleControlTest.aspx 

Figure 5-2 shows how the output should look.

Figure 5-2. SimpleControlTest.aspx page that tests SimpleControl , viewed in a browser

graphics/f05hn02.jpg



Developing Microsoft ASP. NET Server Controls and Components
Developing Microsoft ASP.NET Server Controls and Components (Pro-Developer)
ISBN: 0735615829
EAN: 2147483647
Year: 2005
Pages: 183

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net