Andreas M's Windows Home Server AddIns

It’s been a while since Windows Home Server MVP Sam Wood published his excellent five-part WHS AddIn development tutorial over at the Tentacle Software Blog. His tutorial covers everything from setting up your development environment (using the free Visual Studio Express) to building your AddIn installation package (using the free WiX toolset).

The WiX (Windows Installer XML) toolset is a great tool for experienced Windows Installer package (MSI) authors but it comes with a steep learning curve. Unfortunately, Visual Studio Express does not contain support for creating setup projects. This feature is reserved for Visual Studio Professional and higher editions. If you want to create your MSI packages using a graphical tool you could of course do so by choosing tools from market leaders like InstallShield from Flexera or WISE Installer from Symantec, but these are quite pricey. A couple of weeks ago I stumbled across another tool for building MSI packages from a company called Caphyon Ltd. Its name is Advanced Installer and the best thing about it: it comes in a free edition that allows us to conveniently create our WHS AddIn Windows Installer package.

In this small tutorial I want to show you how you can package your Windows Home Server AddIn as a Windows Installer package (MSI) using the free edition of Caphyon Advanced Installer.

Step 1: Download and install Advanced Installer
Advanced Installer is small and lightweight. Simply download it from here and run the installation wizard.

Just click through the wizard and Advanced Installer will be set up in no time.

Step 2: Creating our installer project

Run Advanced Installer by finishing the installation wizard or from the shortcut the installer has placed on your desktop and you will be presented with the ‘New project’ dialog.

As you can see, Advanced Installer supports a variety of project types for all your installation needs. Only the ‘Simple’ project type is available in the free edition but this is not a problem as it offers all the functionality we will need to build our WHS AddIn package.

When you select the ‘Simple’ project type and click OK the ‘New Simple Project’ wizard is launched.

First enter the name of your AddIn and your company name. This information will later be displayed in the WHS settings dialog’s available AddIns tab.

Next, select the name and location of your Advanced Installer project file (.aip), the name for your AddIn MSI package and the folder where the MSI package should be placed when it’s being created by Advanced Installer.

Now point the wizard to the folder where your Visual Studio build output is located (your HomeServerConsoleTab.*.dll) and click ‘Finish’.

Step 3: Fine tune the package settings
When the wizard finishes you’ll be brought to the ‘Product Details’ sheet of your setup project. Here you can enter the product version number of your AddIn. Please note that the Windows Installer format for version numbers is major.minor.build which differs from the usual .NET assembly version format (major.minor.build.revision).

Use the navigation pane on the left to switch to the ‘Install Parameters’ sheet. Change the Application Folder to ‘[ProgramFilesFolder]Windows Home Server’. [ProgramFilesFolder] is a symbolic name for “C:\Program Files”. By using it in your application folder setting you can make sure that your AddIn will install properly on non-english versions of the operating system, where this folder is named differently (e.g. “C:\Programme” in German). You should also set the ‘Installation Type’ to ‘Per-machine only’ so only users with administrative privileges will be able to install the package (this is not absolutely necessary since the WHS console from where your AddIn is going to be installed from is running from the Administrator account, but still….).

Now under ‘Properties’ click the ‘New’ button to fire up the ‘New Property’ dialog and enter ‘WHSLogo’ as your property name and ‘1’ as your value. This setting is required for WHS to recognize your MSI package as a valid AddIn installation package. When you’re done the ‘Instal Parameters’ sheet should look like in the second screen here:

You can navigate to the ‘Upgrades’ sheet if you want to see what’s in there but since Windows Home Server does not make use of the automatic upgrade feature of Windows Installer for AddIns you should just leave the setting as it is.

On the ‘Launch Conditions’ sheet under ‘System Launch Conditions’ you should set the minimum Windows NT version to ‘Windows Server 2003 Service Pack 2’. This is the version of Windows Server that WHS v1 is based on and setting it as a requirement will prevent your users from accidentally installing your MSI package on their client machines. Since WHS v1 only comes as 32bit operating system you can disable the Windows NT 64-bit base version requirement.

If your AddIn targets .NET Framework 3.5 you can set it as the minimum .NET version on the ‘Software Launch Conditions’ tab. This way, installation of your AddIn will only be possible on WHS machines that already have .NET Framework 3.5 installed (version 3.5 of the .NET Framework is distributed to WHS via Windows Update so it should be ok to set this requirement).

You even can define your own launch conditions on the ‘Custom Launch Conditions’ tab but that’s beyond the scope of this tutorial. See this MSDN Library topic for more information about custom launch conditions.

Step 4: Complete the package definition
Now it’s time to define the real contents of your MSI package. Go to the ‘Files and Folders’ tab and review the list of files that got imported by the project creation wizard. It automatically should have imported your HomeServerConsoleTab.*.dll and the subfolders containing localization satellite assemblies (if any). You can add additional files by clicking ‘Add Files’ on the toolbar or the context menu. Please make sure that this list does NOT contain any Microsoft assemblies from the WHS SDK like Microsoft.HomeServer.SDK.Interop.v1.dll and HomeServerExt.dll as these should NEVER be redistributed with your AddIn.

If you want your installer to add or modify registry keys you can define these on the ‘Registry’ sheet.

Step 5: Building your MSI package
On the ‘Media’ tab’ you can review the output folder and MSI filename settings you made earlier in the project creation wizard (and modify them, if needed). All other settings are already correct and will result in the creation of a single MSI package, so that you don’t have to change anything here.

Now click ‘Build’ on the toolbar or the ‘Project’ menu and wait until Advanced Installer has finished building your MSI package.

If everything goes well the build should finish successfully and you should be able to click the link to your MSI package in the log window of the ‘Build project’ dialog. This will take you directly to the folder where your MSI package has been written to. You can now copy the MSI package to the \Software\Add-Ins share of your WHS test box to install it from the WHS console settings dialog.

Bonus Step: Build automation
If you want to create an up-to-date version of your MSI package every time you build your AddIn project in Visual Studio you’ll be happy to find that Advanced Installer supports build automation from the command line (if you don’t want to use this, just skip this step).

First, create a new .bat-file using Notepad (or whichever text editor you prefer) with this content:

cd /d "C:\Program Files\Caphyon\Advanced Installer 7.6.1\bin\x86"

set MSIPROJECT="C:\Temp\Sample WHS AddIn\SampleWHSAddIn.aip"

set MSIVERSIONFILE="C:\Temp\Sample WHS AddIn\Sample WHS AddIn\bin\Release\HomeServerConsoleTab.SampleWHSAddIn.dll"

advinst.exe /edit %MSIPROJECT% /SetVersion -fromfile %MSIVERSIONFILE%advinst.exe /build %MSIPROJECT%

Set the correct path of your Advanced Installer installation in the first line. The second line must contain the path to your Advanced Installer project file (.aip) as defined in Step 2 of this tutorial. In line three you specify the full path of the assembly that carries the version number you want to use for your MSI package (your main assembly).

The first call of advinst.exe will instruct Advanced Installer to take the version number of the assembly you specified and set it as version number of your installer project. The second and last call of advinst.exe will then build your installation package (MSI).

Now save this .bat file as ‘autobuild.bat’ (for example) and put the full path to ‘autobuild.bat’ into the ‘Post-build event command line’ box on the ‘Build Events’ tab of your AddIn project properties window in Visual Studio:

Now every time you build your project in Visual Studio the ‘autobuild.bat’ script will be executed and your MSI package will be recreated incorporating your latest code changes.

Conclusion
As you have seen it’s pretty easy to create a professional MSI package of your Windows Home Server AddIn using the free edition of Caphyon Advanced Installer. I personally like this way better than fiddling around with XML and WiX. Of course there’s nothing wrong with using WiX but it’s good to know that there are other free alternatives out there for your personal (and professional) MSI packaging needs.

I’ve been working with the market leading (and quite pricey) InstallShield Premier (which has its share of annoyances and bugs) for years and I have to say that Advanced Installer has the potential to shake up the market for professional Windows Installer package creation tools. For one, this is because it comes with an ingeniously simple user interface which helps you to define your package parameters very easily. Second, it contains some productivity tools like the condition editor with condition validation functionality (not covered in this tutorial) which can be real time savers and which professional MSI developers will love (I don’t want to make this sound like a rant towards InstallShield, but condition validation is an outstanding feature InstallShield still does not have after years in the marketplace).

Now have fun exploring Advanced Installer! Stay tuned for a version of this tutorial covering the package creation for Windows Server Codename ‘VAIL’.

Version 0.5.0 Beta was released back in May 2009. Since then only one bug has been reported. So I think it’s time to remove the beta tag from the Advanced Admin Console.

This release fixes a bug which caused a console crash when AAC tried to load a corrupt custom link file (see this forum thread). Also the installer has been improved. It’s no longer possible to install AAC over an existing installation. In this case you now are prompted to uninstall any existing version first.

Download Advanced Admin Console AddIn Version 0.5.2 Beta.

CRC-32 5F6395D7
   MD5 505E4E3915CAFE96971ECCE9C3D38120
  SHA1 4757DF42CFDFF0EFDAE103F3BDFB08F2FD226AB4

Important: Before installing the new release, please UNINSTALL any previous version!

As always, feedback is welcome. See the support page on how to get in touch with me.

As an avid Windows Home Server AddIn developer you probably followed the steps from the Windows Home Server SDK which explain how to implement your own console tab and a settings tab for the WHS console settings dialog.

Now when the user makes changes to the settings on your settings tab and ultimately clicks OK or Apply you may need a way to notify your console tab of the new settings.

The easiest way to accomplish this is by using a singleton object which provides the necessary means of communication:

public sealed class ChangeNotifier {
    public event EventHandler Changed;

    private ChangeNotifier() {
    }
    public static readonly ChangeNotifier Instance = new ChangeNotifier();

    public void Notify() {
        OnChanged(new EventArgs());
    }

    void OnChanged(EventArgs e) {
        EventHandler handler = Changed;
        // Make a temporary copy of the event to avoid possibility of
        // a race condition if the last subscriber unsubscribes
        // immediately after the null check and before the event is raised.
        if (handler != null) {
            handler(this, e);
        }
    }
}

Simple enough! Now we can access a common instance (the singleton) from everywhere in our code by calling on ChangeNotifier.Instance. Note: If you’re not familiar with the singleton design pattern you can read more about it in this Wikipedia article.

Now there’s two things left to do: First we need to subscribe to the ChangeNotifier’s Changed event in our console tab and second we have to call the Notify() method (which will fire the Changed event) from our settings tab when setting changes are committed.

Place this code in your console tab:

ChangeNotifier.Instance.Changed += new EventHandler(ChangeNotifier_Changed);

void ChangeNotifier_Changed(object sender, EventArgs e) {
    // TODO: Apply changed settings to your console tab here
}

And this line of code could be the last statement of your ISettingsTab.Commit() implementation:

ChangeNotifier.Instance.Notify();

This is pretty much it. Every time the user clicks OK or Apply on the settings dialog of the Windows Home Server your ISettingsTab.Commit() method is called where you now call Notify() on your ChangeNotifier singleton. This will raise the Changed event which will be handled by your event handler in your console tab (or any other class in your addin) so that you instantly can apply the settings changes the user has just made.

So you’ve written your Windows Home Server AddIn, made it available for download and are happy that people all over the world start using it on their Windows Home Servers. But shortly after you’ve put your work out in the wild users send you emails or start complaining on WHS related forums about weird behavior of your addin or WHS console crashes. You look at your code again, determine the culprit, fix the bug and compile a new version of your addin and put it in the download section of your website or blog. But how can you notify all users of older versions of your software about the availability of the new bugfix release? Of course the easiest way to do this is by having your addin check for available updates from time to time.

I want to show you the simplest form of an update check in less than 20 lines of C# code. Before we can have a look at the code we have to ask ourselves which steps are required to perform:

1. Determine the version of our addin that is currently running
2. Retrieve information about the latest version of our addin from the web
3. Compare these two versions and decide whether the currently running version is outdated

Step one is fairly easy: By the use of System.Reflection.Assembly we can determine the version of the assembly the currently executing code resides in like so:

// Determine the Version of your addin by getting the assembly version
// of the assembly that contains the code that's currently being executed.
Version currentVersion = Assembly.GetExecutingAssembly().GetName().Version;

Before we can implement Step 2 we have to decide how and where we want to store the version information of out addin on the web. For this example we simply create a single-line text file (.txt) with the version number of our latest addin build:

Next we place this file on our web space so that our addin can retrieve it from there. For instance the URL to the file could be http://ourwhsaddin.com/OurAddInVersion.txt.

Now we can write the code that will download the version information file and parse its contents:

// URL of the file containing the version number of the latest available
// version of your addin
String versionURL = "http://ourwhsaddin.com/OurAddInVersion.txt";

// Prepare the HttpWebRequest object for downloading the version information
// file
HttpWebRequest req = (HttpWebRequest)WebRequest.Create(versionURL);
// Set the current addin + version number as user agent so that
// the web server logs it as the "user's browser"
req.UserAgent = "My WHS AddIn Version " + currentVersion.ToString();
// Set the cache policy so that the version informatin file is always
// downloaded and not retrieved from the local cache.
req.CachePolicy = new RequestCachePolicy(RequestCacheLevel.NoCacheNoStore);
// Get the version information file by executing the web request
WebResponse resp = req.GetResponse();
Version availableVersion;
using (StreamReader sr = new StreamReader(resp.GetResponseStream())) {
    // Read and parse the version information
    string availableVersionString = sr.ReadLine();
    availableVersion = new Version(availableVersionString);
    sr.Close();
}

As you probably know web servers usually log all activity for hosted content like client IP addresses, users’ web browsers (= User Agent) locations of accessed files and so on. If you want to be able to determine which versions of your addin are performing update checks you can set the addin name and current version as user agent (see above) and you will find this information in your server logs.

The code above is pretty self-explanatory (I think). We create System.Net.HttpWebRequest object from our version file URL, set the user agent string and cache policy and execute the request by calling GetResponse() on it. We then set a System.IO.Streamreader on the response stream and read the first (and only) line from the stream (= our version information file). The next step is to convert the version string into a System.Version object by creating a new System.Version object passing the version string to the constructor.

So we have the version of our currently running code in currentVersion and the version of the latest available release in availableVersion. Our last step (Step 3) is to compare these two in order to determine whether the latest release is newer than what’s currently running:

if (availableVersion > currentVersion) {
    // A new version is available for download

}

Tadaa! That’s it! Of course you’d have to do proper exception handling which I omitted from the example in order to make the code look simple and clean.

Like I said this is the most basic form of an update check mechanism. Instead of downloading a simple text file we could set up a web service and submit more information about the current addin version when we call it. But be sure that you respect the user’s privacy, when doing this! We could also include the download URL and version history in the text file (or the web service response) and display it to the user when we notify them about the availability of an update. The possibilities are endless!

While it’s a nice feature to get update notifications I believe it would be best if the operating system would handle this and users would have a central place where they can go to update their software. However, Windows Home Server does not have such a place but the upcoming AddIn Central from HomeServerLand looks very promising and I hope that it will become this central place of addin administration.

UPDATE:

I just got notified by Björn Bürstinghaus that they are still looking for beta testers for the german version of AddIn Central. If you speak german and want to participate in the beta please visit http://blog.buerstinghaus.net/add-in-central-beta-fur-den-home-server/ and leave a comment. You’ll then be contacted by the AddIn Central team via email.

As you probably know, the Advanced Admin Console AddIn (AAC) checks for available updates from time to time by querying a webservice. In order to get an idea of how many people are actually using AAC I did some statistical analysis on the web server’s logs and here are the overwhelming results:

AAC is being used in 53 countries and by almost 13,500 people in the United States, Germany and the United Kingdom alone.

Countries with < 0.5 % of installations are filed under ‘Other’. These are (in order of number of installations): New Zealand, Spain, Portugal, Greece, Finland, Italy, South Africa, Ireland, Poland, Hungary, Brazil, Czech Republic, Slovakia, Luxembourg, Israel, Slovenia, Croatia, Iceland, Ukraine, Lithuania, Argentina, Romania, Turkey, Estonia, Zimbabwe, Bulgaria, Mexico, Malaysia, Latvia, Peru, Venezuela, Chile, Dominican Republic, Serbia and Montenegro, Bolivia, Republic of the Philippines, Jamaica, Kuwait, El Salvador

Woohoo!

It’s been a while since Microsoft started their Stay-At-Home Server marketing campaign for Windows Home Server. Part of this campaign was the release of the tongue-in-cheek children’s book “Mommy, Why is There a Server in the House?”. It even was available for purchase at Amazon.com.

I happen to have a spare copy of the book to give away to one of you Windows Home Server users/enthusiasts. All you have to do is send me your story about how you’re using one of my addins (Advanced Admin Console, Update History, FRITZ!Box Anrufliste) explaining which use you get out of them and how they make your lives with your Windows Home Server easier. The best story will be published on this blog and the author will be given the brand new (paperback) copy of the “Mommy book” (free shipping worldwide!).

The winner will be drawn on March 16th, 10:00 pm (Germany time, GMT+01:00).

Use the contact form to send me your story (don’t forget to include your full address). The lucky winner will be announced on this blog and via Twitter, so make sure to subscribe to my blog’s RSS feed and follow me on twitter so that you won’t miss it.

Good luck!

Update: Since I did not receive any user stories from you there’s no winner to announce.

Windows Home Server has been covered lately over at HowToGeek.com with an article about the Advance Admin Console AddIn being the latest addition to the series. The article which you can find here will walk you through the installation, configuration and usage of the Advanced Admin Console. If you want to learn more about the power user features of this addin I recommend reading my Feature Focus article series:

Feature Focus 1: Minimize

Feature Focus 2: Show Desktop

Feature Focus 3: Windows PowerShell

To be continued…

This is the third in a series of blog articles highlighting some of the non-obvious features of my popular Advanced Admin Console Add-In (AAC) for Windows Home Server. You can find a German version of this article over at www.home-server-blog.de.

Users of the Advanced Admin Console Add-In should be able to perform any administrative task on their Windows Home Server with it. As with everything, there’s always more than one way to do things. While many users are quite happy with graphical user interfaces and using the mouse there are others who value the lightness and speed of text-based command line interfaces. Advanced Admin Console contains links to the classic Windows Command Prompt (cmd.exe) that has been part of Windows NT-based operating systems since the dawn of time, as well as to the “new” Windows PowerShell.

Windows PowerShell is Microsoft’s object-oriented command-line shell and scripting language. It’s way more powerful than cmd.exe. However, it’s not preinstalled on Windows Home Servers so when you try to launch it from the AAC toolbar you’ll receive the following error message:

So in order to be able to use Windows PowerShell on your server you will have to install it first. The easiest way to do that is by using my Update History AddIn.

Windows PowerShell is available as an optional update on the Windows Update website. Simply click on “Launch Windows Update” on the “Troubleshooting” menu of the Update History AddIn:

On Windows Update click “Custom”:

After searching for available updates is complete, click “Software, Optional” and select “Windows PowerShell 1.0 for Windows Server 2003 (KB926139)”:

Now click “Install updates” and wait until the selected package has finished installing.

From now on you can launch Windows PowerShell from the AAC toolbar:

If you haven’t worked with PowerShell before you should visit the Windows PowerShell website to get started.

PowerShell 2.0 was released by Microsoft back in October 2009 but since it’s not available on Windows Update I wouldn’t recommend installing it on your server.

Fear not! My Windows Home Server Add-Ins (Advanced Admin Console, Update History, FRITZ!Box Anrufliste) have always been available at no charge and they will be for the foreseeable future. However, every now and then I get emails from users who find my add-ins really useful and want to show their gratitude by donating money for my work. While I appreciate their offers I still refuse to accept money for my WHS community add-ins.

I’ve developed these add-ins out of curiosity and passion for the Windows Home Server platform. I’m very much committed to being a member of the WHS community and by accepting donations I might be incurring liabilities for the future and raising expectations which I might be unable to meet.

If you want give a donation I think it would be best to donate your money to NGOs who work hard to make life better for millions of poor people on this planet. That was my response to the latest donation inquiry from Justin Caron. He didn’t hesitate and donated $50 (CAD) to the Haiti Relief and Development fund of the Red Cross. Well done, Jason!

So please, if you have some money to spare think about giving some of it to those who really need it (instead of offering it to me)!

P.S.: You also may want to read this article on the subject of making donations to Haiti: What To Think About Before Giving Money To Haiti

This is the second in a series of blog articles highlighting some of the non-obvious features of my popular Advanced Admin Console Add-In (AAC) for Windows Home Server. You can find a German version of this article over at www.home-server-blog.de.

As a user of the Advanced Admin Console Add-In you know that you can run external programs like Task Manager or the Windows Command Prompt from the Windows Home Server Console by utilizing the AAC toolbar. If you’ve read my first AAC Feature Focus article describing the Minimize feature, you also know that while you can minimize the WHS console and switch back and forth between multiple running external programs, you do not have access to the Windows Home Server’s Desktop.

Even though I see little reason for running a fully fledged desktop session with taskbar, start menu and everything on your server, I’ve included this feature in AAC Version 0.5.0 because many people were asking for it.

If you want to start a desktop session all you need to do is click on ‘Show Desktop’ on the drop down menu at the top right hand corner of the Advanced Admin Console toolbar:

Advanced Admin Console will run explorer.exe which itself provides the taskbar, start menu and desktop functionality. You are now free to do anything on your WHS machine but remember: Windows Home Server was NOT designed to be used this way and Microsoft explicitly discourages users from doing so. Everything you do from there is at your own risk. Microsoft support services will most likely not help you with problems that arise from your fiddling with the WHS desktop.

That being said, have fun exploring your Windows Home Server!

Note: It is very likely that after clicking ‘Show Desktop’ you will see the taskbar only for a short time. Next thing you see is a full screen Internet Explorer window warning you from using the desktop too carelessly. After you close this window you will be brought back to the WHS console and the taskbar is gone. That’s when the Minimize feature of the Advanced Admin Console Add-In comes to the rescue: Just click the Minimize button in the lower right corner of the AAC window and you can finally start working with your server’s desktop.

There’s one final thing you should be aware of: When you close the WHS Console window on your client computer the Windows Home Server Console and any external program you started from it will keep running on your server. This is also true for the desktop session you launched using AAC. Because of that you really should log off from the server (either from the WHS console or the start menu) instead of just closing the console window. Otherwise one of the external programs or the desktop may prevent your server from going to hibernation or power off when it should.

The next installment of my “AAC Feature Focus” article series will explain the “Windows PowerShell” command on the AAC toolbar and why it doesn’t seem to do anything useful. If you don’t want to miss new articles simply subscribe to my RSS feed.