Channel 9 - Entries tagged with windows miscellaneous

Windows 7: Jump Lists

Arian Kulp — Wed, 09 Dec 2009 21:59:00 GMT

In this article, learn how to provide quick access to links and actions in your Windows 7 application by creating a Jump List.

Introduction

Windows 7 includes a wealth of new features for developers to take advantage of. This includes better rendering subsystems, new sensor and location API's, file libraries, federated search, and of course, the improved taskbar. My last article discussed the taskbar's ability to show custom previews and toolbar icons. This article focuses on Jump Lists - the replacement for notification area context menus.

To get started, download Visual Studio 2008 Express Edition or higher (C# or VB). Or, just go for Visual Studio 2010 Beta 2 - it's available now and well worth the download. All Express editions are free, and either 2008 or 2010 versions will work fine with this article's accompanying code.

What's a Jump List?

Jump Lists are a new concept in Windows 7 that allow developers to provide shortcuts for users right from their icon's context menu in the taskbar or Start menu. The shortcuts could be simple links to the documents folder or a library for a given application, or links back to the same application with a parameter passed to cause something to happen.

You can use this method in Live Messenger to change online status, display the new message window, or open web pages relating to the application. In the end, all of these are shortcuts. Shortcuts to URL's, or shortcuts back to the executable with an argument that causes some change to occur.

Windows API Code Pack

The Windows API Code Pack lets you take advantage of specific features of Windows Vista and Windows 7 that aren't available across the general framework, as well as native features that don't make sense in the common CLR used across all the supported configurations. Much of it consists of interop wrappers.

With the Code Pack, you get access to the new taskbar, Direct2D, DirectWrite, shell properties, Jump Lists, and more. The download also includes numerous sample code projects to get you started, so there's no excuse for avoiding new features!

Adding a Jump List

Adding a Jump List is easy. After you create the list itself, add items (shortcuts to files or folders, and tasks) to it. Then, you can choose how a user's recent or frequently used documents show up. Windows manages the user documents list, which relieves you of some work.

It's important to note that in order to make a change to the list, you have to recreate the entire thing. In other words, you'll replace the old list with a new one, rather than updating it.

Here's how the process works:

First, add the two required references from the Windows API Code Pack. You can either build a project and reference the DLL's, or directly add projects to your solution:

For convenience, you can add the namespaces to your using block to shorten typing later:

Visual Basic

Imports Microsoft.WindowsAPICodePack.Taskbar
Imports Microsoft.WindowsAPICodePack.Shell

Visual C#

using Microsoft.WindowsAPICodePack.Taskbar;
using Microsoft.WindowsAPICodePack.Shell;

The Microsoft.WindowsAPICodePack.Taskbar.JumpList class is where most of the action is. There's a static factory method, CreateJumpList, to create the list. Always start by calling this method, even if the application has created a Jump List in the past.

Visual Basic

Private Sub CreateJumpList()
    Dim jl As JumpList = JumpList.CreateJumpList()

Visual C#

private void CreateJumpList()
{
    JumpList jl = JumpList.CreateJumpList();

Next, you have several options, depending on what you need in the list. The most basic group is the list of files. You can choose to show Recent files, Frequent files, or neither-but you can't have both. If you don't make a choice here, you'll get Recent files automatically, as long as you have a registered file type.

Visual Basic

' Show user files: Recent, Frequent, or None
jl.KnownCategoryToDisplay = JumpListKnownCategoryType.Recent

Visual C#

// Show user files: Recent, Frequent, or None
jl.KnownCategoryToDisplay = JumpListKnownCategoryType.Recent;

Now you can add one or more custom categories of items. These are either folders or files. There are two very important rules:

The files/folders must exist! If necessary, check the path before adding the JumpListItem or you'll have a crash.
The files you add have to be of a type registered for your application, or you'll crash. Even worse: the exception won't occur on the line where you add it, but rather when you're done setting it up and try to refresh the list.

I've commented out the last item here, but you would use a JumpListItem for actual file system files, and JumpListLink objects for non-filesystem references. Again, don't add a JumpListItem unless you know that it exists and that you're registered to handle it.

Visual Basic

' Add my own links (nouns)
Dim catActions As New JumpListCustomCategory("Destinations")

catActions.AddJumpListItems(
    New JumpListLink(Environment.GetFolderPath(Environment.SpecialFolder.MyPictures), "My Pictures"), _
    New JumpListLink("http://blogs.msdn.com/coding4fun", "Visit Coding4Fun"), _
    New JumpListLink("http://code.msdn.microsoft.com/WindowsAPICodePack", "Windows API Code Pack"))
    'new JumpListItem(@"c:\Test1.c4f")

jl.AddCustomCategories(catActions)

Visual C#

// Add my own links (nouns)
JumpListCustomCategory catActions = new JumpListCustomCategory("Destinations");
catActions.AddJumpListItems(
    new JumpListLink(Environment.GetFolderPath(Environment.SpecialFolder.MyPictures), "My Pictures"),
    new JumpListLink("http://blogs.msdn.com/coding4fun", "Visit Coding4Fun"),
    new JumpListLink("http://code.msdn.microsoft.com/WindowsAPICodePack", "Windows API Code Pack")
    //new JumpListItem(@"c:\Test1.c4f")
    );

jl.AddCustomCategories( catActions);

You can add one or more tasks as links to system executables by using the AddUserTasks method of the JumpList object. Either create multiple objects and add them as a variable argument list, or add them one at a time, as I have here.

Visual Basic

' Add our user tasks (verbs)
jl.AddUserTasks(New JumpListLink(Path.Combine(systemFolder, "notepad.exe"), "Open Notepad") _
    With {.IconReference = New IconReference(Path.Combine(systemFolder, "notepad.exe"), 0)})

Visual C#

jl.AddUserTasks(new JumpListLink(Path.Combine(systemFolder, "notepad.exe"), "Open Notepad")
{
    IconReference = new IconReference(Path.Combine(systemFolder, "notepad.exe"), 0)
});

The IconReference property sets a pointer to the icon by referencing a DLL or EXE and then an index. Specifying an EXE with "0" is a good way to get the default icon for an executable that you are linking to.

You can add a separator to the list whenever you need to. The JumpListSeparator class represents a separator and can be added using the AddUserTasks call.

Visual Basic

jl.AddUserTasks(New JumpListSeparator())

Visual C#

jl.AddUserTasks(new JumpListSeparator());

The final links in our Jump List link back to our own executable. This is the most common use of Jump Lists. Just having a Recent/Frequent list is nice, but being able to trigger actions on the program itself-even when it's not started-is really handy. It's almost like a menu of command line options!

Commands in the list that invoke actions on the application itself involve calling the same application with different arguments. Remember that this isn't a true menu; you won't receive a Click event. Instead, you need to deal with an argument that's passed to you, even if you're already running.

Remember that the first argument on the command line is always the fully-qualified location to the running executable. The Arguments property lets you specify command line arguments that users don't directly see. For this sample application, I've defined three dummy arguments. If one of these is passed in, the application changes the background color of a label and indicates which argument it was.

Visual Basic

jl.AddUserTasks(New JumpListLink(Assembly.GetEntryAssembly().Location, "Action 1 (Green)") _
    With {.Arguments = "-1", .IconReference = New IconReference(Assembly.GetEntryAssembly().Location, 0)})

Visual C#

jl.AddUserTasks(new JumpListLink(Assembly.GetEntryAssembly().Location, "Action 1 (Green)")
{
    IconReference = new IconReference(Assembly.GetEntryAssembly().Location, 0),
    Arguments = "-1"
});

Invoking Self Actions

Windows Live Messenger uses Jump List actions for setting its own available status, and Windows Media Player has Jump List actions for skipping tracks or stopping. Likewise, you can add tasks that invoke actions on the same executable. If the application isn't running (remember that the Jump List is still available), this will cause it to be launched with the right argument. That's no problem. What if it's already running though?

The key is to find a way to pass messages between running instances. When the application starts up, check to see if another instance is running by using a Mutex (see Program.cs). If not, just use the arguments directly. If it is running, send the information about the parameter to the other instance and then quit. You could use temporary files, shared registry keys, or memory-mapped files. I find it easiest to use window messages.

You can find the code to create custom message ID's, to find the right window, and to send the message in my WindowsMessageHelper class.

From the main window code, override the WndProc method. This is the message loop for everything: mouse events, key events, window closing, and much more. Ensure that the message is something you need; otherwise pass it on to the underlying handler.

If the application is already running, post a message. If not, start as usual and watch your message queue. If you see a message of interest, take some action (in this case, just showing a message and changing a color).

The only other tricky thing to remember, is that you might startup as the only instance, and also have a parameter. For example, if the user clicked a task on the Jump List but the application isn't running. I take the easy way out and check for parameters after fully starting up and then post to my own queue if needed! That simplifies some of the logic anyway.

If you don't mind using the Microsoft.VisualBasic.ApplicationServices namespace from C#, then you can take advantage of the VB SingleInstance application mode. This removes the need for any explicit mutex, interop, or message passing. You can find some great information about this on Jocelyn Villaraza's excellent blog post.

Registering a File Type

Remember: unless you're registered as a file handler for the type, you can't show recent or frequent files or point to individual files. Register to be a file handler by creating a registry write operation to a key under HKEY_CLASSES.

The problem is, you can't write to the HKEY_CLASSES branch of the registry without proper permissions. By default, permission is only granted to the Administrators group. You really don't want to require that your application run under administrative privileges-that would be so Windows XP!

There are two alternatives: you could create a second application that can run elevated in order to perform the registration. This is how the samples do it with the Windows API Code Pack. A better method is to create a custom installer for the project and perform the association there. Installers always require administrative rights, and they only need to run once.

Creating the Installer

To create the installer, first add a setup project to your solution, following the usual steps. Then, from the Project types list, click Other Project Types | Setup and Deployment. In the Templates list, click Setup Project. Give it a name, then add it.

From Solution Explorer, right-click the setup project, then click the View | File Types menu command.

From the File Types list, right-click File Types on Target Machine, and then click Add File Type. Fill out the properties to name the file type and provide the extension. For Command, be sure to set it to the Primary output of the main project.

The file type should appear like the following in the File Types tab:

Now you have a registered file type. You still need to modify your setup project to copy the primary output (the EXE) to Program Files and customize any other properties in the setup project, but these are the special steps for file types. If in doubt, take a look at sample code to see how the Setup project is configured.

Conclusion

Working with the Windows API Code Pack makes it much easier to customize the taskbar and add Jump Lists, and gives you a great experience that really integrates well with the system. Download Visual Studio Express, grab the Windows API Code Pack, and start digging in.

The new features won't work on machines prior to Windows 7, so be sure to check that they're supported.

Creating a Utility Framework

ArianKulp — Tue, 14 Apr 2009 13:00:00 GMT

In this article I demonstrate how you can take advantage of a light application framework when creating simple utilities. Instead of working on lower-level plumbing, just create the code for whatever tool you need, and this framework can get you working faster.

Introduction

When you write small utilities, there's a certain amount of tedious repetitive work to get it up and going. Creating the main window, the tray icon (including the icon and context menu), and other common tasks just get in the way. In this article, I've created a reusable utility framework and will show you how to make use of it.

To run this code, you'll need to use Visual Studio 2008 SP1, Express Edition or higher. If you haven't downloaded it yet, go to http://www.microsoft.com/express. You can either use Visual Basic or Visual C# to work with the main project or create add-ins for this project.

A Framework?

So what did I actually create for this article? We all know that using base classes is a great way to tie together closely-related objects. As a very practical example, a base window or control class lets you add functionality to something that already exists without reinventing the wheel, so to speak. Windows exposes a number of code execution models such as services, console apps, Sidebar gadgets, Windows forms, WPF, COM, and more. Each of these provides a certain amount of functionality that you don't need to worry about, such as start/stop hooks for services, or the system message loop for Windows forms and WPF.

Having built a good number of small utilities over the years, I've definitely realized that I'm copying or rewriting too much code. What a waste! Since I always create a notification icon (shows up by the system clock), and I like to hide to tray on minimize, and remember window settings, I implement these in each project. I probably should have created a project template in Visual Studio as a shortcut, but this has a disadvantage. If I added a cool new feature to my framework, I'd need to recompile and rework the older apps to take advantage of it

The better solution was to create a “base application.” This would actually be its own application that exposes a notification icon and menu, and a main window. If you move the window, the location is saved. Individual utilities can then be added as plugins. I originally envisioned a framework able to host multiple applications, but that creates some interesting design challenges with visual apps. In the end, I settled on a reusable application which can host a single utility.

A Common User Interface

I decided to write this in WPF since it affords so many great options for layout and interactivity. I still write some Winforms code, but WPF is just an incredible way to build your application declaratively (not that XAML is required…) and it enables a nice clean code layout. If you are really tied to Windows Forms, you can always use the WindowsFormsHost control to expose it.

The basic application isn't very complicated. It lets you set the application name which it uses in the tray menu and in the main window title. You can also set whether it minimizes to tray or not. If not, the close button will actually kill the application. Minimize always minimizes as normal.

Finally, the main window shows both the preferences UI. Most small utility apps don't really have a UI other than settings. You can always show dialogs and windows, but if all you have is a few settings, you can just create a UserControl to contain them and the application will host it.

As an example, I created a utility add-in. It looks like some sort of file watching utility. It's not actually functional – it's just a collection of controls in a UserControl. This is paired up with the application name, icon, and more.

Figure 1 : Main Application Window

Modularity

So I mentioned before that one of my motivations with this project was to allow me to update the framework without needing to recompile the utilities themselves. To be clear, this won't be possible 100% of the time, but as long as I leave the public interfaces alone, it should work well. So here's the cool implementation: Managed Extensibility Framework, or MEF.

MEF allows you to build extensibility into your applications with little effort. Build your interfaces or contracts, and as long as plugins use that contract, code can be compiled into separate assemblies with no dependencies. When the application starts up, you tell it where to find extensions and it takes care of loading them. The contract for addins (IWpfService) is defined as:

Visual C#

public interface IWpfService
{
    // Gets the custom control to display in the host preferences dialog.
    UserControl OptionsUserControl { get; }

    string Name { get; }
    System.Drawing.Icon TrayIcon { get; }
    string Description { get; }
    string Author { get; }
    Version Version { get; }
    Uri AuthorUri { get; }
    bool HideOnClose { get; }
    string Status { get; set; }

    void Initialize();
    void Start();
    void Stop();

    event EventHandler StatusUpdated;
}

Visual Basic

Public Interface IWpfService
    ' Gets the custom control to display in the host preferences dialog.
    ReadOnly Property OptionsUserControl() As UserControl

    ReadOnly Property Name() As String
    ReadOnly Property TrayIcon() As System.Drawing.Icon
    ReadOnly Property Description() As String
    ReadOnly Property Author() As String
    ReadOnly Property Version() As Version
    ReadOnly Property AuthorUri() As Uri
    ReadOnly Property HideOnClose() As Boolean
    Property Status() As String

    Sub Initialize()
    Sub Start()
    Sub [Stop]()

    Event StatusUpdated As EventHandler

End Interface

The UserControl reference is a composite control with any necessary user interface elements for configuring the application. This could be a file dialog, checkboxes for options, buttons to start or stop processing threads, or whatever makes sense. The base application (the host) then provides access to them based on user request. The Name, TrayIcon, Description, and other such properties are used to generate information such as found in an About dialog. The methods are used by the host to control the lifecycle, similar to a Windows service. The Initialize() method is called on startup, followed by Start(). Stop() is called at shutdown/close. The hosted utility doesn't need to worry about many of the general application logic – just specific units of work.

Figure 2 : Showing About this Application

The ExtensibleWpfApp project contains a base class called ApplicationWindow, which descends from Window. This can be used by any application that wants a simple tray menu, position and size saving, and minimize to tray. On top of that is the MainAppWindow class. This descends from ApplicationWindow and also implements IWpfHost. This takes care of creating a main window that displays the application metadata and settings. You're welcome to take either class as a base class, but then you wouldn't get the benefit of MEF extensibility.

During the instantiation of the MainAppWindow class it also initializes itself and its base class using properties from the add-in:

Visual C#

public MainAppWindow()
{
    InitializeComponent();

    Compose();

    // Settings menu item on or off, ShowApp menu item on or off, Wire up callbacks, etc.
    CurrentAddin.Start();

    this.ApplicationName = CurrentAddin.Name;
    this.HideOnClose = CurrentAddin.HideOnClose;

    // Sets a custom icon or leaves it as default
    if( CurrentAddin.TrayIcon != null )
    {
        this.TrayIcon = CurrentAddin.TrayIcon;
    }

    dockPanelAddinInfo.DataContext = CurrentAddin;

    Application.Current.Exit += new ExitEventHandler(CurrentApp_Exit);
    CurrentAddin.StatusUpdated += new EventHandler(CurrentAddin_StatusUpdated);
}

Visual Basic

Public Sub New()
    InitializeComponent()

    Compose()

    ' Settings menu item on or off, ShowApp menu item on or off, Wire up callbacks, etc.
    CurrentAddin.Start()

    Me.ApplicationName = CurrentAddin.Name
    Me.HideOnClose = CurrentAddin.HideOnClose

    ' Sets a custom icon or leaves it as default
    If CurrentAddin.TrayIcon IsNot Nothing Then
        Me.TrayIcon = CurrentAddin.TrayIcon
    End If

    dockPanelAddinInfo.DataContext = CurrentAddin

    AddHandler Application.Current.Exit, AddressOf CurrentApp_Exit
    AddHandler CurrentAddin.StatusUpdated, AddressOf CurrentAddin_StatusUpdated
End Sub

Notice how it has the concept of application name and a tray icon – something a standard application doesn't have. It's easy enough to add these things, but it can be tedious, and beginner programmers just have that much more to figure to get started.

Next Steps

Though the application is a good start, I see a need for more. The application could invoke add-in features on a timer with the framework prompting the user for the interval and handling that automatically. The concept of saving and cancelling settings changes should really be built into the framework. It might also be good for the add-in to have access to show/hide the window as needed. Hooking into the system Event Log or other logging and other tracing mechanisms could also be handled by the framework.

The key is to find common services that applications can use which also normally require some user configuration. If the framework can handle that automatically, it makes for less work for each utility.

Conclusion

First of all, this is only the first part of this article. Next time I'll dig into the MEF implementation and explain how an add-in works in better detail. I'll flesh out the sample add-in a bit as a point of reference and hopefully you'll see how you might benefit from it as well.

Building reusable application code can make a huge difference over time. Unfortunately it always takes longer the first time to do it right. Good code ends up being reused, but copy-and-paste reuse isn't as good as binary reuse (referencing an assembly/DLL), and that's still not as good as composition where new components bind to a framework at runtime. Frameworks like MEF, System.Addin, PRISM, and others make it much easier than it used to be to create extension points so code can fit in later. Used wisely this can lead to a more streamlined code base where you can rely on other contributors or communities to implement new features instead of coming to you each time. You can focus on creating a solid foundation and let people create niche or mainstream features as they see fit. You'll be happier and your users will love it too!

If you haven't already, download Visual Studio Express Edition today and get started.

About the Author

Arian Kulp is a software developer living in the Midwest. He has been writing software since the fifth grade (though not always professionally). Arian creates developer evangelism stuff, speaks at INETA and Code Camps, and loves to stay on the cutting edge of technology. In his spare time, he enjoys nature, photography, and his family.

WPF Custom Screen Saver Art

Erik Klimczak — Fri, 20 Jun 2008 15:24:00 GMT

Summary

Creating custom wallpaper is easy. But what about custom screen savers? This post will detail how to build a custom saver using Windows Presentation Framework (WPF). The posted code also provides some insight on how to create interesting particle effects using WPF's animation engine, and how to implement multiple monitor support in .Net.

Erik Klimczak - Clarity Consulting

Download

http://wpfscreensaverart.codeplex.com/

Introduction

Microsoft Unified Communications (UC) is a new technology that has been getting a lot of hype in the past couple of months. UC is essentially the integration of messaging, voice, and video across the applications and devices that people use every day. More information about UC can be found here. One of the coolest things about UC is the concept of “presence” (see below). The Presence indicator effectively allows the user to reflect his/her status in other Office Communicator Server friendly applications (i.e. Outlook, Office communicator, Live Meeting, etc.)

While building out some communicator functionality on another project I found myself recreating the presence “bubbles” in xaml so that they could scale without losing quality (see below). I used Expression Design to re-create the presence bubbles and export then to xaml.

In doing so it occurred to me that the presence “bubbles” would make for some excellent art sprites.

So after a hop-skip-and a jump to Photoshop I found myself with a shiny new “presence art” wallpaper.

Immediately after creating the wallpaper I thought to myself, “this would also make a great screen saver”. This article will attempt to show how to build a custom WPF screen saver that implements a simple physics particle effect using the WPF animation engine.

Particle Animation

With my graphic designer hat on I knew that I wanted to create a floating particle effect. Particle effects can be used to simulate anything from rain, snow, fire to bubbles and clouds. Then by varying the presence “bubbles” in size and opacity the illusion of depth and space can be created. After some research I found the CompositionTarget.Rendering event handler in WPF. Essentially, this event is a timer that ticks all the time and fires once each time WPF decides to render a frame. Inside the event handler you have complete freedom to do whatever you want to any object. In other words, hooking CompositionTarget.Rendering is very much a "do it yourself" animation system. This event is especially good for physics-based animations and is very similar to the way Flash's rendering engine works. The MSDN entry for this event handler can be found here.

Once I had found the appropriate animation hook I created the particle user control. This control holds the various particle attributes that will be animated. The code below shows the various properties that can be used to create very interesting physics-based effects. These properties can be used to calculate collision detection, gravitational pull and other kinetics-related effects.

   1: public partial class Particle : UserControl

   2:    {

3:

   4:        public Particle()

   5:        {

6:

   7:            InitializeComponent();

   8:        }

9:

  10:        public static readonly DependencyProperty StatusProperty = DependencyProperty.Register("Status", typeof(Status), typeof(Particle), new UIPropertyMetadata(Particle.StatusValueChanged));

  11:        public Status Status

  12:        {

  13:            get { return (Status)GetValue(StatusProperty); }

  14:            set { SetValue(StatusProperty, value); }

  15:        }

16:

  17:        private static void StatusValueChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)

  18:        {

  19:            Particle myclass = (Particle)d;

  20:            myclass.imgStatus.Source = Application.Current.FindResource(((Status)e.NewValue).ToString() + "Png") as BitmapImage;

  21:        }

22:

  23:        public double Radius

  24:        {

  25:            get { return this.imgStatus.Height / 2; }

  26:            set { this.imgStatus.Height = this.imgStatus.Width = value * 2; }

  27:        }

28:

  29:        private double vy;

  30:        public double VY

  31:        {

  32:            get { return this.vy; }

  33:            set { this.vy = value; }

  34:        }

35:

  36:        private double vx;

  37:        public double VX

  38:        {

  39:            get { return this.vx; }

  40:            set { this.vx = value; }

  41:        }

42:

  43:        private double mass;

  44:        public double Mass

  45:        {

  46:            get { return this.mass; }

  47:            set { this.mass = value; }

  48:        }

  49:        private double x;

  50:        public double X

  51:        {

  52:            get { return this.x; }

  53:            set { this.x = value; }

  54:        }

55:

  56:        private double y;

  57:        public double Y

  58:        {

  59:            get { return this.y; }

  60:            set { this.y = value; }

  61:        }

  62:    }

VB

   1: Partial Public Class Particle

   2:     Inherits UserControl

3:

4:

   5:     Public Sub New()

   6:         InitializeComponent()

   7:     End Sub

8:

   9:     Public Shared ReadOnly StatusProperty As DependencyProperty = DependencyProperty.Register("Status", GetType(Status), GetType(Particle), New PropertyMetadata(AddressOf Particle.StatusValueChanged))

  10:     Public Property Status() As Status

  11:         Get

  12:             Return CType(GetValue(StatusProperty), Status)

  13:         End Get

  14:         Set(ByVal value As Status)

  15:             SetValue(StatusProperty, value)

  16:         End Set

  17:     End Property

18:

  19:     Private Shared Sub StatusValueChanged(ByVal d As DependencyObject, ByVal e As DependencyPropertyChangedEventArgs)

  20:         Dim [myclass] As Particle = CType(d, Particle)

  21:         [myclass].imgStatus.Source = TryCast(Application.Current.FindResource((CType(e.NewValue, Status)).ToString() & "Png"), BitmapImage)

  22:     End Sub

23:

  24:     Public Property Radius() As Double

  25:         Get

  26:             Return Me.imgStatus.Height / 2

  27:         End Get

  28:         Set(ByVal value As Double)

  29:             Me.imgStatus.Width = value * 2

  30:             Me.imgStatus.Height = Me.imgStatus.Width

  31:         End Set

  32:     End Property

33:

  34:     Private _vy As Double

  35:     Public Property VY() As Double

  36:         Get

  37:             Return Me._vy

  38:         End Get

  39:         Set(ByVal value As Double)

  40:             Me._vy = value

  41:         End Set

  42:     End Property

43:

  44:     Private _vx As Double

  45:     Public Property VX() As Double

  46:         Get

  47:             Return Me._vx

  48:         End Get

  49:         Set(ByVal value As Double)

  50:             Me._vx = value

  51:         End Set

  52:     End Property

53:

  54:     Private _mass As Double

  55:     Public Property Mass() As Double

  56:         Get

  57:             Return Me._mass

  58:         End Get

  59:         Set(ByVal value As Double)

  60:             Me._mass = value

  61:         End Set

  62:     End Property

63:

  64:     Private _x As Double

  65:     Public Property X() As Double

  66:         Get

  67:             Return Me._x

  68:         End Get

  69:         Set(ByVal value As Double)

  70:             Me._x = value

  71:         End Set

  72:     End Property

73:

  74:     Private _y As Double

  75:     Public Property Y() As Double

  76:         Get

  77:             Return Me._y

  78:         End Get

  79:         Set(ByVal value As Double)

  80:             Me._y = value

  81:         End Set

  82:     End Property

83:

  84: End Class

85:

86:

Once I had the particle class created, I decided to use a variation of a spring physics equation to get the desired float animation. The spring equation forces the particles toward each other and then springs them past each other similar to how a ball on the end of a rubber band would act when pulling it and letting it spring back and forth. Then by tweaking the force and velocity applied to each particle I successfully simulated a floating effect (I am by no means a physicist and I am sure there is a better way of implementing this equation). By combining the CompositionTarget.Rendering event and the positioning logic we can effectively scatter and animate the particles on our Canvas. The math involved looks something like this:

   1: void Spring(Particle a, Particle b)

   2:         {

   3: double dx = b.X - a.X;

   4: double dy = b.Y - a.Y;

5:

   6: double dist = Math.Sqrt(dx * dx + dy * dy);

   7: if (dist < _minDist)

   8:             {

   9: double ax = dx * _spring;

  10: double ay = dy * _spring;

11:

  12:                 a.VX += ax;

  13:                 a.VY += ay;

14:

  15:                 b.VX -= ax;

  16:                 b.VY -= ay;

17:

  18: Canvas.SetLeft(a, a.X);

  19: Canvas.SetTop(a, a.Y);

20:

  21: Canvas.SetLeft(b, b.X);

  22: Canvas.SetTop(b, b.Y);

23:

24:

  25:             }

26:

  27: Canvas.SetLeft(a, a.X);

  28: Canvas.SetTop(a, a.Y);

29:

  30: Canvas.SetLeft(b, b.X);

  31: Canvas.SetTop(b, b.Y);

32:

33:

  34:         }

35:

  36: VB:

  37: PrivateSub Spring(ByVal a As Particle, ByVal b As Particle)

  38: Dim dx AsDouble = b.X - a.X

  39: Dim dy AsDouble = b.Y - a.Y

40:

  41: Dim dist AsDouble = Math.Sqrt(dx * dx + dy * dy)

  42: If dist < _minDist Then

  43: Dim ax AsDouble = dx * _spring

  44: Dim ay AsDouble = dy * _spring

45:

  46:             a.VX += ax

  47:             a.VY += ay

48:

  49:             b.VX -= ax

  50:             b.VY -= ay

51:

  52:             Canvas.SetLeft(a, a.X)

  53:             Canvas.SetTop(a, a.Y)

54:

  55:             Canvas.SetLeft(b, b.X)

  56:             Canvas.SetTop(b, b.Y)

57:

58:

  59: EndIf

60:

  61:         Canvas.SetLeft(a, a.X)

  62:         Canvas.SetTop(a, a.Y)

63:

  64:         Canvas.SetLeft(b, b.X)

  65:         Canvas.SetTop(b, b.Y)

66:

67:

  68: EndSub

69:

  70: And the main animation loop looks like this:

71:

  72: C#:

  73: void CompositionTarget_Rendering(object sender, EventArgs e)

  74:         {

  75: for (int i = 0; i < _numParticles; i++)

  76:             {

  77:                 _particles[i].X += _particles[i].VX;

  78:                 _particles[i].Y += _particles[i].VY;

79:

  80: Particle p = _particles[i];

81:

  82: if (p.X >this.Width)

  83:                 {

  84:                     p.X = 0;

  85:                 }

86:

  87: elseif (p.X < 0)

  88:                 {

  89:                     p.X = this.Width;

  90:                 }

91:

  92: if (p.Y >this.Height)

  93:                 {

  94:                     p.Y = 0;

  95:                 }

  96: elseif (p.Y < 0)

  97:                 {

  98:                     p.Y = this.Height;

  99:                 }

 100:             }

 101:

 102:

 103: for (int i = 0; i < _numParticles - 1; i++)

 104:             {

 105: var partA = _particles[i];

 106: for (int j = i + 1; j < _numParticles; j++)

 107:                 {

 108: var partB = _particles[j];

 109:                     Spring(partA, partB);

 110:

 111:                 }

 112:             }

 113:         }

   1: Sub CompositionTarget_Rendering(ByVal sender As System.Object, ByVal e As System.EventArgs)

   2: For i AsInteger = 0 To _numParticles - 1

   3:             _particles(i).X += _particles(i).VX

   4:             _particles(i).Y += _particles(i).VY

5:

   6: Dim p As Particle = _particles(i)

7:

   8: If p.X >Me.Width Then

   9:                 p.X = 0

10:

  11: ElseIf p.X < 0 Then

  12:                 p.X = Me.Width

  13: EndIf

14:

  15: If p.Y >Me.Height Then

  16:                 p.Y = 0

  17: ElseIf p.Y < 0 Then

  18:                 p.Y = Me.Height

  19: EndIf

  20: Next i

21:

22:

  23: For i AsInteger = 0 To _numParticles - 2

  24: Dim partA = _particles(i)

  25: For j AsInteger = i + 1 To _numParticles - 1

  26: Dim partB = _particles(j)

  27:                 Spring(partA, partB)

28:

  29: Next j

  30: Next

31:

  32: EndSub

33:

Supporting Multiple Monitors

After the animation was rendering correctly the next step was getting it to run on multiple monitors. To make this happen I wrote some code in the application entry point to get a handle to the active screens. The System.Windows.Forms namespace has a Screen class which contains a collection of screens and their attributes including working area, width, and height. By looping through the screen collection I measure the screen boundaries and set the window size dynamically based on the available screen real estate.

   1: private void Application_Startup(object sender, StartupEventArgs e)

   2:         {

3:

   4: Window1 _window = null;

5:

   6:             System.Windows.Forms.Cursor.Hide();

7:

   8: foreach (Screen screen inScreen.AllScreens)

   9:             {

  10: if (screen.Primary)

  11:                 {

  12: Rectangle location = screen.Bounds;

  13:                     _window = newWindow1(location.Height, location.Width);

  14:                     _window.Width = location.Width;

  15:                     _window.Height = location.Height;

  16:                     _window.Left = 0;

  17:                     _window.Top = 0;

  18:                     _window.WindowState = WindowState.Maximized;

  19:                     _window.Show();

  20:                 }

21:

  22: elseif (!screen.Primary)

  23:                 {

24:

  25: Rectangle location = screen.Bounds;

  26:                     _window = newWindow1(location.Height, location.Width);

  27:                     _window.Left = screen.WorkingArea.Left;

  28:                     _window.Top = screen.WorkingArea.Top;

  29:                     _window.Width = location.Width;

  30:                     _window.Height = location.Height;

  31:                     _window.Show();

  32:                 }

33:

  34:             }

35:

  36:         }

   1: private void Application_Startup(object sender, StartupEventArgs e)

   2:         {

3:

   4: Window1 _window = null;

5:

   6:             System.Windows.Forms.Cursor.Hide();

7:

   8: foreach (Screen screen inScreen.AllScreens)

   9:             {

  10: if (screen.Primary)

  11:                 {

  12: Rectangle location = screen.Bounds;

  13:                     _window = newWindow1(location.Height, location.Width);

  14:                     _window.Width = location.Width;

  15:                     _window.Height = location.Height;

  16:                     _window.Left = 0;

  17:                     _window.Top = 0;

  18:                     _window.WindowState = WindowState.Maximized;

  19:                     _window.Show();

  20:                 }

21:

  22: elseif (!screen.Primary)

  23:                 {

24:

  25: Rectangle location = screen.Bounds;

  26:                     _window = newWindow1(location.Height, location.Width);

  27:                     _window.Left = screen.WorkingArea.Left;

  28:                     _window.Top = screen.WorkingArea.Top;

  29:                     _window.Width = location.Width;

  30:                     _window.Height = location.Height;

  31:                     _window.Show();

  32:                 }

33:

  34:             }

35:

  36:         }

Making it a Screen Saver

The last step to this application is making it a screen saver. By implementing mouse and keyboard event handlers to shut down the application we essentially can mimic the interaction of a screen saver.

   1: MouseMove += newMouseEventHandler(Window2_MouseMove);

   2:   MouseDown += newMouseButtonEventHandler(Window2_MouseDown);

   3:   KeyDown += newKeyEventHandler(Window2_KeyDown);

   4: void Window2_KeyDown(object sender, KeyEventArgs e)

   5:         {

   6: Application.Current.Shutdown();

   7:         }

8:

   9: void Window2_MouseDown(object sender, MouseButtonEventArgs e)

  10:         {

  11: Application.Current.Shutdown();

  12:         }

13:

  14: void Window2_MouseMove(object sender, MouseEventArgs e)

  15:         {

  16: Point currentPosition = e.MouseDevice.GetPosition(this);

17:

  18: if (!isActive)

  19:             {

  20:                 mousePosition = currentPosition;

  21:                 isActive = true;

  22:             }

  23: else

  24:             {

25:

  26: if ((Math.Abs(mousePosition.X - currentPosition.X) > 10) ||

  27:                     (Math.Abs(mousePosition.Y - currentPosition.Y) > 10))

  28:                 {

  29: Application.Current.Shutdown();

  30:                 }

  31:             }

  32:         }

   1: AddHandlerMe.MouseMove, AddressOf Window_MouseMove

   2: AddHandlerMe.MouseDown, AddressOf Window_MouseDown

   3: AddHandlerMe.KeyDown, AddressOf Window_KeyDown

4:

   5: PrivateSub Window_KeyDown(ByVal sender AsObject, ByVal e As KeyEventArgs)

   6:         Application.Current.Shutdown()

   7: EndSub

8:

   9: PrivateSub Window_MouseDown(ByVal sender AsObject, ByVal e As MouseButtonEventArgs)

  10:         Application.Current.Shutdown()

  11: EndSub

12:

  13: PrivateSub Window_MouseMove(ByVal sender AsObject, ByVal e As MouseEventArgs)

  14: Dim currentPosition As Point = e.MouseDevice.GetPosition(Me)

  15: If (Not isActive) Then

  16:             mousePosition = currentPosition

  17:             isActive = True

  18: Else

  19: If (Math.Abs(mousePosition.X - currentPosition.X) > 10) OrElse (Math.Abs(mousePosition.Y - currentPosition.Y) > 10) Then

  20:                 Application.Current.Shutdown()

  21: EndIf

  22: EndIf

  23: EndSub

24:

Lastly, simply set the build configuration to Release mode and build it. In the output bin->Release directory find the built executable. Rename the file extension from .exe to .scr then right click and choose Install from the context menu.

That's it!

Challenges to You

One of the interesting things about Office Communicator Server is that it comes with an SDK to build your own custom Unified Communications applications.

I would love to see the presence bubbles actually hooked up to real users' status, and maybe a cool animation to indicate when a users' status is changed.
Create a config file to let the user specify his/her own images and tweak other settings like speed and velocity.

Conclusion

This was a great opportunity to brush up on my physics skills and play with some of the animation possibilities in WPF. This application is also a great example of alternative data visualization. Sometimes I get tired of seeing everything in tabular form and I think that “presence art” is a great example of Art + Code (aesthetically pleasing and functional). I hope you enjoy it.

YeahTrivia: Creating a Trivia Server/Client with WPF and WCF

Steve Holstad — Mon, 29 Oct 2007 21:01:00 GMT

In this article I'll take you along for the ride as I attack the learning curve required to create a fun, interactive application using both the Microsoft Windows Presentation Foundation (WPF) and the Windows Communication Foundation (WCF). Afterwards, you'll have a flexible trivia client/server game ready to play by yourself or against friends, coworkers and your local know-it-all. And in honor of Halloween, I've included three games of horror movie trivia.

Steve Holstad

The Bright Lights

Difficulty: Advanced

Time Required: 6-10 hours

Cost: Free

Software: Visual Studio Express, 2005, 2008 Beta 2 Microsoft .NET Framework 3.0

Hardware:

Download: Download Source

What can YeahTrivia do for me?

Glad you asked. This project started when I decided I wanted to dive headfirst into learning WPF and WCF, without hacking through countless Hello World examples. And I wanted something fun that I could improve over time as my skills developed in these new technologies. In this article I'll take you along for the ride as I attack the learning curve required to create a fun, interactive application using both the Microsoft Windows Presentation Foundation (WPF) and the Windows Communication Foundation (WCF). Afterwards, you'll have a flexible trivia client/server game ready to play by yourself or against friends, coworkers and your local know-it-all. And in honor of Halloween, I've included three games of horror movie trivia.

In case you were wondering, the "YeahTrivia" name honors my new bride & her favorite prefix. Think of it as YeeeeaaaaahhTrivia!

Basic Setup

This demo project was built using Visual Studio 2008 Beta 2, and is based on the Microsoft .NET Framework version 3.0. The game is fed by a small windows app that acts as a game server, providing game selection, user registration, question loading, response times, chat messaging and scorekeeping. The server loads a game by reading a predefined XML format, which we will look at a bit later. This dynamic load lets anyone create their own flavor of trivia game, with any number of questions.

The server app exposes one WCF endpoint, a wsDualHttpBinding channel that supports duplex (two-way) communication between the server and any number of game clients. Clients attach themselves to this endpoint and provide a callback address to the server. The server saves an instance of this callback channel and uses each client's instance to contact the clients en masse during general game flow. Enough talk, here's how to build one yourself.

Trivia Common and WCF Service Interfaces

The TriviaCommon project provides both the server and client projects access to shared objects. To keep things simple the Common project only contains two classes:

Constants.cs defines the AnswerItem enumeration, which gives easy access to the five answer options (None, A, B, C, D), and the QuestionItem struct. This structure is delivered to the client and contains question text, answer text, and the correct answer object of type AnswerItem. Notice that objects being directly passed over the wire need to be marked with the [DataContract] attribute.

The second class, Interfaces.cs is where our WCF fun begins. Take a look:

C#:

using System;
using System.Collections.Generic;
using System.ServiceModel;
using System.Text;

namespace Trivia.Common
{
    #region Interfaces

    #region Service Interface

    /// 
    /// Interface that defines Trivia service contract.
    /// 
    [ServiceContract(CallbackContract = typeof(ITriviaCallback))]
    public interface ITrivia
    {
        [OperationContract(IsOneWay = true)]
        void RegisterUser(string userName);

        [OperationContract(IsOneWay = true)]
        void AcceptAnswer(string userName, string answerValue);

        [OperationContract(IsOneWay = true)]
        void ChatPublish(string userName, string message);
    }

    #endregion Service Interface

    #region Client Callback Interface

    /// 
    /// Interface that defines Trivia client callback contract.
    /// 
    public interface ITriviaCallback
    {        
        [OperationContract(IsOneWay = true)]
        void OnGameStart(int questionCount);

        [OperationContract(IsOneWay = true)]
        void OnGameEnd();

        [OperationContract(IsOneWay = true)]
        void OnUserRegistered(string userName);

        [OperationContract(IsOneWay = true)]
        void OnPublishChat(string userName, string chatMessage);

        [OperationContract(IsOneWay = true)]
        void OnQuestionLoad(int questionIndex, QuestionItem questionItem);

        [OperationContract(IsOneWay = true)]
        void OnQuestionEnd();

        [OperationContract(IsOneWay = true)]
        void OnQuestionStatusUpdate(Int64 questionTimeRemaining);

        [OperationContract(IsOneWay = true)]
        void OnScoreboardUpdate(Dictionary<string, Int64> scoreboard);

        [OperationContract(IsOneWay = true)]
        void OnGameServerStopped();
    }

    #endregion Client Callback Interface

    #endregion Interfaces
}

VB:

Imports System
Imports System.Collections.Generic
Imports System.ServiceModel
Imports System.Text

Namespace Trivia.Common

#Region "Interfaces"

#Region "Service Interface"
    
    ''' 
    ''' Interface that defines Trivia service contract.
    ''' 
    GetType(ITriviaCallback))> _
    Public Interface ITrivia
        True)> _
        Sub RegisterUser(ByVal userName As String)

        True)> _
        Sub AcceptAnswer(ByVal userName As String, ByVal answerValue As String)

        True)> _
        Sub ChatPublish(ByVal userName As String, ByVal message As String)
    End Interface
        
#End Region

#Region "Client Callback Interface"

    ''' 
    ''' Interface that defines Trivia client callback contract.
    ''' 
    ''' 
    Public Interface ITriviaCallback
        True)> _
      Sub OnGameStart(ByVal questionCount As Integer)

        True)> _
        Sub OnGameEnd()

        True)> _
        Sub OnUserRegistered(ByVal userName As String)

        True)> _
        Sub OnPublishChat(ByVal userName As String, ByVal chatMessage As String)

        True)> _
        Sub OnQuestionLoad(ByVal questionIndex As Integer, ByVal questionItem As QuestionItem)

        True)> _
        Sub OnQuestionEnd()

        True)> _
        Sub OnQuestionStatusUpdate(ByVal questionTimeRemaining As Long)

        True)> _
        Sub OnScoreboardUpdate(ByVal scoreboard As Dictionary(Of String, Long))

        True)> _
        Sub OnGameServerStopped()

    End Interface

#End Region

#End Region

End Namespace

A few items of interest here. Notice we're importing the System.ServiceModel namespace. This is the key assembly when using WCF, so don't forget to add a reference to your project. The first interface, ITrivia, defines the operations the server is required to implement, which handle basic user actions: Register a team, accept an answer and accept a chat message. Easy.

The second interface, cleverly named ITriviaCallback, lays out the callback contract a client must fulfill in order to play nicely with our server. The operations listed here describe events the server will publish. These aren't actual events, but the naming convention "OnX..." helps you remember that these are server published activities.

Notice that the [OperationContract] attribute notifies WCF that each method is part of a service contract. The IsOneWay flag gives us "fire-and-forget" behavior (the app shouldn't wait around for a response). So now that the common objects are ready, let's move on to...

Building the Trivia Server

The YeahTrivia Server is a simple utility app, but don't let the plain looks fool you; I thought about calling this the BrainStumper Pumper, but this is a family site. This app lets a user (anyone acting as game admin) start the service, select the desired game, await team registrations, and then start the game. If this were to become a larger scale project, I would make this an IIS hosted service that manages multiple games and provides more autonomy. Until those sports bar royalty checks start rolling in, however, a utility app will do just fine.

The only form, GameServerDashboard, simply provides user interaction with the GameServer class. On startup, the form inits an instance of GameServer and tells it to start the service. It also loads all trivia question sets from the Games directory, and displays them in the list.

GameServer is the brain behind YeahTrivia. The attributes below set up the GameServer for action:

C#:

[ServiceBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant
        ,InstanceContextMode = InstanceContextMode.Single)]
    public class GameServer : ITrivia

VB:

Single)> _
    Public Class GameServer
        Implements ITrivia

ConcurrencyMode.Reentrant prevents deadlocks between the apps by stating that while this service is single-threaded, callbacks are allowed to invoke new operations.

InstanceContextMode.Single sets the service as a singleton, so that all messages are delivered to the same object instance.

These are advanced topics if you're new to WCF, so I'll include some links at the end that helped clarify some of this for me. Let's keep moving forward by looking at a few activities of the game server:

Start the Service: Passes in the configured base address as a Uri, inits and opens a new ServiceHost.

C#:

public void StartService()
{
   // Set base address and open service host
   Uri baseAddress = new Uri(ConfigurationManager.AppSettings[CONFIG_KEY_BASEURI]);
   _serviceHost = new ServiceHost(new GameServer(), baseAddress);
   _serviceHost.Open();
}

VB:

  Public Sub StartService()
     'Set base address and open service host
     Dim baseAddress As New Uri(ConfigurationManager.AppSettings(CONFIG_KEY_BASEURI))
     _serviceHost = New ServiceHost(New GameServer(), baseAddress)
     _serviceHost.Open()
  End Sub

Register a new team: Saves off the callback, adds it to the callback collection and scoreboard containers, notifies the user of a successful registration, and notifies all game clients of the new team.

C#:

 public void RegisterUser(string userName)
 {
     _currentCallback = OperationContext.Current.GetCallbackChannel();

     // Store callback
     if (!_callbacks.ContainsKey(userName))
     {
         _callbacks.Add(userName, _currentCallback);
         _scoreboard.Add(userName, 0);

         // Notify user of registration
         _currentCallback.OnUserRegistered(userName);

         // Notify clients of new user
         foreach (string userKey in _callbacks.Keys)
         {
            _currentCallback = _callbacks[userKey];
            _currentCallback.OnPublishChat(GAME_USERKEY, string.Format(FORMAT_USER_REGISTERED, userName));
         }                
     }
     else
     {
         // User already registered, throw exception
         throw new Exception(ERROR_USER_ALREADY_EXISTS);
     }
 }

VB:

Public Sub RegisterUser(ByVal userName As String) Implements ITrivia.RegisterUser
   _currentCallback = OperationContext.Current.GetCallbackChannel(Of ITriviaCallback)()

   'Store callback
   If Not _callbacks.ContainsKey(userName) Then
      _callbacks.Add(userName, _currentCallback)
      _scoreboard.Add(userName, 0)

      'Notify user of registration
      _currentCallback.OnUserRegistered(userName)

      'Notify clients of new user
      For Each userKey As String In _callbacks.Keys
         _currentCallback = _callbacks(userKey)
         _currentCallback.OnPublishChat(GAME_USERKEY, String.Format(FORMAT_USER_REGISTERED, userName))
      Next
   Else
      'User already registered, throw exception
      Throw New Exception(ERROR_USER_ALREADY_EXISTS)
   End If
End Sub

You can start to see how the server is able to handle incoming calls and process them back to the clients using the duplex channel. I'll leave the rest of the server actions for you to examine on your own.

Building the Game Client (WCF)

Address, Binding, Contract. These are the ABC's of WCF. The client's app.config file handles connecting to the service and specifying the channel and contract used to interact with it. Examine the client portion of the client .config:

<client>
   <endpoint address="http://localhost:8088/Trivia" binding="wsDualHttpBinding"
      bindingConfiguration="WSDualHttpBinding_ITrivia" contract="Trivia.Common.ITrivia"
      name="WSDualHttpBinding_ITrivia">
   endpoint>
client>

The address points to the exposed service endpoint. The binding sets the channel as "wsDualHttpBinding" (our http duplex channel). The bindingConfiguration attribute is an optional pointer to another group of configurations for the binding, and finally, the contract sets the interface with which our client will be interacting.

Next it's time to generate a proxy class. Memorize this: Svcutil.exe is your friend. The client needs a proxy class that it can use to interact with the service model. The utility is a bit tricky at first, because of the wealth of optional flags, but stick with it, it's better than coding the proxy class by hand! You can generate your client code by starting the service and running a command line similar to this:

svcutil /language:cs /out:ServerProxy.cs http://localhost:8088/Trivia

Add the generated class to the client project and you can begin to interact with the service. The svcutil is available as part of the Windows SDK. Check out the referenced site below for more information on this handy utility.

Building the Game Client (WPF)

Building the WPF portion of the client app was really a learning experience, and it will be the priority for me to improve in a later version. Learning to program in XAML markup can seem daunting, and it requires a large paradigm shift on your part in order to grasp the new concepts. Microsoft Expression is powerful tool for XAML work, but this time I coded all of the XAML by hand in order to fully see what was taking place inside.

A deep discussion of WPF is beyond the scope of this article, but take a look at the example code to get an idea of the layout. An excellent book to start with is WPF Unleashed by Adam Nathan. An easy read (for a programming book), and solid examples to get you rolling.

I've set up the client using a instance of the Window class, which is shown below:

<Window x:Class="Trivia.Client.GameClient"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    Title="YeahTrivia" MinHeight="620" MinWidth="620" 
    WindowStartupLocation="CenterScreen" WindowState="Normal"  Style="{DynamicResource MainWindowStyle}"
    Background="{DynamicResource MainWindowBackgroundBrush}">

The window class sets up the outermost container of the app, and includes two default namespaces. I've also set a few other properties here: a min height and width, window startup location & state, and two styling attributes set by dynamic resources.

Resources are a great way to further separate form & function, allowing a programmer to handle the behavior of an app, while a designer can work simultaneously on the look, all without stepping on too many toes. As a 2.0 task for this project, I would remove all inline styling and move them into resource dictionaries. A dictionary contains styles and control templates (a skin) that can be loaded & switched at runtime.

ResourceDictionaries are linked to your XAML in the App.Xaml file. Once you've set up the reference, the example above show how to reference the current dictionary: The Background and Style properties are set as dynamic resources by naming the Keys specified in the ResourceDictionary (DefaultResources.xaml):

<LinearGradientBrush x:Key="MainWindowBackgroundBrush" StartPoint=".45,.45" EndPoint=".55,.55" SpreadMethod="Reflect">
   <GradientStop Offset="0" Color="DodgerBlue"/>
   <GradientStop Offset=".8" Color="DarkSlateBlue"/>
LinearGradientBrush>

<Style TargetType="{x:Type Window}" x:Key="MainWindowStyle">
   <Setter Property="FontFamily" Value="Trebuchet MS"/>
Style>

Not quite as easy as CSS, but for a Forms project, it's a nice feature. The sample ResourceDictionary includes a button control template for all of my buttons, based on Rob Eisenberg's excellent article (link below).

One other interesting feature to point out: Take a look at the code-behind class MarshalToUIThread method, which accepts a SendOrPostCallback parameter. This is where the client is transferring actions from the sync thread back to the UI thread. In each interface method implementation (OnX..), you can see how I wrap any UI-directed code and assign it to the postCallback field. Passing this to the MarshalToUIThread method simply issues a SynchronizationContext.Post call, and the UI thread executes as expected.

Creating a New Trivia Game (XML)

New trivia games can be added at any time using the simple XML format shown here. After installing the server application, simply drop the new .XML file into the Games directory ([Server Install Location]\Yeah Trivia Server\Games). This demo comes pre-loaded with Geek Trivia, and a special Halloween Trivia version in case you're feeling festive.

<TriviaQuestionDataSet xmlns="http://tempuri.org/TriviaQuestionDataSet.xsd">
  <TriviaQuestion>
    <QuestionText>Name the highest grossing Monty Python creation.QuestionText>
    <AnswerTextA>A) Holy GrailAnswerTextA>
    <AnswerTextB>B) The Life of BrianAnswerTextB>
    <AnswerTextC>C) ShrubberyAnswerTextC>
    <AnswerTextD>D) The Meaning of LifeAnswerTextD>
    <CorrectAnswerKey>ACorrectAnswerKey>
  TriviaQuestion>
  <TriviaQuestion>
    <QuestionText>Ferris Bueller's best friend was _________.QuestionText>
    <AnswerTextA>A) Sloane PetersonAnswerTextA>
    <AnswerTextB>B) Edward R. RooneyAnswerTextB>
    <AnswerTextC>C) Charlie SheenAnswerTextC>
    <AnswerTextD>D) Cameron FryeAnswerTextD>
    <CorrectAnswerKey>DCorrectAnswerKey>
  TriviaQuestion>
TriviaQuestionDataSet>

It's Time to Play YeahTrivia

Install both the Server and Client applications. First, fire up the server, and then start your game client(s). Once everyone has registered a team, select your game and hit "Start Game". You're off...

Game Over

So there you have it. We've seen how WCF manages communication between objects, extracting complicated service protocols away from your code. And just a small subset of the WPF functionality has shown us how quickly a rich, XAML-based UI can come together. And maybe, just maybe, you've learned why a CD is 74 minutes long... but I'm not telling.

I challenge you to improve on this initial version of YeahTrivia: Crack open the XAML and add animations, images, video, music & more. Create a self-maintaining server to run multiple games at once. Add a High Score storage system. Extend the WCF settings to enable other communication channels. Add a new skin. Create new question files to share with us. Whatever you do, have fun and go nuts. YeahCoding4Fun.

Download source files

Download compiled demo (C# and VB)

About The Author

Steve Holstad works as a software consultant for Clarity Consulting in Chicago. He blogs at The Bright Lights, and is available via email at sholstad@claritycon.com

References

wcf.netfx3.com/
wpf.netfx3.com/
Generating a client proxy class
ConcurrencyMode
SvcUtil.exe Tutorial
Rob Eisenberg's WPF control template

Special thanks to Bryan Dougherty for the WCF jumpstart, Kevin Marshall for the Halloween Trivia and Jay Garmon, creator of TechRepublic's Geek Trivia.

Outlook Webmail Add-in for Windows Home Server

Brian Peek — Fri, 10 Aug 2007 08:33:56 GMT

In this article, Brian Peek will demonstrate how to create an add-in for Windows Home Server that will allow users to view their Outlook mail from a web browser.

Brian Peek

ASPSOFT, Inc.

Difficulty: Intermediate

Time Required: 2-3 hours

Cost: Free

Software: Windows Home Server, Microsoft Outlook 2000/XP/2003/2007 (not Outlook Express/Windows Mail), Visual Basic or Visual C# Express Editions, Visual Web Developer Express Edition, Microsoft .NET Framework 3.0 runtime, Outlook/Office Primary Interop Assemblies (more on this below), Windows SDK (Vista or later, which includes the .NET 3.0 bits. Note that this installs and works just fine under Windows XP. The SDK can build applications for Windows XP and greater.)

Hardware: None

Download: CodePlex Project

Introduction

Windows Home Server is a new product from Microsoft which allows home users to manage and share data, including photos, documents, videos, music, etc. It also provides a very easy way to backup all computers on your home network to a central storage server.

Windows Home Server can also be extended via add-ins to enhance the experience and provide new and interesting functionality other than what comes in the box.

One feature not present in WHS that I would find useful is the ability to view my Outlook mail box from the web at any time. I have 6 or 7 email accounts that are all setup to retrieve via POP3 to Outlook. Most of these accounts do not support IMAP or have a web-based interface. Therefore, Outlook is generally open all day and checking messages. When I'm away from home for work or pleasure, it's very often inconvenient to have to remote desktop into the machine with Outlook running to read my email, so it would be nice to have a web-based version of my current Outlook folders so I can view all email (old and new) at any time simply by browsing to a web server at home. Windows Home Server comes with Internet Information Services 6 (IIS6) and one can easily add a new web application to IIS on the server.

So, this article will attempt to show how to build a new web site using ASP.NET that can be added to your Windows Home Server installation that will allow one to view the Outlook folders running on whatever computer contains your current Outlook installation and message store.

If you wish to just use the application, download the sample from above and skip down to the deployment section for installation instructions.

NOTE: This application will only work with Microsoft Outlook. It will not work with Outlook Express, Windows Mail, or any other mail client.

Setup

Setup can be a bit tricky. Office/Outlook will need to be installed on your development machine. It does not need to be the same machine which contains your store at this point, but that too would help. Once Office/Outlook is installed, the Primary Interop Assemblies for the version of Office you are using need to be installed. For Office 2003/2007, this can be done choosing .NET Programming Support from the list of sub-items in the Microsoft Office Outlook section of the setup program.

Unfortunately I do not have an earlier copy of Office with which to check, but the procedure should be the same. If anyone happens to try this with Office XP/2000, please let me know if/how it works.

If you will be developing on an OS earlier than Vista, install the .NET Framework 3.0 runtime.

Finally, install the Windows SDK linked above accepting all defaults.

Architecture

The architecture we will be using is very similar that to an N-tier application. The machine running Outlook with the message store to be viewed is, in essence, the server machine. That machine will run a host process that we will develop which will expose several methods via Windows Communication Foundation. These methods will be consumed by an ASP.NET application running on the Windows Home Server.

The Host

Let's start by building the host application. This will run on the computer where Outlook is installed and the messages are stored. The application will be written to run in the notification area next to the Windows system clock.

To start, create a new Windows Application project named WHSMailHost. Rename the default Form1.cs/.vb file to frmMain.cs/.vb. Double-click on the file in the Solution Explorer to bring up the design surface.

In order to get the application to run in the notification area, drag and drop a NotifyIcon control from the Toolbox to the design surface, name it niIcon. Also, drag over a ContextMenuStrip to the design surface and name it cmsMenu. This will be used to pop up a context menu when the icon in the notification area is clicked. Finally, set the following properties on the niIcon control:

Text	WHS Mail Host
ContextMenuStrip	cmsMenu
Visible	True

Select the cmsMenu control and add a single menu item named Exit to the list. Double-click on that menu item to create a default Click event. In the code for the Click event, simply close the form as follows:

private void mnuExit_Click(object sender, EventArgs e)
{
    // exit the application
    this.Close();
}

Private Sub mnuExit_Click(ByVal sender As Object, ByVal e As EventArgs) Handles mnuExit.Click
    ' exit the application
    Me.Close()
End Sub

Finally, add the following events to frmMain by selecting them from the Event Property window and implementing them with the following code:

private void frmMain_Resize(object sender, EventArgs e)
{
    // hide the form
    this.Hide();
}

private void frmMain_Load(object sender, EventArgs e)
{
    // start the WCF service
    MyServiceHost.StartService();
}

private void frmMain_FormClosing(object sender, FormClosingEventArgs e)
{
    // stop the WCF service
    MyServiceHost.StopService();
}

Private Sub frmMain_Resize(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Resize
    ' hide the form
    Me.Hide()
End Sub

Private Sub frmMain_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
    ' start the WCF service
    MyServiceHost.StartService()
End Sub

Private Sub frmMain_FormClosing(ByVal sender As Object, ByVal e As FormClosingEventArgs) Handles MyBase.FormClosing
    ' stop the WCF service
    MyServiceHost.StopService()
End Sub

The code above references a class named MyServiceHost. This is what starts the WCF host and will be discussed next.

Windows Communication Foundation (WCF)

Windows Communication Foundation (formerly known as Indigo) is a feature of the .NET Framework 3.0 that allows one to build and run connected systems. The simplest definition that fits with what we will be doing here is that it allows an application running on one machine (the client, in this case, the ASP.NET application) to execute a method on another machine (the host, in this case, the application we're currently building).

First, add a reference to the System.ServiceModel assembly. Then, add a class to the project named WHSMailService. Open the class and add the following code beneath the generated WHSMailService class implementation:

internal class MyServiceHost
{
    internal static ServiceHost myServiceHost = null;

    internal static void StartService()
    {
        // Instantiate new ServiceHost 
        myServiceHost = new ServiceHost(typeof(WHSMailService));
        myServiceHost.Open();
    }

    internal static void StopService()
    {
        // Call StopService from your shutdown logic (i.e. dispose method)
        if (myServiceHost.State != CommunicationState.Closed)
            myServiceHost.Close();
    }
}

Friend Class MyServiceHost
    Friend Shared myServiceHost As ServiceHost = Nothing

    Friend Shared Sub StartService()
        ' Instantiate new ServiceHost 
        myServiceHost = New ServiceHost(GetType(WHSMailService))
        myServiceHost.Open()
    End Sub

    Friend Shared Sub StopService()
        ' Call StopService from your shutdown logic (i.e. dispose method)
        If myServiceHost.State <> CommunicationState.Closed Then
            myServiceHost.Close()
        End If
    End Sub
End Class

This code simply creates a new WCF ServiceHost of the type WHSMailService (which we will implement next) and then opens that host so that it may receive incoming connections. We will look at how this connections are configured later in the article.

Remember that the code in the form above above called the StartService and StopService methods located here when the main form loads and closes. This very easily allows to immediately start the service host when the application starts and closes the service host when the application exits.

Contracts and Entities

A contract is an interface that defines which methods are exposed by the service host that can be consumed by the client application. Both the client application and the server application will need to know what is in this interface, so we will need to create a second project that will contain the interface definition. Additionally, we will need a way to pass folder and email information to and from each application, so we will define some custom classes to encapsulate those objects.

Create a new Class Library project in the current solution named WHSMailCommon. In this new project, create a directory named Contracts and a directory named Entities.

Inside the Entities directory, create a new class named Folder. This will represent an Outlook message folder. The class should look like the following:

using System;
using System.Collections.Generic;

namespace WHSMailCommon.Entities
{
    // entity object representing an Folder
    [Serializable]
    public class Folder : IComparable
    {
        private string _entryID;
        private string _name;
        private List _folders;
        private int _unreadMessages;
        private int _totalMessages;

        public Folder(string entryID, string name, int unreadMessages, int totalMessages)
        {
            _entryID = entryID;
            _name = name;
            _unreadMessages = unreadMessages;
            _totalMessages = totalMessages;
        }

        // MAPI unique identifier
        public string EntryID
        {
            get { return _entryID; }
            set { _entryID = value; }
        }

        // subfolders of this folder
        public List Folders
        {
            get { return _folders; }
            set { _folders = value; }
        }

        public string Name
        {
            get { return _name; }
            set { _name = value; }
        }

        public int UnreadMessages
        {
            get { return this._unreadMessages; }
            set { this._unreadMessages = value; }
        }

        public int TotalMessages
        {
            get { return this._totalMessages; }
            set { this._totalMessages = value; }
        }

        // used so we can sort the folders alphabetically later on
        public int CompareTo(object obj)
        {
            return string.Compare(this.Name, ((Folder)obj).Name);
        }
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic

Namespace WHSMailCommon.Entities
    ' entity object representing an Folder
     _
    Public Class Folder
        Implements IComparable
        Private _entryID As String
        Private _name As String
        Private _folders As List(Of Folder)
        Private _unreadMessages As Integer
        Private _totalMessages As Integer

        Public Sub New(ByVal entryID As String, ByVal name As String, ByVal unreadMessages As Integer, ByVal totalMessages As Integer)
            _entryID = entryID
            _name = name
            _unreadMessages = unreadMessages
            _totalMessages = totalMessages
        End Sub

        ' MAPI unique identifier
        Public Property EntryID() As String
            Get
                Return _entryID
            End Get
            Set(ByVal value As String)
                _entryID = value
            End Set
        End Property

        ' subfolders of this folder
        Public Property Folders() As List(Of Folder)
            Get
                Return _folders
            End Get
            Set(ByVal value As List(Of Folder))
                _folders = value
            End Set
        End Property

        Public Property Name() As String
            Get
                Return _name
            End Get
            Set(ByVal value As String)
                _name = value
            End Set
        End Property

        Public Property UnreadMessages() As Integer
            Get
                Return Me._unreadMessages
            End Get
            Set(ByVal value As Integer)
                Me._unreadMessages = value
            End Set
        End Property

        Public Property TotalMessages() As Integer
            Get
                Return Me._totalMessages
            End Get
            Set(ByVal value As Integer)
                Me._totalMessages = value
            End Set
        End Property

        ' used so we can sort the folders alphabetically later on
        Public Function CompareTo(ByVal obj As Object) As Integer Implements IComparable.CompareTo
            Return String.Compare(Me.Name, (CType(obj, Folder)).Name)
        End Function
    End Class
End Namespace

This class defines several properties to describe the folder (EntryID, Name, etc.) and additionally implements the IComparable interface's CompareTo method so that we can easily sort the folders alphabetically later on.

Next, create a class named Email. The code for this class looks like the following:

using System;
using System.Collections.Generic;
using System.Text;

namespace WHSMailCommon.Entities
{
    // entity object representing an Email
    [Serializable]
    public class Email
    {
        private string _entryID;
        private string _from;
        private string _fromName;
        private string _subject;
        private DateTime _received;
        private int _size;
        private string _body;

        public Email(string entryID, string from, string fromName, string subject, DateTime received, int size)
        {
            _entryID = entryID;
            _from = from;
            _fromName = fromName;
            _subject = string.IsNullOrEmpty(subject) ? "(no subject)" : subject;
            _received = received;
            _size = size;
        }

        public Email(string entryID, string from, string fromName, string subject, DateTime received, int size, string body) :
            this(entryID, from, fromName, subject, received, size)
        {
            _body = body;
        }

        // MAPI unique ID
        public string EntryID
        {
            get { return _entryID; }
            set { _entryID = value; }
        }

        // email address of sender
        public string From
        {
            get { return _from; }
            set { _from = value; }
        }

        // name of sender
        public string FromName
        {
            get { return _fromName; }
            set { _fromName = value; }
        }

        public string Subject
        {
            get { return _subject; }
            set { _subject = value; }
        }

        public string Body
        {
            get { return _body; }
            set { _body = value; }
        }

        public DateTime Received
        {
            get { return _received; }
            set { _received = value; }
        }

        public int Size
        {
            get { return _size; }
            set { _size = value; }
        }
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.Collections.Generic
Imports System.Text

Namespace WHSMailCommon.Entities
    ' entity object representing an Email
     _
    Public Class Email
        Private _entryID As String
        Private _from As String
        Private _fromName As String
        Private _subject As String
        Private _received As DateTime
        Private _size As Integer
        Private _body As String

        Public Sub New(ByVal entryID As String, ByVal From As String, ByVal fromName As String, ByVal subject As String, ByVal received As DateTime, ByVal size As Integer)
            _entryID = entryID
            _from = From
            _fromName = fromName
            If String.IsNullOrEmpty(subject) Then
                _subject = "(no subject)"
            Else
                _subject = subject
            End If
            _received = received
            _size = size
        End Sub

        Public Sub New(ByVal entryID As String, ByVal From As String, ByVal fromName As String, ByVal subject As String, ByVal received As DateTime, ByVal size As Integer, ByVal body As String)
            Me.New(entryID, From, fromName, subject, received, size)
            _body = body
        End Sub

        ' MAPI unique ID
        Public Property EntryID() As String
            Get
                Return _entryID
            End Get
            Set(ByVal value As String)
                _entryID = value
            End Set
        End Property

        ' email address of sender
        Public Property From() As String
            Get
                Return _from
            End Get
            Set(ByVal value As String)
                _from = value
            End Set
        End Property

        ' name of sender
        Public Property FromName() As String
            Get
                Return _fromName
            End Get
            Set(ByVal value As String)
                _fromName = value
            End Set
        End Property

        Public Property Subject() As String
            Get
                Return _subject
            End Get
            Set(ByVal value As String)
                _subject = value
            End Set
        End Property

        Public Property Body() As String
            Get
                Return _body
            End Get
            Set(ByVal value As String)
                _body = value
            End Set
        End Property

        Public Property Received() As DateTime
            Get
                Return _received
            End Get
            Set(ByVal value As DateTime)
                _received = value
            End Set
        End Property

        Public Property Size() As Integer
            Get
                Return _size
            End Get
            Set(ByVal value As Integer)
                _size = value
            End Set
        End Property
    End Class
End Namespace

This class simply contains properties to describe an email message.

You will note that both of these classes have the [Serializable] attribute attached to them. When objects are passed through WCF, they are serialized at the source and deserialized at the destination. By marking the objects with the [Serializable] attribute, the .NET CLR can do this for us automatically since we are not using any complex data types in our entities.

With our entities out of the way, we can define our contract. Inside the Contracts directory, create a new Interface file named IWHSMailService.

This interface/contract will define three methods: one method to return a tree of objects which represent the folder tree in Outlook (GetFolders), one method to return a list of messages inside that folder (GetMessages), and one method to return the contents of a specific message (GetMessages). The interface will look like the following:

using System.Collections.Generic;
using System.ServiceModel;
using WHSMailCommon.Entities;

namespace WHSMailCommon.Contracts
{
    // list of methods of the WHSMailService service
    [ServiceContract()]
    public interface IWHSMailService
    {
        [OperationContract]
        List GetFolders();

        [OperationContract]
        List GetMessages(string entryID, int numPerPage, int pageNum);

        [OperationContract]
        Email GetMessage(string entryID);
    }
}

Imports Microsoft.VisualBasic
Imports System.Collections.Generic
Imports System.ServiceModel
Imports WHSMailCommon.Entities

Namespace WHSMailCommon.Contracts
    ' list of methods of the WHSMailService service
     _
    Public Interface IWHSMailService
         _
        Function GetFolders() As List(Of Folder)

         _
        Function GetMessages(ByVal entryID As String, ByVal numPerPage As Integer, ByVal pageNum As Integer) As List(Of Email)

         _
        Function GetMessage(ByVal entryID As String) As Email
    End Interface
End Namespace

As with the entities, this interface is also decorated with several attributes. First, any WCF contract interface must be tagged with the [ServiceContract()] attribute to define it as a contract to WCF. Additionally, all methods which will be exposed for consumption by a client must be marked with the [OperationContract] attribute.

The implementation and description of these methods will come later when we write the contract implementation.

Configuration

The final thing to setup on the WCF server is the configuration file. The service can very easily be configured using an application configuration file. Add an Application Configuration file to the project named App.config. Set the contents of the file to the following:

xml version="1.0" encoding="utf-8" ?>
<configuration>
    <system.serviceModel>
        <bindings>
            <netTcpBinding>
                <binding name="NewBinding0">
                    <security mode="None" />
                binding>
            netTcpBinding>
        bindings>
        <services>
            <service name="WHSMailHost.WHSMailService">
                <endpoint address="net.tcp://localhost:12345/IWHSMailService"
                    binding="netTcpBinding" bindingConfiguration="NewBinding0"
                    contract="WHSMailCommon.Contracts.IWHSMailService" />
            service>
        services>
    system.serviceModel>
configuration>

The section defines the services that the WCF host will enable. This creates a single named WHSMailHost.WHSMailService, which is the full name of the service class that we will implement shortly. Inside the tag an endpoint is defined. And endpoint is essentially the "port" on which the client connects. The endpoint defined here is using the net.tcp protocol and is set to listen on the localhost on port 12345 at the name IWHSMailService. The next thing defined is a binding. This sets protocol by which the service will communicate, its configuration, and the contract it implements. The binding configuration named NewBinding0 (a default name) can be found above inside the tag. The only configuration item that is specified is that security will be turned off for communication between the client and server. Given that these two machines will be connecting to each other on your own local network, security is not a great concern. If you were to use this over a real internet connection where the client and server were open to the outside world, you would definitely not want to do this.

There are around several billion other options, protocols, bindings, etc. etc. etc. that can be configured here. At the end of the article you will find several links to WCF documentation that you can explore to learn more about the WCF internals. Also note that you can configure WCF with a windows UI by selecting the Service Configuration Editor application installed with the Windows SDK. You'll find this in the Microsoft Windows SDK program group off your Start menu.

Outlook and MAPI

MAPI (Messaging Application Programming Interface) is what allows one to develop applications and plugins for Microsoft Outlook and other messaging applications which support it (Exchange, Windows Messaging, etc.). We will be using MAPI to get the data we require from Outlook for our application.

Earlier we created a contract named IWHSMailService. This contract will be implemented by the WHSMailService class that was also created earlier. To do this, set a reference to the project's WHSMailCommon assembly. Then, bring the Contracts and Entities namespaces into the WHSMailService class with the following:

using WHSMailCommon.Contracts;
using WHSMailCommon.Entities;

Imports WHSMailCommon.Contracts
Imports WHSMailCommon.Entities

Then, setup the class to implement the interface as follows:

public class WHSMailService : IWHSMailService

Public Class WHSMailService
    Implements IWHSMailService

Visual Studio will then create the 3 methods that must be implemented according to the interface (GetFolders, GetMessages, GetMessage). We will fill those in shortly. But first, we must implement our constructor. When WCF calls the service, a new instance of the object will be created on each call. Therefore, it is easy to setup any initialization code for the service in the default constructor method. In this case, we will initialize the MAPI layer and logon to the default instance.

First, set a reference to the Microsoft Outlook XX.0 Object Library which you will find under the COM tab assuming Outlook is installed as per the instructions above. Note that the version will depend on what version of Outlook you have installed on your local machine. I'm using Outlook 2007, so version 12 is what the sample code above is referencing. If you are using a different version, reference the appropriate version before continuing.

Once the reference is set, bring the namespace into the WHSMailService class with the following line which will import the namespace and setup an alias named Outlook to save some typing:

using Outlook = Microsoft.Office.Interop.Outlook;

Imports Outlook = Microsoft.Office.Interop.Outlook

Now the constructor can be implemented. We need to get an instance of the Outlook ApplicationClass. From there we can get an instance of the MAPI namespace. All methods that we will be using hang off that namespace object. The code for the constructor follows:

private readonly Outlook.NameSpace _nameSpace = null;

public WHSMailService()
{
    // get an instance of the MAPI namespace and login
    Outlook.Application app = new Outlook.ApplicationClass();
    _nameSpace = app.GetNamespace("MAPI");
    _nameSpace.Logon(null, null, false, false);
}

Private ReadOnly _nameSpace As Outlook.NameSpace = Nothing

Public Sub New()
    ' get an instance of the MAPI namespace and login
    Dim app As Outlook.Application = New Outlook.ApplicationClass()
    _nameSpace = app.GetNamespace("MAPI")
    _nameSpace.Logon(Nothing, Nothing, False, False)
End Sub

With a handle to the namespace, we can write our GetFolders method. This method will get the default Inbox folder in the default Outlook message store, look at the parent node, recursively enumerate from there, pulling out only folders that contain mail items, and finally sort them alphabetically (recall the CompareTo method of the IComparable interface we implemented earlier).

public List GetFolders()
{
    List list = new List();

    // get the inbox and then go up one level...that *should* be the root of the default store
    Outlook.MAPIFolder root = (Outlook.MAPIFolder)_nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox).Parent;

    // add root folder
    Folder folder = new Folder(root.EntryID, root.Name, root.UnReadItemCount, root.Items.Count);
    list.Add(folder);

    // Enumerate the sub-folders
    EnumerateFolders(root.Folders, folder);

    return list;
}

private void EnumerateFolders(Outlook.Folders folders, Folder rootFolder)
{
    foreach(Outlook.MAPIFolder f in folders)
    {
        // ensure it's a folder that contains mail messages (i.e. no contacts, appointments, etc.)
        if(f.DefaultItemType == Outlook.OlItemType.olMailItem)
        {
            if(rootFolder.Folders == null)
                rootFolder.Folders = new List();

            // add the current folder and enumerate all sub-folders
            Folder subFolder = new Folder(f.EntryID, f.Name, f.UnReadItemCount, f.Items.Count);
            rootFolder.Folders.Add(subFolder);
            if(f.Folders.Count > 0)
                this.EnumerateFolders(f.Folders, subFolder);
        }
    }

    // alphabetize the list (Folder implements IComparable)
    rootFolder.Folders.Sort();
}

Public Function GetFolders() As List(Of Folder) Implements IWHSMailService.GetFolders
    Dim list As List(Of Folder) = New List(Of Folder)()

    ' get the inbox and then go up one level...that *should* be the root of the default store
    Dim root As Outlook.MAPIFolder = CType(_nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox).Parent, Outlook.MAPIFolder)

    ' add root folder
    Dim folder As Folder = New Folder(root.EntryID, root.Name, root.UnReadItemCount, root.Items.Count)
    list.Add(folder)

    ' Enumerate the sub-folders
    EnumerateFolders(root.Folders, folder)

    Return list
End Function

Private Sub EnumerateFolders(ByVal folders As Outlook.Folders, ByVal rootFolder As Folder)
    For Each f As Outlook.MAPIFolder In folders
        ' ensure it's a folder that contains mail messages (i.e. no contacts, appointments, etc.)
        If f.DefaultItemType = Outlook.OlItemType.olMailItem Then
            If rootFolder.Folders Is Nothing Then
                rootFolder.Folders = New List(Of Folder)()
            End If

            ' add the current folder and enumerate all sub-folders
            Dim subFolder As Folder = New Folder(f.EntryID, f.Name, f.UnReadItemCount, f.Items.Count)
            rootFolder.Folders.Add(subFolder)
            If f.Folders.Count > 0 Then
                Me.EnumerateFolders(f.Folders, subFolder)
            End If
        End If
    Next f

    ' alphabetize the list (Folder implements IComparable)
    rootFolder.Folders.Sort()
End Sub

This code will return a generic hierarchal list of our Folder entity objects which will be displayed in the web application. Note that one of the items assigned to the Folder entity is the EntryID property from the MAPIFolder object. All MAPI items, be they email messages, folders, appointments, etc. have a unique identifier which is stored in the EntryID field. We will need this unique value later on to retrieve messages from that folder.

Next, let's implement the GetMessages method. This method will return a list of messages (minus the bodies) from the folder specified using the GetFolderFromID method, sorted by the received date with the most current first. It will also handle paging so that the entire folder is not returned at once.

public List GetMessages(string entryID, int numPerPage, int pageNum)
{
    List list = new List();

    Outlook.MAPIFolder f;

    // if no ID specified, open the inbox
    if(string.IsNullOrEmpty(entryID))
        f = _nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox);
    else
        f = _nameSpace.GetFolderFromID(entryID, "");

    // to handle the sorting, one needs to cache their own instance of the items object
    Outlook.Items items = f.Items;

    // sort descending by received time
    items.Sort("[ReceivedTime]", true);

    // pull in the correct number of items based on number of items per page and current page number
    for(int i = (numPerPage*pageNum)+1; i <= (numPerPage*pageNum)+numPerPage && i <= items.Count; i++)
    {
        // ensure it's a mail message
        Outlook.MailItem mi = (items[i] as Outlook.MailItem);
        if(mi != null)
            list.Add(new Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size));
    }

    return list;
}

Public Function GetMessages(ByVal entryID As String, ByVal numPerPage As Integer, ByVal pageNum As Integer) As List(Of Email) Implements IWHSMailService.GetMessages
    Dim list As List(Of Email) = New List(Of Email)()

    Dim f As Outlook.MAPIFolder

    ' if no ID specified, open the inbox
    If String.IsNullOrEmpty(entryID) Then
        f = _nameSpace.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
    Else
        f = _nameSpace.GetFolderFromID(entryID, "")
    End If

    ' to handle the sorting, one needs to cache their own instance of the items object
    Dim items As Outlook.Items = f.Items

    ' sort descending by received time
    items.Sort("[ReceivedTime]", True)

    ' pull in the correct number of items based on number of items per page and current page number
    Dim i As Integer = (numPerPage*pageNum)+1
    Do While i <= (numPerPage*pageNum)+numPerPage AndAlso i <= items.Count
        ' ensure it's a mail message
        Dim mi As Outlook.MailItem = (TryCast(items(i), Outlook.MailItem))
        If Not mi Is Nothing Then
            list.Add(New Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size))
        End If
        i += 1
    Loop

    Return list
End Function

The method takes a string parameter named entryID which is the unique identifier of the folder (from the code above) from which to return the messages. If no ID is specified, messages are returned from the Inbox. This code also handles paging by indexing into the array of Items of the MAPIFolder object at the specified position and counting out numPerPage records to be returned. A list of Email entity objects is returned from this method to be displayed on the web interface.

Finally, let's implement the GetMessage method. This will return a specific message based on the MAPI EntryID using the GetItemFromID method and format the body for plain text or HTML display.

public Email GetMessage(string entryID)
{
    // pull the message
    Outlook.MailItem mi = (_nameSpace.GetItemFromID(entryID, "") as Outlook.MailItem);

    if (mi != null)
    {
        string body;

        // if it's a plain format message, wrap it in  tags for nice output
        if(mi.BodyFormat == Outlook.OlBodyFormat.olFormatPlain)
            body = "" + mi.Body + "
";
        else
            body = mi.HTMLBody;

        return new Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size, body);
    }
    else
        return null;
}

Public Function GetMessage(ByVal entryID As String) As Email Implements IWHSMailService.GetMessage
    ' pull the message
    Dim mi As Outlook.MailItem = (TryCast(_nameSpace.GetItemFromID(entryID, ""), Outlook.MailItem))

    If Not mi Is Nothing Then
        Dim body As String

        ' if it's a plain format message, wrap it in  tags for nice output
        If mi.BodyFormat = Outlook.OlBodyFormat.olFormatPlain Then
            body = "" & mi.Body & "
"
        Else
            body = mi.HTMLBody
        End If

        Return New Email(mi.EntryID, mi.SenderEmailAddress, mi.SenderName, mi.Subject, mi.ReceivedTime, mi.Size, body)
    Else
        Return Nothing
    End If
End Function

With these three methods in place, we can get our folders, get messages in those folders, and get a specific message from a folder. Now we can switch our attention to the web-based "client" application which will plug into WHS.

ASP.NET "Client"

The client we are going to produce is going to be a very simple 3-paned screen much like Outlook with folders on the left, messages on the top right, and message text on the bottom right.

Create a new ASP.NET Web Application named WHSMailWeb (if you are using the Express editions of Visual Studio, you will need to do this in Visual Web Developer Express). Set a reference to the WHSMailCommon assembly along with the System.ServiceModel assembly. Again, if you are in Express, you will have to set the reference to WHSMailCommon in the other project's bin directory.

First, let's configure the ASP.NET application so it can properly call our WCF service running on the host machine. Open the web.config file and add the following after the end tag and before the end tab:

<system.serviceModel>
    <bindings>
        <netTcpBinding>
            <binding name="NewBinding0" maxReceivedMessageSize="1048576">
                <readerQuotas maxStringContentLength="1048576" />
                <security mode="None" />
            binding>
        netTcpBinding>
    bindings>
    <client>
        <endpoint address="net.tcp://SERVERNAME:12345/IWHSMailService"
            binding="netTcpBinding" bindingConfiguration="NewBinding0"
            contract="WHSMailCommon.Contracts.IWHSMailService" name="WHSMailService" />
    client>
system.serviceModel>

This looks very similar to the configuration information from our host service. An endpoint is defined which points to the host server. YOU WILL NEED TO CHANGE THE "SERVERNAME" HOST TO THE NAME OR IP ADDRESS OF THE MACHINE THAT WILL RUN THE HOST SERVICE WE CREATED ABOVE!

You will see the same setup for the binding and contract. The name parameter will be used by the code a bit later so WCF knows how to contact the host to instantiate the remote object.

The one thing that is different here is the netTcpBinding configuration. The security mode is set to none as it was before, but we have the addition of the maxReceivedMessageSize and maxStringContentLength. Both of these are set at 1 megabyte to allow that much data to be transferred from the host to the client. The default is only 64K which is not enough to return most of the data we need to serialize and transmit between the two machines.

Next, add a page to the project named BasePage. This page will be inherited by all pages in the project to easily startup and shutdown the WCF channel required to retrieve the message data.

Open the code-behind file for BasePage and add the following code:

using System;
using System.ServiceModel;
using WHSMailCommon.Contracts;

namespace WHSMailWeb
{
    public partial class BasePage : System.Web.UI.Page
    {
        ChannelFactory _factory = null;
        private IWHSMailService _channel = null;

        protected void Page_Init(object sender, EventArgs e)
        {
            // create a channel factory and then instantiate a proxy channel
            _factory = new ChannelFactory("WHSMailService");
            _channel = _factory.CreateChannel();
        }

        protected void Page_Unload(object sender, EventArgs e)
        {
            try
            {
                _factory.Close();
            }
            catch
            {
                // for the moment, we don't really care what happens here...if it fails, so be it
            }
        }

        public IWHSMailService WHSMailService
        {
            get { return _channel; }
        }
    
    }
}

Imports Microsoft.VisualBasic
Imports System
Imports System.ServiceModel
Imports WHSMailCommon.Contracts

Namespace WHSMailWeb
    Public Partial Class BasePage
        Inherits System.Web.UI.Page
        Private _factory As ChannelFactory(Of IWHSMailService) = Nothing
        Private _channel As IWHSMailService = Nothing

        Protected Sub Page_Init(ByVal sender As Object, ByVal e As EventArgs)
            ' create a channel factory and then instantiate a proxy channel
            _factory = New ChannelFactory(Of IWHSMailService)("WHSMailService")
            _channel = _factory.CreateChannel()
        End Sub

        Protected Sub Page_Unload(ByVal sender As Object, ByVal e As EventArgs)
            Try
                _factory.Close()
            Catch
                ' for the moment, we don't really care what happens here...if it fails, so be it
            End Try
        End Sub

        Public ReadOnly Property WHSMailService() As IWHSMailService
            Get
                Return _channel
            End Get
        End Property

    End Class
End Namespace

This code overrides the page's Init and Unload methods. Page_Init is called at the beginning of a page request and Page_Unload is called just before the request completes.

The Page_Init method here uses WCF to create a ChannelFactory object factory that will return proxy objects of type IWHSMailService. Recall that this is the interface which defines the contract of our service. The name passed as a parameter to the ChannelFactory constructor must match the name of the service in the configuration file, as discussed earlier.

Next, a channel object is created by calling CreateChannel from the ChannelFactory. This is what returns the fake, proxy object defined by our contract. A property named WHSMailService at the bottom of the class exposes this so that the inherited pages can easily use the object to call the host service. We'll see this a bit later.

The Page_Unload method simply closes the factory object and very poorly handles any exceptions that may occur when doing so. An error on close isn't critical to this application, but that is certainly not always the case.

Now we will implement the default page. I'm not going to repeat the entire HTML of the page itself here, and I'm certainly not a HTML/CSS designer, so I wouldn't recommend learning from that anyhow. It does, however, get the job done.

What you do need to know is that the page contains 4

tags: one contains an ASP.NET TreeView object (the left-most pane), one contains an ASP.NET GridView object (the top-right pane), one contains 2 ASP.NET LinkButton's which implement a Next/Back paging scheme (the middle-right pane), and the last contains a table to display some header information, and a

to display the message contents.

After that poor description, here's what the application looks like in an instance of Internet Explorer with my instance of Outlook (with some blurring over the (not really) sensitive data):

Now let's implement the actual logic for the page. Open the Default.aspx page's code behind file. Bring in the WHSMailCommon.Entities namespace as follows:

using WHSMailCommon.Entities;

Imports WHSMailCommon.Entities

Next, change the _Default class to inherit from BasePage instead of System.Web.UI.Page:

public partial class _Default : BasePage

Public Partial Class _Default
    Inherits BasePage

Then, implement the Page_Load method. This method will be called after the Page_Init method which is implemented in our parent object and will be called automatically.

private string _folderEntryID = string.Empty;
private int _pageNum = 0;

protected void Page_Load(object sender, EventArgs e)
{
    // first time in (tvFolders has viewstate enabled
    if(tvFolders.Nodes.Count == 0)
    {
        // get the folder tree
        List folderList = this.WHSMailService.GetFolders();

        // add the root node and expand it
        TreeNode node = new TreeNode(folderList[0].Name, folderList[0].EntryID);
        node.Expanded = true;
        tvFolders.Nodes.Add(node);

        // load up the sub-folders
        LoadNode(folderList[0].Folders, node);

        // get the inbox list and bind it to the grid
        List list = GetMessages();
        BindMessages(list);

        // save off the default page number and folder ID
        ViewState["PageNum"] = _pageNum;
        ViewState["FolderID"] = _folderEntryID;
    }

    _pageNum = int.Parse(ViewState["PageNum"].ToString());
    _folderEntryID = ViewState["FolderID"].ToString();
}

private void LoadNode(List folders, TreeNode node)
{
    foreach(Folder f in folders)
    {
        // add the node with the format of Folder (Unread/Total)
        TreeNode subNode = new TreeNode(f.Name + " (" + f.UnreadMessages + "/" + f.TotalMessages + ")", f.EntryID);

        // expand and select the inbox
        subNode.Expanded = subNode.Selected = (f.Name == "Inbox");
        node.ChildNodes.Add(subNode);

        // load the subfolders
        if(f.Folders != null)
            LoadNode(f.Folders, subNode);
    }
}

private List GetMessages()
{
    // get a group of messages based on the current page number and size
    return this.WHSMailService.GetMessages(_folderEntryID, GridView1.PageSize, _pageNum);
}

private void BindMessages(List list)
{
    // load the grid
    GridView1.DataSource = list;
    GridView1.DataBind();

    // save off the new page number
    ViewState["PageNum"] = _pageNum;
}

Private _folderEntryID As String = String.Empty
Private _pageNum As Integer = 0

Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
    ' first time in (tvFolders has viewstate enabled
    If tvFolders.Nodes.Count = 0 Then
        ' get the folder tree
        Dim folderList As List(Of Folder) = Me.WHSMailService.GetFolders()

        ' add the root node and expand it
        Dim node As TreeNode = New TreeNode(folderList(0).Name, folderList(0).EntryID)
        node.Expanded = True
        tvFolders.Nodes.Add(node)

        ' load up the sub-folders
        LoadNode(folderList(0).Folders, node)

        ' get the inbox list and bind it to the grid
        Dim list As List(Of Email) = GetMessages()
        BindMessages(list)

        ' save off the default page number and folder ID
        ViewState("PageNum") = _pageNum
        ViewState("FolderID") = _folderEntryID
    End If

    _pageNum = Integer.Parse(ViewState("PageNum").ToString())
    _folderEntryID = ViewState("FolderID").ToString()
End Sub

Private Sub LoadNode(ByVal folders As List(Of Folder), ByVal node As TreeNode)
    For Each f As Folder In folders
        ' add the node with the format of Folder (Unread/Total)
        Dim subNode As TreeNode = New TreeNode(f.Name & " (" & f.UnreadMessages & "/" & f.TotalMessages & ")", f.EntryID)

        ' expand and select the inbox
        subNode.Selected = (f.Name = "Inbox")
        subNode.Expanded = subNode.Selected
        node.ChildNodes.Add(subNode)

        ' load the subfolders
        If Not f.Folders Is Nothing Then
            LoadNode(f.Folders, subNode)
        End If
    Next f
End Sub

Private Function GetMessages() As List(Of Email)
    ' get a group of messages based on the current page number and size
    Return Me.WHSMailService.GetMessages(_folderEntryID, GridView1.PageSize, _pageNum)
End Function

Private Sub BindMessages(ByVal list As List(Of Email))
    ' load the grid
    GridView1.DataSource = list
    GridView1.DataBind()

    ' save off the new page number
    ViewState("PageNum") = _pageNum
End Sub

If the tvFolders tree-view has not been filled in, we call our host service's GetFolders method from the WHSMailService property as defined above. The method then enumerates through the hierarchical list of folders returned, building the same tree structure that exists in Outlook. The Text property of each TreeNode is set to the folder name with a count of messages unread and total count of messages. The Value property of the node is set to the unique MAPI-defined EntryID so that we can later grab that value to return the list of messages from that specific folder.

Next, we call our service's GetMessages method to return messages from the Inbox. We pass in the value from the grid view's PageSize property and a member variable named _pageNum. This will handle our paging scheme as we discussed earlier. Once that list of messages is returned, is it bound to the data grid for display.

Finally, the default page number and folder entry ID (0 and "" respectively) are stored in the ViewState so they can be assigned back to our member variables on each page request.

If you were to run the application right now, you would see the same page that you do above, minus the message text at the bottom.

Next, we will implement what occurs when a user clicks on a folder in the tree view. We simply pull out the MAPI unique EntryID which is stored in the Value field of the selected node, assign it to the local member variable and view state, and then call the GetMessages method from our service to return a list of messages from that folder, just as we did with the inbox above. The code below shows the process:

protected void tvFolders_SelectedNodeChanged(object sender, EventArgs e)
{
    // new folder, so reset the view
    _pageNum = 0;
    _folderEntryID = this.tvFolders.SelectedNode.Value;
    ViewState["FolderID"] = _folderEntryID;

    List list = GetMessages();
    BindMessages(list);
}

Protected Sub tvFolders_SelectedNodeChanged(ByVal sender As Object, ByVal e As EventArgs)
    ' new folder, so reset the view
    _pageNum = 0
    _folderEntryID = Me.tvFolders.SelectedNode.Value
    ViewState("FolderID") = _folderEntryID

    Dim list As List(Of Email) = GetMessages()
    BindMessages(list)
End Sub

Next, we can implement the Next/Back link buttons. These methods simply increment or decrement the current page number, assign it to the view state for use on the next request, and then, just as before, gets the list of messages specific to the currently selected folder, using the unique ID stored in the view state.

protected void btnPrev_Click(object sender, EventArgs e)
{
    // first page
    if(_pageNum > 0)
        _pageNum--;

    List list = GetMessages();
    BindMessages(list);
}

protected void btnNext_Click(object sender, EventArgs e)
{
    // next page
    _pageNum++;
    List list = GetMessages();

    // if we're out of messages, go back to the previous page
    if(list == null || list.Count == 0)
    {
        _pageNum--;
        list = GetMessages();
    }
    BindMessages(list);
}

Protected Sub btnPrev_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' first page
    If _pageNum > 0 Then
        _pageNum -= 1
    End If

    Dim list As List(Of Email) = GetMessages()
    BindMessages(list)
End Sub

Protected Sub btnNext_Click(ByVal sender As Object, ByVal e As EventArgs)
    ' next page
    _pageNum += 1
    Dim list As List(Of Email) = GetMessages()

    ' if we're out of messages, go back to the previous page
    If list Is Nothing OrElse list.Count = 0 Then
        _pageNum -= 1
        list = GetMessages()
    End If
    BindMessages(list)
End Sub

And finally, we need to implement what happens when the user selects a message from the top pane. If you look at the HTML for the Default page, you will see that the Subject field is bound to a LinkButton control in the grid view via a TemplateField (the rest of the fields are standard BoundFields. The LinkButton sets the CommandArgument property to the unique EntryID of that message as defined by MAPI. So, all we need to do is listen on the server for the LinkButton's Command event, grab the unique ID and call our service's GetMessage method with that ID to return the message itself.

protected void btnLink_Command(object sender, CommandEventArgs e)
{
    Email email = this.WHSMailService.GetMessage(e.CommandArgument.ToString());

    // fill out the header with some basic info
    lblFrom.Text = email.FromName + " (" + email.From + ")";
    lblSubject.Text = email.Subject;
    lblReceived.Text = email.Received.ToString();

    // when a message is selected, write out the content
    msgContent.InnerHtml = email.Body;
}

Protected Sub btnLink_Command(ByVal sender As Object, ByVal e As CommandEventArgs)
    Dim email As Email = Me.WHSMailService.GetMessage(e.CommandArgument.ToString())

    ' fill out the header with some basic info
    lblFrom.Text = email.FromName & " (" & email.From & ")"
    lblSubject.Text = email.Subject
    lblReceived.Text = email.Received.ToString()

    ' when a message is selected, write out the content
    msgContent.InnerHtml = email.Body
End Sub

The Email entity is retrieved, its properties are set to the labels in the header, and the message content is assigned to the InnerHtml property of the content holding

Voila! A very simple mail reader.

That's it for code. Now we need to deploy the applications and configure Windows Home Server.

Deployment

WHSMailHost

If you are deploying to a machine that is not your development machine, install the .NET Framework 3.0 runtime on the machine to which you will be running the host service. Then, copy the WHSMailHost.exe, WHSMailHost.exe.config, and WHSMailCommon.dll files to the machine running Outlook that will be connected to by the web application. You may want to create a shortcut in the Startup group so it will launch when you log into Windows.

Next, open Outlook and select Trust Center from the Tools menu. Choose Programmatic Access and set the option to Never warn me about suspicious activity. Unfortunately this must be disabled, otherwise Outlook will prompt you every time the host process attempts to retrieve any data. There is no way to bypass this on an application-by-application basis, so we have to turn it off for all applications.

If you are running firewall software on the PC, ensure that port 12345 will allow traffic to pass through. You may also change port 12345 to a different port, but you must change it in the configuration files for both applications.

Finally, note that Outlook does not need to remain open to use this application. You do, however, need to be logged into the machine with the host running.

WHSMailWeb

On your Windows Home Server machine, install the .NET Framework 3.0 Runtime. This is needed to use WCF. Next, create a new directory named mail (or anything you wish, but it is assumed it is named mail) in the c:\inetpub directory. Copy all .aspx pages, web.config, icon.png and the bin directory to the mail directory. You could also share out the mail directory and use Visual Studio's Publish command to automatically copy the files to that share. Then, open the Internet Information Services (IIS) Manager application from the Administrative Tools group on the Start menu. Open Web Sites and then Default Web Site in the left pane. Right-click on Default Web Site and select New -> Virtual Directory... from the context menu. When prompted, use the following values:

Alias	mail
Path	c:\inetpub\mail
Permissions	Read, Run Scripts

The next part is a bit tricky. We want to integrate with the security already provided by Windows Home Server. The WHS remote website uses Forms security from ASP.NET. Ideally, you should be able to log into the main page of the WHS remote website and then open the webmail link without having to log in again. Additionally, if the mail URL is used directly, you should be prompted for your login credentials.

To achieve this, open the web.config file from c:\inetpub\remote in Notepad. In the XML, between the start and end tags you will find the configuration for the Forms-based authentication used by WHS. In order to use the cookie that is created by this authentication method, we need to have the same key values in our web.config file. The easiest way to achieve this is to copy all of the the text between the two tags. Next, open the web.config file from the mail directory that you just copied over and paste the text between the two lines informing you to do so. Finally, we need to update the loginUrl and defaultRedirect paths in the forms and customErrors keys. Add /remote/ to the beginning of each to make them /remote/login.aspx and /remote/error.aspx. Be sure that the SERVERNAME item in the endpoint configuration is updated to the name/IP address of the machine running the host process.

With the files copied and edited, ensure that permissions on the file are propagated from the root mail directory to the files inside.

Finally, open the websites.xml file in the /remote directory and add the following XML before the end tag:

<WebSite name="Outlook Webmail" uri="/mail" imageUrl="/mail/icon.png" absolute="false">WebSite>

With the configuration done, we need to enable web site connectivity in WHS. Double-click the Windows Home Server Console icon on the desktop. When it loads, click the Settings button in the top right corner. When the Settings dialog appears, select Remote Access in the left pane and then click the Turn On button in the right pane, assuming web site connectivity is off. If it already enabled, skip this step.

With all that done, create a user account for yourself in WHS so that you can login remotely. That's it!

Running the Application

Ensure the WHSMailHost application is running on the PC with Outlook installed. Then, browse to your Windows Home Server's default website. After logging in, you should see a link on the right side of the screen named Outlook Webmail.

Click that to start our application and if everything is working, you should see the web page as shown above.

Troubleshooting

If the web page displays an error message, open the web.config file in the mail directory on your Windows Home Server. Look for the tag and change the mode parameter to Off. This should allow you to see the actual error that is occurring and provide more information as to the status of the application.

Conclusion

Phew! Two applications and one shared assembly later, we have a web-based add-in for Windows Home Server that allows one to remotely access their Outlook message store. Currently the application is read-only and provides only minimal functionality. It's a great starting point to create a full-fledged webmail client interface. The project is hosted on CodePlex so I'm hoping to see you readers implement additional features and functionality that you find useful.

Additional Information

Here are a few links with additional information on the items discussed here:

Bio

Brian is a Microsoft C# MVP and a recognized .NET expert with over 6 years experience developing .NET solutions, and over 9 years of professional experience architecting and developing solutions using Microsoft technologies and platforms, although he has been "coding for fun" for as long as he can remember. Outside the world of .NET and business applications, Brian enjoys developing both hardware and software projects in the areas of gaming, robotics, and whatever else strikes his fancy for the next ten minutes. He rarely passes up an opportunity to dive into a C/C++ or assembly language project. You can reach Brian via his blog at http://www.brianpeek.com/.

Amazon Mobile: Book Shopping from your Smartphone

Will Danford — Sat, 23 Dec 2006 14:32:19 GMT

	This article walks the reader through the development of a Windows Mobile 5.0 application that interacts with Amazon's E-Commerce Service (ECS). I cover set up of the development environment and much of the code that is needed. Readers can download the C# or VB.NET source code that accompanies the article.
Will Danford Clarity Consulting Difficulty: Intermediate Time Required: 3-6 hours Cost: Greater than $200 Software: ActiveSync 4.2 .NET Compact Framework Windows Mobile 5.0 SDK Hardware: Motorola Q Download: C# Download VB Download

Introduction

In this article I'll examine part of Amazon's web service functionality and use the new Pocket Outlook API to create a useful application for the Windows Mobile 5.0 Smartphone. The current version of the application lets the user search Amazon's inventory, view book details, create and edit a cart, and checkout from the device. A Pocket Outlook task is used to store the cart's checkout link.

Development Environment

I wrote Amazon Mobile using Visual Studio 2005 Professional and a Motorola Q Smartphone running Windows Mobile 5.0. Windows Mobile devices use Microsoft's ActiveSync software to synchronize with a desktop, so you'll need to have it installed to set up the environment on the phone. Next you'll need the .NET Compact Framework, since this application is written in managed code. Lastly, download the appropriate software development kit (SDK) for your platform. I installed the Windows Mobile 5.0 SDK for Smartphone because I am writing code for the Q. If you are using a Pocket PC device you should download and install the Pocket PC version. The rest of this article will assume that you are writing a Smartphone application, but if that is not the case you will find it easy enough to follow along using a Pocket PC device.

Readers who are not familiar with Amazon's web service may find it helpful to review Peter Bernhardt's introduction in this previous Coding4Fun article. I used ECS version 4.0 for this project. You won't have to download an SDK as in version 3.0, but you will need to create an account with Amazon to get a unique access key. Make sure to replace the “Your Access Key Here” string in Constants.cs with your own access key before running my code.

Once you've set up your dev environment, start by creating a new project for your application. Select New > Project from Visual Studio's File menu. You'll find the Device Application template under Visual C# > Smart Device > Windows Mobile 5.0 Smartphone in the Project Types tree on the left side of the New Project dialog.

Figure 1: The New Project dialog.

Visual Studio will use the default resolution and DPI settings of the current “form factor” to create the form you see in the designer. If you open a project written for a device with a 320x240 screen (such as the project I wrote for this article) before changing the settings, the IDE will move or resize the contents of the forms to make them fit the smaller 176x220 resolution. You can prevent this by changing the designer's form factor to match that of the Q. Choose Tools > Options, and then expand “Device Tools” in the tree on the left side of the dialog and select “Form Factors.” Find “Windows Mobile 5.0 Smartphone” in the menu and edit its properties. Clear the “Enable rotation support” checkbox and make sure that both the horizontal and vertical resolutions are set to 131 pixels per inch. Now clear the “Show Skin” checkbox and enter 320 for the screen width and 240 for the screen height. You can save this form factor with a new name, such as “MotoQ,” and make it your default if you prefer.

Writing the Application

Now let's get started in the code. First you'll need to add a reference to Amazon's Web Services Definition (Description) Language (WSDL). The web reference wizard will use the WSDL to create a proxy class that you'll use to access the service's functionality. Right-click on “Web References” in Solution Explorer, select “Add Web Reference” and enter the address of the WSDL as shown in the figure below.

Figure 2: Feel free to change the unwieldy name that Visual Studio assigns your Web reference.

Visual Studio has created a startup form that, by default, is the entry and exit point for your application. This form is a great place to accept search criteria from the user and display the results you get back from the web service. Find the Toolbox and add a TextBox control to your form to capture the user's input. You'll also need a ListView control to display the results. The softkey menu that's built into the default Smartphone form is a convenient way to let the user start the search. Add a MenuItem and handle its click event to call the search method you're about to write.

Figure 3: The SearchForm.

Make sure you've set a reference to the namespace created by the WSDL wizard in a using statement at the top of your code. To perform a keyword search against Amazon's product database, start by creating an ItemSearchRequest object and setting a few of its properties. ItemSearchRequest is declared as a partial class in the web reference's Reference.cs file, along with all of the other ECS classes. Here is the code I used to set up the search:

Imports AmazonMobile.com.amazon.webservices

...

       Private Sub PerformSearch(ByVal searchText As String)
            Dim aws As New AWSECommerceService()

            ' set up the request
            Dim itemSearchRequest As New ItemSearchRequest()
            itemSearchRequest.Keywords = searchText
            itemSearchRequest.SearchIndex = "Books"
            itemSearchRequest.ResponseGroup = New String() {"ItemAttributes"}
            itemSearchRequest.ItemPage = "1"

            Dim itemSearch As New ItemSearch()
            itemSearch.Request = New ItemSearchRequest(0) {itemSearchRequest}
            itemSearch.SubscriptionId = Constants.AMAZON_ACCESS_KEY

using AmazonMobile.com.amazon.webservices;

...

private void PerformSearch(string searchText)
{
    Cursor.Current = Cursors.WaitCursor;
    
    // clear out old results
    resultsView.Clear();

    AWSECommerceService aws = new AWSECommerceService();
    
    // set up the request
    ItemSearchRequest itemSearchRequest = new ItemSearchRequest();
    itemSearchRequest.Keywords = searchText;
    itemSearchRequest.SearchIndex = "Books";
    itemSearchRequest.ResponseGroup = new string[] { "ItemAttributes" };
    itemSearchRequest.ItemPage = "1";
    
    ItemSearch itemSearch = new ItemSearch();
    itemSearch.Request = new ItemSearchRequest[1] { itemSearchRequest };
    itemSearch.SubscriptionId = Constants.AMAZON_ACCESS_KEY;

Notice that I've set the ResponseGroup property to a string array containing the string “ItemAttributes.” The web service uses the values in this array to determine the subset of fields it should populate in the response object. You'll find a list of all possible options in the web service's documentation, a helpful guide to the functionality that the service exposes. Now you can ask the web service to perform the search.

// perform the search
ItemSearchResponse itemSearchResponse = aws.ItemSearch(itemSearch);
Items[] itemsResponse = itemSearchResponse.Items;

'perform the search
Dim response As ItemSearchResponse = aws.ItemSearch(itemSearch)
Dim itemsResponse As Items() = response.Items

Almost every interaction with ECS will follow the straightforward pattern you've just seen. First, create and set the properties of one or more request objects. Next, create the appropriate search object and use its properties to wrap one or more request objects, as well as your ECS access key. Finally, pass the search object to the appropriate web service method. The results of your request will be encapsulated by the object that is returned from the web service. You'll use the response object's properties to access the information that you want to display. Loop through the response object's Item collection, adding a new ListViewItem to the ListView's Items collection for each of the results. You can use the ListViewItem's Tag property to store the item's Amazon Standard Identification Number (ASIN) for future reference. In most cases, a book's ASIN is simply its ISBN.

The next step is creating a form to lookup any offers that might be associated with a search result. Right-click on the project node in Solution Explorer and select Add > Windows Form from the context menu. Give your form a name and click “Add” to create it in your project. For the offer form you'll probably want a ListView control to display the results of your lookup operation, as well as a few menu items at the bottom of the form for navigation. If you add a back button to the menu to return to the previous form the button's event handler should call the form's Close method.

In my code I construct an OfferForm using an ASIN string, which simply sets an instance variable to track the book associated with the current instance of the form. Your application will use a book's ASIN to lookup offers. You already know the item's ASIN, so you should create an ItemLookupRequest, in this case, instead of the ItemSearchRequest that you used to perform the initial search. You'll need to set the properties of one or more of the request objects and then set the ItemLookup's Request property as I did above. Finally, call the ItemLookup method on your instance of the web service and use the resulting ItemLookupResponse object to populate the ListView object. I suggest doing all this in a method that can be called by the form's Load event handler rather than the constructor. That way you'll avoid any conflicts that might occur if the form has not finished initializing its controls when you begin setting their properties.

Next you need a method to create a cart when the user selects an offer and since you don't want to create a new cart every time, you'll also want to be able to add an offer to a cart that already exists. A mechanism for writing information about a cart to the file system would be helpful. These are the functions of the Settings and SettingsManager classes that I've created to store the cart's ID and HMAC key. Take a look at the OnAddItem, CreateCart and GetCart methods to see how I implemented add and edit operations for the cart.

Amazon cart response objects have a PurchaseURL property that contains a URL string used to access the cart's checkout page. Once you have a cart with at least one item you should provide the user with access to this URL. I wanted to make use of the new Pocket Outlook API, so I added a Checkout method that stores the cart's purchase URL in the Body property of a new Pocket Outlook task. The Task class is part of the Microsoft.WindowsMobile.PocketOutlook namespace, so you'll need to add another reference to your project. Once you've done so, creating and adding a new task is simple:

Imports Microsoft.WindowsMobile.PocketOutlook

...

        Private Sub Checkout()
            ' warn the user that the cart will no longer be accessible
            If MessageBox.Show(Constants.MESSAGE_CHECKOUT_CONFIRMATION, Constants.CAPTION_CHECKOUT, MessageBoxButtons.OKCancel, MessageBoxIcon.None, MessageBoxDefaultButton.Button1) = Windows.Forms.DialogResult.OK Then
                ' Outlook Session implements IDisposable...
                Dim session As New OutlookSession()
                Try
                    Dim task As New Task()
                    task.Body = String.Format(Constants.MESSAGE_TASK_BODY, _purchaseUrl)
                    task.Subject = String.Format("{0}, {1}", Constants.CAPTION_CHECKOUT, DateTime.Now.ToLocalTime())
                    task.Complete = False
                    session.Tasks.Items.Add(task)
                Finally
                    session.Dispose()
                End Try

                ' clear the contents of the local cart
                LocalCartReset()
                ' reset the user interface
                OnCartEmpty(Constants.MESSAGE_CHECKOUT_COMPLETED)
            End If
        End Sub ' Checkout

using Microsoft.WindowsMobile.PocketOutlook; 

… 

private void Checkout() 
{ 
    // warn the user that the cart will no longer be accessible 
    if (DialogResult.OK == MessageBox.Show(Constants.MESSAGE_CHECKOUT_CONFIRMATION,
            Constants.CAPTION_CHECKOUT, MessageBoxButtons.OKCancel, MessageBoxIcon.None, 
            MessageBoxDefaultButton.Button1)) 
    { 

        // Outlook Session implements IDisposable 
        using (OutlookSession session = new OutlookSession()) 
        {
            Task task = new Task(); 
            
            task.Body = string.Format(Constants.MESSAGE_TASK_BODY, _purchaseUrl); 
            task.Subject = string.Format("{0}, {1}", Constants.CAPTION_CHECKOUT, DateTime.Now); 
            task.Complete = false; 
            
            session.Tasks.Items.Add(task); 
        } 

        // clear the contents of the local cart 
        LocalCartReset(); 

        // reset the user interface 
        OnCartEmpty(Constants.MESSAGE_CHECKOUT_COMPLETED); 
    } 
}

I reset the local cart's contents after storing the task because Amazon recommends that a cart no longer be used once a purchase is submitted. I don't know when my user will complete the transaction, so I make sure that my application can't access the cart again by clearing any saved information. It's worth noting that, for performance reasons, Microsoft suggests reusing the OutlookSession object for the life of the application rather than taking the above approach. My code has infrequent need of the task collection, however, so I've chosen to release the session's resources instead.

Once you have written the code to create a cart and edit its contents you should go back to your search form and handle the ListView's ItemActivate event. When someone selects an item from the list, your event handler should instantiate a new form to lookup offers for the item. In this case, it is best to do this modally, which means that execution in the search form halts until the OfferForm has been closed. Instantiate a new OfferForm and call ShowDialog:

using (OfferForm offerForm = new OfferForm(_asin)) 
{ 
    // the next line of code shows the OfferForm modally 
    offerForm.ShowDialog(); 
}

Using offerForm As OfferForm = New OfferForm(_asin)
     offerForm.ShowDialog()
End Using

When the OfferForm is closed the search form will exit the using statement, calling the Dispose method on the OfferForm to release its resources.

Debugging

If you have a Motorola Q or any other Windows Mobile 5.0 Smartphone with a landscape resolution, debugging your code is as simple as connecting the device and then selecting “Windows Mobile 5.0 Smartphone Device” from the dropdown in the Debugging toolbar. When you start debugging, the IDE will deploy both your code and, depending on your configuration, the .NET Compact Framework to the device through ActiveSync.

If you don't have the hardware you want to use yet, don't worry. You can use an emulator to create a virtual device for testing your code. The emulator that ships with Visual Studio supports only portrait Smartphone layout, however, so the first thing you'll need is Microsoft's Emulator Image for Windows Mobile 5.0 Smartphone with 320x240 (Landscape) Screen. Next you'll want to download the Q skin plug-in, which you should be able to find at www.motocoder.com, and you may find the MOTO Q Developer Guide useful for the installation. Your emulator will not have a network connection when first installed but this post will help you get one configured. Select your emulator from the Debug toolbar dropdown and press F5 when you're ready to debug.

Figure 4: Amazon Mobile in action on the Q emulator.

Conclusion

As we've seen, the .NET Compact Framework makes distributed applications such as this one as easy to write for the mobile device as they are for the desktop. With much of the processing and storage done server-side, the scaled down processor and memory of the phone aren't a problem for most applications. Check back soon – my next version (v2.0) of Amazon Mobile will hopefully feature the device's camera as an ISBN scanner using the framework's new CameraCaptureDialog class.

Extending the Screen Saver Starter Kit with Microsoft Visual Basic Express

Clint Rutkas — Tue, 07 Nov 2006 11:54:00 GMT

Introduction

Visual Studio 2005 Express is the most comprehensive and full- featured interactive development environment (IDE) released to date. As part of the product mix, Microsoft has announced a series of Express editions, which make this power available to anyone for almost no investment. In this article, we'll explore the installation of one of the editions—Visual Basic—and then use one of the "Starter Kits" included with each Express edition to build and customise a screen saver.

Installing Visual Basic Express Edition

First, you'll need to install Visual Basic Express Edition (from now on, I'll just refer to it as Visual Basic Express). You can download it from the Visual Basic Express website.

Run the vbsetup.exe file you downloaded from the Visual Basic Express site. After the installer has copied some setup files to your hard drive, you should see the screen shown in Figure 1. I'd strongly encourage you to check the box that allows the installer to gather information and send it to Microsoft. This information is used to make the setup process as seamless as possible.

Figure 1: Initial screen for Visual Basic Express Edition Setup
Click the Next button and you will see the End User License Agreement screen. Accept the agreement and click the Next button again.
You're now at the screen that allows you to choose which of the optional components (in addition to Visual Basic Express) you want to install. If you've got the disk space (about 1.3 GB for the install process and about 500 MB once the install is complete and all of the temporaray installation files have been removed) spare, I'd encourage you to install both the MSDN Express Library 2005 and SQL Server 2005 Express Edition April CTP. The MSDN Express Library is the documentation (tailored for the Express editions) and SQL Server 2005 Express is the SQL Server engine (with a few limitations).
Click the Next button and you'll be prompted for the installation path. Either accept the default or browse to choose another.
Click the Next button and the install will begin. Progress will be displayed for each of the components to be installed as shown in Figure 2.

Figure 2: Setup is progressing
Along the way, you may well be prompted to restart you machine. If it's not convenient to restart now, you can choose to restart later, but you will have to manually restart the setup process after doing so. If you choose to restart now, the setup process will continue seamlessly after you've logged back in.
Once you've completed the setup process, you will be greeted with the screen shown in Figure 3. At some stage in the next 30 days you'll need to register your copy of Visual Basic Express and you can do it now by clicking on the link in the dialog or do it later by choosing Product Activation from the help menu in Visual Basic Express. Either way, registering will give you free access to the online e-book, Writing Secure Code 2nd ed. by Michael Howard and Davis LeBlanc.

Figure 3: Setup's done its thing. The rest is up to you.
The final setup step is to start Visual Basic Express. Choose Start, All Programs, Visual Basic 2005 Express Edition.

Building a Screen Saver using the Starter Kit

All of the Visual Studio Express Editions come with one or more Starter Kits—pre-configured applications from which you can learn, and which you can adjust. Visual Basic Express comes with a Movie Database tracking application and a Screen Saver. These applications demonstrate best practices in coding and also showcase a number of the great new features in the language, the framework and the development environment. There are also a number of other starter kits being developed, both by Microsoft and by members of the developer community.

In this article we'll concentrate on the Screen Saver. First we'll explore the functionality that comes with the application as it ships, and then we'll make a couple of adjustments to personalize it and to demonstrate another very powerful feature: calling a web services.

Creating a new project

Click the New Project button on the main toolbar or choose File, New Project from the menu. In the dialog box, choose a name for your project (I've called mine mySS if you're typing along) and a location. Make sure you've selected the Screen Saver starter kit as shown in Figure 4.

Figure 4: Let's start at the very beginning (click image to zoom)

Visual Basic Express goes away and creates a new project based on the Screen Saver Starter Kit and then opens it in the IDE. The file that you see open is the documentation explaining how the application works and what to do to build and install it.

Building the screen saver

Press the F5 key to build and run the Screen Saver application. If you're connected to the Internet, you'll get an image (probably of a chess board) and a list of articles from the MSDN Visual Basic RSS feed. The currently highlighted article will have a description or précis displayed on the right-hand side of the screen.

Installing your creation to your desktop

To install your screen saver, follow the instructions in the documentation, that is:

If you haven't already done so, load the Starter Kit into Visual Basic.
On the File menu, click Save All.
If you are requested to enter a location to save the project, select a directory or accept the default location. Make a note of where the project is saved; by default it will be in a directory under \My Documents\Visual Studio 2005\Projects.
On the Build menu, click Build Solution. This creates an executable file for the screen saver.
Open up the directory specified in step 3 containing the saved project.
Open the bin subdirectory. You will see two files: ssNews.scr and ssNews.scr.config.
Copy these two files to your Windows directory. If you are using Windows XP, this is \Windows\System32 in your system drive. If you are using Windows 2000, it is \WinNT\System32.
Open Control Panel, click Appearance and Themes if using the Category View, and open the Display Properties dialog box.
Click the Screen Saver tab.
Click the Screen Saver drop-down list, and select News.
Click the Preview button.
The screen saver launches. Press any key to stop it.
Click the Settings button to see the screen saver options. Try changing the background image or the RSS feed.
Click OK.

Make your Screen Saver do what you want it to do

It's all very well having the Screen Saver do what the designer of the Starter Kit wanted it to, but it's much more fun if you get it what you want it to do.

Getting images based on a keyword or at random

I decided that instead of picking up a set of images from a folder on my hard drive, I'd rather the screen saver selected a number of images from the web at random. I looked for a web service that would do this for me in the public directory of Web Services at Web Methods. I found one called getRandomGoogleSearch. This web service takes a single parameter (a string) and returns a URL pointing to an image related to that string. If the string passed is empty, it chooses a random English word and uses that as the seed word.

The other important piece of information (apart form the description of the functionality) in the directory is the URL of the Web Services Description Language (WSDL) for this service. This is the metatdata in XML format that tells an application calling the service all about what information is required and what's returned. In this case, the WSDL is at http://www.ghettodriveby.com/soap/?wsdl.

To get Visual Basic Express to be able to use this web service, right click on the references node in the Project Explorer pane and choose Add Web Reference. In the dialog, enter the WSDL URL and click the Go button. Once the WSDL has been retrieved, either accept the default name for the service or choose a new (possibly shorter) name. I chose GoogleImage.

Clicking the Add Reference button will generate all of the reference code to enable your application to treat the web service as just another component. This will all come together in a little while when I show you the code used to get the image.

Storing information between sessions

One of the things that's got significantly easier with Visual Studio 2005 is the persistence of settings and configuration between sessions of an application. In our case, we want to save the keyword for which images are retrieved and the total number of images we want to load into the screen saver cache.

To set up these settings, expand the Properties node in the Solution Explorer and double-click on the settings.settings file. You will see a grid with all of the settings like the one shown in Figure 5. Add a user-level string setting called Keyword and leave its value blank. Add a user-level int setting called ImageCount and set its default value to 5.

Figure 5: Saving settings is easier than ever before (click image to zoom)

We now need to adjust the mechanism for the user to adjust and save these settings. In the Solution Explorer, double-click on the OptionsForm.vb file to open the options form in the designer. We'll leave the top half of the form alone—we're not changing the RSS reader functionality. Down at the bottom, though, we'll need to change the panel's caption, as well as the caption for the TextBox to reflect its new functionality as a keyword, rather than a path holder. Finally (from a UI point of view), we need to add a control to adjust the image count. The other thing that needs to happen on this form is that we need to get rid of the two controls at the bottom used for selecting a folder.

Let's do this in reverse order. Deleting the folder controls is easy. Click on them to select them and press the delete key. They're gone. Drag a label onto the form below the TextBox and change its text property to ImageCount. Below the label, place a numeric UpDown control and change its name to something more meaningful than the default. I chose ImageCountUpDown. Notice that as you drag controls around, guides appear helping you align controls. Change the text label above the TextBox to Background image keyword. You should end up with something that looks a bit like Figure 6.

Figure 6: UI Changes for the Options Dialog

Now it's time to adjust the code that's used to save the settings. Right-click on the form and choose View Code. The first thing we want to do is rename the textbox that used to be called backgroundImageFolderTextBox. Locate the line of code in the OptionsForm() constructor that reads:

backgroundImageKeywordTextBox.Text = Settings.[Default].Keyword

and right-click on the name of the TextBox. Choose Refactor, Rename. In the dialog, change the name to backgroundImageKeywordTextBox. Click OK and then OK again in the preview changes dialog. Changing the name of the control in this way will update all the references to the control including in the auto- generated designer code.

When the form loads, the values that are currently set are used to populate the controls on the form. Change the code in the constructor method (called OptionsForm()) to:

backgroundImageKeywordTextBox.Text = Settings.[Default].Keyword
ImageCountUpDown.Value = Settings.[Default].ImageCount
rssFeedTextBox.Text = Settings.[Default].RssFeedUri

Notice how we can just use the Properties.Settings.Default construct to get at the settings. The type and value of the setting is taken care of automatically for us.

Now update the UpdateApply and ApplyChanges methods to read:

 ' Update the apply button to be active only if changes 
 ' have been made since apply was last pressed
Private Sub UpdateApply()
    If Settings.[Default].Keyword <> backgroundImageKeywordTextBox.Text OrElse _
        Settings.[Default].ImageCount <> ImageCountUpDown.Value OrElse _
        Settings.[Default].RssFeedUri <> rssFeedTextBox.Text Then
        applyButton.Enabled = True
    Else
        applyButton.Enabled = False
    End If
End Sub

' Apply all the changes since apply button was last pressed
Private Sub ApplyChanges()
    Settings.[Default].Keyword = backgroundImageKeywordTextBox.Text
    Settings.[Default].ImageCount = CInt(ImageCountUpDown.Value)
    Settings.[Default].RssFeedUri = rssFeedTextBox.Text
    Settings.[Default].Save()
End Sub

Note that I had to cast the value from the UpDown control from its native Decimal to an int to save it back to the ImageCount setting.

Finally, we need to add a handler to the ValueChanged event for the UpDown control so we can enable the Apply button when the value changes. Go back to the designer view for the options form and select the UpDown control. In the properties window, click on the Events button (the yellow bolt of lightning) and then doube-click on ValueChanged. All of the wiring will be hooked up to handle the event, you just need to add the call to the UpdateApply method in the event handling method.

Private Sub ImageCountUpDown_ValueChanged(ByVal sender As Object, _
        ByVal e As EventArgs) Handles ImageCountUpDown.ValueChanged
    UpdateApply()
End Sub

That's it: all the heavy lifting has been done by the .NET Framework.

Loading images for each keyword

Now that we've updated the options dialog, it's time to move onto the form that displays the screen saver itself. This form works by loading images into a list when it starts up and cycling through those images while the screen saver is active. We're not going to change the structure of the screen saver very much. We're just going to change the way it loads images so that, instead of getting them from a folder on the local disk, it gets them from the Internet.

In the Solution Explorer, right-click on ScreenSaverForm.vb and choose View Code. Choose LoadBackGroundImage from the drop-down box on the right-hand side of the code window. This will take you to the code for this method. This is the only method we need to change on this form.

Since we're not loading images from folders, I've done away with the code calling the LoadImagesFromFolder method (as well as the method itself). I then declare a local variable to hold the imageURL returned from the call to the web service. Next, because calling over the web is fraught with uncertainty, I wrap the next block of code in a try...catch block to handle any exceptions that might occur.

Creating an instance of the object that will call the web service is very straightforward: just declare a local variable and assign a new GoogleImage.RandomGoogleSearchService object to it. While I'm about it I create a WebClient object that I'll use to go out to the web and grab the image itself (the web service only returns a URL, not the binary data that makes up the image).

Next I loop until I've got as many images loaded as the user has asked for in the settings, and each time I call the web service. Note that the web service actually returns a data object with two properties: image (the image URL) and word (the word used to select the image).

If the image URL isn't empty, I try looking it up and retrieving the binary data. If successful, I create an image object from the stream of bits and add that image to the list of background images.

Finally, if, for some reason, no images were loaded, I call the LoadDefaultBackgroundImages method that was pat of the original application. The full code listing for the updated method is shown below.

Private Sub LoadBackgroundImage()
    ' Initialize the background images.
    backgroundImages = New List(Of Image)()
    currentImageIndex = 0

    Dim imageURL As String

    Try
        Dim oWS As GoogleImage.RandomGoogleSearchService = _
            New GoogleImage.RandomGoogleSearchService()

        Dim webClient As System.Net.WebClient = New System.Net.WebClient()

        While backgroundImages.Count < Settings.[Default].ImageCount
            ' call the web service to look up a random image
            imageURL = oWS.getRandomGoogleSearch(Settings.[Default].Keyword).image
            If imageURL <> String.Empty Then
                Try
                    Using imageStream As Stream = webClient.OpenRead(imageURL)
                        Dim image As Image = Drawing.Image.FromStream(imageStream)
                        backgroundImages.Add(image)
                    End Using
                Catch generatedExceptionName As System.Net.WebException
                    ' probably a 404 (not found error);
                Catch generatedExceptionName As Exception
                    Throw
                End Try
            End If
        End While
    Catch
        ' ignore any other exceptions and get on with the images
    End Try

    ' If no images were loaded, load the defaults
    If backgroundImages.Count = 0 Then
        LoadDefaultBackgroundImages()
    End If
End Sub

That's it! We've finished tweaking the screen saver. Press F5 and check that it runs. Follow the instructions in the section above to put it into your list of Windows Screen Savers.

Next Steps

You may have noticed one or two things that could be done better here. Why, for example, have an image count at all; why not just grab an image form the Internet each time you need a new one? The form seems to take a long time to load. Perhaps loading a single image and displaying that while you load the others in the background would be better. Wouldn't it be nice to display the word that was used to retrieve the image at the same time that the image is displayed? I'm sure you can think of some others.

Well, what are you waiting for? Make changes, try stuff, delve into the window paint code. Above all have fun.

Conclusion

The Visual Studio Express Editions put the power of the .NET Framework in to the hands of just about anyone. The starter kits that come with the Express Editions are great place to, well, start. There's a wealth of information both in the product itself and online. There's never been a better time to get into writing powerful and dynamic Windows applications and web sites.