Building the Custom Server Control Examples

  • Article

This topic describes how to compile the custom control examples into an assembly and use the controls in ASP.NET Web pages. It also describes how you can use the App_Code folder of an ASP.NET Web site to test control code without compiling them.

Creating a Control Assembly

To create and compile the custom controls into an assembly

  1. Create a folder for the source files for custom controls and related classes.

  2. Create a text file with the appropriate language extension for each example that you want to compile.

    For example, create a file named MailLink.cs for the C# code of the MailLink control in Web Control Rendering Example.

  3. Copy and paste the source code for each example into the corresponding text file and save the file.

  4. Run the following command from the source code folder to compile the controls and related classes into an assembly.

    csc /t:library /out:Samples.AspNet.CS.Controls.dll /r:System.dll 
/r:System.Web.dll /r:System.Design.dll *.cs

    vbc /t:library /out:Samples.AspNet.VB.Controls.dll /r:System.dll 
/r:System.Web.dll /r:System.Design.dll *.vb

    The /t:library compiler option tells the compiler to create a library (rather than an executable assembly). The /out option provides a name for the assembly and the /r option lists the assemblies that are linked to your assembly.

    Note

    If you cannot execute the compiler command, you must add the .NET Framework installation path to the Windows PATH variable before running the command. In Windows, right-click My Computer, click Properties, click the Advanced tab, and then click the Environment Variables button. In the System variables list, double-click the Path variable. In the Variable value text box, add a semicolon (;) to the end of the existing values in the text box, and then type the path of your .NET Framework installation. The .NET Framework is usually installed in the Windows installation folder at \Microsoft.NET\Framework\versionNumber.

  5. Re-run the compilation command in Step 4 whenever you add new source files to the source code folder or change existing ones.

Creating an ASP.NET Web Site

To create the ASP.NET Web site

  1. Create an ASP.NET Web site using Internet Information Services (IIS) or another tool.

  2. For information about creating and configuring an IIS virtual directory, see How to: Create and Configure Virtual Directories in IIS 5.0 and 6.0.

    Note

    If you want to use IIS, install IIS before installing the .NET Framework.

  3. Create a Bin folder under the root folder of your Web site.

  4. Copy the assembly you created in the preceding procedure to the Web site's Bin folder.

    Note

    If you recompile the control assembly (the final step in the previous section) you must recopy the new assembly to the Bin folder of your Web site.

  5. Create a text file named Web.config in the root folder of your Web site, add the following XML to the Web.config file, and then save the file.

    <?xml version="1.0"?>
<configuration>
  <system.web>
    <compilation debug="true"/>
    <pages>
      <controls>
        <add tagPrefix="aspSample" 
          namespace="Samples.AspNet.CS.Controls" 
          assembly="Samples.AspNet.CS.Controls" >
        </add>
      </controls>
    </pages>
  </system.web>
</configuration>

    <?xml version="1.0"?>
<configuration>
  <system.web>
    <compilation debug="true"/>
    <pages>
      <controls>
        <add tagPrefix="aspSample" 
          namespace="Samples.AspNet.VB.Controls" 
          assembly="Samples.AspNet.VB.Controls" >
        </add>
      </controls>
    </pages>
  </system.web>
</configuration>

  6. Add a text file with an .aspx extension to the root folder of your Web site for each example that you want to test.

    For example, create a file named MailLinkTest.aspx for the test page of the MailLink control provided in Web Control Rendering Example.

  7. Copy and paste the source code for each example test page into the corresponding .aspx file and save the file.

  8. Request the .aspx pages in a Web browser.

    For example, if your Web site is named ServerControls and it includes a page named MailLinkTest.aspx, type the following URL in the address bar of your browser:

    https://localhost/ServerControls/MailLinkTest.aspx

Using the App_Code Folder for Testing Controls

You can use the dynamic compilation feature of ASP.NET 2.0 to test controls without compiling them into an assembly manually.

To put controls in the App_Code folder

  1. Create an App_Code folder under the root folder of your Web site.

  2. Copy the source files for the controls and related classes into the App_Code folder.

  3. If you previously added an assembly for the control to the Bin folder, delete it.

    Note

    You can either pre-compile a control into an assembly and place the assembly in the Bin folder or place the control's source file in the App_Code folder. If you add the control to both folders, the page parser will not be able to resolve a reference to the control in a page and will generate an error.

  4. Change the entry under the controls section in the Web.config file to the following highlighted entry, which maps the control's namespace to a tag prefix:

    <controls>
  <add tagPrefix="aspSample"     namespace="Samples.AspNet.CS.Controls">..</add>
</controls>

    <controls>
  <add tagPrefix="aspSample"     namespace="Samples.AspNet.VB.Controls">..</add>
</controls>

    For more information, see @ Register.

  5. Request the .aspx pages in a Web browser.

If you place the source files for the QuickContacts and ContactCollectionEditor classes from Web Control Collection Property Example in the App_Code folder, you must also add a reference to the System.Design assembly in the compilation section of the Web.config file. This reference requires the fully qualified assembly name of the System.Design assembly. You can get the information required for the fully qualified name by running the Global Assembly Cache Tool (Gacutil.exe) that ships with the Windows Software Development Kit (SDK), using the following syntax:

gacutil /l System.Design

Note

To run the .Global Assembly Cache Tool (Gacutil.exe) from the command line, the Windows environment PATH variable of your computer must include the path to your .NET Framework installation. In Windows, right-click My Computer, click Properties, click the Advanced tab, and then click the Environment Variables button. In the System variables list, double-click the Path variable. In the Variable value text box, add a semicolon (;) to the end of the existing values in the text box, and then type the path of your .NET Framework installation. The .NET Framework is usually installed in the Windows installation folder at \Microsoft.NET\Framework\versionNumber.

The tag you add to the compilation section of the Web.config file is similar to the highlighted section in the following example. However, you must replace the values of the Version and the PublicKeyToken attributes with the values returned by the Gacutil.exe tool.

<compilation >
  <assemblies>    <add assembly="System.Design, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" />    </assemblies>
</compilation>

Note

If you are using an integrated development environment, the designer might provide a simpler technique for adding an assembly reference to the Web.config file. For example, in Visual Studio 2005, if you right-click the Web site name in Solution Explorer and click Add Reference in the shortcut menu, you can use a dialog box that allows you to select an assembly to add. When you select the assembly, the designer automatically adds the relevant entry to the Web.config file.

See Also

Tasks

Walkthrough: Developing and Using a Custom Web Server Control

Other Resources

Developing Custom ASP.NET Server Controls