Silverlight 3 Tutorial - Introduction

Krzysztof Mossakowski

Tutorials

Demonstrated issues:

Silverlight Application
Silverlight Navigation Application
- Frame and Pages
Hosting a Silverlight application in the ASP.NET Web application

Prerequisities:

Visual Studio 2008 SP1
Silverlight 3 Tools for Visual Studio 2008 SP1

Steps:

Create a new Silverlight Application in Visual Studio 2008, name it 'FirstApp':

Do not create a hosting ASP.NET Web site for this application, let's start from a simple application embedded in a static HTML page:

Investigate the project created by Visual Studio:

Note similarities with a WPF application - we have an application object of Application class and a page.

The page is a UserControl object, which is set as the displayed content in response for the Startup event of the application:

this.Startup += this.Application_Startup;

private void Application_Startup(object sender, StartupEventArgs e)

    this.RootVisual = new MainPage();

Note a special way of handling application unhandled exceptions:

private void Application_UnhandledException(object sender, ApplicationUnhandledExceptionEventArgs e)

    // If the app is running outside of the debugger then report the exception using

    // the browser's exception mechanism. On IE this will display it a yellow alert

    // icon in the status bar and Firefox will display a script error.

    if (!System.Diagnostics.Debugger.IsAttached)

        // NOTE: This will allow the application to continue running after an exception has been thrown

        // but not handled.

        // For production applications this error handling should be replaced with something that will

        // report the error to the website and stop the application.

        e.Handled = true;

        Deployment.Current.Dispatcher.BeginInvoke(delegate { ReportErrorToDOM(e); });

private void ReportErrorToDOM(ApplicationUnhandledExceptionEventArgs e)

try

        string errorMsg = e.ExceptionObject.Message + e.ExceptionObject.StackTrace;

        errorMsg = errorMsg.Replace('"', '\'').Replace("\r\n", @"\n");

        System.Windows.Browser.HtmlPage.Window.Eval("throw new Error(\"Unhandled Error in Silverlight Application " + errorMsg + "\");");

    catch (Exception)

Add some content to the MainPage.xaml file, e.g.:

<UserControl

    x:Class="FirstApp.MainPage"

    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"

    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"

    mc:Ignorable="d"

    d:DesignWidth="640" d:DesignHeight="480"

    <Border

        BorderBrush="Black"

        BorderThickness="1"

        CornerRadius="5"

        Margin="5"

        Background="Beige"

        <TextBlock

            Text="Hello from FirstApp!"

            FontSize="24"

            FontWeight="Bold"

            HorizontalAlignment="Center"

            VerticalAlignment="Center"

/>

    </Border>

</UserControl>

There is no visual designer nor a "live" preview for Silverlight XAML files in the Visual Studio 2008. Such designer is built in the Microsoft Expression Blend application and will be available in the Visual Studio 2010.

Compile and run the project.

The default Web browser starts and displays the application:

Note the address displayed for the application:
file:///d:/PW/tutorials/silverlight/3/Introduction/First/FirstApp/Bin/Debug/TestPage.html
This is the address of a test HTML page generated automatically by Visual Studio.

It's worth taking a look at the HTML page. It contains HTML code responsible for hosting Silverlight object:

<body>

    <form id="form1" runat="server" style="height: 100%">

    <div id="silverlightControlHost">

        <object data="data:application/x-silverlight-2," 
               type="application/x-silverlight-2"

                width="100%" height="100%">

            <param name="source" value="FirstApp.xap" />

            <param name="onError" value="onSilverlightError" />

            <param name="background" value="white" />

            <param name="minRuntimeVersion" value="3.0.40624.0" />

            <param name="autoUpgrade" value="true" />

            <a href="http://go.microsoft.com/fwlink/?LinkID=149156&v=3.0.40624.0"

               style="text-decoration: none">

                <img src="http://go.microsoft.com/fwlink/?LinkId=108181" 
                    alt="Get Microsoft Silverlight"

                     style="border-style: none" />

            </a>

        </object>

        <iframe id="_sl_historyFrame"

                style="visibility: hidden; height: 0px; width: 0px; border: 0px">

       </iframe>

    </div>

    </form>

</body>

The image taken from the go.microsoft.com server is responsible for longer time of the first loading of the application when you can notice the "Waiting for go.microsoft.com" text in the browser's status bar (next time the image is taken from the browser's cache). When the user has no Silverlight installed (or a version that is older than the version required by the application), this image is displayed as a link to a place where the Silverlight plugin can be downloaded and automatically installed in the browser.

The output directory of the project contains 5 files:
AppManifest.xml, FirstApp.dll, FirstApp.pdb, FirstApp.xap, TestPage.html
Analysing the code of the TestPage.html file reveals that the only file used by the page is FirstApp.xap. (You can test it by deleting the rest files - the page will still work properly.)
The FirstApp.xap file is a .zip file which contains two of the rest files: AppManifest.xaml and FirstApp.dll.

The AppManifest.xaml file determines the starting point of the application:

<Deployment

    xmlns="http://schemas.microsoft.com/client/2007/deployment"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    EntryPointAssembly="FirstApp"

    EntryPointType="FirstApp.App"

    RuntimeVersion="3.0.40624.0"

  <Deployment.Parts>

    <AssemblyPart x:Name="FirstApp" Source="FirstApp.dll" />

  </Deployment.Parts>

</Deployment>

Note the name of the assembly and the name of the main class of the application. Note also the version number of the runtime.

The FirstApp.dll file contains the compiled project.

Add to the solution a new project of the Silverlight Navigation Application type, name it 'FirstNavApp':

As for the previous project, do not generate a host Web site.

This project is more complicated than the previous one. There are more files and more code automatically generated. Set the project as StartUp (right click on the project in the solution explorer and "Set as StartUp Project), compile it and run.

The project is made of pages displayed in a frame. The frame is defined in the MainPage.xaml file:

<Grid x:Name="LayoutRoot" Style="{StaticResource LayoutRootGridStyle}">

    <Border x:Name="ContentBorder" Style="{StaticResource ContentBorderStyle}">

        <navigation:Frame x:Name="ContentFrame" Style="{StaticResource ContentFrameStyle}"

                          Source="/Home" Navigated="ContentFrame_Navigated"

                          NavigationFailed="ContentFrame_NavigationFailed">

            <navigation:Frame.UriMapper>

              <uriMapper:UriMapper>

                <uriMapper:UriMapping Uri="" MappedUri="/Views/Home.xaml"/>

                <uriMapper:UriMapping Uri="/{pageName}" MappedUri="/Views/{pageName}.xaml"/>

              </uriMapper:UriMapper>

            </navigation:Frame.UriMapper>

        </navigation:Frame>

    </Border>

Pages are defined in files stored in the View folder, e.g the Home page is in the Views/Home.xaml file:

<navigation:Page x:Class="FirstNavApp.Home"

    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"

    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"

    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"

    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"

    xmlns:navigation="clr-namespace:System.Windows.Controls;assembly=System.Windows.Controls.Navigation"

    mc:Ignorable="d" d:DesignWidth="640" d:DesignHeight="480"

    Title="Home"

    Style="{StaticResource PageStyle}">

    <Grid x:Name="LayoutRoot">

        <ScrollViewer x:Name="PageScrollViewer" Style="{StaticResource PageScrollViewerStyle}">

            <StackPanel x:Name="ContentStackPanel">

                <TextBlock x:Name="HeaderText" Style="{StaticResource HeaderTextStyle}"

                                   Text="Home"/>

                <TextBlock x:Name="ContentText" Style="{StaticResource ContentTextStyle}"

                                   Text="Home page content"/>

            </StackPanel>

        </ScrollViewer>

    </Grid>

</navigation:Page>

To understand the concept of the frame and pages, add a new page to the application.

Add to the Views folder a new Silverlight Page, name it MyPage.xaml:

Add a button to the new page:

<Grid x:Name="LayoutRoot">

    <Button

        Content="Do something"

        Click="Button_Click"/>

</Grid>

and in response for its Click event, change its content:

private void Button_Click(object sender, RoutedEventArgs e)

    (sender as Button).Content = "Something has been done!";

Run the application and note that nothing has changed - the new page is not displayed anywhere. We must add a link to the page manually modifying the code in the MainPage.xaml file:

<Border x:Name="LinksBorder" Style="{StaticResource LinksBorderStyle}">

    <StackPanel x:Name="LinksStackPanel" Style="{StaticResource LinksStackPanelStyle}">

        <HyperlinkButton x:Name="Link1" Style="{StaticResource LinkStyle}"

                         NavigateUri="/Home" TargetName="ContentFrame" Content="home"/>

        <Rectangle x:Name="Divider1" Style="{StaticResource DividerStyle}"/>

        <HyperlinkButton x:Name="Link2" Style="{StaticResource LinkStyle}"

                         NavigateUri="/About" TargetName="ContentFrame" Content="about"/>

        <Rectangle x:Name="Divider2" Style="{StaticResource DividerStyle}"/>

        <HyperlinkButton x:Name="Lin32" Style="{StaticResource LinkStyle}"

                         NavigateUri="/MyPage" TargetName="ContentFrame" Content="my page"/>

    </StackPanel>

</Border>

There is no need to modify the navigation:Frame control placed in the same file, because it is defined to use a generic mapping of URI addresses, which will work for our new page:

<navigation:Frame x:Name="ContentFrame" Style="{StaticResource ContentFrameStyle}"

                  Source="/Home" Navigated="ContentFrame_Navigated"

                  NavigationFailed="ContentFrame_NavigationFailed">

    <navigation:Frame.UriMapper>

      <uriMapper:UriMapper>

        <uriMapper:UriMapping Uri="" MappedUri="/Views/Home.xaml"/>

        <uriMapper:UriMapping Uri="/{pageName}" MappedUri="/Views/{pageName}.xaml"/>

      </uriMapper:UriMapper>

    </navigation:Frame.UriMapper>

</navigation:Frame>

Compile and run the application, test if everything works:

To test the error page, make a mistake in the code responsing for the Click event of the button:

private void Button_Click(object sender, RoutedEventArgs e)

    sender = null;

    (sender as Button).Content = "Something has been done!";

The popup window which displays information about the error is quite impresive:

It uses the new, introduced in Silverlight 3, ChildWindow control.

The error window appears in response for the UnhandledException of the Application object. This event can be used to catch exception not handled in a proper way.:

private void Application_UnhandledException(object sender, ApplicationUnhandledExceptionEventArgs e)

    // If the app is running outside of the debugger then report the exception using

    // a ChildWindow control.

    if (!System.Diagnostics.Debugger.IsAttached)

        // NOTE: This will allow the application to continue running after an exception has been thrown

        // but not handled.

        // For production applications this error handling should be replaced with something that will

        // report the error to the website and stop the application.

        e.Handled = true;

        ChildWindow errorWin = new ErrorWindow(e.ExceptionObject);

        errorWin.Show();

Probably the most important aspect of using the Frame and Page controls is integration of the application with the browser. Each page in the application has its own address, which allows to integrate with the browser's history:

Close the solution and create a new one, containing a Silverlight application which will be hosted in a Web site:
- Allow Visual Studio to create a host Web site. Choose the ASP.NET Web Application Project as the project type (ASP.NET Web Site has some very important limitations):
- According to our choices, Visual Studio has created two projects:
- Add some content to the MainPage.xaml file, e.g.:
```
<UserControl 
```
```
    x:Class="SecondApp.MainPage"
```
```
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
```
```
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
```
```
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 
```
```
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
```
```
    mc:Ignorable="d" 
```
```
    d:DesignWidth="640" d:DesignHeight="480"
```
```
    >
```
```
    <Border
```
```
        BorderBrush="Black"
```
```
        BorderThickness="1"
```
```
        CornerRadius="5"
```
```
        Margin="5"
```
```
        Background="LightBlue"
```
```
        >
```
```
        <TextBlock
```
```
            Text="Hello from SecondApp!"
```
```
            FontSize="24"
```
```
            FontWeight="Bold"
```
```
            HorizontalAlignment="Center"
```
```
            VerticalAlignment="Center"
```
```
            />
```
```
    </Border>
```
```
</UserControl>
```
- Compile and run (note that the Web application project is set as StartUp):
  
  Note the address - the ASP.NET Development Server has been run (as usually for Web applications not configured to run in IIS) and the Silverlight application is hosted on the SecondAppTestPage.aspx page. The code in the SecondAppTestPage.aspx and SecondAppTestPage.html is exactly the same.
- The Silverlight object placed on the HTML or ASP.NET page points its source to the file in the ClientBin folder:
```
<param name="source" value="ClientBin/SecondApp.xap"/>
```
  The magic of copying the output .xap file to the ClientBin folder is configured in the properties of the SecondApp.Web project:

[Source code]