One of the features in ASP.NET WebPages that is super powerful yet super simple is the “magic names” you can give to a page that make that page behave differently. Unfortunately the feature isn’t really called “magic names” (That would be way too cool!). Instead they are broken down into the two variations, Start pages and Init Pages. You may have seen these pages used before in other posts (I used one in my SimpleMembership post) or maybe even covered in one of the tutorials. I just figured that I would give them their own post as they are pretty powerful and could use some further explanation than what is normally given.
So let’s start with Start Pages (see what I did there?). What is the idea behind a Start Page? Well, as the name implies this is a page that will be executed every time your application starts. For those of you familiar with the Application_Start event in ASP.NET this is basically the same thing. This page will execute only once when your application is first started or if you’re running in IIS, when the Application Pool is recycled. So what is the magic file name you have to give a page to make it a Start Page? It’s simple, just name the file “_start.cshtml” or “_start.vbhtml”.
Now would be a good time to stop and talk about what the underscore character at the beginning of the file name does. ASP.NET WebPages use a concept for routing that will automatically wire up pages to nice routes for you. This was originally prototyped as “Smarty Routes” and I will be making a post about how they work later. For now what you should know is that the underscore tells routing not to serve that page up directly, effetely making it unrequestable from a browser. This trick works for any page not just these magically named pages. For instance if you have a “partial page” that contains some common UI and you don’t want the end user to be able to navigate to that page just start the name with an underscore.
Okay so back to Start Pages. Start Pages do not have any output, they are basically just a code block (the @{ } at the top of the file). If for whatever reason there is markup in the file it is just ignored. So what is a Start Page good for? Well it is used to perform programmatic setup of your site. Some of the built in features that need to be configured in a Start Page are SimpleMembership and the Email Helper. The last thing about Start Pages is that there can only be one Start page per website. Below is a sample of what a possible Start page might look like.
- @{
- //Set up Simple Membership
- WebSecurity.InitializeDatabaseFile("Demo.sdf", "Users", "UserID", "Username", true);
- //Set Up Email Server
- Mail.SmtpServer = "smtp.Server";
- Mail.SmtpPort = 25;
- Mail.EnableSsl = true;
- Mail.UserName = "UserName";
- Mail.Password = "Password";
- Mail.From = "Demo App";
- }
Okay so the second “magical name” is “_init.cshtml” or “_init.vbhtml”. For the same reason (not being requestable) Init Pages also begin with an underscore. So what is an Init Page? Init Pages run at the beginning of each request prior to the requested page. I bolded the words “each request” in the last sentence because I want you to understand that for each request that comes to the sever this page with execute. So that means it would not be beneficial to put long running setup code in this page, anything you put in an Init Page should run fast. Unlike Start Pages there can be multiple Init Pages in each website. This means that you can have the root contain an Init Page and then a subfolder contain one as well. Earlier I said that they would run for each request that came to the server that is not really 100% true. They will only run if they are in the parent folder chain of the requested page. If you have two subfolder both with Init Pages in them and then request a file from one of the subfolders only the Init Page in that subfolder will run. So you might be asking yourself “what is the order in which they execute?” The easiest way to sum that up would be that the execution starts furthest away from the requested file and works its way down the chain closer to the requested file. There is one last difference between Start Pages and Init Pages that I would like to call out. An Init Page does have an output. This means that if you put mark up in the file it will show up in the output of the request. The output follows the order of execution so an Init Page’s output would appear before the requested files output. A key point to make here is that due to the life cycle of a page if you are using a Layout Page that will appear after the output of the Init Page.
So what is a good use for Init Pages? Well there are a couple examples I’d like to give. First, is to define a Layout Page for the site. This way you do not need to include the setting of the Layout Page in each page in the site but it can still be overridden. You could override the page by placing an additional Init Page “closer” to the page or by simply just setting it to something new in the page you want to look different. The other use that Init Pages are ideal for is securing your website. I talked about this a little in my SimpleMembership post, but you can use an Init Page to require authentication to view the pages in a folder. Also because you can have multiple Init Pages you could add additional security requirements (e.g. require a cretin role) as you go deeper in a folder structure. Below is an example of an Init Page that sets the Layout Page and then requires authentication and the user to be in the “admin” role.
- @{
- LayoutPage = "~/Account/adminLayout.cshtml";
- WebSecurity.RequireAuthenticatedUser();
- if(!WebSecurity.IsCurrentUserInRole("Admin")){
- Response.Redirect("~/Account/unauthorized");
- }
- }
Hopefully this post clears up some of the mystery around these special magical file names that you may have heard about before. If not don’t hesitate to ask your question, the only stupid questions are the ones not asked! I’d like to see the creative ways that you can come up with to use both Start Pages and Init Pages so please feel free to email me your ideas!