ASP.NET Silverlight Server Control

Introduction

The ASP.NET System.Web.UI.SilverlightControls.Silverlight server control enables you to provide a Rich Internet Application (RIA) experience with your Web application, beyond what can be done with AJAX and DHTML alone. By using this control, you can integrate XAML and any supporting code (a managed-code assembly, a managed dynamic-language script module, or client JavaScript libraries) into your Web site.

The Silverlight server control uses XAML in combination with the Silverlight plug-in and the JavaScript Sys.UI.Silverlight.Control class. Unlike the MediaPlayer server control, the Silverlight server control is generic and is not designed only to manage media files.

You can use managed code to handle interaction with the Silverlight server control (a Silverlight 2 scenario). Alternatively, you can use JavaScript to create a JavaScript type to handle the interaction (a Silverlight 1.0 scenario, supported in Silverlight 2). To use the JavaScript type, you reference the type by using the ScriptType property of the server control. Then in the Scripts collection of the ScriptManager control, you add a reference to the script library that contains the type definition.

This topic provides the following about the Silverlight server control:

• Silverlight server control syntax.

• Using the Silverlight server control.

• Extending the Silverlight server control.

• Creating a class in JavaScript to use with the Silverlight server control.

• Creating code in a managed-code assembly to use with the Silverlight server control.

To be able to work with the Silverlight control, you need:

• The .NET Framework version 3.5.

• The Silverlight plug-in. The plug-in can be installed the first time that you run a Silverlight application.

• The Silverlight 2 Beta 1 SDK release.

• Visual Studio 2008, if you want to work with the Silverlight control in the Visual Studio designer.

Using the Silverlight Server Control

The following example shows the markup for a Silverlight server control that defines a simple calculator in XAML. The logic for interacting with the XAML is defined in a separate JavaScript class. The Silverlight server control references the file that contains the XAML markup (Calculator.xaml). You can also see how to reference the client-script library (Calculator.js) for the calculator code, and how to reference the JavaScript class (Custom.Calculator).

<asp:ScriptManager ID="ScriptManager1" runat="server">
  <Scripts>
    <asp:ScriptReference Name="SilverlightControl.js"
         Assembly="System.Web.Silverlight"/>    
    <asp:ScriptReference Path="calculator.js" />
  </Scripts>
</asp:ScriptManager>

<asp:Silverlight runat="server" ID="Silverlight1" 
    Height="340" 
    Width="320" 
    Source="../calculator.xaml" 
    ScriptType="Custom.Calculator" 
    OnPluginError="onXamlError">

In its basic form, the Silverlight server control provides a JavaScript type that includes members such as the onPluginLoaded method and the onPluginError method. The Silverlight server control references a XAML file through the Source property. The code for interacting with the XAML can be in a managed-code assembly or in a client JavaScript library (.js file).

Extending the Silverlight Server Control

The Silverlight server control is a simple control that provides the basics for XAML as well as supporting the Silverlight installation logic for you. There are no members that you can use to set properties or bind event handlers of the supporting class (for either a managed-code assembly or in unmanaged client JavaScript).

In some cases, you might want to create a class that inherits from the Silverlight control and then expose your own members, much like the implementation of the MediaPlayer control.

Creating a Class in JavaScript to Use with the Silverlight Server Control

To create a class in JavaScript to use with the Silverlight server control, you can use the Microsoft ASP.NET AJAX Extensions client framework and create a type that derives from the Sys.UI.Silverlight.Control base class. This enables you to attach event handlers to XAML DOM elements during the pluginLoadedevent. This event is raised when the XAML DOM is loaded and ready. The framework provides error handling for your custom type and provides default cleanup of resources (such as attached events) in its PluginDispose method.

The following example shows a client class that derives from the Control base class.

Type.registerNamespace("Custom");

Custom.Calculator = function(element) {
  Custom.Calculator.initializeBase(this, [element]);
    // Define private fields
    this._n0 = null;
    
    // Additional set up follows.
  }

Custom.Calculator.prototype = {
  onPluginLoaded : function(args) { 
    Custom.Calculator.callBaseMethod(this, 'onPluginLoaded', [args]);
    
    // Get the specific component's XAML element fields.
    this._initializeFields(this.get_element());
    
    // Additional initialization and event hookup. Note that these will 
    //  be automatically removed in dispose in the base class.
    var f = Function.createDelegate(this, this._numClick);
    this.addEventListener(this._n0, "mouseLeftButtonUp", f);
    
    // Additional set up follows ..
  },
  _initializeFields: function(slhost) {
    var host = slhost.content;
    this._n0 = host.findName("n0");
    
    // Additional set up follows ..
   }
  // Additional members follow ..
 }
Custom.Calculator.registerClass('Custom.Calculator', 
    Sys.UI.Silverlight.Control);

The following example shows the complete calculator, written in JavaScript.

Run an example of this feature.

Creating Code in a Managed-Code Assembly to Use with the Silverlight Server Control

A XAML file can reference code written in a managed assembly by using the x:Class attribute. Event handlers can be attached by using attributes in XAML. You can create a Silverlight project in tools such as Visual Studio 2008, in which you can create XAML and a managed-code assembly. These outputs can be referenced in the Silverlight server control.

The following example shows the contents of a XAML element that references a managed-code assembly.

<Canvas x:Name="parentCanvas"
  xmlns="http://schemas.microsoft.com/client/2007" 
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
  Loaded="OnPageLoaded" 
  x:Class="CustomClass;assembly=CustomAssembly.dll"
  Width="640" 
  Height="480" 
  Background="White" >

You can reference this XAML file through the Source property of the Silverlight server control. You must also make sure that the Version property is set appropriately. The following example shows how to do this. Although the XAML that is downloaded references the managed code, the framework generates a client base Sys.UI.Silverlight.Control instance. This lets you provide additional JavaScript interaction in a manner consistent with the Microsoft ASP.NET AJAX Extensions model.

The following example shows a Silverlight server control that includes a version number and a reference to a .xap file. The ScriptManager control in the example references a JavaScript code file. The code file is assumed to include a JavaScript class that derives from Control.

<asp:ScriptManager ID="ScriptManager1" runat="server">
</asp:ScriptManager>

<asp:Silverlight runat="server" ID="Silverlight1" 
  Height="340" 
  Width="320" 
  Source="calculator_managed.xap" 
  Version="2.0" 
  OnPluginError="onPluginError">

The following example shows the Silverlight control being used with a managed-code assembly.

Run an example of this feature.

This topic is ASP.NET 3.5 Extensions pre-release documentation and is unsupported by Microsoft. Blank topics are included as placeholders and existing content is subject to change in future releases. To provide feedback or ask questions about the release, please go to the ASP.NET 3.5 Extensions forums.