SSW Rules to Setup Packages

Is your Setup.exe real user friendly with just Next, Next, Next?

Ideally the setup.exe should not be complicated. Its only purpose is to allow the user to install the required software so that it can be run or tested.
Simple meaningful screens for every dialog of the installation will help the user only click "Next, Next, Next" until the application has been installed correctly.

See http://www.ssw.com.au/ssw/Standards/WiseSetup/UserGuide.aspx for an example of appropriate dialogs used for the setup.exe.

Do you avoid deploying a separate application for users to check for update?

We used to include the built-in Wise Update in our applications for users to check and update to the latest version easily. However the problem is that users dont check for updates manually.

Figure: Wise installer provides a version checker as a merge module for easy integration.

Figure: A separate application to check for update, how often will you check for update manually? (Bad)

Wise updater will never work because the WiseUpdt.exe is being called from the application - so it can't fully uninstall itself when it is open - so it asks for a reboot.

The better way to check for updates is to do it automatically whenever the application launches. We implement a version checker on the first wizard screen or applications main screen, this way the users will know that we have a newer version available.
E.g.:

Figure: Users know that a new version is available, and they can click the link to download new version. (Good)

See http://rules.ssw.com.au/Management/RulesToSuccessfulProjects/Pages/AllowUsersToCheckNewVersionEasily.aspx to see how to implement.

Do you keep your setup source files in a standard location?

For consistency, always keep the <Application>.bld and <Application>.wsi in <Application Folder>\Setup.

Do you build a new version every day there are changes (a.k.a. Continuous Integration)?

Each time changes have been made to an application, a new version should be built at the end of the day (as a minimum). This enables testers to test the latest version, and gives clients the ability to check progress made on their application.

The easiest way to achieve this is to have a continuous integration server (we use Team Foundation Build Server). The continuous integration server automates a build and unit test run for an application and reports on success/failure of the build and tests.

At the end of a successful auotmated build process the install files produced are available for testers and clients to use.

This process can be automated to run at specific times during the day and/or after each check in to source control.

Figure: Configure in TFS to build a new version every day

Do you display the version number publicly?

Displaying the version number publicly allows easier access to version number for both testers and clients.

There should be 2 specific ways of displaying the version number:

1. A 3 part version number to be displayed throughout the application made up of the Major, Minor and Patch numbers
2. A 4 part version number (including the build number) and date for display on the Help, About screen

The version number should be meaningful.

Figure: 4 part version number with no date / build number (Bad)

Figure: 4 part version number with no date / build number - not meaningful to the user (Bad)

Figure: Proper display of 3 part version number on main screen (Good)

Figure: Proper display of 3 part version number, date and build number on Help, About screen (Good)

Figure: Proper display of 3 part version number, date and build number on Help, About screen (Good)

This is how we follow our version conventions for .NET projects

Is your version number meaningful?

A version number is only good if it conveys useful information. We use a 4 part version number which is made up of the following:

1. Major version number
2. Minor version number
3. Patch number
4. Build / Changeset number

Each part of the version number has specific meaning:

• The Major version number should only be changed at the discretion of the product owner. This is usually due to addition of completely new areas of functionality for the application.
• The Minor version number should be incremented for each release and resets to zero for a new major version.
• The Patch number should be incremented for each hotfix applied in between releases and resets to zero each new release.
• The Build number should match the TFS changeset number and this increases non-sequentially over time.

See the reason for making the build number match the TFS changeset number, and why it increases non-sequentially.

Figure: 4 part version number - not meaningful to the user (Bad)

Figure: Version number is more meaningful to users and testers (Good)

Do you make a setup.exe before development?

The setup.exe should be in the first release. Many developers leave it to the end and all sorts of problems start happening when we realize that it would be better if the application creates the virtual directory, rather than the setup.exe Nothing good can happen when you leave the setup.exe to the end.

Can you make a setup.exe in one step?

Making a setup.exe should be simple. As I have do to it every day I want to make it as painless as possible. If it takes too long to package up your software, you're going to run into troubles.

Regardless of the size of the project, if there are many steps involved in creating a build, then chances are you will run into problems.
My recommendation is to aim for a one-step build. A single program (or script) that gets all the latest required files, adds a version number, compiles them, generates a setup executable and places it on the correct media - CD ROM, FTP Site, etc.

On our .NET software development projects, look at all the steps we need to do to make a setup.exe

1. Add a version number to the AssemblyInfo.vb or AssemblyInfo.cs
   • eg.

     // "2.22" - DH 05-08-2004 implementing .NET error catching and
     
     // "2.23" - DH 16-08-2004 Clean up setup and options screen
     
     
     
     [assembly: AssemblyVersion("2.24.*")

2. Build Solution
   
3. Open wise and change the Version number
   e.g. Updating Version number 2.24 to:
   • Product Details,
   • General Information,
   • Shortcut Names,
   • Wise Update .ini file information,
   • Product Summary,
   • Any Many more places in wise where eg "2.23" would be found.
     
4. Change the Source Paths in Wise for files
   • All WiseSourcePaths need to be made generic
     i.e.
     from "C:\Data\SSWCodeAuditor\References\TaskScheduler.dll"
     to "..\References\TaskScheduler.dll")
     
5. Rename the executable file to have version number
   • SSWCodeAuditor_2-24.exe (or SSWCodeAuditor_2-24.msi)
     
6. Copy to a specified location
   • e.g. \\ant\ssw\Download
     
7. Q:\ Would you like to make this version live??
   • If "yes" then
   • Copy to ftp location
   • Update database table
     
8. Now the product can be installed.

Figure: Bad - The common way to update version number and build solution

Now you can automate this using the following methods:

• Visual Build Professional (Recommended)
• MSBuild (Recommended)
• .bat file
• . vbs script
• nANT
• Final Builder

We have chosen Visual Build Pro to automate our Version numbers in our .msi files. This lessens the steps significantly. For future projects we will use MS Build as we see this as the way forward with automating builds. MS Build provides several advantages including, customizable build tasks, integration with a continuous build server, source controlled build scripts.

1. Add a version number to the AssemblyInfo.vb or AssemblyInfo.cs
   • eg.

     // "2.22" - DH 05-08-2004 implementing .NET error catching
     
     // "2.23" - DH 16-08-2004 Clean up setup and options screen
     
     
     
     [assembly: AssemblyVersion("2.24.*")

2. Check-in all files and folders and close the solution.
   
3. Right-click the VBPAutoBuild.bld file in the Setup folder and select "build"
   • If all the steps are "skipped" you must make sure everything is checked in
     
4. After the build is complete, the product can be installed.
   

Figure: Good - The better way to create a setup.exe

Note: Wise or Installshield? Well not that much between them, but we use Wise Install Master most of the time, because it is simpler than InstallShield.
Here you can find our standards of how to use Wise

Do you always update the version number whenever a new build is made?

By using a meaningful version number we can easily identify exactly which version of an application someone is using. If the version number is not changed for each build, we can never be sure which version of an application is being used or what source was used to compile it.

The best way to ensure the build number is always updated is to update it during the build process. We use Team Foundation Server's changeset number instead of an incrementing build number. This can be achieved by using MSBuild Community Tasks.

By using the changeset number as the build number this means anyone can go into source control and retrieve the exact source used to build a particular version of an application. By definition this number is always increasing (it increments any time someone commits a change to the repository). It also means we're implicitly 'tagging' each build. If explicit tags aren't set on the repository for a build/release in other versioning conventions it can be very difficult to identify which version of the source was used to produce that build/release.

It is very common for an application to still require minor fixes before the approval to release it. Developers tend to ignore incrementing the version number for the product even when making a minor change, and do not consider it to be important (perhaps hoping that no one has yet installed the version that has been packaged).

However if the version number has not been increased then the installation package will not prompt the user to upgrade it, rather it will ask the user to repair the product which gives the impression that there has been no updates.

Figure: The setup package will always pop up a dialog box to automate the upgrade of the product as long as the version number has been changed.

Do you put the minimal amount of intelligence in the setup.exe?

The setup.exe should really just do an xcopy. Avoid putting any intelligence (like creating databases or virtual directories) into the Wise/InstallShield Setup. It is much cheaper and better to put this logic into the actual app.

As an example sees the three choices you have for creating a database - see the KB about how to create a SQL Server database as part of a script.

Exceptions do exist. We do put intelligence into the setup.exe if we need a clean uninstall. Examples where we put intelligence in the setup.exe instead of the Windows/Web Application:

• Adding a VS.NET Toolbar - SSW Health Auditor adds a Toolbar - we would prefer to do that inside the UI of the CodeAuditor.exe however if they uninstalled that, the toolbar would still be there.
• Adding a Outlook Toolbar - SSW Lookout and SSW eXtreme Emails have the same situation, installing Toolbars in Outlook
• Installing MSDE - but the uninstall should tell them they have to delete the database first as per RulestoBetterInterfaces.aspx
• Creating a Virtual Directory - SSW Access Reporter has ASP.Net Samples that require a virtual directory to be created. We would like to be able to uninstall it.

Note: If you use one of the exceptions like the above, you should add a text file documenting this.
e.g. C:\Program Files\SSW Code Auditor\_Instruction.txt

Do you know that the installer should only install files to the program files folder?

For your applications the user settings should not stored in C:\Program Files - if you do you can be assured that they wont work in Vista!

Instead you need to store the user's settings in the application data folder. A common mistake is that the installer is used to copy the installer to copy the settings files to the application data folder.

Figure: Bad - The installer copies the settings files to the user's application data folder.

Therefore the installer should only copy files to the installation folder (eg: C:\Program Files\SSW Code Auditor), because if the settings files are copied to the application data folder by the installer, they will get removed on un-installation. This is bad as they contain the user's settings.

The better way of doing this is keeping the default settings file in the installation folder, and when the application starts up, if no settings file is found in the user's application data folder, then copy the default settings file into the application data folder.

Do you skip setup installers for web project packages ?

If you want lots of people to use your Windows App, then you always need an installer. Does the same rule apply for Web apps?

Web applications generally only need to be setup in three locations. That is, the development machine, the test server, and the web (production) server. Therefore there is no need to make a setup package for these projects as they will never need to be installed on a mass scale which means that it's not worth the money to attempt to have a more complicated setup package.

Option 1:

If you have access then simply use FTP to transfer synchronise files between servers

Option 2:

For most of our web projects we will commonly just use a zip file for distributing the project for someone else to install at a remote location. This zip file includes:

• The layout files (.aspx)
• The resource files (.jpg, .css, .js, etc)
• The bin directory with the .dll files
• a _Instructions.doc with screen captures and detailed documentation on how to configure the file system, IIS, and directory security.
  This way our network administrators can be kept happy by having full control over where in the file-system the websites live (which might be important for the backup strategy) and allow us to make full use of webserver features within our application.

Figure: Shows the folder of a website as a Zip File.

Need more reasons:

The reasons we do not make an .exe or .msi for a web project are many. As detailed above it mainly development the development cost that only a couple of people will use. There are other difficulties developing .exe's and .msi's like:

• creating virtual directories. Wise will only allow you to install to the Default Website
• configuring the directory and IIS security options, for example granting the local ASPNET user account access to your physical directory
• handling important settings in the web.config file (remember the normal implementation of a website has this read-only)
• support of other web server platforms (other than IIS)

Note: There is one obvious exception to the rule, and that is when you need to create a sample web project as part of some other application. For example, a website would be included in your .msi when installing a web control component with samples.

Do you have an "Installation Prerequisites" screen during installation?

There is no point to allow the user to install your software and find out they cannot use it. Therefore, the setup.exe should always have an "Installation Prerequisites" screen in your installation, after the first welcome screen.

Furthermore, you should detect if your user's computer meets all these requirements and give them the link to download the required software if possible.

Figure: Detect installation prerequisites and give download buttons

Sometime, it's not possible to detect the required software during the installation. An example would be if you require your users to have SQL Server installed, but this can be on a networked computer. If you have this case then your setup.exe should have an "Other Requirements" form in your installation.

Figure: In this case SQL Server 2000 or SQL Server 2005 Reporting Services can be installed on a networked machine, so the user is only given the information and the application will worry about checking and setting up this.

Warning: Too many times the 'Continue Anyway' approach is not taken, and the developers add validation but with no flexibility to continue. An example of this can be found in an installation package that requires a user to have a certain version of SQL Server, or SQL Server Reporting Services, or Exchange Server, or .NET Framework on his computer. The disabled button stops the user just clicking "Next" without noticing the problem and the checkbox gives the user to ignore it when they know it is OK, for example if a newer version of the .NET Frameword is released that supports .NET 2.0 apps but the registry key that the setup.exe is looking for has changed.

Figure: 'Continue Anyway' checkbox allows user to continue even when conditions are not met (Good)

Do you always use the same name for virtual directory and its physical location?(* This feature has been fixed in Wise 7)

Have your installer educate with a screen capture?

In your Installer need include a screen capture like below:

Figure: While installing Resharper, then teach you 8 things about the product. Awesome.

Do you include version numbers in your setup filename?

I'm always downloading my favourite 3rd party software utilities from the web. But I find it very frustrating if the developer has not made it easy to check whether I've already got the latest version. It is not OK to expect a user to run the setup.exe in order to find out what version it is.

The easy solution is to include the version number in the name of the setup file. We use [productname]_ver[major version]-[minor version].exe E.g. SSWCodeAuditor_Ver1-89.exe

In .NET, however, you strike a problem. .NET removes any 0 in the prefix and so e.g. _v1-02 becomes _v1-2.  The rather contrived solution is to start minor versions at 11. Therefore _v1-11.exe is your first version.

To deal with those naughty developers who don't include version numbers, rename the file after you download it...

Figure: Download the software then rename it with version.

setup.exe
ExtremeEmailsSetup.exe

Bad setup file name

ExtremeEmails_Ver1-12.exe

Good setup file name

Do you have an "unattended installation" screen in your installer?

The installer should include a screen showing how to do an unattended installation.

Figure: Including unattended installation information