WHS Developer Tip #10: Home Server Controls

Did you know that most of the custom visual controls used in the Windows Home Server Console (with the exception of the graphs) are unofficially available for your use in your add-ins?

In order to access them in the designer, simply add the controls to your Toolbox, to do so:

1. Launch Visual Studio
2. Open desired project
3. Open form or user control in designer
4. If the Toolbox is not displayed, use the View -> Toolbox menu option to display it
5. Right click inside of Toolbox and select Add Tab
6. Specify name of tab (ie Windows Home Server)
7. Right click inside of new tab and select Choose Items...
8. In the Choose Toolbox Items dialog, click the Browse button and browse to location of HomeServerControls.dll (C:\Program Files\Windows Home Server\ if working directly on the server)
9. Press the space bar to check all selected controls from HomeServerControls.dll
10. Click the OK button to close the dialog

Once done you should be greeted with a new list of available controls:

Designer Friendliness

Because the controls in HomeServerControls.dll were not intended for use by third-party programmers, most of the controls are not the most designer or developer friendly. While the majority of the controls that are displayed in the Toolbox can be dragged to the form and modified there, some cannot... either because they lack a default constructor or other dependencies. Of those that can be, issues will be seen from time to time of a property or other operation that needs to be done that cannot be made via the designer... leading to the necessity of some extra manual tweaks in code.

A little historical note... initially the biggest problem with these controls was that very few of them had a default (parameterless) constructor which made it it impossible for a programmer to use the Windows Forms designer to use a good number of them without manually creating each control programmatically (ie how the official tabs in the Home Server Console were built) and largely ignoring the benefits of the designer.

It is here where the necessity for some of these extra tweaks come into play.

Despite the majority of the controls now having default constructors... a number of them have extra configuration work being done in the their non-default constructors but not in the default one, forcing a third-party developer to go without the additional functionality (likely not even knowing what they are missing), guessing as to what is being done and doing it themselves, or reverse engineering to determine exactly what they lack.

Another issue (albeit minor) encountered when dealing with HomeServerControls.dll is that not one of the controls in it is decorated with the ToolboxBitmap attribute (which enables the displaying of a descriptive icon in the Toolbox) which means developers must rely on the names of the controls instead if icons for finding what they want in the Toolbox.

Administrative Permissions

For years we've heard that we should not log into our computers as an Administrator unless it is absolutely necessary... they are right. Unfortunately there are a few times when dealing with HomeServerControls.dll it is necessary.

While I cannot provide a list of controls and cases, it is possible that when viewing a form or user control in the Visual Studio Forms designer (when not run as Administrator) that designer errors would be encountered informing you that certain assemblies cannot be loaded.

If you are sure that those assemblies should be accessible, re-launching Visual Studio with administrative permissions should allow you to proceed.

Does this mean that you should run Visual Studio as administrator all the time when working on your add-in? Certainly not. Just be aware that if you encounter these errors... you've likely hit one of these rare cases and will need to re-load your project in an instance of Visual Studio that is running as Administrator.

Other Assemblies

HomeServerControls.dll does not live in a vacuum and in turn references multiple other assemblies when one of it's controls is used... assemblies that your add-in project will also need to reference. The easiest way to achieve is through the same registry hack features in Dev Tip #6 to allow Visual Studio to know where the assemblies are, allowing Visual Studio to automatically add the references for you.

Next Time

Tomorrow will come the previously promised post on the FancyListView control and will discuss other controls from HomeServerControls.dll in future posts.

Note: The information in this post is based on undocumented and at times deduced information on Windows Home Server and is not officially supported or endorsed by Microsoft and could very easily be wrong or subject to change in future, so please take it and everything else said on this blog with a grain of salt and use with caution.