Longhorn SDK Annotations

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.

O'Reilly's Role

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.

Getting Started

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:

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.

Anatomy of an Annotation Source

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:

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:

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.)

The Client-Side Component

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.

Conclusion

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.