.comment-link {margin-left:.6em;}

I Hate Linux

Monday, September 17, 2007

Windows Home Server Controls Documentation

I've got a little problem... I tend to do weird things when I'm bored (which isn't a common state) and given the amount of free time I've had over the last number of months my level of boredom has steadily increased and avenues for productive release decreased.

What is my latest weird act? Documenting a publicly visible API on Windows Home Server that Microsoft has yet to release public info for.

I love Windows Home Server and am thrilled to be able to program against it... only from time to time I run into a little thing which makes me yell a bit, shake my fist angrily in the general direction of Redmond, and then get back to coding. One of those items has been the complete lack of intellisense support and other in-depth documentation other than what limited info is available on the official documentation site.

So as to fix this... I started using reflection to look through the public interfaces of some of the classes within the HomeServerControls assembly, do some general testing to figure out how they work and take what I learn to create XML comments for a new project (also named HomeServerControls) and output the XML comments separately.

There's a lot in there and some pretty crazy things being done and I've only been able to document significant parts of a few classes which are:

  • Microsoft.HomeServer.Controls.ClientCommunicator
  • Microsoft.HomeServer.Controls.ConsoleServices
  • Microsoft.HomeServer.Controls.ConsoleSubForm
  • Microsoft.HomeServer.Controls.ITabExtender
  • Microsoft.HomeServer.Controls.QMessageBox

Know more about something in there than I do? I'd love to hear about it.

The XML file is available here:

Wanting to make the documentation a little more useable... I've also use built a compiled HTML file (which takes a full 3.5 minutes to build) and just as soon as I get SandCastle to like me better and build a web site that I can successfully deploy and run on my sever this same info will be available in an online web form as well.

Download the CHM file here:

If you think this is a pretty weird and crazy thing... wait until you see the other little WHS project I'm working on so as to make developers job a little easier. That though I think I'll delay until I get my hands on the RTM bits where it will be a little more useful.

Labels: ,

2 Comments:

  • Remember, just because an assembly identifies something as "public" does not mean it is "documented" and intended for use by 3rd parties. Using undocumented APIs is a risky proposition because they can change at any time (e.g. a Windows Update) breaking your Add-in.

    I believe Microsoft didn't document these things because they did not design them to be used by 3rd parties.

    By Anonymous Anonymous, at 7:22 AM  

  • I agree that these things could change at any time and may not have been intended for public consumption. At the same time though, given the support thus far for the use of the controls in the assembly in question and the usefulness of some of the methods/classes within I'm more than willing to risk deprecation in V2 or worse sometime between now and then via an official update.

    Worst case I'm hoping that this encourages the expansion of the available official documentation and/or some clear lines of what is supported and what we are encouraged to use.

    By Blogger Brendan, at 11:02 AM  

Post a Comment

<< Home