WebMatrix Beta 2 Changes

WebMatrix Beta 2 was released a few days ago, and introduced a number of breaking changes which will affect the downloadable samples in my previous articles. I'm going to update the articles and their downloads when I can, but in the meantime, here are the most important changes introduced within the newer Beta release.

Database methods

In all the previous articles, I have used the Database.OpenFile() method to open a connection to a SQL CE database file. This will no longer work. OpenFile() has been replaced with a new simpler method: Database.Open(). When connecting to Sql CE, all that's needed is the name of the file without the .sdf extension. The method will check Web.Config for a connection with the name matching the string passed in. If it can't find one, it will look in App_Data for a database file with a matching name. So, instead of Database.OpenFile("Books.sdf"), use Database.Open("Books").

Helpers

This change has been publicised quite well by Erik Porter, the WebMatrix team PM. A couple of my articles include a way of creating reusable helpers based on adding a static C# class to App_Data and then creating a static method that can be called anywhere. A new @helper syntax has now been added that lets you do the same thing, but with Razor syntax. A simple helper can be created by adding a cshtml file to App_Code (we'll call this one Helpers.cshtml) and creating a method in it like so:

@helper TellMeTheTime()
{
    Response.Write(DateTime.Now);
}

The result can be called in a Web Page like this:

@Helpers.TellMeTheTime()

Notice that the method belongs to a class which follows the file name.

Commenting

Razor commenting has been simplified (Yay!). You just need to wrap your Razor comments with @*..... *@. When in a code block, normal language specific commenting works as previously.

RenderSection

In Beta 1, if you had a section which you might or might not want to render within a Layout page, you passed in an argument specifiying that the section was optional, and then tested to see if the section should be rendered using the IsSectionDefined method. This meant that by default all sections were required. In Beta 2 this is still the case, but the parameter is now required, and you need to set that to false to get the same result. So to clarify, optional: true has been replaced with required: false.

Request Validation

I haven't covered this area at all yet, but will be looking to do so in the near future. Request Validation within ASP.NET is a mechanism that by default, prevents the posting of html via a web form. This is a security measure that helps to prevent Cross Site Scripting (XSS) attacks being successful. In ASP.NET Web Forms, this can be turned off a page level, or site level. In Web Pages, you previously needed to turn it off at site level. Beta 2 introduces the ability to leave Request Validation in place for the site, but to disable it at form input level. This highly granular approach is a very good step forward in that it helps making a secure site easier.

A new Validation.Exclude method has been introduced, which takes a an array of strings which correlate to the name attribute of form fields that should not be validated for the presence of html. Since this change doesn't affect any of the code in previous articles of mine, I shall leave a more detailed examination for a future article.

AppData, PageData, _start.cshtml and _init.cshtml

AppData, the place to store site-wide variables has been renamed AppState. Files names _start.cshtml and _start.vbhtml have a special meaning within Web Pages in that they are used for managing global site settings etc by setting AppState values. Web Pages recognised these files by their name. That's been changed so that you need to rename the files _AppStart.cshtml or _AppStart.vbhtml.

_init.cshtml and its VB counterpart have been renamed to _PageStart.cshtml. AppState and PageData are still string-based dictionaries, but they now have equivalents that accept dynamic properties - App and Page. When using these, you use the form App.SomeValue or Page.SomeValue when setting or getting the values. VB users should note that this approach requires your application to be running in Full Trust, which is unlikely to be the case for most shared hosting environments. In that case, using the string-based dictionary approach (AppState("SomeValue") and PageData("SomeValue")) still works.

Routing and URLs

This is another area that I haven't really explored in previous articles, but in Beta 1, URLs are parsed from left to right. Each segment is examined and if a file without an extension is found that matches a segment, that file is assumed to be the one that is to be used. All other segements are considered to be data for that page. This caused problems for example where subfolders were named the same as files in the root folder. If I had a site with a page in the root folder called "Article.cshtml" and I also had a folder called "Article", any link to a page within the Article subfolder would not be found. Article.cshtml would be executed instead. The order in which URL segments are parsed has been reversed so that www.mydomain.com/Article/List.cshtml/3 will ensure that List.cshtml in the Article subfolder would be executed with "3" being passed in as UrlData[0].

NuPack Packaging Manager

NuPack is a package manager that's been introduced to both WebMatrix and ASP.NET MVC. Its role is to locate and download libraries of code that you might want to use in your application. In this respect, it works in a very similar way to Ruby Gems in Ruby On Rails. The libraries will be managed by Microsoft (initially at least) and to start with, include quite of few of the Helpers that appeared in Beta1, packaged as microsoft-web-helpers 1.0. These include the Twitter, Gravatar, Facebook and ReCaptcha helpers which were part of Microsoft.WebPages.Helpers.Toolkit. Making this library optional will help to keep the size of WebMatrix nice and small. Other libraries that have been added at the time of writing include the OData helper created by James Senior from the WebMatrix team, and his AzureStorage helper. Additional libraries will be added over time. To get NuPack to work, simply navigate to _Admin within your application. You will be presented with a screen asking for a password. Once set, try to remember it. If you forget it, you can always delete the Password.txt file that gets created in the Admin folder within App_Data when you first run the package manager.

FileUpload

The FileUpload helper has been moved out of the core Web Pages assemblies and into the microsoft-web-helpers package along with the Video helper. This means that you need to download the package to make use of @FileUpload.GetHtml(). This change makes little sense to me.

WebSecurity

The database schema has been changed. Some additional fields have been added, so you need to make sure that the schema of the webpages_Membership table has been updated if you have used WebSecurity within Beta 1.0.

Other Changes

Some of the original helpers such as Mail and LayoutPage have been renamed. Mail has become WebMail to keep it consistent with other Web Pages helpers (WebImage, WebGrid etc) and LayoutPage is now simply Layout. There is a new Json helper for serialising and deserialising items to and from JSON. I shall look at that in a bit more detail soon as well. Many of the MVC helpers have been added to the System.Web.WebPages.Html.HtmlHelper namespace which makes it easier to use them within Web Pages, although their primary use is for Razor files in MVC.