HOW TO: Share ASP.NET Pages and User Controls Between Applications by Using Visual Basic .NET

This step-by-step article describes how to share Microsoft ASP.NET pages (.aspx files) and user controls (.ascx files) between applications by using Microsoft Visual Basic .NET.

Requirements

• Microsoft Windows 2000 Professional, Microsoft Windows 2000 Server, Microsoft Windows 2000 Advanced Server, Microsoft Windows XP Professional, or Windows Server 2003
• The Microsoft .NET Framework 1.0 or the Microsoft .NET Framework 1.1
• Microsoft Internet Information Services (IIS) 5.0 or later
• Microsoft Visual Studio .NET

Develop the Sample ASP.NET Web User Control

Create one ASP.NET application that contains the shared user controls, and then create two other ASP.NET applications that incorporate the user control that are developed in the first application.

Create the ASP.NET Web Application That Contains the User Control

1. Start Visual Studio .NET.
2. On the File menu, point to New, and then click Project.
3. In the New Project dialog box, select Visual Basic Projects under Project Types, and then select Empty Web Project under Templates.
4. In the Location box, replace the WebApplication# default name with MyUserControls. If you are using the local server, you can use the server name http://localhost. The Location box appears as follows:
   http://localhost/MyUserControls

Add a New User Control

To add a new Web user control to the MyUserControls application that was created in the "Create the ASP.NET Web Application That Contains the User Control" section, follow these steps:

1. In Solution Explorer, right-click Project, point to Add, and then click Add Web User Control.... Name the control as TimeStamp.ascx, and then click Open. The user control is displayed in the editor.
2. Switch to HTML view in the editor, and then replace the automatically generated template code with the following code:

   <%@ Control Language="vb"%>
   <script runat=server>
   Private Sub Page_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
         CurrentTime.Text = System.DateTime.Now.ToLongTimeString()
   End Sub
   </script>
   
   <TABLE id="Table1" cellSpacing="1" cellPadding="1" width="200" border="1">
   	<TR>
   		<TD bgColor="gainsboro">
   			<P align="center">Current System Time</P>
   		</TD>
   	</TR>
   	<TR>
   		<TD>
   			<P align="center">
   				<asp:Label id="CurrentTime" runat="server"></asp:Label></P>
   		</TD>
   	</TR>
   </TABLE>		

   Note In the earlier code sample, the AutoEventWireup attribute is not explicitly set. If the AutoEventWireup attribute is not explicitly assigned a value, the default value is true. If you use Visual Studio .NET to develop your applications, the default template code explicitly sets the AutoEventWireup attribute value to false.
   
   Important The difference between the default value that is used by ASP.NET itself and the value that the Visual Studio .NET template code assigns to the attribute is subtle. If the AutoEventWireup attribute value is set to false, the event handlers that are declared in the .aspx page are not fired. This can be a source of confusion if you are not aware of this functionality.
3. On the File menu, click Save All.
4. On the Build menu in the Visual Studio .NET IDE, click Build Solution.

Develop the Sample Applications to Use the Control

Create the First Sample Application to Implement the User Control

1. Start Visual Studio .NET.
2. On the File menu, point to New, and then click Project.
3. In the New Project dialog box, select Visual Basic Projects under Project Types, and then select ASP.NET Web Application under Templates.
4. In the Location box, replace the WebApplication# default name with MySampleDemo1. If you use the local server, you can use the server name http://localhost. The Location box appears as follows:
   http://localhost/MySampleDemo1

Add a New Web Form

1. In Solution Explorer, right-click Project, point to Add, and then click Add Web Form.....
2. Name the Web form as MyControlTester1.aspx, and then click Open.
3. Switch to HTML view in the editor, and then add the following directive at the beginning of the page to refer the user control:

   <%@ Register TagPrefix="uc1" TagName="TimeStamp" Src="DemoControls/TimeStamp.ascx" %>

4. Add the following line of code directly after the opening <FORM> tag:

   <uc1:TimeStamp id="TimeStamp1" runat="server"></uc1:TimeStamp>						
   

5. To add a reference to MyUserControls, right-click References in Solution Explorer, and then click Add Reference....
6. Click the Projects tab, and then select the MyUserControls project from the list of available projects.
7. To add the reference, click Select, and then click OK. Alternatively, you can also select Browse, and then locate the assembly in the \bin directory for the MyUserControls application.
8. To save the Web form and the other associated project files, click Save All on the File menu.
9. On the Build menu in the Visual Studio .NET IDE, click Build Solution.

Create the Second Sample Application to Implement the User Control

1. Start Visual Studio .NET.
2. On the File menu, point to New, and then click Project.
3. In the New Project dialog box, select Visual Basic Projects under Project Types, and then select ASP.NET Web Application under Templates.
4. In the Location box, replace the WebApplication# default name with MySampleDemo2. If you are using the local server, then you can use the server name http://localhost. The Location box appears as follows:
   http://localhost/MySampleDemo2

Add a New Web Form

1. In Solution Explorer, right-click Project, point to Add, and then click Add Web Form..... Name the Web form as MyControlTester2.aspx, and then click Open.
2. Switch to HTML view in the editor, and then add the following directive at the beginning of the page to refer the user control:

   <%@	Register TagPrefix="uc1" TagName="TimeStamp" Src="DemoControls/TimeStamp.ascx"	%>

3. Add the following line of code directly after the opening <FORM> tag:

   <uc1:TimeStamp id="TimeStamp1"	runat="server"></uc1:TimeStamp>

4. To add a reference to MyUserControls, To do this, right-click References in Solution Explorer, and then click Add Reference....
5. Click the Projects tab, and then select the MyUserControls project from the list of available projects.
6. To add the reference, click Select, and then click OK. Alternatively, you can also select Browse, and then locate the assembly in the \bin directory for the MyUserControls application.
7. To save the Web Form and other associated project files, click Save All on the File menu.
8. On the Build menu in the Visual Studio .NET IDE, click Build Solution.

Configure the Virtual Directories in IIS

In the next series of steps, you create the related virtual directories in IIS to map to the physical location of the application that contains the user control. Follow these tasks for both the MySampleDemo1 and the MySampleDemo2 applications.

1. Click Start, and then click Run.
2. In the Open box, type inetmgr, and then click OK. Internet Information Services (IIS) Manager appears.
3. In Internet Information Services (IIS) Manager, expand the root Web node, and then locate the MySampleDemo1 virtual directory. Right-click the virtual directory, point to New, and then click Virtual Directory. Virtual Directory Creation Wizard is displayed.
4. Click Next.
5. To create the alias for the virtual directory, type DemoControls, and then click Next.
6. To map the virtual directory with a physical directory, click Browse, navigate to the MyUserControls folder, and then click Next. By default, the MyUserControls folder is located at DriveLetter:\Inetpub\wwwroot.
7. Click Next to accept the default settings, and then click Finish.
8. Right-click the newly created DemoControls virtual directory, and then click Properties.
9. On the Virtual Directory tab, click Remove. The text on the button control switches to "Create". The virtual directory mapping remains the same, but does not become an application.
10. Repeat steps 1-9 for the MySampleDemo2 virtual directory.

Verify That It Works

1. Open Microsoft Internet Explorer, and then go to the URL for MyControlTester1.aspx. For example, if you are developing on the local server, then the URL is as follows:
   http://localhost/MySampleDemo1/MyControlTester1.aspx
   You may see the page with the results of the user control.
2. In Internet Explorer, go to the MyControlTester2.aspx file that is associated with the second demo application. The URL will be as follows:
   http://localhost/MySampleDemo2/MyControlTester2.aspx
   You may see that the page is rendered together with the output from the user control, because of the mapping scheme that you implemented in IIS.

Troubleshoot

While this technique works well, you must be aware of the following issues before you decide to use it:

• The pages and the user controls are shared, but they are compiled separately for each application that uses them. Therefore, while you improve the maintainability of your sites, you do not affect the memory usage, even though you do not have several copies of the user controls.
• If the shared pages and the user controls use precompiled code-behind assemblies, you must copy the assemblies in the \bin directory of each application that uses them. Alternatively, you can sign the assemblies and then put them in the global assembly cache.
• Make sure that you not only use the @ Register directive in your .aspx page, but that the path is correctly added also. For example, in the sample for this article, the user control is located in a directory that is deeper than the .aspx page that is referencing it. Therefore, the SRC attribute of the @ Register directive appears as follows:

  <%@ Register TagPrefix="uc1" TagName="TimeStamp" Src="DemoControls/TimeStamp.ascx" %>

• If you plan to reference your user control in the code-behind class file of a Web form, you must add a reference to the namespace, and then manually add the data member declaration to the user control.

For additional information, click the following article numbers to view the articles in the Microsoft Knowledge Base: