This documentation is archived and is not being maintained.

MasterPage Class

Acts as a template and merging container for pages that are composed only of Content controls and their respective child controls.

Namespace:  System.Web.UI
Assembly:  System.Web (in System.Web.dll)

[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal)]
public class MasterPage : UserControl
<asp:MasterPage />

A master page functions as a template container and merging page for content pages in your ASP.NET Web application. Master pages provide a convenient way to share structure and content across a set of content pages. You use content placeholders to define the sections of the master page to replace with content from the content pages.

When you use a master page and its related content pages, you add the required XHTML document tags (such as html, head, and body) only to the master page and no longer create your other .aspx files (ASP.NET pages) as stand-alone Web pages. The content pages define the content to insert into the placeholders in the master page.

When an HTTP request is made for a page at run time, the master page and content pages are combined into a single class with the same name as the content pages. The resulting compiled, merged class derives from the Page class.

A master page can contain direct markup and server controls, as well as container controls. Every element that is placed in the master page outside of a ContentPlaceHolder control is rendered on all pages that result from merging the master page and content pages.

Each content page that is related to the master page must reference the master page in a MasterPageFile attribute of its @ Page directive. Content pages can contain only a @ Page directive and one or more Content controls. All of your page text, markup, and server controls must be placed within Content controls. You identify the ContentPlaceHolder control of a master page that a Content control is associated with by setting the ContentPlaceHolderID property of the Content control.

At run time, the dynamic content from each Content control in the requested page is merged with the master page in the exact location of the related ContentPlaceHolder control. Any other markup and controls in the master page are unaffected. Event handlers can be defined in both the master class and on the content page. For more information, see Events in ASP.NET Master and Content Pages.

The MasterPage class is associated with files that have a .master extension. These files are compiled at run time as MasterPage objects and are cached in server memory.

The master page is made available to the content page through the Master property of the base Page class. The Master property returns the instance of the master page; however, it is typed as the base MasterPage class. To access controls, properties, and functions of the master page, the Master property can be cast to a MasterPage object. The class name of the master page is defined using the ClassName attribute of the @ Master directive.

NoteNote:

Files with .master extensions are not served to a browser.

The directives that are valid on a master page are the same as those that are available on a UserControl object. They can include the following attributes:

  • AutoEventWireup

  • ClassName

  • CodeFile

  • CompilerMode

  • CompilerOptions

  • Debug

  • Description

  • EnableTheming

  • EnableViewState

  • Explicit

  • Inherits

  • Language

  • LinePragmas

  • MasterPageFile

  • Src

  • Strict

  • WarningLevel

Master page directives do not override the directives on individual content pages.

Master pages are most often created declaratively. If you want to create a master page programmatically, derive directly from the MasterPage class. In addition to extending the MasterPage class, you must create the .master file to visually display the user interface (UI) that is associated with the classes that you have invoked in your source file.

NoteNote:

When you create a master page by creating your own class first, you must include all namespaces that are required for the classes that are used by the page.

For more information about master pages, see ASP.NET Master Pages Overview.

This section contains four code examples:

  • The first code example demonstrates how to create a master page declaratively.

  • The second code example represents the content page that is associated with the master page that was created in the first code example.

  • The third code example demonstrates how to add a property to a master page.

  • The fourth code example demonstrates how to use a content page to access a public property on the master page.

The following example demonstrates how to create a master page declaratively and to add some content to it using a content page. The first Web page is the .master page named MasterPageSample_1.master.

<%@ Master Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>MasterPage Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <asp:contentplaceholder id="ContentPlaceHolder1" runat="server" />
    </div>
    </form>
</body>
</html>

The following example represents the content page that is associated with MasterPageSample_1.master. It contains a Content control and identifies the ContentPlaceHolder control that the content is associated with by using the ContentPlaceHolderID property.

<%@ Page Language="C#" MasterPageFile="~/MasterPageSample_1cs.master" Title="Content Page"%>

<asp:content 
    runat="server"
    contentplaceholderid="ContentPlaceHolder1" >Hello, Master Pages!</asp:content>

The following example demonstrates how to add a property to a master page. The ClassName attribute is used to name the master page.

<%@ Master Language="C#" ClassName="MasterExample" %>

<script runat="server">
        public string SiteName
        {
            get { return "My Site Name"; }
        }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>MasterPage Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <asp:contentplaceholder id="ContentPlaceHolder1" runat="server">
        </asp:contentplaceholder>
    </div>
    </form>
</body>
</html>

The following example shows how to use a content page to access the public property SiteName on the master page in the preceding code example.

<%@ Page Language="C#" MasterPageFile="~/MasterPage.master" Title="MasterPage Example" %>

<script runat="server">
  protected void Page_Load(object sender, EventArgs e)
  {
    MasterExample m = (MasterExample)Page.Master;
    mylabel.Text = m.SiteName;
  }
</script>

<asp:Content ID="Content1" ContentPlaceHolderID="ContentPlaceHolder1" runat="Server">
    Hello, Master Pages!
    <asp:Label runat="server" Text="Label" ID="mylabel"></asp:Label>
</asp:Content>

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0
Show: