How to customize scaffolding templates for ASP.NET vNext

Yesterday I posted the announcement for command line scaffolding in ASP.NET vNext. Shortly after we received a comment asking.

“Would be interesting to see how easy/hard it is to change the scaffolding template.”

For context in Visual Studio 2013/2012 you could customize the template content by copying files from c:\program files\ into your source project.

When I saw the comment come in, I wasn’t sure if the feature had been implemented yet or not. So I quickly created a sample to try it out. Unfortunately it wasn’t working. In the morning (11:30 so I’m using that term lightly) stand up I brought up the comment and asked about the status of the feature. Pradeep, the dev owner for this feature, confirmed that he had not yet implemented the feature. I asked him how easy/hard it would be and he said he would look into it. A few hours later he comes back and let’s me know that he got the feature implemented and checked in! Now that the build has completed and passed it’s available for everyone to try. So let’s move on to try it out!

When an ASP.NET vNext scaffolder is executed it’s common for those scaffolders to use templates to generate content into the project. It is easy to customize these templates on a per-project basis. Let’s get a new project created with scaffolding enabled so that we can customize the content. Follow these steps.

  1. Create a new ASP.NET vNext Web Application project (we don’t support Empty web just yet)
  2. Update project.json to add dependency for generators and the gen command
  3. Add a Person model which will be used for scaffolding

If you need more details on the previous steps checkout the previous post http://blogs.msdn.com/b/webdev/archive/2014/08/21/command-line-scaffolding-for-asp-net-vnext.aspx.

We have modified project.json to include the following for the generators.

"Microsoft.Framework.CodeGenerators.Mvc": "1.0.0-*"

This will pull the highest version of 1.0.0 that is published on the NuGet repositories. The feature allowing templates to be overridden in the project exists in versions > 1.0.0.-alpha4-10177. The NuGet package actually contains the templates. This enables us to modify them easily and re-ship via NuGet. To customize the templates you’ll just copy the Templates folder from the NuGet package into the root of your project. For ASP.NET vNext, NuGet packages are stored on a per-user basis by default. On my machine, for the 10185 version,  that path is C:\Users\ibrahim\.kpm\packages\Microsoft.Framework.CodeGenerators.Mvc\1.0.0-alpha4-10185\Templates. After you add the templates folder to your project your Solution Explorer should look like the following image.

Screenshot 2014-08-22 16.35.24

The extension of these files is .cshtml. That is because we are using Razor as our templating language in ASP.NET vNext. Two reasons why we are using Razor here; It’s cross platform via ASP.NET vNext and because many ASP.NET developers already know Razor. For this project, you can edit the contents of these files to control what content is generated during scaffolding.

If you customize the contents of these files and you are re-generating some existing content using k gen you can pass the –f (force) switch to overwrite existing files. I modified these templates with the following changes.

  • For generated controllers: move using statements inside the namespace declaration
  • For generated views: modify html element to specify en-us and modify meta tags in the head

You can grab my samples from https://github.com/sayedihashimi/scaffolding-samples/tree/master/CustomizeScaffoldingTemplates/ if you are interested in following along or tweaking what I have. In the screenshot below you can see the customized controller template.

Screenshot 2014-08-22 16.58.38 

After making these changes in this project when you execute the command k gen controller -m CustomizeScaffoldingTemplates.Person -dc CustomizeScaffoldingTemplates the generator will use the customized templates instead of the ones shipped with the NuGet package itself.

That is pretty much it. Please try it out and let us know in the comments below what you think. You never know, it may end up being a new feature 🙂

Sayed Ibrahim Hashimi | @SayedIHashimi