Part 2 of 3: Creating shared user controls and master pages with sub-projects

Part 2 of 3: Creating shared user controls and master pages with sub-projects

Rate This
  • Comments 42

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

Prerequisite

  • 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.

Summary

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 ;-).

-- Omar

Leave a Comment
  • Please add 7 and 7 and type the answer here:
  • Post
  • I've used these tricks already. And on my MasterPageFile, I use "~/Masterpage.master".
  • One scenario that many large development teams often ask me about is whether it is possible to split
  • Great walkthrough! I can recommend using subprojects if you have large web projects and epically if you have a mix of ASP and ASP.NET. We've been using this approach since we switched from WSP to WAP this spring.
  • Omar Khan, GPM for the VS 2005 web tools has posted a lengthy example of how to create a partitioned...
  • 在ASP.Net开发中,我们通常需要将一个大的Web项目拆分成几个小的Web项目,这样做的优点是:使项目更加清晰明了,开发人员相互不受影响;其次,增强了项目的伸缩性,我们可以根据需求部署不同版本的子项...
  • Thanks Omar,

    We've also been having similar approach to build "white-label" website clones where-by root replicates similar functionality to multiple websites with varying look-and-feel.

    My question is, with your approach, how can we 'best' make use of inherent App_Themes' folders in child website?

    Thanks
    -- Sharad
  • Hi I followed the instructions and everything worked fine but not the user controls.

    WebApplication 2 is the root and WebApplication 1 is the sub project.

    here is my code
    <%@ Page MasterPageFile="~/Site1.Master" Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" Inherits="WebApplication1._Default" %>
    <%@ Register Src="~/WebUserControl1.ascx" TagName="WebUserControl1"  TagPrefix="url"%>
    <asp:Content runat="server" ContentPlaceHolderID="ContentPlaceHolder1">
       hi
       <ucl:WebUserControl1 ID="WebUserControl11" runat="server" />
    </asp:Content>

    I added the reference, but it still can't be rendered
  • Probably this is the same problem/question like Sharad's.

    But here i go:
    Is there any way to "split" not only the Projects into Master and Sub but also the Themes. What I think of is using something like partial themes for each subproject.
    Any suggestions or ideas are very welcome.

    Thanks in advance!
  • Would it be safe to say that, using this same technique, it would be possible to have the root project use content from the sub-project?

    I ask this because I would like to make a sub-project that is used as a sub-project in multiple root projects, and use user controls created in the sub-project in all of the root projects.

    Thanks, and WAPs are great!
  • I implemented the sub-projects principle in my solution and every works really fine. I also added resources files and a theme folder to my root project en these could also be used in the sub-projects. Great!!

    Now I have only a problem publishing the website. The problem is that the App_GlobalResources directory isn't published. So all my references to my resources result in error messages. Did somebody also had this problem and found a solution for this. And are there perhaps more disadvantages that have to be taken care of? I hope not, because I really like this solution!!!!
  • Hello Omar,
    Great article! Keep up this good work. I have two questions:

    1. Overall it seems the whole scenario of subprojects was not considered by the Visual Studio development team?
    2. Relates to question 1. When you say errors in Visual Studio, does that mean it will be fixed in SP1? Because I think that would imply that VS would get 'real' support for subprojects, so it would actually 'know' or 'understand' the fact that the developer wants to use resources (ALL resources including themes, css, images etc) from parent- and/or childprojects. That would mean that Visual Studio would have to be aware of these parent- and childrelations.

    In conclusion, I would REALLY appreciate if development would go the way of full support for parent- and/or childprojects, because that would make life easier for everyone who is developing projects in a 'module-based' way.

    Thanks!!
  • Hello Sharad,

    You can use App_Themes folder in the root project, and refer to the theme in a sub-project.  However like master pages they will not get applied in design view, and will only work in the browser.

    -Omar
  • Hello James,

    In your code i noticed the tag-prefix is "url", whereas in your code it is "ucl".  These two need to be the same for the control to get loaded.

    Hope that helps.

    Omar
  • Alan,

    Yes the technique you describe would work.  However instead of a sub-project, I would make the shared control project a seperate peer web-app.  You can then reference the DLL produced by that app using a project reference.  But you will also need to add a post-build step to copy the ASCX files to the projects where you want to use the shared controls.
  • More goodness, looking forward to the Part 3

    Cheers,
    Steve C.
Page 1 of 3 (42 items) 123