An ASP.NET master page is a template file with the .master extension that holds the shared layout of a Web Forms site, such as the header, menu and footer. It marks editable regions with ContentPlaceHolder controls. Each content page (.aspx) points to it through the MasterPageFile attribute, and ASP.NET merges the two on the server before sending one HTML page to the browser.
Key Takeaways
- Master pages were introduced in ASP.NET 2.0, released with Visual Studio 2005, and the core concept has not changed since, according to Microsoft’s master pages tutorial.
- A master page starts with an @ Master directive instead of the @ Page directive used by ordinary .aspx pages.
- Content pages supply Content controls whose ContentPlaceHolderID matches a ContentPlaceHolder on the master page; markup outside those Content controls causes an error.
- Users always request the content page, never the master page; the browser sees the content page’s URL.
- Master pages belong to ASP.NET Web Forms on .NET Framework; ASP.NET Core does not support Web Forms and uses layout files such as _Layout.cshtml instead.
How to Use a Master Page in ASP.NET Web Forms
A master page is often one of the first things a developer sets up when starting an ASP.NET Web Forms project. ASP.NET provides many built-in features for building web applications. When this tutorial was first written, the newest version was .NET Framework 4.5; as of October 2026, the latest .NET Framework release is 4.8.1, released in August 2022, and Microsoft recommends modern .NET for new development. This was the first post in the site’s ASP.NET tutorial series, and it walks through the basics step by step. When the author started an online shopping project, the first step was to create a master page before building the rest of the site.
A master page defines the shared structure or layout of a website. At run time, ASP.NET merges each content page into its master page. A master page is never requested on its own; the browser always requests the content page, which brings its master page with it. The steps below show how to implement a master page in ASP.NET.
Steps to Use a Master Page in ASP.NET
First, right-click the project name in Solution Explorer and choose Add New Item. The dialog below appears.
Select the Master Page template and click Add. A master page uses the .master extension, and the default name in this example is MasterPage.master. Visual Studio then generates the starter code shown below.
After adding the master page, build the site layout in it with HTML, and link a CSS style sheet to control its appearance.
Next, add a content page that will be merged with the master page.
Add a Web Form and tick the Select master page check box so the new page is bound to the master page. After designing the content page, run the content page itself. In this example, the content page holds a registration form. A master page lets one structure or layout be shared by every page of the website.
That is how to use a master page in ASP.NET Web Forms. The sections below cover the generated code, nesting and the modern ASP.NET Core alternative.
Don’t forget to read :- How to Install WorPress On HostGator
What Is a Master Page in ASP.NET?
An ASP.NET master page is a special ASP.NET file that defines the markup shared by a group of pages and the regions each page can customize. Microsoft’s ASP.NET Master Pages Overview describes it as a single file that defines the look and feel and standard behavior for all pages, or a group of pages, in an application.
A master page contains the top-level HTML elements, such as html, head and form, plus any static text, images and server controls that should appear on every page. Content pages fill in only the parts that change.
How Do Master Pages and Content Pages Work Together?
A master page and its content pages work as a pair: the master page supplies the frame and the content page supplies the fill. According to Microsoft’s documentation, ASP.NET handles a request in this order:
- The user requests the URL of a content page.
- ASP.NET reads the content page’s @ Page directive. If it references a master page, the master page is read too, and both are compiled on the first request.
- The master page is merged into the control tree of the content page.
- The content of each Content control is placed into the matching ContentPlaceHolder on the master page.
- The merged page is rendered and sent to the browser as one HTML document.
The merge happens entirely on the web server, so the browser receives ordinary HTML with no frames. The page URL stays that of the content page.
What Code Does Visual Studio Generate for a Master Page?
Visual Studio generates a master page that begins with an @ Master directive, for example <%@ Master Language=”C#” AutoEventWireup=”true” CodeFile=”Site.master.cs” Inherits=”Site” %>. In Microsoft’s tutorial, the default master page contains four server-side pieces:
- A server-side head element (head runat=”server”), so the page title can be set from code.
- A ContentPlaceHolder named head inside the head element, for page-specific scripts or meta tags.
- A Web Form (form runat=”server”) that wraps the page body.
- A ContentPlaceHolder named ContentPlaceHolder1 inside the form, where each page’s main content appears.
Microsoft advises that a master page should contain a Web Form with at least one ContentPlaceHolder inside it. The ContentPlaceHolder IDs can be renamed, for example to MainContent, as long as the content pages use the same IDs.
What Does a Content Page Look Like?
A content page is an ordinary .aspx page whose @ Page directive includes a MasterPageFile attribute, such as MasterPageFile=”~/Site.master”. Inside the page, each asp:Content control sets a ContentPlaceHolderID that matches one ContentPlaceHolder on the master page.
According to Microsoft, anything in a content page that is not inside a Content control, except server script blocks, results in an error. The title set in the @ Page directive is merged into the master page, which is why the master page’s head element needs runat=”server”.
In a Web Application Project, the Select master page check box is not shown in the Add New Item dialog. Microsoft’s tutorial says to choose the Web Content Form template instead, which opens the same Select a Master Page dialog.
How Can a Master Page Be Applied to Many Pages at Once?
A master page can be attached at three levels, according to Microsoft’s ASP.NET Master Pages Overview:
| Level | How it is set | What it affects |
|---|---|---|
| Page | MasterPageFile attribute in each page’s @ Page directive | That page only |
| Application | <pages masterPageFile=”MySite.Master” /> in the root Web.config | All .aspx pages in the application that contain Content controls |
| Folder | The same pages setting in a Web.config inside one folder | Pages in that folder |
Pages without Content controls are not affected by an application-level or folder-level setting.
Can Master Pages Be Nested?
Yes. Master pages can be nested, so a child master page can inherit a site-wide master page and add a sub-layout for one section of a site. Nesting has been possible since ASP.NET 2.0, while Microsoft notes that design-time support for nested master pages arrived in Visual Studio 2008.
Common Master Page Mistakes
- Plain img tags with relative paths: ASP.NET rewrites URLs only on server controls. Microsoft recommends using an Image server control instead of a plain img element on a master page so paths resolve correctly from content pages in other folders.
- Setting a theme on the master page: adding a theme attribute to the @ Master directive raises an error. Set the theme on the content page or in the pages element of Web.config instead.
- Conflicting page-wide settings: the master page is the closest parent of the page’s controls, so if EnableViewState is false on the master page, view state is effectively disabled even when the content page sets it to true.
- Markup outside Content controls: in a content page, any markup outside an asp:Content control causes an error.
Master Pages vs. ASP.NET Core Layouts
Master pages are part of ASP.NET Web Forms, which runs only on the classic .NET Framework on Windows. ASP.NET Core, Microsoft’s successor released in 2016, does not support Web Forms. Its equivalent of a master page is a Razor layout file.
| Feature | ASP.NET Web Forms master page | ASP.NET Core layout |
|---|---|---|
| File | .master file, for example Site.master | _Layout.cshtml in Pages/Shared or Views/Shared |
| Main content region | ContentPlaceHolder control | @RenderBody() |
| Extra regions | More ContentPlaceHolder controls | @RenderSection(“Scripts”, required: false) |
| How a page picks it | MasterPageFile attribute or Web.config | Layout property, usually set once in _ViewStart.cshtml |
| Platform | .NET Framework (Windows only) | Modern cross-platform .NET |
Microsoft states that .NET Framework apps do not need to be migrated and that .NET Framework will continue to be included with Windows, but it recommends modern .NET for new development. For background on the platform, see this overview of what the .NET Framework is, and compare ASP.NET with other options in this guide to back-end frameworks for web development. There is also a broader look at building applications with the ASP.NET framework.
Which .NET Framework Version Should Be Used for Master Pages?
As of October 2026, .NET Framework 4.8.1 is the latest .NET Framework release. It came out on 9 August 2022 and is installed by default on recent Windows 11 releases and Windows Server 2025, according to Microsoft’s version table. Microsoft also notes that Visual Studio 2022 and later cannot build apps that target .NET Framework 4.0 through 4.5.1 because those versions are no longer supported, so older master page projects should be retargeted to a supported version such as 4.8.1.
Master page layouts are built with standard HTML and CSS. This guide to HTML5 development covers the markup side, and these HTML escape tools help when pasting code samples such as master page markup into a web page.
Frequently Asked Questions
What is the file extension of an ASP.NET master page?
An ASP.NET master page uses the .master extension, for example Site.master or MasterPage.master. Its code-behind file adds the language extension, such as Site.master.cs for C#.
Can a user open a master page directly in the browser?
No. A master page is not requested directly. Users request a content page, and ASP.NET merges that page with its master page on the server before rendering the result.
Which ASP.NET version introduced master pages?
Master pages were introduced in ASP.NET 2.0, which shipped with .NET Framework 2.0 and Visual Studio 2005 in October 2005.
What is the difference between ContentPlaceHolder and Content controls?
A ContentPlaceHolder sits on the master page and marks a replaceable region. A Content control sits on the content page and supplies the markup for one ContentPlaceHolder, linked through its ContentPlaceHolderID property.
Does ASP.NET Core have master pages?
No. ASP.NET Core does not support Web Forms, so it has no .master files. It uses Razor layout pages, by convention named _Layout.cshtml, with RenderBody and RenderSection marking where page content appears.
Can a master page have code-behind?
Yes. A master page can contain server controls, code and event handlers. Microsoft’s tutorial shows a Page_Load handler on the master page that writes the current date into a Label, and the change appears on every content page.
Justwebworld has published guides since 2012. How we write and update articles Report an error
