Part 2 of 3: Creating shared user controls and master pages with sub-projects
This is the Part 2 of a 3 part series on using sub-projects with the Web Application Projects add-in for Visual Studio 2005.
Part 1 of the series can be found here.
I apologize to folks for the delay in getting this second post out, we’ve been super busy the past few weeks. This post covers two concepts when using sub-projects with the Web Application Projects add-in:
- Creating a shared master page in the root project and using it in sub-projects
- Creating a shared user control in the root project and using it sub-projects
- Visual Studio 2005 with Web Application Projects add-in installed
- This article assumes the user has already done the steps described in the Part 1 of this series which sets up a root project and sub-project in Visual Studio 2005. NOTE: It is very important to have done these prerequisite steps as the examples below will not work otherwise.
Creating a shared master page and using it in sub-projects
In this example, i’ll show how to setup a master page in the root project and then use that master page in sub-projects in the same solution.
1) The first step is to create a master page in the root project. To do this right-click on the root project’s node in solution explorere and select Add New Item. In the dialog select the Master Page item and provide a name for it (e.g. – RootProject.master).
2) Once the master page is created in the root project, edit it Design view and add some default content as shown below.
3) Now that we have a master page created in the root project, we need to create a content page in the sub-project which will use the master page from the root project. To do this right-click on the sub-project’s node in solution explorere and select Add New Item. In the dialog select the Web Form item and provide a name for it (e.g. – ContentPage.aspx).
4) The next step is to convert the web form created in the sub-project to a content page. To do this first remove all the content from the Web Form so it only has the Page directive line left as shown below.
5) Next add in a MasterPageFile attribute and one or more asp.net content control to use the master page from the root project as shown in the diagram below. In the MasterPageFile attribute, refer to the master page in the root project using a relative path from the current document. Add as many content controls as “contentplaceholder” areas in the master page that you would like to override.
Note: Visual Studio 2005 will indicate an error on the MasterPageFile and ContentPlaceHolderID attributes. Both of these are known bugs in Visual Studio and can be ignored as they really aren’t errors when the page is run.
6) If one switches to Design view on the content page in the sub-project, you will notice that only the content from the content page renders and the master page itself does not render. This also is a known limitation of Visual Studio 2005. Although the master page portion of the content is not shown in Design view when using a master page from a root project, the content page can still be fully edited like any other page, so this limitation should not be too impactful to most users.
7) To test that the master page is actually working with the content page, right click on the content page in the sub-project. and select View in Browser. This will launch the web broswer and show the content page merged with the master page from the root project.
Creating a shared user control and using it in in sub-projects
The previous section described how to create a shared master page in the root project and then how to use that master page with content pages in sub-projects. This section describes how to use the similar technique but to create a shared user control in the root project which can be used on pages in sub-projects.
1) The first step is to create the shared user control in the root project. To do this right-click on the root project’s node in solution explorere and select Add New Item. In the dialog select the Web User Control item and provide a name for it (e.g. – RootUserControl.ascx).
2) Once the user control is created in the root project, edit it Design view and add some default content as shown below.
3) Now that the shared user control is created in the root project, the next step is to use it within a page inside of a sub-project. When using a user control from another project, Visual Studio 2005 does not provide drag/drop support (i.e. – you can’t drag the ASCX file to the design surface), so one must manually type in a Register directive and add an instance of the user control. To do this, modify a page in the sub-project (default.aspx in this case), as shown in the diagram below. For the Src attribte of the Register directive use a relative path to refer to the shared user control in the root project.
Note: you may see several compile errors in the task list at this step. Those can be ignored for now as the next step addresses them.
4) To use the shared user control in the sub-project, one additional step is requried. The sub-project will need a project reference to the root project. To do this right-click on the sub-project’s node in solution explorer and select Add Reference. In the Add Refernece dialog go to the Projects tab and select the root project to reference (MyLargeWeb in this example).
5) As long as the output folder of the sub-project is set to the target the \bin of the root project, then just adding a project reference to the root project should be enough and this step can be skipped. However if the output directory of the sub-project project is set anywhere else, then one should bring up the sub-project’s references list and modify the reference to the root project in the property grid and set its Copy Local property to False as shown below.
7) After the reference to the root project has been added, switching to Design view for pages in sub-projects should render controls from the root project. Selecting a page in a sub-project that uses a user control from the root project and running it should work fine in the web browser also.
Note: you will still continue to get markup validation errors against some of the attributes on pages opened for editing which are using shared user controls from the root project. Similar to the master pages scenario in the last section, those validation errors are bugs in Visual Studio 2005 and since these are not compile errors they can be ignored.
Additional Note: there is a known intermittment bug when using the Web Application Projects add-in where switching a page to Design view may cause the IDE to hang. The bug is very intermittment and may or may not occur when doing a sub-project scenario with Web Application Projects. The product team has identified a fix for this issue and it will be fixed in the next servicing release of Visual Studio 2005. If you do happen to encounter this issue, and are blocked by it, please contact me via this blog or directly at omark-at-microsoft-dot-com and we will make a hotfix available to you.
As is described in this post, creating and using shared master pages and user controls is fairly straightforward when using the Web Application Projects add-in. There are a few extra steps one needs to take but other than that the pattern is fairly similar to how master pages and user controls are used within a single project.
Looking forward to hearing your feedback again on this topic, and I will try to get Part 3 of the series done in shorter time than it took for this one ;-).