WindowsDevCenter.com
oreilly.comSafari Books Online.Conferences.

advertisement


AddThis Social Bookmark Button

Longhorn SDK Annotations

by Ian Griffiths, coauthor of .NET Windows Forms in a Nutshell and Mastering Visual Studio .NET
11/19/2003

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:

Related Reading

Mastering Visual Studio .NET
By Ian Griffiths, Jon Flanders, Chris Sells

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.

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:

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>&lt;p&gt;This item annotates the &lt;a 
    href="http://longhorn.msdn.microsoft.com/lhsdk/ref/ns/msavalon.windows
	/c/frameworkelement/p/width.aspx" 
    &gt;FrameworkElement.Width&lt;/a&gt; 
    property.&lt;/p&gt;</description>
  <link></link>
  <dc:creator>Ian Griffiths, O&apos;Reilly &amp; 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.)

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.


Return to ONDotnet.com