Steven Sanderson's blog

This post is part of a series about the MvcScaffolding NuGet package:

1. This post: Scaffold your ASP.NET MVC 3 project with the MvcScaffolding package
2. Standard usage: Typical use cases and options
3. One-to-Many Relationships
4. Scaffolding Actions and Unit Tests
5. Overriding the T4 templates
6. Creating custom scaffolders
7. Scaffolding custom collections of files

Among many other improvements with ASP.NET MVC 3, we’re keen to make it easier to pick up and start using productively if you’re entirely new to the framework, and to automate common development tasks if you’re experienced and already know what you’re doing.

So, I’ve been working with Scott Hanselman lately on an enhanced new scaffolding package called MvcScaffolding. The term “Scaffolding” is used by many software technologies to mean “quickly generating a basic outline of your software that you can then edit and customise”. The scaffolding package we’re creating for ASP.NET MVC is greatly beneficial in several scenarios:

• If you’re learning ASP.NET MVC for the first time, because it gives you a fast way to get some useful, working code, that you can then edit and adapt according to your needs. It saves you from the trauma of looking at a blank page and having no idea where to start!
• If you know ASP.NET MVC well and are now exploring some new add-on technology such as an object-relational mapper, a view engine, a testing library, etc., because the creator of that technology may have also created a scaffolding package for it.
• If your work involves repeatedly creating similar classes or files of some sort, because you can create custom scaffolders that output test fixtures, deployment scripts, or whatever else you need. Everyone on your team can use your custom scaffolders, too.

Other features in MvcScaffolding include:

• Support for C# and VB projects
• Support for the Razor and ASPX view engines
• Supports scaffolding into ASP.NET MVC areas and using custom view layouts/masters
• You can easily customize the output by editing T4 templates
• You can add entirely new scaffolders using custom PowerShell logic and custom T4 templates. These (and any custom parameters you’ve given them) automatically appear in the console tab-completion list.
• You can get NuGet packages containing additional scaffolders for different technologies (e.g., there’s a proof-of-concept one for LINQ to SQL now) and mix and match them together

It’s currently at a beta level so it is expected to work but if you push it in funny ways you might get odd results. Please let me know if you discover issues – I’m sure there’ll be some – so we can tidy it up and make it more robust.

Installation

The short version is this: Install-Package MvcScaffolding. If you understood that, do it and skip ahead to “Scaffolding a CRUD interface”. If not, read on.

1. Install ASP.NET MVC 3, which includes the excellent NuGet Package Manager.

2. Create or open an ASP.NET MVC 3 web application. I’m calling mine ‘SoccerSite’.

3. Install the MvcScaffolding package. You can install it using the NuGet Package Manager Console, so it only takes a few seconds and you don’t have to download anything using your browser.  To do so,

• Open the Package Manager Console window using Visual Studio’s View->Other Windows->Package Manager Console menu item.
• Enter the following:

Install-Package MvcScaffolding

• That’s it! Note: be sure you installed MvcScaffolding, not MvcScaffold. We’ll retire the old MvcScaffold package shortly.

In case you’re wondering, EFCodeFirst is the new super-elegant version of Entity Framework that persists plain .NET objects to a relational database without any configuration fuss, T4Scaffolding is the core scaffolding infrastructure (locates types in your project, finds scaffolders in other packages, renders templates, etc), and MvcScaffolding is a set of ASP.NET MVC-specific templates (for controllers and views) that bolts onto the T4Scaffolding core.

Scaffolding a CRUD interface

Let’s create a model for a soccer team. Add the following class to your Models folder, then compile your solution (Ctrl-Shift-B):

namespace SoccerSite.Models
{
    public class Team
    {
        public int TeamId { get; set; }
        [Required] public string Name { get; set; }
        public string City { get; set; }
        public DateTime Founded { get; set; }
    }
}

Next, we can create a complete Create-Read-Update-Delete (CRUD) UI for this model by issuing a single scaffolding command into the Package Manager Console:

Scaffold Controller Team

Note: You can use the TAB key to autocomplete many things in the Package Manager Console. In this case, you can autocomplete the words “Scaffold” and “Controller”, since the scaffolding package knows about them. It doesn’t know about “Team”, though – we may add completion on model type names in a future version.

As you can see, it’s gone ahead and created a controller, a database context (a tiny bit of Entity Framework code that represents a data store), and views for all the CRUD actions. You can run it right now (Shift-F5), and as long as you have SQL Server Express running on your machine, EFCodeFirst will automatically connect to it, create your database schema, and you’ve got a basic working application without writing a single line of procedural code.

Note that since the model was called “Team”, the controller is called “TeamController”, so to reach it you need to point your browser to http://…/team:

The database is initially empty.

Creating an item. Validation rules are applied automatically. Note that since “Founded” is a DateTime it can’t be null and hence is required. Change it to DateTime? (i.e., with the question mark to make it nullable) if you want it to be optional.

Listing items

Deleting an item

But what if I don’t have SQL Express installed?

If you don’t have SQL Express installed and running, you may have got the following error when your code tried to read or write some data:

A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible. Blah blah blah…

No problem! You can quickly switch to use the new SQL Server Compact – a lightweight, in-process database – without having to download or install anything manually. Simply add SQL Server Compact to your project by issuing the following command in the Package Manager Console:

Install-Package EFCodeFirst.SqlServerCompact

Ta da – no more external database required. Run your project again (Shift-F5) and this time it will create and connect to a file-based database (a .sdf file will appear in your ~/App_Data folder). The EFCodeFirst.SqlServerCompact package adds a file to your project called AppStart_SQLCEEntityFramework.cs, which configures the runtime to use SQL CE.

Of course you probably still want the proper version of SQL Server when you eventually deploy your application for public use, but for small applications or for learning, SQL CE is really handy.

Scaffolding a repository

If you check out the code right now, you’ll see that TeamController reads and writes the data in SoccerSiteContext directly. That’s fine in many simple scenarios, but if you want to decouple your controller logic from persistence logic a little (e.g., so that you can write clean unit tests for the controller), you may prefer to reach your data through an interface.

No problem! Let’s regenerate the controller with the –Repository flag:

Scaffold Controller Team –Repository -Force

Notice that we also need to say –Force, otherwise the scaffolder won’t overwrite the files you already have in your project. Now the scaffolder will produce an additional class, TeamRepository, and the following interface which TeamRepository implements:

    public interface ITeamRepository
    {
        void Add(Team post);
        void Delete(int id);
        IEnumerable<team> GetAllTeams();
        Team GetById(int id);
        void Save();
    }

TeamController will now only read and write data using ITeamRepository. If you’re new to ASP.NET MVC it may not be obvious why this is desirable, but if you start trying to write unit tests or switch data access technologies, you’ll find this interface-based data access method to be much cleaner and more flexible.

There’s so much more

It’s not just about CRUD! You can use scaffolding to create any type of project item if you write a template for it. This blog post has covered only the absolute beginning of what you can do, so over the coming days I’ll write blog posts to cover:

• Scaffolding specific individual items (e.g., views, repositories, etc) rather than whole controllers and related files
• Getting additional scaffolder packages and controlling which ones are used by default. For example, there’s currently a proof-of-concept LINQ to SQL scaffolding package that you can install and set to act as the default type of repository/data context.
• Customising the T4 templates that the scaffolders use to generate code
• Creating entirely new custom scaffolders for new types of things (e.g., unit test fixtures)

Mobile devices continue to grow in popularity as a way to access the Web. If you’re building any kind of public-facing site, you probably way to make it look and behave well on mobiles just as on traditional desktop browsers.

ASP.NET MVC allows for lots of possible architectures to support this:

1. You could render different views for mobiles, as in Scott Hanselman’s recent post
2. You could have a separate MVC area for mobiles, so you can handle their requests using different controller logic as well as different views
3. You could simply have a separate layout/master page for mobiles, but otherwise let them share the same controller logic and views as desktop browsers

Hopefully soon we’ll publish some updated and more detailed guidance about these options, but for now this blog post is about option (3) – the simplest of them all.

Setting up a mobile-specific Razor layout

One of the really neat aspects of the Razor view engine (the default in ASP.NET MVC 3) is that a lot of it can be controlled by procedural code, not just declarative statements. So, if you want to implement custom logic to control layout selection, just add some logic to ~/Views/_ViewStart.cshtml. For example, change this:

@{
    Layout = "~/Views/Shared/_Layout.cshtml";
}

… to this:

@{
    Layout = Request.Browser.IsMobileDevice
        ? "~/Views/Shared/_LayoutMobile.cshtml"
        : "~/Views/Shared/_Layout.cshtml";
}

… and now it will attempt to use _LayoutMobile.cshtml for requests from mobiles. Next, of course, you’ll need to actually create _LayoutMobile.cshtml. To get started, you can just copy & paste the existing _Layout.chtml file, changing its name. To ensure we can tell the difference between the two, I’ll modify the “title” element to display a special message for mobiles:

<div id="title">
    <h1>My *mobile* app</h1>
</div>

Time to check it works. Perhaps the quickest way to simulate a mobile device (without downloading any emulators) is by using Firefox and its User Agent Switcher add-on: it already knows how to simulate the iPhone’s user agent string, for example. Here’s how my home page renders, first with the default Firefox user agent string, and second simulating the iPhone’s user agent string:

Spot the difference

At the point, you might think we’re done. Surely from here it’s just a matter of customizing _LayoutMobile.cshtml to better suit the small screen of a mobile device, right? Well, kind of. But how does Request.Browser.IsMobileDevice actually work? Is it always right?

Some popular mobile devices/browsers won’t be detected this way

In case you don’t know, Request.Browser is a core ASP.NET platform feature that can give you a lot of information about the type and capabilities of the browser making the current request. It works by comparing the incoming User-Agent header against regular expressions in a set of built-in .browser files. ASP.NET 4’s browser files are recent enough to detect iPhone, but not Opera Mobile or Android. For example, if you download the Opera Mobile emulator and visit the page we just created, here’s what you’ll see:

If you can read the tiny text, you’ll see it doesn’t say “My *mobile* app”.

One way to improve this is to add your own .browser files for newer devices and browsers – accounting for the many variations in their user agent strings. Then Request.Browser.IsMobileDevice could successfully recognize Opera Mobile. But if you don’t want to do all that work?

Improving device detection using the 51Degrees.Mobi package

51Degrees.Mobi Foundation is an open source .NET project that enhances Request.Browser so it gets its information from Wireless Universal Resource File (WURFL) – one of the most comprehensive and up-to-date databases of mobile device information. The great news is that 51Degrees.Mobi Foundation is now available as a NuGet package, so it’s incredibly easy to install and update.

If you haven’t already installed the NuGet package manager, do so right away! Next, install 51Degrees by entering the following into the NuGet Package Manager Console:

Install-Package 51Degrees.mobi

Easy! This does the following to your project:

• Adds a reference to FiftyOne.Foundation.dll, the assembly containing the 51Degrees logic
• Adds AppStart_51Degrees.cs to the root of your project. This enables the 51Degrees mobile detection provider, which populates Request.Browser information whenever you ask for it
• Adds a recent copy of the WURFL device list to your project at ~/App_Data/wurfl.xml.gz
• Adds a folder, ~/Mobile/ containing a Web Form that displays information about the device. We don’t want this in an ASP.NET MVC application – just delete the ~/Mobile folder that it added.
• Adds a section to your Web.config file that configures 51Degrees.Mobi Foundation with some default settings. One of its default settings is to redirect mobile browsers to the URL ~/Mobile. This would be useful if you were setting up an MVC Area called “Mobile” for mobile browsers, but since we’re just changing the master page, we don’t want this redirection to happen. Disable it by modifying Web.config: Find the <redirect> element inside <fiftyOne>, and comment it out or delete it.

Now you’ve got a much more up-to-date device database. Here’s what you’ll see if you reload the site in Opera Mobile emulator:

You can download newer versions of the WURFL database to pick up newly-released mobile devices and browsers at any time from its page on SourceForge. Whenever you download a new version, install it by copying it to the location ~/App_Data/wurfl.xml.gz, overwriting your previous version of that file. Note that WURFL does not yet appear to detect Windows Phone 7 WURFL does detect Windows Phone 7 already.

Improving the layout for small screens

OK, we’ve got as far as distinguishing mobiles from desktop browsers and rendering views with different Razor layout file. It’s beyond the scope of this blog post to explain all the dozens of HTML and CSS tricks you can use to create layouts that look great on the widest range of mobiles, but here’s one I want to mention:

When modern mobile browsers render web pages, they lay it out on a virtual “viewport” that by default is about as wide as a typical desktop browser window. Then, after rendering the page, they scale down the output to fit on the tiny device screen. That’s why the preceding Opera Mobile screenshots have really tiny body text: the HTML page was laid out for a screen around 1000px wide and then scaled down. The user is expected to zoom in and pan around to get a closer look at the text.

Mobiles do this as a workaround for the fact that most web pages assume you’re using a desktop browser. If the mobile didn’t do this, typical web pages wouldn’t fit horizontally and would end up getting hideously mangled. But if you’re designing a layout especially for mobiles, you’ll take account of the much smaller width and spare the user all that awkward zooming and panning.

How can you tell the mobile not to use a wide virtual viewport, but instead to lay out the page to match the device’s actual (narrow) width? You can use the unofficial “viewport” meta tag. Here’s an example. Add the following to the <head> section of _LayoutMobile.cshtml:

<meta name="viewport" content="width=device-width">

Now if you reload the page in Opera Mobile emulator, here’s what you’ll see:

Much better! The body text is now pretty much readable, and the user only needs to scroll vertically (not horizontally). No zooming required. The “viewport” meta tag is respected by most recent mobile devices/browsers, including Windows Phone 7 and iPhone. Read more about how iPhone interprets it here.

From here on, it’s up to you to customize your mobile layout, perhaps using a different CSS stylesheet, to look as neat as possible on mobiles. Of course, you can also inspect Request.Browser.IsMobileDevice in other parts of your code too (e.g., controllers or filters) if you need to vary your logic further.

Starting later this month, I’m going to be working for Microsoft – I just accepted a job on the Web Platform and Tools (WPT) team in the Developer Division. This is pretty exciting for me, as it means I’ll be able to directly focus my energy on pushing the MS web stack forwards, and will get to work with many of the very smart people who bring you technologies like ASP.NET and IIS.

In case I need to drop some names to clarify where I fit in, I’ll be somewhere many levels of management below ScottGu, and on the same team as Scott Hanselman.

Why do this?

I’m a web developer, so of course I’m personally motivated to make web development better! We all want our technologies to help us be more productive, solve bigger problems, and let us have more fun in the process, right? For someone who’s focused on the MS web stack for the last 7 years, where better to participate in the evolution of web development than inside Microsoft itself?

Well, that’s the big picture. On a more practical, immediate level I’m also keen to get involved with Developer Division’s leaning towards supporting open source development (e.g., notice that the NuGet project even accepts code contributions) and in advocating professional-grade development practices, whether they originate inside Microsoft or inside developer communities using any other technology platform.

A key part of WPT’s responsibility is to be aware of what developers want, and be sure we’re meeting your needs. As I find out what specific projects I’ll focus on, I’ll be asking for your feedback so I can reflect your views back into the collective product teams.

What changes, and what remains

• This blog: It’s still mine and will continue.
• Open source projects: The one I’m most actively working on is Knockout, an MVVM library for creating dynamic Web UIs. I’m still excited about this project and its potential, and it continues exactly as-is, and will evolve in whatever direction I and its user community wishes to take it. This isn’t a Microsoft product.
• The Apress ASP.NET MVC book series: I’m discussing this with Apress at the moment. Hopefully we’ll get the excellent Adam Freeman to co-author the MVC 3 book, otherwise it might end up being very, very late… Thanks for all the enquiries about this – and no, we don’t have a publishing schedule yet.
• Being an MVP: Shockingly, I’ll be dismissed from the MVP program, before I even got to go to my first MVP summit. Apparently this has happened to others before.
• My location: I’ll be staying in the UK.