When you create a new ASP.NET MVC 3
project, the new project wizard dialog contains several options for different
MVC project templates:
There’s a lot of white space in that
dialog. To many of you, all that unsullied territory smells like opportunity.
When I talk about this dialog, I go to great pains to tell folks that, yes!,
you too can extend that dialog and add your own project templates in there.
If you wanted to, you could have
your own ASP.NET MVC 3 project template configured exactly the way you want.
Hate the default template? Make your own!
The only problem is, I keep telling
you that you can extend it, but sadly I never told you how. But that’s about to
change!
I don’t expect that a large number
of people will want to do this, which is one reason we haven’t spent a large
amount of time making it easy (though that may change in the future). But for
the few of you impatient masochists who want to add your own custom templates
now, this blog post will walk you through the hacking around it takes to make
it happen.
Imitation
is the sincerest form of productivity
The easiest way to get started is to
simply copy and modify an existing project template. For example, I looked in
the following directory:
C:\Program Files (x86)\Microsoft
Visual Studio 10.0\Common7\IDE\ProjectTemplates\CSharp\Web\1033
on my machine and stole
*ahem* borrowed the project template named MvcWebApplicationProjectTemplatev3.01.cshtml.zip.
Note that the 1033 folder is for English (en-US) templates. For other
languages, you may need to look in a different folder.
I then renamed it to MyProjectTemplate.cshtml.zip
and extracted the contents into a folder so I could make some modifications to
its contents.
When you extract the contents,
you’ll want to rename the .vstemplate file to match the name of the template
you chose. In my case, I renamed MvcWebApplicationProjectTemplatev3.01.cshtml.vstemplate
to MyProjectTemplate.cshtml.vstemplate.
Open up the .vstemplate file in
NotePad and make sure to change the TemplateID element value to something unique.
You can change any of the contents
of the template folder now, but be very careful to make sure that any additions
or deletions of content are reflected in the .vstemplate file. That file is a
manifest of all the files within the VSIX package that makes up the project
template. Also make sure that the .csproj file reflects those changes as
well, to ensure any new files you add to the template are properly referenced
in the project.
Pre-installed
NuGet packages
UPDATE: The upcoming NuGet 1.5
feature will provide support for this feature in a way that doesn’t require the
following harsh warning. Marcin Dobosz has a blog
post detailing the feature.
Warning: I probably shouldn’t show you this next section and some of
my co-workers may chide me on this. But if you promise to be responsible and
pay close attention to the information and context for that information
I’m about to show you, I’ll do it anyways and trust you not to inundate us with
support calls when this blows your hand off.
The ASP.NET MVC 3 Tools Update
includes very limited support for project templates that include NuGet
packages. We originally wanted it to be very extensible, but ran out of time
and imposed some severe limitations on the feature, hence the caution.
If you scroll to the bottom of the
.vstemplate file, you’ll notice the following section:
<WizardData>
<packages>
<package id="jQuery" version="1.5.1"
/>
<package id="jQuery.vsdoc"
version="1.5.1" />
<package id="jQuery.Validation"
version="1.8.0" />
<package id="jQuery.UI.Combined"
version="1.8.11" />
<package id="EntityFramework"
version="4.1.10331.0" />
<package id="Modernizr" version="1.7"
/>
</packages>
</WizardData>
That is the list of NuGet packages
that the MVC 3 project template installs when you invoke the project template.
But as I mentioned, there are two
major limitations:
- The package must exist in the %ProgramFiles%\Microsoft
ASP.NET\ASP.NET MVC 3\Packages folder. MVC 3 doesn’t go searching
online for them.
- The version attribute of the package in the <package>
element is required and is an exact match.
If you are fine with these
limitations, you can modify this section of your custom project template to
install the NuGet packages you care about. Just make sure they exist in the MVC
3 packages folder like I mentioned.
Once you are done making your
changes, zip up the contents of the folder with the same file name you had
before.
Registering
your project template
At this point, all you need to do is
copy the project template to the right location and add the appropriate
registry entries. For extra credit, you can write an installer (MSI) that does
all this for you.
The place to copy your template is
the same place I mentioned previously, C:\Program Files (x86)\Microsoft
Visual Studio 10.0\Common7\IDE\ProjectTemplates\CSharp\Web\1033
Once the template is there, you’ll
need to setup the correct registry settings.
Since I’m lazy, I put these registry
settings in a .reg file to make it easy to install. You’ll just need to modify
the settings within the .reg file to match your project template.
32-bit
Windows
Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\MVC3\
ProjectTemplates\MyProjectTemplate]
"Title"="My
Project Template"
"Description"="This
is the coolest project template EVAR MADE."
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\10.0\
MVC3\ProjectTemplates\MyProjectTemplate\C#\Razor]
"Path"="CSharp\\Web"
"SupportsHTML5"=dword:00000000
"SupportsUnitTests"=dword:00000000
"Template"="MyProjectTemplate.cshtml.zip"
64-bit
Windows
Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\MVC3\
ProjectTemplates\MyProjectTemplate]
"Title"="My
Project Template"
"Description"="This
is the coolest project template EVAR MADE."
[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\VisualStudio\10.0\
MVC3\ProjectTemplates\MyProjectTemplate\C#\Razor]
"Path"="CSharp\\Web"
"SupportsHTML5"=dword:00000000
"SupportsUnitTests"=dword:00000000
"Template"="MyProjectTemplate.cshtml.zip"
The important thing to note are the
options in the second registry section:
- Path
– Relative path from the ProjectTemplates folder. For C# projects,
enter “CSharp\\Web”. For VB.NET use “VisualBasic\\Web”
- SupportsHTML5 – Whether
or not the project template supports HTML5. If set to 1, then the HTML 5
checkbox is enabled. That checkbox sets a project template variable, $usehtml5$.
You can look at the default /Views/Shared/_Layout.cshtml inside of MvcWebApplicationProjectTemplatev3.01.cshtml.zip
for an example of this.
- SupportsUnitTests
– This allows you to associate a unit test project template with your
project template.
- Template
– the name of your project template file.
The last step is to run the command devenv
/installvstemplates to force Visual Studio to recognize
the project templates.
I wrote a batch file, install.bat,
when combined with the .reg file, that automates these steps.
cd
%~dp0
regedit.exe
/s project-template.reg
xcopy
MyProjectTemplate.cshtml.zip "C:\Program Files (x86)\Microsoft Visual
Studio
10.0\Common7\IDE\ProjectTemplates\CSharp\Web\1033"
/Y
devenv
/installvstemplates
For your convenience, I packaged up
the necessary files in a zip
file. Unzip the file, and run install.bat and you’ll see a
new project template when you create a new ASP.NET MVC 3 project.
