On Monday October 27, 2003 at the Professional Developers Conference, Microsoft unveiled its vision for the future of Windows: the core features that will be added to the Windows platform over the next few years were shown in public for the first time. An impressive number of new technologies was revealed. We saw Indigo, the new technology for building service-oriented systems. There was Yukon, the next version of SQL Server. The forthcoming Whidbey versions of Visual Studio .NET and the .NET Framework were presented. And of course, the developer preview of Longhorn, the next version of Windows, was shown, along with the new Aero look and feel.
If you saw the presentation at the PDC by Eric Rudder (Microsoft Senior Vice President of Servers and Tools), you saw that Microsoft has added a new experimental facility to the MSDN library. The Longhorn SDK can display extra content from external sources alongside Microsoft's own documentation. At the PDC, Microsoft only showed one part of this feature: the discussion forums associated with each MSDN page. However, you can also choose to view annotations from selected external sources.
Working closely with Microsoft, O'Reilly has seized upon this new feature to deliver its own, independently written commentaries on selected Longhorn SDK documentation entries via an RSS feed hosted at oreilly.com. The first of these became available at PDC 2003. In the coming weeks, O'Reilly will publish a series of articles on ONDotNet devoted to Longhorn software development with the WinFX API. And as these articles are published--often drawing on their content--O'Reilly will provide additional annotations to further enhance the content provided by MSDN.
O'Reilly is the first to provide a Microsoft-recommended source of annotations through this new mechanism. If you want to see these in your web browser, you will need to perform an installation step on your system. (The MSDN Annotations system relies on a small piece of client-side code being present.) This can be obtained from the Microsoft lab web site.
Once you have installed the annotation component, you will find that an extra section appears at the bottom of any page in the online Longhorn SDK documentation:
|
Related Reading 
Mastering Visual Studio .NET |
http://longhorn.msdn.microsoft.com/
Note that annotations currently work only on the web-based version of the SDK. You will not see them on a locally installed copy of the SDK documentation. They also require version 1.1 of the .NET Framework to be installed on your machine, and they are only supported when using Internet Explorer. (This is because, as we will see shortly, most of the work is done on the client side.)
At the bottom of each page, you should now see two extra sections. One is labeled "Microsoft public discussion," and provides a forum to which anyone can post questions or comments. The second, "Discussion from other sources," will contain annotations from sources you have chosen to view. By default, your system will not be subscribed to any external sources. To change that, click on the Subscriptions link at the right of the "Discussion from other sources" section. This will open a Discussion Services dialog, enabling you to choose the external sources to which you subscribe. O'Reilly & Associates, Inc. will be listed as one of the recommended services.
We haven't annotated everything in the Longhorn SDK -- it's a little large for that -- so you will not find O'Reilly annotations on every page. But to see an example, here's a page with an annotation.
When you subscribe to a source of annotations, you are simply subscribing to an RSS feed. You can see the raw RSS for O'Reilly's feed here:
www.oreillynet.com/pub/q/annotation.xml?x-mimetype=text/xml.
Although this is just a normal RSS 2.0 feed, be aware that it will look slightly out of place if you subscribe to it via a normal RSS aggregator -- these annotations are written to be read in the context of the article in which they appear, and won't necessarily make sense when read in isolation. The feed is designed to be consumed by the MSDN annotation system.
Each <item> element in the feed contains a single annotation. The
annotation system needs to be told which page in the SDK each item annotates,
which we do by linking to the SDK page; we simply embed a normal HTML
<a> tag somewhere in the item's <description> element. The
<description> element itself must be HTML-encoded (including the
<a> tag used to associate it with the article). Here is a very simple
example:
<item>
<title>Widths</title>
<description><p>This item annotates the <a
href="http://longhorn.msdn.microsoft.com/lhsdk/ref/ns/msavalon.windows
/c/frameworkelement/p/width.aspx"
>FrameworkElement.Width</a>
property.</p></description>
<link></link>
<dc:creator>Ian Griffiths, O'Reilly & Associates, Inc.</dc:creator>
<pubDate>Thu,23 Oct 2003 05:47:15 PST</pubDate>
</item>Once unencoded, the contents of the <description> element will appear as:
<p>This item annotates the
<a href="http://longhorn.msdn.microsoft.com/lhsdk/ref/ns/msavalon.windows
/c/frameworkelement/p/width.aspx">
FrameworkElement.Width</a> property.</p>This is the HTML that will be added to the MSDN page as an annotation. So the
<description> effectively serves two purposes: it both provides the content
for the annotation, and this content must also contain the <a> tag
indicating which page is to be annotated. (If you want to annotate a page
without having a visible link to the page, you can simply leave the contents of
the <a> tag empty. As long as the tag is present and has an appropriate
href attribute, it doesn't matter to the annotation system whether it contains
any visible content.)
The other elements in the <item> shown in this example are also used by
the annotation system. If you place a URL in the <link> element, that URL
will be used as the href for the <a> tag containing the article's title, so if the user clicks on the article title, they will be taken to that link.
(This is consistent with the behavior of most RSS aggregators.) The
<dc:creator> tag is used for the From heading. (The dc namespace
prefix should be associated with the Dublin Core namespace,
http://purl.org/dc/elements/1.1/ somewhere in the RSS document.)
Although the annotations appear as a part of the pages of Microsoft's site, they do not in fact pass through Microsoft's servers; all of the work is done on the client side (i.e., on your computer). There is a component that downloads and caches RSS feeds. The pages of the SDK site simply contain scripts that use this component to extract relevant annotations from those feeds as you browse the site.
This component is downloaded automatically by the browser; the HTML that
manages the annotations contains an <OBJECT> tag that fetches a .NET
component called RssCommentator.dll from Microsoft's web site. This enables
Microsoft to issue updates to the component without requiring you to reinstall
it. Given that all of the necessary client-side code is downloaded dynamically,
you might be wondering why you need to go through an installation process to
enable annotations. The reason is that the RssCommentator component needs to be
able to connect to all of your configured RSS feeds, and cache those feeds
locally, which requires a less restrictive set of permissions than code from
the Internet normally gets. When you "install" the client-side component, all
you are really doing is setting up your machine's security policy to enable the
component to run with the privileges it needs.
If you are curious about the workings of the client-side RSS component, you can see the cached copy of any annotation feeds you have subscribed to by looking in the Isolated Storage section of your user profile. (It will be somewhere under Documents and Settings\username\Local Settings\Application Data\IsolatedStorage. Isolated storage directory names are randomized for security, so the exact location will vary from machine to machine, but if you search for an MSDNAnnotations\Cache directory, you should find it.) The component stores a file called feedPreference.xml, containing the list of subscriptions, along with the date and time at which data was last fetched from the feed. The directory also contains a copy of the latest version of the feed downloaded from each subscription.
Note that the component typically only refreshes its cached feed every 24 hours. If you are experimenting with your own feeds, bear this in mind, as it means that any changes will take a while to appear.
The RssCommentator component provides a method that the hosting HTML code calls, which simply injects the appropriate HTML into a placeholder on the web page.
The component generates this HTML by feeding the RSS feed through an XSLT
transform to extract the <description> element from the appropriate
<item>. (There is also some JScript that unencodes the HTML, since this
is difficult to achieve with XSLT.)
This HTML extraction process ends up displaying whatever HTML is contained in
the feed item's <description> element. Since the system can use RSS feeds
from anywhere, there is a potential security hazard here; the author of the
RSS feed can generate whatever HTML she likes and this HTML will be displayed
in the browser. In most web applications, this behavior would be
regarded as a bug, as it is the kind of thing that can be exploited in certain
cross-site scripting attacks. However, in this case, this is the whole point of
the system: to allow external sources to add content to the main page. To
avoid security problems with potentially evil annotation sources, the
annotation system injects the external HTML into an IFRAME with a SECURITY
attribute set to restricted to ensure that the feed cannot play any dirty
tricks.
The MSDN annotation system is simple to exploit; all you need to do is supply an RSS feed. This also makes it very flexible. O'Reilly is providing annotations for general consumption, but you could easily use this technology within an organization to share notes with your colleagues, or even to keep your own personal notes on the SDK. The RSS feed is consumed and integrated into the page by the client PC, and not the main MSDN web site, so you can create and use annotation sources that are only available on your internal networks just as easily as you can make your annotations available to the whole world. All that is required is the ability to generate an RSS 2.0 feed.
Ian Griffiths is an independent consultant specializing in medical imaging applications and digital video. He also works as an instructor, teaching courses on .NET for DevelopMentor. Ian holds a degree in computer science from Cambridge University.
Return to ONDotnet.com
Copyright © 2009 O'Reilly Media, Inc.