Changing the default HTML Templates to HTML5 in Visual Studio

December 23, 2011 • from Maui, Hawaii

On this page:

If you're using Visual Studio 2010 to create Web applications, you probably have found out that the default Web templates for ASP.NET Web Forms and Master pages and plain HTML pages all create HTML 4 XHTML headers like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="$fileinputname$.aspx.cs" Inherits="$rootnamespace$.$classname$" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

Now I don't know about you, but I'm happy to use HTML5's simple DOCTYPE definition. The first thing I tend to do is manually change my document header so that it looks like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="$fileinputname$.aspx.cs" Inherits="$rootnamespace$.$classname$" %>
<!DOCTYPE html>
<html>

Wouldn't it be nice if this was the default?

If you have a few minutes it's easy to change the stock templates in Visual Studio, or if you prefer you can create your own custom templates to exactly suit your needs.

Stock templates in Visual Studio 2010

All the default document types in Visual Studio are based on templates which are stored conveniently in .zip files. The folder where Visual Studio stores its HTML templates for Web Application Projects lives in this location:

C:\Program Files (x86)\Visual Studio 2010\Common7\IDE\ItemTemplates\CSharp\Web\1033

If you're using Web Site project the location is:

C:\Program Files (x86)\Visual Studio 2010\Common7\IDE\ItemTemplates\Web\CSharp\1033

There are a ton of templates in both folders. For WebForms the one we want is - not surprisingly - WebForms.zip. If you open up WebForm.zip with your favorite Zip tool (or Explorer) you'll see something like this for Web Application Projects:

You can see the three templates - the ASPX, .cs and designer files in the zip file. You can edit all of these, but for our purpose here I'll just change the HTML header.

If I open the default.aspx page you see the following default markup:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="$fileinputname$.aspx.cs" Inherits="$rootnamespace$.$classname$" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    
    </div>
    </form>
</body>
</html>

It's a template so you see a few template expressions like $fileinputname$ and $rootnamespace$ in the document. Visual Studio fills those values in when the template is loaded and a new item added to a project. However, the rest of the document can be changed to your heart's delight. For the basic WebForms template I simply added the HTML 5 doctype header like this:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="$fileinputname$.aspx.cs" Inherits="$rootnamespace$.$classname$" %>
<!DOCTYPE html>
<html>
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
    
    </div>
    </form>
</body>
</html>

Save the file and make sure that the zip file gets updated with the saved data (check: Open the Zip file again and edit the file again to make sure). If you use any recent zipping tool (or even Explorer) you will be able to simply edit the file and save it to write the changes to the Zip file.

Rebuild the TemplateCache

You're not quite done yet, unfortunately. Once you've updated your zip template you need to override the Cache that Visual Studio creates from templates. Visual Studio internally unzips these template zip files and stores them in a TemplateCache folder which lives in:

C:\Program Files (x86)\Visual Studio 2010\Common7\IDE\ItemTemplatesCache\CSharp\Web\1033\WebForms.zip

C:\Program Files (x86)\Visual Studio 2010\Common7\IDE\ItemTemplatesCache\Web\CSharp\1033\WebForms.zip

Basically there are folders that mimic the .zip files and hold the unzipped content on disk. Updating the Zip file in the ItemTemplates folder on its own will not yet give you the new template until the TemplateCache has been updated.

To do this you need to run:

DevEnv /InstallVsTemplates

from the Visual Studio Command Prompt. This recreates the template cache with the updated templates you modified.

Alternately I also found that you can delete all the folders in the ItemTempaltesCache folder which effectively clears the cache. Visual Studio will then use the templates directly from the zip file. This can be useful if you're mucking around with the templates a bit or you're trying out multiple templates all at once as it bypasses the Template registration steps. When you're all done though it's a good idea to /InstallVsTemplates just to be 'correct' about it.

While you're at it you probably also want to change:

HtmlPage.zip
MasterPage.zip

along the same lines. Note that the various Razor templates already use HTML5 doc headers, so no need to update them for HTML 5.

Creating new Templates

Changing the stock templates is useful because you probably use them all the time every day. But if you want to make sweeping changes to templates, or you want to have multiple templates that do various specific tasks, it's probably better to create brand spanking new templates instead. It's also very easy to create brand new templates. One of the easiest ways to do that is actually built right into Visual Studio via the Template Export mechanism.

Let's look at an example. I'll use a Web Application project here, but the same works for any kind of project: Web Site, MVC w/ Razor, Web Pages.

Let's start with a page that acts as my default template I'm going to create. This template includes a few basic setups for some base layout that is common on sample pages I create:

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="WebForm1.aspx.cs" Inherits="WebApplication10.WebForm1" %>
<!DOCTYPE html>
<html>
<head id="Head" runat="server">
    <title></title>
    <link href="css/westwind.css" rel="stylesheet" type="text/css" />
    <script src="//ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js" type="text/javascript"></script>
    <script type="text/javascript">
        if (typeof (jQuery) == 'undefined')
            document.write(unescape("%3Cscript src='scripts/jquery.min.js' type='text/javascript'%3E%3C/script%3E"));
    </script>
</head>
<body>
    <form id="form1" runat="server">
    
    <h1></h1>

    <div class="toolbarcontainer">
        <a href="" class="hoverpanel"><img src="css/images/home.gif" /> Home</a>
        <a href="" class="hoverpanel"><img src="css/images/refresh.gif" /> Refresh</a>
    </div>
    
    <div class="containercontent">
    
    
    </div>
    </form>
</body>
</html>

Now to create a template from this page:

Select the Web project or any file within it
Click on File | Export Template and select Item Template

Click Next and select the file or files in the project to export
Fill in the info for the template:

This ends up creating a new template in your My Documents folder:
<MyDocuments>\Visual Studio 2010\My Exported Templates

and

<MyDocuments>\Visual Studio 2010\Templates\ItemTemplates\Visual C#

You might want to move the latter file into the

C:\Users\rstrahl\Documents\Visual Studio 2010\Templates\ItemTemplates\Visual C#\Web

folder, so the template properly shows up in the Web folder which then looks like this in the Add New Item dialog:

When you select the template it now produces your custom HTML for the template you created.

Templates A-GoGo

Templates are a nice way to create pre-fab content. I've found it useful for certain kinds of projects to create project specific templates just so some common content can be loaded into the page. While WebForm Master and Razor Content Pages remove some of the need to build large custom headers, for some situations having custom content pumped directly into pages is still useful. Templates make this task easy and save you from repetitive typing. It's worth the effort to spent a little time to customize those templates you use daily to fit your needs. Whether it's changing the existing templates or create brand new ones, you now have the tools to customize to your hearts' content. Go for it!

Rick Strahl's Weblog