ASP.NET master pages

ASP.NET master pages enable you to create a consistent layout for the pages in your application. A single master page defines the look and feel and standard behavior that you want for all of the pages (or a group of pages) in your application. You can then create individual content pages that contain the content you want to display. When users request the content pages, they merge with the master page to produce output that combines the layout of the master page with the content from the content page.

Both master pages and Dynamic Web Templates allow you to create a consistent layout that can easily be updated in all the pages in your site. If you are working with ASP.NET files, use master pages to define a consistent look with shared content across pages. If you are working with HTML files, use Dynamic Web Templates.

Master Pages

Dynamic Web Templates

Use with .aspx files

Use with .htm or .html files

Master content and page content are merged on the server when the page is requested

Template content exists in all pages based on the template and must be updated in all pages whenever the template is updated

Individual page content must be between <asp:contentplaceholder> and </asp:contentplaceholder> tags

Individual page content must be between <!-- #BeginEditable --> and <! #EndEditable --> tags

Master pages provide functionality that was traditionally created by copying existing code, text, and control elements repeatedly; using framesets; using include files for common elements; using ASP.NET user controls; and so on. Advantages of master pages include the following:

  • They allow you to centralize the common functionality of your pages so that you can make updates in just one place.

  • They make it easy to create one set of controls and code and apply the results to a set of pages. For example, you can use controls on the master page to create a menu that applies to all pages.

  • They give you fine-grained control over the layout of the final page by allowing you to control how the placeholder controls are rendered.

  • They provide an object model that allows you to customize the master page from individual content pages.

Master pages actually consist of two pieces, the master page itself and one or more content pages.

Master pages

A master page is an ASP.NET file with the extension .master (for example, MySite.master) with a predefined layout that can include static text, HTML elements, and server controls. The master page is identified by a special @ Master directive that replaces the @ Page directive that is used for ordinary .aspx pages.

In addition to the @ Master directive, the master page also contains all of the top-level HTML elements for a page, such as html, head, and form. For example, on a master page you might use an HTML table for the layout, an IMG element for your company logo, static text for the copyright notice, and server controls to create standard navigation for your site. You can use any HTML and any ASP.NET elements as part of your master page.

In addition to static text and controls that will appear on all pages, the master page also includes one or more ContentPlaceHolder controls. These placeholder controls define regions where replaceable content will appear. In turn, the replaceable content is defined in content pages.

Content pages

You can define the content for the placeholder controls on the master page by creating individual content pages, which are ASP.NET pages (.aspx files and, optionally, code-behind files) that are bound to a specific master page.

After creating Content controls, you can add text and controls to them.

At run time, IIS handles master pages in the following sequence:

  1. Users request a page by typing the URL of the content page.

  2. When the page is fetched, the @ Page directive is read. If the directive references a master page, the master page is read as well. If this is the first time the pages have been requested, both pages are compiled.

  3. The master page with the updated content is merged into the control tree of the content page.

  4. The content of individual Content controls is merged into the corresponding contentplaceholder control in the master page.

  5. The resulting merged page is rendered to the browser.

From the user's perspective, the combined master and content pages are a single, discrete page. The URL of the page is that of the content page.

Referencing external resources

Both the content page and master page can contain controls and elements that reference external resources. For example, both might contain image controls that reference image files, or they might contain anchors that reference other pages.

The context for the merged content and master pages is that of the content page. This can affect how you specify URLs for resources, such as image files and target pages, in anchors.

In server controls on master pages, ASP.NET dynamically modifies the URLs of properties that reference external resources. For example, you might put an Image control on a master page and set its ImageUrl property to be relative to the master page. At run time, ASP.NET will modify the URL so that it resolves correctly in the context of the content page.

ASP.NET can modify URLs in the following cases:

  • The URL is a property of an ASP.NET server control.

  • The property is marked internally in the control as being a URL. (The property is marked with the attribute UrlPropertyAttribute.) In practical terms, ASP.NET server control properties that are commonly used to reference external resources are marked in this way.

ASP.NET cannot modify URLs on elements that are not server controls. For example, if you use an IMG element on a master page and set its SRC attribute to a URL, ASP.NET will not modify the URL. In that case, the URL will be resolved in the context of the content page and create the URL accordingly.

In general, when working with elements on master pages, it is recommended that you use a server control, even for elements that do not require server code. For example, instead of using an IMG element, use an Image server control. That way, ASP.NET can resolve URLs correctly and you can avoid maintenance issues that might arise if you move the master or content page.

For more detailed information on master pages, see the following ASP.NET topics in the MSDN library:

Community Additions