Writing the Console Tab Code

The Console tab that you create in this tutorial allows end users to retrieve information about Windows Home Server objects and then display that information in the Console tab pane area. The Console tab also allows end users to show an associated Settings tab.

To provide this functionality, you need to write code that responds to actions that end users take on your Console tab.

Write the Console Tab application code

With Visual Studio open to the SDKSample project that you created in Setting Up an Add-In Solution, right-click HomeServerTabExtender.cs (HomeServerTabExtender.vb in Visual Basic) in Solution Explorer, and then click View code from the popup menu.

Before you begin adding code for your Console tab, add the appropriate using statements (Imports in Visual Basic) to your code file:

using System.Drawing;
using System.Windows.Forms;
using Microsoft.HomeServer.Extensibility;
using Microsoft.HomeServer.SDK.Interop.v1;

Imports System.Drawing
Imports System.Windows.Forms
Imports Microsoft.HomeServer.Extensibility
Imports Microsoft.HomeServer.SDK.Interop.v1

Step 1: Declare a class that implements the IConsoleTab interface

To create a Console tab, you must create a class that implements the Microsoft.HomeServer.Extensibility.IConsoleTab interface. The IConsoleTab interface contains methods and properties that all Console tabs should contain. Later in this topic, you implement the methods and properties of the interface.

Declare a class that implements the IConsoleTab interface. Delete the existing class declaration for Class1, and replace it with the following:

public class HomeServerTabExtender : Microsoft.HomeServer.Extensibility.IConsoleTab  

Public Class HomeServerTabExtender
    Implements Microsoft.HomeServer.Extensibility.IConsoleTab

Step 2: Code the class fields and the HomeServerTabExtender constructor

HomeServerConsole.exe is the program that runs the Windows Home Server Console. When HomeServerConsole.exe finds the HomeServerTabExtender class inside your .dll, it calls the HomeServerTabExtender class constructor to initialize your tab. HomeServerConsole.exe passes in values for the width, height, and Console Services objects for your Console tab as parameters to the constructor call.

In this step, you create three private fields in the HomeServerTabExtender class. The first private field holds the reference to the IConsoleServices object that is passed in with the constructor call. The second private field references the instance of the user control, ShowWHSInfoPanel, that appears in the Console tab pane area. Because the Console tab needs to access information about Windows Home Server objects on the server, you create a third private field for an instance of WHSInfoClass. This is a Microsoft.HomeServer.SDK.Interop.v1 type that provides methods to get information about several Windows Home Server objects.

After creating the private fields, you code the HomeServerTabExtender constructor, which must have the following signature:

public HomeServerTabExtender(int width, int height, IConsoleServices consoleServices)

Public Sub New(ByVal width As Integer, ByVal height As Integer, ByVal consoleServices As IConsoleServices)

In the constructor, initialize each of the private fields, and hook up event handlers (that you code in the next step) for the button click events for all three buttons on the instance of the ShowWHSInfoPanel user control.

// The class declaration
public class HomeServerTabExtender : Microsoft.HomeServer.Extensibility.IConsoleTab
  {
    // Private fields declared
    private IConsoleServices services;
    // Declare an instance of the UserControl, ShowWHSInfoPanel
    private ShowWHSInfoPanel nPanel;
    private WHSInfoClass whsInfo;

// The constructor
    public HomeServerTabExtender(int width, int height, IConsoleServices consoleServices)
      {
         // Initialize the private fields
         nPanel = new ShowWHSInfoPanel();
         nPanel.Size = new Size(width, height);
         this.services = consoleServices;
         whsInfo = new WHSInfoClass();

         // Hook up event handlers for the nPanel buttons
         nPanel.btnClearInfo.Click += new EventHandler(BtnClearInfo_Click);
         nPanel.btnShowInfo.Click += new EventHandler(BtnShowInfo_Click);
         nPanel.btnOpenSettings.Click += new EventHandler(BtnOpenSettings_Click);
       }
  }

'The class declaration
Public Class HomeServerTabExtender
    Implements Microsoft.HomeServer.Extensibility.IConsoleTab

    'Private fields declared
    Private services As IConsoleServices
    'Declare an instance of the user control, SHOWWHSInfoPanel
    Private nPanel As ShowWHSInfoPanel
    Private whsInfo As WHSInfoClass

    'The constructor
    Public Sub New(ByVal width As Integer, ByVal height As Integer, ByVal consoleServices As IConsoleServices)
        nPanel = New ShowWHSInfoPanel()
        nPanel.Size = New Size(width, height)
        Me.services = consoleServices
        whsInfo = New WHSInfoClass()

        'Hook up event handlers for the nPanel buttons
        AddHandler nPanel.btnClearInfo.Click, AddressOf BtnClearInfo_Click
        AddHandler nPanel.btnShowInfo.Click, AddressOf BtnShowInfo_Click
        AddHandler nPanel.btnOpenSettings.Click, AddressOf BtnOpenSettings_Click

    End Sub

Step 3: Code event handlers

In the section of code above, you hooked up event handlers with the click event for each of the three buttons on the ShowWHSInfoPanel instance, nPanel. In this step, you write the three event-handler methods.

Code the BtnShowInfo Click method

First, code the event handler for the nPanel.btnShowInfo.Click event. When an end user clicks Show WHS Info on the Console tab pane area, the BtnShowInfo_Click method sets the Text property for the RichTextBox Control, nPanel.rtShowWHSInfo, to a string that contains information about some Windows Home Server objects that are on the server.

The BtnShowInfo_Click method creates three Array objects, and then populates each Array with objects of a given Windows Home Server type. Then, the method loops through each Array, collecting information about each item in the Array. Finally, the text property for the nPanel.rtShowInfo RichTextBox Control is set to the string that contains all of the collected information:

internal void BtnShowInfo_Click(object sender, EventArgs e)
  {
    string displayText;
            
    // Fill each array with WHS objects
    Array disks = whsInfo.GetDiskInfo();
    Array volumes = whsInfo.GetVolumeInfo();
    Array shares = whsInfo.GetShareInfo();

    displayText = "DISK INFORMATION:\nSystem Name\t\tSize\n";

    // Iterate through each array and get individual WHS object information
    foreach (IDiskInfo pDisk in disks)
      {
         displayText += pDisk.DevicePath.ToString() + "\t\t" + pDisk.Size.ToString() + "\n\n";
      }

    displayText += "VOLUME INFORMATION:\nPath\t\tSize\n";

    foreach (IVolumeInfo pVolume in volumes)
      {
        displayText += pVolume.Path.ToString() + "\t\t" + pVolume.Size.ToString() + "\n\n"; 
      }

    displayText += "SHARE INFORMATION:\nName\t\tIs Duplicated\n";

    foreach (IShareInfo pShare in shares)
      {
        displayText += pShare.Name.ToString() + "\t\t" + pShare.IsDuplicated.ToString() + "\n\n";
      }

    // Display the collected information
    nPanel.rtShowWHSInfo.Text = displayText;
  }

Friend Sub BtnShowInfo_Click(ByVal sender As Object, ByVal e As EventArgs)
        Dim displayText As String

        'Fill each array with WHS objects
        Dim disks As Array = whsInfo.GetDiskInfo()
        Dim volumes As Array = whsInfo.GetVolumeInfo()
        Dim shares As Array = whsInfo.GetShareInfo()

        displayText = "DISK INFORMATION: " + vbLf + "System Name" + vbTab + vbTab + "Size" + vbLf

        'Iterate through each array and get individual WHS object information
        Dim pDisk As IDiskInfo
        For Each pDisk In disks
            displayText += pDisk.DevicePath.ToString() + vbTab + vbTab + pDisk.Size.ToString() + vbLf + vbLf
        Next pDisk

        displayText += "VOLUME INFORMATION: " + vbLf + "Path" + vbTab + vbTab + "Size" + vbLf

        Dim pVolume As IVolumeInfo
        For Each pVolume In volumes
            displayText += pVolume.Path.ToString() + vbTab + vbTab + pVolume.Size.ToString() + vbLf + vbLf
        Next pVolume

        displayText += "SHARE INFORMATION: " + vbLf + "Name" + vbTab + vbTab + "Is Duplicated" + vbLf

        Dim pShare As IShareInfo
        For Each pShare In shares
            displayText += pShare.Name.ToString() + vbTab + vbTab + pShare.IsDuplicated.ToString() + vbLf + vbLf
        Next pShare

        'Display the collected information
        nPanel.rtShowWHSInfo.Text = displayText

    End Sub

Code the BtnClearInfo Click method

Next, code the event handler for the nPanel.btnClearInfo.Click event. The BtnClearInfo_Click method is fairly simple. It uses one line of code to clear any text from the display area of the nPanel user control.

When an end user clicks Clear Display on the nPanel user control, the BtnClearInfo_Click method sets the Text property of the nPanel.rtShowWHSInfo RichTextBox control to an empty string:

internal void BtnClearInfo_Click(object sender, EventArgs e)
  {
    nPanel.rtShowWHSInfo.Clear();
  }

Friend Sub BtnClearInfo_Click(ByVal sender As Object, ByVal e As EventArgs)
        nPanel.rtShowWHSInfo.Clear()

    End Sub

Code the BtnOpenSettings Click method

Finally, code the event handler for the nPanel.btnOpenSettings.Click event. When an end user clicks Open Settings on the nPanel user control, the Windows Home Server Settings dialog opens to the Settings tab that you specify in the BtnOpenSettings_Click method.

The BtnOpenSettings_Click method calls the Microsoft.HomeServer.Extensibility.IConsoleServices.OpenSettings(System.Guid) method, passing the globally unique identifier (GUID) for a specific Settings tab as the only argument:

internal void BtnOpenSettings_Click(object sender, EventArgs e)
  {
    this.services.OpenSettings(new Guid("{A99FEB96-A120-44af-9972-3CB942F521A0}"));
  }

Friend Sub BtnOpenSettings_Click(ByVal sender As Object, ByVal e As EventArgs)
        Me.services.OpenSettings(New Guid("{A99FEB96-A120-44af-9972-3CB942F521A0}"))

    End Sub

Step 4: Implement the TabText property

The TabText property is read-only and returns a string that contains the caption or text for the Console tab. This is the caption that describes your Console tab. For example, the TabText property for the Console tab that deals with user accounts is User Accounts.

Code the TabText property so that it returns "SDK Sample" as in the following code snippet:

public string TabText
  {
    get 
      {
        return "SDK Sample";
       } 
  } 

Public ReadOnly Property TabText() As String Implements IConsoleTab.TabText

        Get
            Return "SDK Sample"
        End Get
    End Property

Step 5: Implement the TabImage property

The TabImage property of the IConsoleTab interface returns a bitmap. This bitmap appears on the Console tab above the TabText.

Use the image file SDKSampleImg that you added as a resource to the SDKSample project in the topic Setting Up an Add-In Solution:

public Bitmap TabImage 
  {
    get 
      {
        return Properties.Resources.SDKSampleImg;
       } 
  } 

 Public ReadOnly Property TabImage() As Bitmap Implements IConsoleTab.TabImage

        Get
            Return My.Resources.SDKSampleImg
        End Get
    End Property

Step 6: Implement the TabControl property

The TabControl property returns the Control that appears on the pane area of the console when you select the tab, as mentioned in Step 1 of this topic. For the purposes of this tutorial, return the Control nPanel UserControl, that you instantiated in the HomeServerTabExtender class constructor.

Code the TabControl property so that it returns the Control, nPanel:

public Control TabControl
  {
    get 
      {
        return nPanel;
      }
  }

 Public ReadOnly Property TabControl() As Control Implements IConsoleTab.TabControl
        Get
            Return nPanel
        End Get
    End Property

Step 7: Implement the GetHelp() method

Use GetHelp to display Help content when an end user selects your tab and presses one of the Help keys (Help on the Windows Home Server Console or F1). You must implement the GetHelp method as part of the IConsoleTab interface, and if you are an OEM or System Builder you must hook up your own Help content to your Console tab.

The signature of the GetHelp method requires you to return a Boolean value that indicates that you will display custom Help content for your Console tab. A return value of true indicates that you will display your custom Help content.

For this tutorial, you can just display a MsgBox for your Help, but when you create an actual production tab, you may want to display a Help topic in a compiled Help file (.chm):

public bool GetHelp()
  {
        // Open a simple Message Box for Help
        MsgBox(“You clicked Help or pressed F1.”, , “My Tab Help”);

        // Open a custom compiled Help file (.chm)topic
        // this.services.OpenHelp(“MyHelpFile.chm”,”<MyTopicGUID>”);
        return true;
  }

Public Function GetHelp() As Boolean Implements IConsoleTab.GetHelp
        ‘ Open a simple Message Box for Help
        MsgBox(“You clicked Help or pressed F1.”, , “My Tab Help”)

        ‘ Open a custom compiled Help file (.chm)topic
        ‘ Me.services.OpenHelp(“MyHelpFile.chm”,”<MyTopicGUID>”)
        Return True

End Function

Step 8: Implement the SettingsGuid property

Depending upon how your add-in works, you may want to provide end users the ability to set options for your application. To do so, create a custom Settings tab on the Settings page dialog for the Windows Home Server Console. The custom Settings tab must be an implementation of the ISettingsTab interface.

For example, a user who wants to change settings for shared folders clicks the Settings button on the console. When the Settings page dialog appears, the user clicks Shared Folders in the tab area of the Settings page dialog, and then changes the settings.

You can also associate a Settings tab with a Console tab. You create the association by using the SettingsGuid property.

For the SettingsGuid property, you have two choices:

• Return a GUID for a specific Settings tab. To do this, you must return a System.Guid object with the GUID of the Settings tab that you want to associate with your Console tab.

• Return an empty Guid. Returning an empty System.Guid indicates that you do not want to associate a Settings tab with your Console tab.

For this tutorial, do not use this property to create an association between the Console tab and a Settings tab because this tutorial implements a button on the Console tab pane area that opens the Settings page dialog directly.

Code the SettingsGuid so that it does not create an association with a Settings tab:

public Guid SettingsGuid
  {
    get
      {
        return Guid.Empty;
      }
  }

Public ReadOnly Property SettingsGuid() As System.Guid Implements IConsoleTab.SettingsGuid
        Get
            Return Guid.Empty
        End Get
    End Property

Summary

You have now created a Windows Home Server Console tab. Work through the rest of the tutorial to finish your sample add-in solution.

See Also

Concepts

Changing the Tab Order
Creating a Settings Tab
Creating a Console Tab