Silverlight 4 Project Types part III – Silverlight Class Library

Last time, I looked at the Silverlight Navigation Application choice in Silverlight’s New Project wizard.  Next, I’d like to look at the Silverlight Class Library choice.  This is next on the list, out of the six different project types that are listed in the New Project wizard when you pick Silverlight as a project type.

Creating a Class Library

What exactly is a class library?  Well, simply put, it’s a library containing the implementation of one or more classes, implemented as a .NET DLL.  The basic idea is to move basic functionality that you’d likely use in more than one place out to a common library that one or more applications can use.

Silverlight lets us easily create a class library that we can then deploy with our actual Silverlight application.  The class library would contain code that we could invoke from our Silverlight application.

Let’s create a basic Silverlight Class Library using the New Project wizard.  Here’s what the dialog looks like:

Once you enter your project name and click OK, you see the dialog shown below.  This is where you get to decide which version of Silverlight you’re targeting. We saw something similar when creating a Silverlight Navigation Application.

For this project, we’ll stick with version 4 of Silverlight.  Keep in mind that if you author a Silverlight 4 project, the client will need to download Silverlight 4.  If you’re curious about what specific changes were made between Silverlight 3 and Silverlight 4, you can take a look at the article:  Ensuring that Your Silverlight Applications Work with Silverlight 4.  Note the “quirks” mode, in which the Silverlight 4 runtime can behave like Silverlight 3, to avoid breaking applications that targeted version 3.

Here’s what the solution looks like, after the wizard creates it.  Pretty simple.

The obvious question is: how is this different from a standard class library, that you might use with Win Forms or a WPF application?  If we just create a standard class library and then compare the project that we get with our Silverlight Class Library,we see basically the same thing–an empty DLL containing a single class.

One real difference that you’ll notice is related to which assembly references are included in the project by default.  Take a look at the projects shown below.  On the left is a standard C# class library.  On the right is a Silverlight Class Library.  (Nevermind that I’ve changed the default class from “Class1” to “Cat”.

You’ll see some similarities and some differences.  The main thing to remember is that the Silverlight project is built against the Silverlight versions of all of these libraries, rather than the standard .NET Framework versions.  You can convince yourself that there is more than one set installed one your machine by looking at the directory “C:\Program Files\Reference Assemblies\Microsoft\Framework”.  Make note of the .NET Framework and Silverlight sub-directories, with various version numbers under each sub-directory.  If you drill down into the sub-directories, you’ll see the actual .NET Framework or Silverlight DLLs.  There is a completely different set of DLLs for each platform.  As an example of the differences, note that there is a System.Windows.Forms.dll in the .NET Framework directories, but not in the Silverlight directories.

One other thing to remember is that even when you see the same file in both .NET Framework and Silverlight directories, the content of the file may be different.  For example, the Silverlight version of System.Core doesn’t include the System.Diagnostics namespace, because for Silverlight, it’s implemented in mscorlib instead.

There is another important difference between the different versions of the framework–the Silverlight versions are much smaller than their full .NET Framework counterparts.  Remember that Silverlight needs to be deployed over the web, so its copy of the Framework is considerably smaller than the full .NET Framework.  If you just look on a system that has both and compare total size of the files in each directory, you’ll see:

  • Version 3.0 of the .NET Framework = 84.4MB
  • Version 4.0 of the .NET Framework = 189MB
  • v3.0 of Silverlight framework = 20.6MB
  • v4.0 of Silverlight framework = 24.6MB

So the Silverlight runtime is only about 13% of the size of the full .NET 4.0 Framework.  Pretty amazing.

Adding Some Code

Now let’s add some functionality to our Silverlight class library.  We’ll create a Cat class that we can later use in our Silverlight application.  Here’s the implementation:

public class Cat
{
    public string Name { get; set; }
    public string Motto { get; set; }
    public uint NumLives { get; set; }

    public Cat() { NumLives = 9; }

    public void Die()
    {
        if (NumLives > 0)
            NumLives--;
        else
            throw new Exception("This cat is already dead");

        return;
    }
}

Building the Library

What do we get when we build the library that contains an implementation of our Cat class?  As it turns out, we just get a regular .NET DLL.  Let’s take a look at what shows up in our \bin directory:

Take a look at what’s in this directory.  Using the IL DASM tool (Intermediate Language Disassembler, which can be found in Windows 7 at C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin), crack open the DLL and you’ll see:

We could also look at the manifest for our Silverlight class library and compare it with manifest for a .NET 4.0 version.  If you did this, you’d see that the main difference is the version of mscorlib that they reference.  .NET 4.0 class libraries reference version 4.0.30319 of mscorlib and Silverlight 4 class libraries reference version 2.0.50727.  This could be because of the timing of the Silverlight and .NET 4.0 releases–Silverlight 4 just ended up using the version of mscorlib that shipped with .NET 3.5.  Or maybe it’s the case that Silverlight doesn’t make use of any of the new functionality added to .NET 4.0.

The bottom line here is that both class libraries (.NET 4.0 and Silverlight) are structurally the same–just .NET DLLs.  But they are not interchangeable, because they depend on different versions of various .NET DLLs.

Using Our Class

Now let’s actually use the class that we just created.  We’ll go back to our SilverlightClassLibrary1 solution and add a Silverlight Application project.  We leave the option turned on that automatically generates an ASP.NET Web Application project.

The solution now looks like this:

So we have a web project that loads our Silverlight application and we now want to change the application to make use of our class library.  Specifically, we’ll add some code that makes use of our Cat class.

On the MainPage control in the Silverlight application, we switch to the Events tab in the Properties window and double-click to the right of the Loaded event, to generate an event handler for Loaded.

Next, we add a reference to SilverlightClassLibrary1 in the Silverlight application.  In the Solution Explorer, we right-click the References folder in the SilverlightApplication1 project and select Add Reference.  Then we just click on the Project tab and select SilverlightClassLibrary1.  Now we see the class library show up as a reference in the Silverlight application.

Next, we open MainPage.xaml.cs in the code editor and add a using statement at the top for our class library.   Then we add code to the Loaded event to create a new instance of a Cat.  MainPage.xaml.cs now looks like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;
using SilverlightClassLibrary1;

namespace SilverlightApplication1
{
    public partial class MainPage : UserControl
    {
        Cat _garfield;

        public MainPage()
        {
            InitializeComponent();
        }

        private void UserControl_Loaded(object sender, RoutedEventArgs e)
        {
            _garfield = new Cat();
            _garfield.Name = "Garfield Arbuckle";
            _garfield.Motto = "Carpe Catnip";
        }
    }
}

Now let’s do something with our cat.  We go back to the design surface for the main window, add a new button, change the Content property to “Kill” and then double-click on the button to create an instance of the button’s Click event.  The code for the Click event is pretty simple–we just tell Garfield to die.

private void button1_Click(object sender, RoutedEventArgs e)
{
    _garfield.Die();
}

Now we’ve created a Cat and we have a button that lets us kill the cat (repeatedly).  As a next step, let’s just add a label on the main page that indicates how many lives the cat has left.  After you drag the label onto the design surface, it will look like this:

Let’s think about the best way to display the number of lives.  One way would be to add a line in button1_Click() that resets the label’s Content property every time we invoke the Die method.  But the drawback of this is that if we have other places in our code that cause our cats # lives to decrement (or increment), we’d have to remember to add code to all of those places to also update the label.  Better than manually updating the label would be to just “bind” it to Garfield’s NumLives property.  We’d like the label to change automatically whenever Garfield’s NumLives property changes.

Doing the data binding involves two main steps.  The first is to specify the binding of the label’s Content property.  We can set up the binding in XAML, specifying the binding Path, which indicates which property of the Cat object we want to bind this label to.  Below is the XAML for our main page, showing both the Button and the Label.  Note the value of the label’s Content property, with the binding path specified.

<Grid x:Name="LayoutRoot" Background="White">
    <Button Content="Kill" Height="23" HorizontalAlignment="Left" Margin="153,69,0,0" Name="button1" VerticalAlignment="Top" Width="75" Click="button1_Click" />
    <sdk:Label Height="28" HorizontalAlignment="Left" Margin="165,26,0,0" Name="label1" VerticalAlignment="Top" Width="63" Content="{Binding Path=NumLives}" />
</Grid>

(For more info on data binding in Silverlight, see this Silverlight Data Binding article in MSDN).

There’s one more thing that we have to do to get the binding to work.  We need to also specify the object that we’re binding to.  In our case, the object is the instance of the Cat that we created in the Load event–Garfield.  We do this by setting the DataContext property of our main page.  Really, we want to set the DataContext property of the Label.  But we can just set the data context for the whole page and then that data context will automatically get used for all controls on the page (if they don’t set their own data context).  This would be handy if we plan on adding other controls later that are also bound to Garfield.  We do this in our Loaded event:

private void UserControl_Loaded(object sender, RoutedEventArgs e)
{
    _garfield = new Cat();
    _garfield.Name = "Garfield Arbuckle";
    _garfield.Motto = "Carpe Catnip";

    // Set data context of main grid to be our Cat object
    LayoutRoot.DataContext = _garfield;
}

Now let’s try running our application.  When the Silverlight application starts up in a web browser, it looks like this:

Hey, that looks like success.  Our Label appears to have been bound to the NumLives property, because it’s showing that Garfield has 9 lives.

But what happens when we press the Kill button?  When I try it, nothing happens.  Inside the Cat object, the NumLives property should be decrementing.  And our Label should reflect the new value, since we set up the data binding.  But the label doesn’t appear to be changing.  Why not?

As it turns out, the NumLives property is changing internally whenever we kill Garfield.  But our client–the MainPage–is not being told that the property changed.  So the data binding isn’t fully functional and the label does not update.

We missed one small step when we set up data binding on our Cat object.  To properly bind to an object’s property, we need our Cat class to implement the INotifyPropertyChanged interface and to fire the PropertyChanged event whenever the NumLives property changes.  (For more info on INotifyPropertyChanged, see the MSDN documentation for INotifyPropertyChanged Interface).

To start with, we change our Cat class definition to indicate that we plan to implement the INotifyPropertyChanged interface.

public class Cat : INotifyPropertyChanged

If you try to build the project now, you’ll get an error telling you that you haven’t implemented the PropertyChanged event.  This is because when we inherit from INotifyPropertyChanged, we’re agreeing to a contract that says we’ll implement the interface’s methods.  In this case, it means that we’ll implement the PropertyChanged event.

The easiest way to implement the event is to right-click on INotifyPropertyChanged and select “Implement Interface”.  Then select “Implement Interface” again.

When you do that, you’ll get the following event declaration added to your code:

public event PropertyChangedEventHandler PropertyChanged;

Next, we need some code that will fire this event.  So we create a little method that we can use throughout our class.  I added the following code after the event declaration:

public void OnPropertyChanged(PropertyChangedEventArgs e)
{
    if (PropertyChanged != null)
        PropertyChanged(this, e);
}

Finally, we need to fire this event whenever the value of NumLives property changes.  We do this by invoking the OnPropertyChanged method that we just implemented.  We also have to pass the name of the property that is changing when we fire the event.  Here is the updated code for the NumLives property:

private uint _numLives;
public uint NumLives {
    get { return _numLives; }
    set
    {
        _numLives = value;
        OnPropertyChanged(new PropertyChangedEventArgs("NumLives"));
    }
}

That should be everything that we need to get the data binding to work.

For reference, here is the full source code listing for our Cat class:

using System;
using System.Net;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Ink;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;
using System.ComponentModel;

namespace SilverlightClassLibrary1
{
    public class Cat : INotifyPropertyChanged
    {
        public event PropertyChangedEventHandler PropertyChanged;
        public void OnPropertyChanged(PropertyChangedEventArgs e)
        {
            if (PropertyChanged != null)
                PropertyChanged(this, e);
        }

        public string Name { get; set; }
        public string Motto { get; set; }

        private uint _numLives;
        public uint NumLives {
            get { return _numLives; }
            set
            {
                _numLives = value;
                OnPropertyChanged(new PropertyChangedEventArgs("NumLives"));
            }
        }

        public Cat() { NumLives = 9; }

        public void Die()
        {
            if (NumLives > 0)
                NumLives--;
            else
                throw new Exception("This cat is already dead");

            return;
        }
    }
}

Killing the Cat

Finally, let’s run our application.  Now when we start up the application and run it in browser, we see the # lives indicator decrement whenever we click the Kill button.  Success!

Deployment

Let’s look at one more thing.  When we create and use a Silverlight class library and then deploy and run our Silverlight application, what is really going on?  We saw earlier that we’re creating a DLL.  But what actually happens to that DLL when some client hits the web page that hosts our Silverlight Application?

In Windows Explorer, let’s find the project directory and drill down until we see the ClientBin directory under the SilverlightApplication1.Web project.

In ClientBin dir, we see just one file: SilverlightApplication1.xap.  This is the XAP file that represents our Silverlight application and which gets deployed by the web server whenever a client loads the hosting ASP.NET page.

Let’s take a look inside the .xap file.  (Just rename the extension to .zip and double-click to open the .zip archive).  Here’s what we see:

The important components to notice are SilverlightApplication1.dll and SilverlightClassLibrary1.dll.  SilverlightApplication1.dll is the main DLL that contains our Silverlight application (MainPage class, derived from Silverlight UserControl).  SilverlightClassLibrary1.dll is the output of our SilverlightClassLibrary1 project–a DLL that contains our Cat object.  So we see that when our Silverlight application is deployed, the referenced class library is also deployed to the client, since it is included in the .xap file.

Finally

Now we’ve seen the main purpose of the Silverlight Class Library.  You can create a separate DLL that contains one or more classes that your Silverlight application is going to make use of, when running on the client.  Since the Silverlight application makes use of the class library, the class library is deployed to the client along with the main Silverlight application.

Advertisements

8 thoughts on “Silverlight 4 Project Types part III – Silverlight Class Library

  1. Pingback: Silverlight 4 Project Types part II – Silverlight Navigation Application « Sean’s Stuff

  2. Great description, thanks a lot. Are you planning to post a doc for the template “Silverlight Business Application” too?

  3. Just wanted to say thanks for this. Very interesting, well structures, and very easy to comprehend!

    I’ve been using Simple Silverlight Apps for a while now, but increasingly I’m looking at more complex implementations, and this really helps.

    Thanks again.

    Scott

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s