The Silverlight 2 documentation includes many live samples. However, you can access these samples only from a topic with a “run this sample” link. The best way to find the samples in the Silverlight 2 documentation is to do a search on “run this sample”.
For the Silverlight 3 beta release, we have improved this situation by providing a documentation sample browser. In the SL3 beta documentation, each “run this sample” link opens the sample browser to the appropriate sample and highlights the current sample in a navigation pane. You can then browse to related samples or explore samples in other categories.
Each sample includes one or more links back to the documentation that references the sample. This enables you read the context in which the sample is used. In most cases, you can also read the relevant snippets of the sample source code. In some cases, you can also download a full Visual Studio project.
Please note that this is a beta release for both the documentation and the sample browser. We are planning several improvements in the coming months, but for now, you will encounter some rough edges. In particular, the sample browser currently supports Internet Explorer only, although we plan to make it work for all supported browsers by the SL3 RTW release. Additionally, the sample browser will sometimes stop working correctly, but you can get it working again by clicking in the address bar and pressing ENTER.
Comparison to the Silverlight Toolkit Sample Browser
Some of you may be familiar with the Silverlight Toolkit sample browser, which provides several additional features that we will consider for the documentation sample browser.
The documentation sample browser has some special requirements that prevent us from simply leveraging the sample browser code available in the Toolkit source code. In particular, each sample in the Silverlight documentation is a separate application, so the documentation sample browser uses a multi-frame approach rather than the integrated approach used by the Toolkit sample browser. This prevents us from providing a built-in full-screen option (although you can use the browser full-screen mode instead). It also prevents us from providing an out-of-browser experience.
Perhaps most interestingly, the Toolkit sample browser provides an integrated source-code viewer. This is something that we are definitely interested in for the documentation sample browser, but it is low-priority, since the relevant source code for most samples is available in the documentation. In the documentation sample browser, just click a link under Related Documentation, and the relevant topic will open in a new window.
The multi-frame approach used by the documentation sample browser introduces some interesting challenges that require creative solutions. Each frame in the documentation sample browser hosts a separate Silverlight application: one for the navigation pane, one for the sample header, and one for the sample itself. These separate applications communicate with one another through the HTML DOM Bridge and through the Silverlight 3 local messaging feature. As you can perhaps imagine, there are some complexities around load ordering and synchronization. Some of you will be interested in learning about these solutions, so we are planning to release the full source code of the documentation sample browser by the SL3 RTW release.
If you have opinions about various potential features of the documentation sample browser, please send us your feedback. Your comments will help us prioritize our future work so that we can make the sample browser as useful as possible.
Enjoy the samples!