Tuesday, 19 October 2010
04:50 PM
I noted last time that we approached the documentation for WebMatrix and ASP.NET Web page (Razor) a bit differently. This was in part due to the target audience — Razor is aimed at folks who are not already .NET-type developers. Among ways in which the docs are different is that we did not create (or not yet, to be precise) the familiar MSDN-based API reference:
Cranking up the MSDN machine is a big deal, and we often don't do it for beta releases of non-mainstream (aka OOB or "out-of-band") projects. In this case in particular, we also felt like the traditional MSDN API ref wasn't really the best solution for this specific target audience.
So instead we created the ASP.NET API QuickReference. Rather than the one-member-per-article approach of MSDN, this is just a big table that lists what were deemed to be the most interesting methods of (most of) the helpers. We collapsed syntax, descriptions, and examples into single table cells:
Naturally, there are some limitations here.[1] One is that it's selective — although it does describe all the helpers that the target audience is apt to need, it does not show every member, and especially, it does not show every parameter/signature for every method. In simpler terms, it's incomplete.
If you want more information, what are your options, assuming you don't want to wait until the real MSDN API reference becomes available? Well, you can do what I've been doing, which is to use the magic of .NET to have the Razor assemblies cough up information on themselves. I have two suggestions for you.
Using the Object Browser
If you have Visual Studio 2010 available, you can create a project and add a reference to the ASP.NET Web Pages assemblies, and then use the Object Browser to poke around and see what sorts of interesting methods and properties and events the helpers have. Like this:
In Solution Explorer, right-click References and then click Add Reference.
In the Add Reference dialog box, click the Browse tab and browse to where the assemblies are installed (C:\Program Files\Microsoft ASP.NET\ASP.NET Web Pages\v1.0\Assemblies) and then click OK:
Open the Object Browser (Ctrl+Alt+J), browse to (e.g.) the System.Web.Helpers assembly, then drill down to the helper and method that you're interested in:
Using .NET Reflector
The object browser is easy, but isn't an option if you don't have Visual Studio. Plus it lacks (based on my limited familiarity with it) certain handy features, like being able to copy information about the members in a class.[2] But there are other tools. One that I found useful is Redgate's .NET Reflector, which has a free version. For the purposes I was after, it works a lot like the object browser, to wit, you choose File > Open and then browse to where the assemblies are you want:
As in the object browser, you select the assembly and namespace you want. Then right-click and select Disassemble:
Then in the Disassembler window, scroll down and click Expand Types.
And presto, complete member lists for the types, in a window you can copy from if you want:
As a kind of experiment, I used this method to create another, slightly different API Quick Reference. Basically, I took the output from .NET Reflector, threw out the types and members labeled private or internal, and stuck the rest into a table. I borrowed some descriptions from the existing quick ref and did a little formatting-type cleanup. If you're curious, you can see the resulting document. Here's a wee preview to show you how it's different from the existing reference:
What I liked about this was that you can get some of the details like default values by just looking at the signatures. Obviously, many of these APIs need examples to really clarify what they're about. Some are in the Quick Ref on the asp.net site, and more will appear in the MSDN API ref when that is published.
[categories]
aspnet, webmatrix, writing
|
link
|