mike's web log

WebMatrix and ASP.NET Web Pages books

Thu, 02 Feb 2012 10:50:40 GMT

We're quite happy to see a number of books about WebMatrix and ASP.NET Web Pages become available. Here is the list of books that I'm aware of at the moment:

Beginning ASP.NET Web Pages with WebMatrix
Mike Brind, Imar Spaanjaars. Mike is a superstar on the ASP.NET Web Pages forums.

Building ASP.NET Web Pages with WebMatrix (Need2Know)
Jim Wang. Jim is one of the testers on the ASP.NET team.

Building ASP.NET Web Pages with Microsoft WebMatrix (The Expert's Voice in .Net)
Steve Lydford

Introducing Microsoft® WebMatrix
Laurence Moroney

UBelly: A Guide to Web Development 101 Using WebMatrix
Andy Robb

There's also the PDF version of the tutorials that are on the http://asp.net/web-pages site.

Finally, there's also the Starting Web Development with Microsoft WebMatrix tutorial series on MSDN, which is in effect a book-length tutorial.

[more]

Horizontal menu as a Razor helper

Wed, 01 Feb 2012 18:01:21 GMT

On the forums, someone was asking about creating a horizontal menu using Razor code in ASP.NET Web Pages. The technique of combining an unordered list (<ul> element) with CSS to create a horizontal layout, using <a> elements as the menu items, is a pretty well-known one; you can find examples here and here, not to mention in the Site.css file that comes with a lot of the Visual Studio web project templates.

The actual Razor part is likewise not hard. Someone showed this code as a way to dynamically build a list (to which you'd then apply the CSS):

<ul>
@foreach (var item in collection)
{
    <li>@item</li>
}
</ul>

The interesting part was a comment that the original poster made:

It sounds like if I have lots of logic inside the loop, I might be best served moving that to the back end somewhere and just calling a method that returns the text to display within each list item.

What this sounded like to me was a fun excuse to see about creating a custom helper. Helpers are, in effect, chunks of code and markup; when you invoke the helper, it runs the code and emits the markup. For example, by creating a helper to render a horizontal menu, you could do something like this in a page:

@MyHelpers.HorizontalMenu(
    "Home|Default.cshtml", 
    "About|About.cshtml", 
    "Login|Login.cshtml", 
    "Register|Register.cshtml")
<h1>My Page</h1>
      <p>Hello, horizontal menu.</p>

And get something like this:

Well, anyway, in the App_Code [more]

Need feedback: draft article about request validation

Mon, 23 Jan 2012 08:46:27 GMT

A couple of us on the ASP.NET documentation team are working on a topic that describes how to disable request validation in ASP.NET. What do you think about the following draft? Any feedback welcome.

Request validation is a feature in ASP.NET that examines an HTTP request and determines whether it contains potentially dangerous content. In this context, potentially dangerous content is any HTML markup or JavaScript code in the body, header, query string, or cookies of the request. ASP.NET performs this check because markup or code found in the URL query string, cookies, or posted form values might have been added to the request for malicious purposes.

For example, if your site has a form where users enter comments, a malicious user could enter JavaScript code in a <script> element. Then when you display the page with the comment to other users, the browser would execute that JavaScript code as if it had been generated by your website. This is commonly referred to as a cross-site scripting (XSS) attack.

Request validation helps prevent this kind of attack. If ASP.NET detects any markup or code in a request, it throws a "potentially dangerous value was detected " error and stops page processing. The default error page looks like this (click to enlarge):

Request validation throws this exception when any HTML markup is detected, including harmless markup like <b> [more]

From functional to decorative

Fri, 13 Jan 2012 18:16:31 GMT

For Friday Fun, a word that's new to me (tho not a new word per se — in fact, it's from the 1800s). First: I really like the word retronym, which refers to a term that has to be amended due to a technological change. Thus before the invention of the electric guitar, there was no notion of an "acoustic" guitar; all guitars were acoustic. Likewise dial phones, analog clocks, Classic Coke, and so on. (List of retronyms)

The new word I just learned is semantically kinda-sorta in that camp. (Maybe it's kind of opposite-y.) The term is skeuomorph (Greek: "vessel-shape"), and it refers to a vestigial design feature that represents something that was once functional. A popular example is the buckles on shoes — originally used to, you know, buckle the shoe, now used just for looks. Other examples are faux wood or fabric patterns in plastic; light bulbs shaped like candle flames; fake shutters that people mount next to the windows of their house; fake spokes in a hubcap; the "wax" on a bottle of Maker's Mark bourbon; and (a famous example) the tiny and useless "handle" that's on virtually all bottles of maple syrup.

[more]

It's campaign season ... and bad-editing season?

Thu, 12 Jan 2012 18:46:43 GMT

My wife is on the mailing list for the Democrats, and recently the Obama 2012 campaign sent us a peculiar little document that's like a little pocket guide to the accomplishments of the current administration. I say peculiar not just because I simply cannot imagine whipping out my handy wallet-sized list of talking points and lambasting some innocent with them, but because there are some editorial peculiarities in this little doc. And those are the issues I really care about. :-)

The most, er, egregious issue is parallelism in lists. Some of them are ok, like this[1]:

Ending Insurance Company Abuses.
Keeping Premiums Low.
Expanding Access To Care.
Closing the Medicare Prescription Drug "Donut Hole."

Fine; all the list items are gerunds, i.e., they end in –ing. But here's another:

Equal Pay For Equal Work.
Improving Women's Health.
Protecting Women's Right to Choose.

Hmm. Two out of three are gerunds, but that first one is, like, you know, not. Odd.

Things get stranger yet. Here's another list:

Job Creation.
Saved the auto industry from collapse.
The private sector has created jobs.

Um ... what the heck kind of structure is that? It's like a smorgasbord of sentences on an idea platter.

There's more like this, but you get the idea.

Then there's the questionable punctuation. I don’t know if you noticed, but there's a kind of Random Capitalization thing going on with the list text. Some list items use heading caps, some use sentence caps. Is there some logic to the choices? Not that I can tell.

Then I don't know what to make of this. I cite it in full so you can see where the issue is:

Ending Insurance Company Abuses [more]

It's a miracle, but it isn't perfect just yet

Tue, 10 Jan 2012 00:06:49 GMT

One of my tasks over the last few years has been to whittle down our collection of CDs, after of course ripping them. I use Windows Media Player for ripping, which has been quite satisfactory. In fact, more than satisfactory. I have fed innumerable CDs into my machine, and time after time, across a wide range of genres and for CDs going back 25+ years, WMP has blithely displayed the CD title and list of tracks.

This actually is quite amazing, if you think about it. I can start up a CD that I distinctly remember buying 27 years ago, and WMP figures out what it is and then goes out to ... somewhere ... to bring back album art and a track listing. (Try that with your vinyl or cassette tapes, ha.) When I was working my way through the pop/rock and jazz CDs, I don't think it ever failed to find the right CD and track listing. I think the only flaw I ever found was that it would retrieve CD cover art that was for a slightly different edition of the CD.

Now I'm ripping classical CDs, and here I begin to detect that this technology is not exactly, entirely perfect. What I'm realizing (after doing exactly zero research about this) is that WMP is leveraging a wee bit of crowdsourcing in order to come up with track listings.

For example, I put in a Dvorak CD that was an old Sony reissue on the "Essential Classics" label. WMP found the CD, no problem, but this is what it came up with for a track listing:

Oops. A DGG recording by Helene Grimaud was tagged by someone who I think must have intended to come back later and finish:

This RCA recording was tagged by someone who could not be bothered to repeat all of that stuff for every movement, good golly:

[more]

"Lazy" speech

Fri, 23 Dec 2011 09:02:41 GMT

Once again I have heard someone refer to a speech pattern as "lazy." Of all the complaints about the way other people speak (and by golly, there are plenty), the one that makes the least sense to me is that people's speech is lazy. And yet:

... my pet peeves. They’re about pronunciation, rather than grammar and news people on television are doing this more every day:

1. Fill, instead of feel.
2. Pill, instead of peel.
[etc.]

To me, this “sims” just lazy. [source]

Plural forms are always going to be determined by what the majority is used to or comfortable with, with a tendency towards laziness. Very few people are going to bother with Priora when Priuses is perfectly functional. However, that doesn't mean that words adopted into English should use regular plural forms; it simply means that they are likely to. [source]

If I'm talking with friends or sending a text, I don't use "proper" English grammar, but I do recognize that my grammar is incorrect. I just don't care, and I know that my listener will understand me even if I'm lazy. [source]

A split infinitive can be a lazy way not to write a better sentence. [source]

When a speaker or writer uses incorrect subject/verb agreement, it tells the audience that he is either lazy or does not care. [source]

[more]

'Tis the season ... for bad ads

Tue, 20 Dec 2011 22:30:21 GMT

One way for me to retain sanity in the face of the commercial onslaught of Christmas is to keep an ear and/or eye out for the utterly lamest, most obvious attempt to co-opt Christmas for commercial gain. This is a periodic, if not annual, tradition: previous 1, previous 2.

The bar is low, obviously, but my favorites are always the ads in which the merchant tries to establish a connection between their blatantly off-season or aseasonal offering and the holidays. My favorite so far this year is a company that offers zipline tours up on one of the San Juan islands. The premise of their ad — and this is a typical strategy — is that so-and-so is just so hard to get a gift for, so the answer is a gift certificate for a zipline tour! The ad writer in this case felt obliged to provide some backstory on the putative recipient and why swinging through the trees was just the thing for him. Presumably the simple offer of the tour was by itself insufficiently, um, compelling.

My radio listening is way down in latter years, so I'm not really sampling broadly. This is a good thing in general, of course, since it spares me exposure to foolishness like this. On the other hand, it reduces my enjoyment of this little exercise.

Got any candidates?

PS Apologies to John McIntyre for the title.

"In order" to clarify meaning

Mon, 19 Dec 2011 22:54:22 GMT

Not long ago I posted about terms that just bug me. One of the commenters suggested the addition of in order to, on the theory that it's just grandiloquence. This isn't untrue. For example, the BBC suggests that in order to and just plain to "convey exactly the same meaning when conveying purpose."

However, sometimes I actually find myself inserting in order to. This is not because I love wordiness, haha, but because there are contexts in which it helps disambiguate a phrase. Consider these examples:

The method is required to support binary conversion.
The method is required in order to support binary conversion.

The target server is a setting that you add to publish data.
The target server is a setting that you add in order to publish data.

It's a prerequisite that you need to deploy a web site.
It's a prerequisite that you need in order to deploy a web site.

You can assign query strings to the Query property to return data.
You can assign query strings to the Query property in order to return data.

Sign In To Download Credentials
Sign In In Order To Download Credentials

The phrase in order to introduces a so-called infinitive phrase. If the phrase that follows to [more]

Crediting documentation

Thu, 08 Dec 2011 18:19:15 GMT

The standard model for creating large documentation sets pretends, in essence, that the content springs from a single faceless source, namely <Your Company>. This is one of the concerns (not the only one) of a style guide, namely to define an overall tone for a content set that originates with different authors. And of course corporate-created documentation is generally not credited, and certainly not at the article level.

We're starting an experiment with changing this for our own docs. For our last couple of big tutorial sets, we're attaching author names and bios to the bottom. Here are a couple of examples:

In both cases, the author info is at the bottom.

We're also going to be experimenting with adding this info to MSDN topics. Here's an example (actually still a prototype) of what that might look like:

We reckon that adding author attribution has these benefits, in no particular order:

Authors help develop their "brand".
Readers can learn to associate an author's name with a specific level, quality, and focus of work.
Content will get a personality and human face.
Readers get the (correct) impression that documentation is created by actual people.
[more]

Apostrophes and plurals

Fri, 25 Nov 2011 19:59:14 GMT

Flipping through the 28 Nov 2011 edition of The New Yorker, I ran across the following cartoon:[1]

It took me a moment to parse the caption. What really threw me was the last word — ccs, which I initially read as c-c-s. I then worked out that "blind ccs" was intended to be the plural of bcc, as in blind carbon copies, as in that option for sending email.

Frankly, I would have edited the caption to read like this:

"I'm sure we're in all the same bcc's"

For starters, I would not have created the mutant phrase blind cc, which seems like a failure of nerve. But then there is the interesting question of whether you can just whack an -s onto cc in order to pluralize it. We've been admonished plenty that you don't use an apostrophe to mark the plural, right? But there are these exceptions ...

The trusty Chicago Manual of Style (CMoS) has, as usual, sane advice for this situation:

6.11 So far as can be done without confusion, single or multiple letters, hyphenated coinages, and numbers used as nouns [...] form the plural by adding s alone.

6.82 Individual letters and combinations of letters of the alphabet are italicized. If some proverbial expressions the distinction is ignored, and in that case the plural is formed by adding an apostrophe and s:

Mind your p's and q's.
Dot your i's and cross your t's.
[more]

The KJV in everyday speech

Wed, 23 Nov 2011 15:17:47 GMT

The King James Bible (alternately, the Authorized Version or King James Version or KJV) is 400 years old; it was originally printed in 1611. Many people have noted that the book -- specifically, the language of the translation -- has had a widespread impact on everyday English.

For some Friday Fun (tho it's Wednesday, it's a virtual Friday for many in the US), here's a pleasing observation from an article in the latest National Geographic about the creation of the King James Bible. This is by Adam Nicolson, whose book about the KJV is listed below.

If a child is ever the apple of her parents' eye or an idea seems as old as the hills, if we are at death's door or at our wits' end, if we have gone through a baptism of fire or are about to bite the dust, if it seems at times that the blind are leading the blind or we are casting pearls before swine, if you are either buttering someone up or casting the first stone, the King James Bible, whether we know it or not, is speaking through us. The haves and have-nots, heads on plates, thieves in the night, scum of the earth, best until last, sackcloth and ashes, streets paved in gold, and the skin of one's teeth: All of them have been transmitted to us by the translators who did their magnificent work 400 years ago.

Personal anecdote. In my grad school days, I was exposed to a variety of extinct Germanic languages, including Anglo-Saxon and Gothic [more]

And now, some other text generators

Fri, 18 Nov 2011 07:55:44 GMT

A little while back, I played around with various ways to create placeholder text. Those were specifically for generating nonsense text, but there are various sites/tools/utilities for generating text that have a more serious purpose. For a little Friday Fun[1], therefore, let's have a look.

Data Generator
"... a free, open source script that lets you quickly generate large volumes of custom data in a variety of formats for use in testing software, populating databases, and scoring with girls."

Ok, so that actually sounds pretty useful. (Yeah, except the girls part.) The next few are implementations of the general desire for automatic summarization.

FigSum
Supposed to generate text summaries automatically from figures (e.g. in a paper). "... aggregates scattered information to improve figure comprehension. For each figure in an article, FigSum generates a structured text summary comprising one sentence from each of the four rhetorical categories – Introduction, Methods, Results and Discussion (IMRaD)."

Generating Questions Automatically from Informational Text (pdf)
[more]

Getting custom info from the FileUpload helper

Thu, 17 Nov 2011 14:25:50 GMT

In ASP.NET Web Pages, you can use the FileUpload helper[1] to render HTML that lets users upload one or more files. For example, this helper:

@FileUpload.GetHtml(
    initialNumberOfFiles: 1,
    allowMoreFilesToBeAdded: false,
    includeFormTag: true,
    uploadText: "Upload File 1",
    name: "Upload1"
)

Renders this:

The upload controls consist of a <input type="file"> element and a submit button (<input type="submit">). By default, the helper renders a <form> element around this. For example, the markup rendered by the previous example is this:

<form action="" enctype="multipart/form-data" method="post">
<div class="file-upload" id="file-upload-0">
<div>
    <input name="Upload1" type="file" />
</div>
</div>
<div class="file-upload-buttons">
    <input type="submit" value="Upload File 1" />
</div>
</form>

(The <div> elements with their IDs let you specify CSS to make things pretty.)

People sometimes ask whether there's a way to get additional information about the upload. For example, if you have two FileUpload helpers on a page, can you tell which one submitted the file?

Yes. Specify the helper this way:

<form method="post" name="form2" enctype="multipart/form-data">
	@FileUpload.GetHtml(
	    initialNumberOfFiles: 1,
	    allowMoreFilesToBeAdded: false,
	    includeFormTag: false,
	    uploadText: "Upload2",
	    name: "Upload2"
	)
	<input type="submit" name="buttonUpload2" value="Upload File 2" />
</form>

[more]

Wordless diagrams

Wed, 16 Nov 2011 19:39:30 GMT

Think you could explain to someone how to blow bubblegum, but without a single word? Nigel Holmes can:

He's got an entire book of these types of instructions.

Pleasingly, the blog for his book likewise has no words.

MembershipProvider error in ASP.NET Web Pages

Tue, 15 Nov 2011 22:23:45 GMT

If you use membership in ASP.NET Web Pages, you might get the error To call this method, the "Membership.Provider" property must be an instance of "ExtendedMembershipProvider":

I happened to run across this while playing around with the new OAuth login capabilities in the beta version of Web Pages 2, but you might see it under other conditions as well.

Per one of our testers, this can indicate that the server has no AspNetSqlMembershipProvider configured. (A clue here is that everything works great when you test locally, but then throws an error when you deploy to your hosting provider.)

In my case, I fixed this by adding the following to the site's local Web.config file:

<appSettings>
  <add key="enableSimpleMembership" value="true" />
</appSettings>

This is a child of the <configuration> element and a peer of the <system.web> element.

Anyway, that worked for me. I'm curious if others have seen this error and if so, how they fixed it.

Police shoot dead man

Sat, 12 Nov 2011 07:26:01 GMT

An example today of what have come to be called crash blossoms — ambiguous headlines:

[Source]

For a whole blog's worth of these things, see http://www.crashblossoms.com/.

Childhood trauma

Fri, 11 Nov 2011 00:12:39 GMT

For some Friday Fun, a cartoon out of a recent edition of The New Yorker:

The you-could-also problem

Wed, 09 Nov 2011 21:10:14 GMT

I deal with tutorials a lot. A tutorial is, in some senses, a self-guided demo. We want to show you how to accomplish some specific task ... Here's how you read data from a database! Here's how you add login capabilities to your website! Etc. Tutorials are by nature procedural — they consist of sequential steps. Create the page, then add these controls, then write this code. These steps are generally interspersed with pictures to show you either what you're about to do or what you've just done:

What tutorials are not is a leisurely discussion of the many ways you could approach a problem. The tutorial shows you one concrete way to accomplish the task. If you want to show a different way, write a second tutorial.

Yet there is a strong impulse to include asides to the reader that go off this one-track path. As I review tutorials, I'll often run across these types of tossed-off observations: "Another way you could do this is xxxx, although we don't discuss that here." Or "At this point, you could do xxxx, although you don't have to."

Almost without exception, I'll encourage the writer to take these out. My thinking is that the user doesn't really care about alternatives or optional (but non-functional) steps while they're in the middle of something. That's why I note that tutorials are sort of like demos — when someone is doing a sales demonstration, they don't stop as they go and say "Of course, a different way to do this is ...". You want to keep the reader focused on the task at hand and not clutter their minds with roads not taken and steps they don't need.

I say almost [more]

My political beliefs

Sat, 05 Nov 2011 10:53:40 GMT

I belong to the group that has the correct political beliefs. Our side knows the truth, and we're correct about everything, and we're good. The other side is wrong, and they're bad. Our beliefs are true for all circumstances and scenarios. They are valid for all parameters and variables. They apply to all people at all times and for all situations.

Our opponents argue about these beliefs. That's because their morals and thinking are corrupt. They look for weasely ways to rationalize their own unethical behavior. And they hate our beliefs and our nation.

Why is the other side so wrong? Some of them are stupid, or crazy. Many are simple-minded fools who can only parrot the platitudes of their elite. They all are tools of shadowy overlords who manipulate these people's beliefs to thwart the will of all true citizens, probably for financial gain. (Because our opponents are stupid, this is easy.) Some of them hate everything we stand for and are eager to work against their own interests. The important point is that all of them are wrong, always.

History has vindicated us over and over. Our founding fathers all agreed 100% with our beliefs, as we can easily prove by quoting them. These sainted leaders had a unique and inspired vision for our country. But our opponents have co-opted this for their own evil purposes. Sometimes our opponents have temporarily had power, which they gained through deceit and fraud. They then ignored our true and good beliefs and implemented their destructive agenda. Our bitter vindication is that each time they then ran the country straight into the ground.

[more]

Mike Swaine on communicating

Wed, 02 Nov 2011 10:15:14 GMT

In case you don't already follow Mike Swaine at Swaine's World, I'm going to recommend him. Here's an example of why:

[T]he good news is that you only have to worry about those two things when you write: am I communicating what I want to communicate, and am I communicating only what I want to communicate? You don’t have to worry about rules of punctuation, spelling, grammar, or usage. It’s not that they aren’t useful, and you ignore them at the risk of impairing your communication. I’m just saying keep them in their place: so far as you as a writer are concerned, those things are just possibly helpful heuristics to help you say what you mean to say, and not say what you don’t mean to say.

Writing is communication. Don’t lose sight of that fact and you’ll be all right.

Email is not a CMS. Mostly.

Mon, 31 Oct 2011 09:18:13 GMT

Our team uses a formal content management system (CMS), a home-grown but very powerful system that has evolved over the past decade to be suitable for producing the type and volume of information that appears on MSDN. This CMS system includes check-in/out facilities, versioning and history, tons of document metadata, workflow status, custom tools (for example, to generate skeleton API docs), etc. We have our issues with it, but it gets the job done.

Not all of our work is for MSDN, tho. For the "other" documentation that we write, we've settled on using SharePoint for Word-based documents. That isn't quite as powerful in various ways, but it does give us CMS functionality. For HTML-based documentation, we've been using the source-code control facilities of Team Foundation Server, aka TFS.

And then there is the "other-other" work. Stuff that comes in over the transom — error messages to review, screen text, marketing blurbs, whitepapers, readme files, and so forth and so on. This is material that's owned by folks outside of documentation but that they want our help with. Perhaps surprisingly, we don't have a formal system for putting this stuff into the pipeline. What tends to happen instead is that it shows up in email.

[more]

Words (not) to live by

Fri, 21 Oct 2011 13:01:31 GMT

John McIntyre has a post today about using evidence to support assertions about language, and I've been thinking anyway recently about the need for empirical support for things like planning your documentation. (More on that another time.) Thus I was primed today while I was editing to think about edits I make that I really can't justify.

The writer David Owen said once that early in his career he interned for someone who "maintains an idiosyncractic but absolute ban on the word however."[1] Every editor has terms — words, phrases — that they just don't like. A word seems ungainly to them, or it violates some bogus rule that the editor once learned, or ... well, whatever. It's subjective, but in each case it's specific to that editor and can't be justified in the usual ways. (Logic, precedence, or appeal to authority.)

So for a little Friday Fun, here's a list of edits I make that have no more justification than "because I don't like it." :-)

upon
Custom Formatting Based Upon Data [#]

The number of times in which I think upon is better than on is so small that I can't remember the last time I let upon stand.

within
ASP.NET MVC 3 and the @helper syntax within Razor [#]

My ban on within isn't quite as absolute as it is on upon; there are times when it does clarify. (Something like [more]

I speak, therefore I am a linguist

Thu, 20 Oct 2011 09:41:24 GMT
From an article on Ebonics by Ronald Kephart:
If the topic is physics, most people are happy to defer to physicists; if the topic is digestion, even though most people can digest food, they still defer to the gastroenterologists. But if the topic is language, everyone thinks they’re a linguist.

Installing version 1 of WebMatrix after installing WM2 beta

Tue, 18 Oct 2011 08:36:26 GMT
The beta version of WebMatrix 2 was put out for public consumption around the time of the //build/ conference in September. Very nice.

However, installing WebMatrix 2 beta makes it harder to install (reinstall) the WebMatrix 1 (actually, 1.1), should you ever need to do that. (I did recently.) If you go to the download page and try to install the non-beta version of WebMatrix you won't get it, even if you carefully and explicitly don't choose the beta download option. You'll be offered WebMatrix 2 beta only.

Turns out this is due to the installer. WebMatrix is installed via Web Platform Installer (WebPI). When you install the Beta release, you first get an updated version of WebPI, and the updated version of WebPI knows only about the beta version of WebMatrix 2.

Anyway, long story short, if you've instaslled WebMatrix 2 Beta but for some reason need to reinstalled WebMatrix 1, you need to uninstall WebPI.

(Thanks to Chris Sfanos and his WebMatrix expertise for sorting this one out for me.)