Sunday, September 19, 2004

Top 20 Installation Pet Peeves and How to Avoid Making Them

This Top-20 list of pet-peeves/annoyances is presented in no specific order and pertains to all installations, however, some items and examples directly relate to MSI based installations.

Am I missing your top pet-peeves? Are you guilty of any of the below and care to admit it? Please leave feedback in the comments!

20. Security and profile unaware installations. Can the application be installed or used by a non-administrator? Use the principle of least-privilege to ascertain what the real limitations are and make installations compliant with it. Respect user profile settings. Is the installation storing sensitive information unencrypted (such as passwords) in your log files, registry/INI files, or MSI files?

19. Installing to a location other than "Program Files" by default. This also applies to installations that assume "Program Files" is located on the C:\ drive. I recommend testing installations and applications on systems that have Windows installed to a drive other than the default C: drive with a Windows directory name other than Windows or WINNT to catch these assumptions.

18. Non-application file storing directories sharing the application directory. No application should store configuration information or user data (by default) to a directory other than the current user's documents and settings directory. Similarly, if the installation is creating a shared folder, virtual directory, or a directory that will have security implications/working data in it (such as file-sharing or database), the user should be able to select this directory separately (and it should be defaulted to a non-Program Files directory). The rationale for this is simple: Applications are restorable by reinstalling the software. User data isn't. Make it easy for the user to back up these items by default.

17. Not providing a merge module if this software will be redistributed by other vendors. I absolutely despise running an executable from my installation to install a 3rd party component. Not only do I have no idea if the sub-installation succeeded or failed, but automatic reference counting is impossible. If I repackage it, other vendors could do the same and we have out of whack component codes and keyfiles causing endless automatic repair cycles, maintenance, and removal nightmares. This also adds an easy way to assure a common method of distributing patches if the third-party software is found to have a security vulnerability.

16. Full screen installations are evil. Why does the entire screen need to be used for an install whose UI is 640x480 or less? Can't I do anything else while the install is in progress? Conversely, if the install requires a screen resolution greater than 800 x 600, my parents can't install it (or worse yet your help desk will be overwhelmed by my parents and their friends).

15. Product Serial Numbers are usually a pain. If the installation is using the Microsoft style dash separated product keys, don't also suffer from same problem that prevents a simple one step cut and paste from a registration email into the install UI. Also, try to prevent the use of commonly confused digits in the registration code, as it is font and eye-strength dependent when trying to figure out if the code is a capital O or a 0, a lower case l or a 1. If millions of codes are not needed, consider axing the U and V as well.

14. Multiple level start menu shortcuts. If a folder in the start menu only has one option in it, please do not put it into a folder. Also, make sure the folder name makes sense to the majority of end users. If I'm looking for a program "Ink Blot" am I going to think to look in the folder "Joe Schmo Software" first?

13. Unintelligent replacement of system or other redistributable files. Are you using a merge module for redistributables if one exists? Does the install check file versions/dates before replacing them? Is reference counting (shared dlls for legacy installations) being set properly? Are all required redistributables included?

12. Unnecessary Reboots. The converse is also true, where reboots are required but not asked for. Also in this category is detection of running software that makes a reboot necessary prior to running the guts of the install. Please let the user know if they can do something that will prevent a reboot at the end. If it is an older version of the installed application that is running that will require the reboot, do what is required to prevent the reboot (as long as you tell the user first). See Pet-Peeve #3.

11. Upgrades that require an uninstallation of the old version first. If this is truly required, is it being handled automatically?

10. Asking useless questions. If the installation behaves identically regardless of the install type (minimum/typical/custom) why is that dialog there? If there is a difference, is the text on that dialog accurate and/or does it make sense in the context of your application? Also in this category are error messages such as "Unable to do something important. Would you like to continue?" when "something important" is essential to the functionality of the application. This can also extend to the age-old useless "shared file no longer in use, should I delete" question.

9. Status bars that are not accurate (or present). I realize that writing status bar code is incredibly difficult. If we are talking InstallScript, VBScript, or JScript installations/actions threading is impossible, so the author can't give a moving status bar when performing a synchronous operation (like creating a database). If an alternate method is not possible, another strategy is to put a message up saying "Busy doing [something long] which may take up to 10 minutes, started at xx:xx". If you are using a C++ custom action that can be threaded to perform the synchronous action, determine the maximum time on the slowest PC meeting your system requirements and provide a time-based incrementing progress bar.

8. Allowing free-text user inputs when choices can be given. As an example, let's say the installation upgrades a database. Presenting a free-text input box for the old database name is a recipe for disaster. Instead, the install can perform a SQL query of the database server to get a list of databases. If the upgrade is applicable only to a specific type or version of database, it can then query each existing database to determine which ones the upgrade can be performed on and populate a selection list. In silent mode, any UI level checks will not be run, so validation should be performed on any command line parameters as well. See pet-peeve #1 and #6.

7. Requests for source media. If I am on my laptop (and more people are each day), and especially if I am out of the office (or a remote employee) it is practically impossible to get the source media at a moment's notice. This is especially true for installations of patches where a security vulnerability is in the wild and users need to patch immediately. Make sure nothing is being done that would prompt for source media if possible, and try to assure that the MSI and support files is going to be available by caching locally by default. Office 2003 made significant headway in this department.

6. Non-working silent installations. Make sure silent installations work properly. This includes checking properties set on the command line as you would user input in the UI, and failing with some meaningful error posted to a log if required parameters are bad or not present. Are all user interface elements able to be passed in via the command line? Failure to provide a silent installation means IT departments will grumble heavily or look for an alternative if they need to deploy your application.

5. Repair/Maintenance/Uninstallation/Rollback doesn't work. If the install is not going to provide anything useful for maintenance mode, get rid of the option. Make sure all custom setup properties are cached somewhere and pulled back in for the repair operation to succeed. Does auto-repair work correctly (delete the install directory, run from the shortcut, and see if it works)? Does an uninstallation remove everything, including cached copies of the installation? Does an error near or at the end of the installation properly rollback the changes (Throw in a deferred custom action that simply fails prior to InstallFinalize)? If altering a DB, is it being backed up before running the portions of the installation that alter it so the previous version can be restored in a failure case?

4. Assumptions that are not checked. If an installation adds a database to SQL Server 2000, is the system checked for the presence of a running SQL server before it allows the user to start the installation? Think about a system that has SQL Server installed, but the service set to disabled or is currently stopped. Similar comparisons can be made to installations that rely on web servers, messenger service, BITS, etc. If the service is not started or set to disabled, is the installation violating pet-peeve #3?

3. Modifying a system globally without asking or telling the user. This is a huge category with security implications. If the installation adds a network share or internet accessible directory, is the user being told this up-front? Take as an example the .NET framework installation. Is the user asked/told if I want ASP.NET installed to the IIS server? The answer is no. A mention of this or other types of global system changes in the documentation alone (especially since most documentation is installed with the product) is unacceptable. Note that most modern media player installations ask the user if he or she wants to associate file types with it. Installations were not always this nice to your system.

2. Not checking return codes. When running a command that is supposed to do something essential for a successful installation, does the installation check the return code and handle the error? A great example of this problem is found in many database installations, where the result of a SQL script is not checked. The application does not work after a reported "successful" installation, and it takes a tremendous amount of time and effort to determine why.

1. Not validating user input. The install allows the user to free-text something in where choices can not be predetermined (see pet-peeve #8); let's say a timeout value or something that is essential for the installation to succeed or the application to function. The user types in "10h" by accident. The install doesn't verify the input is a number or a number within a valid range. Installation fails (bad) or says it is successful, yet the application does not work (infinitely worse).

Aside from this list, a very useful document for installation (and application development)authors to follow is the "Designed for Microsoft Windows XP" Application Specifications. Many of the items listed there are also listed above.

3 comments:

Anonymous said...

Here are my comments on the items you listed (great work coming up with this list by the way, you nailed a lot of the items I've been frustrated with in the past)

17 - Providing merge modules presents serviceability problems because once your MSM is consumed into someone else's package, you lose knowledge of where your bits are shipping and therefore servicing is more complicated because MSPs are applied based on MSI product codes and product families. We have gotten burned by this within Microsoft for MSMs that were shared between different product groups. Visual Studio setup is currently struggling with th tradeoff between serviceability and setup complexity and trying to find the right balance. If you look at VS 2005 beta1, you can see somewhere on the order of 10 add/remove programs entries created for all the various pieces. It is hard to explain to folks who see VS as one big package how it is really made up of several small technologies and that some of them can be added/removed/repaired independently.

12 - I go crazy when I am told that I have to reboot just to get started with a setup. I understand that pending reboots due to other file renames/removals can possibly lead to instability and unpredictable results, but this is an extreme way of dealing with it. The worst is in some of the cases I've seen where rebooting will not clear out the PendingFileRenameOperations registry key (under HKLM\System\CurrentControlSet\Control\Session Manager) and then you are stuck in a loop and are unable to even run setup. Most of the time I hit this in my testing, I manually inspect the key and rename it myself if I deem that it is OK to do so. Most of the time, the entries I see in this key are removal of temporary files in c:\config.msi that are used by Windows Installer during a previous setup - and I haven't seen a case yet where these entries interfere with any future setup.

10 - It seems like the InstallShield wizard adds that "install for just me" or "install for all users" radio button screen to setups by default. Most of the setups I've encountered behave exactly the same no matter what the user chooses

7 - Office 2003 has done a great job with the source request issue but had to take a more extreme step of caching most/all of the source on the local hard drive. Of course, with newer machines having big hard drives, I would greatly prefer that to being asked for a CD when I'm working on a laptop on a plane or something like that

Here are a few additional items that are on my personal list of pet peeves:

1 - Setups that try to be too fancy and value form over function. In my time working on setups, I have maintained the view that setup does its job if the customer only has to run through it once (meaning it is robust above everything else), and if the customer does not even notice it. People don't buy products to see the setup, and they also don't make buying decisions based on what setup looks like - with one exception - if a setup doesn't work correctly, that is the fastest way to lose a customer. That is the type of first impression that is nearly impossible to correct

2 - Products that create files in the installation directory using a non-standard means. Sometimes that means custom actions, though that can be corrected with rollback/uninstall custom actions. The worst is settings files that are created when using the product. Those are generally left behind, and that causes the entire application directory to be left behind when the user tries to uninstall.

3 - Products that are not deployment aware. This means not thinking of issues that could hinder/block Active Directory deployment for MSIs, neglecting to include Admin sequence tables in an MSI (or including them but not including all the standard and custom actions that are needed for the product to work correctly when installed silently). Also, this can include inadequate silent switches (which can hinder admin deployment and block the ability to include a redist package within another setup), and inadequate testing of administrative scenarios.

Steven Bone said...

Responding to the previous comment:
17 - Merge modules. It is important to remember the MSDE merge modules and the issue of patching the Slammer worm brought up. Vendors that installed MSDE as a merge module had to provide a MSP to patch the MSDE instance. Although I never had to use an MSDE merge module I heard it was a nightmare to get working, so my comment here could be incorrect (and please correct me if I'm wrong). I think the issue with patching was related to the ability to create separate instances of MSDE per product. Typical merge modules (I'm talking about the Visual Studio 6 SP 6 MSM's here) are rather safe to redistribute and patch as long as they go to the default destination. I feel the pain of the GDI+ redistributors who placed it in their application directory.

12 - Microsoft is guilty of this one quite a bit:). I think the big problem with allowing the installation to continue with PendingFileRenameOperations can be related to my previous post on the The Case of the Disappearing DLL. I will put a comment in that post as to what my solution was, since I handwaved the first time. I think with a better API to get what is actually going to happen with file replacement and deletion post-reboot, the MSI engine should be able to be smart about allowing this and "fixing" the Pending Operations to avoid post-reboot catastrophes. I believe this is essentially what the qchain.exe hotfix executable does, but that can probably be explained better by a Microsoft person (hint).

10 - I believe the per-user and per-machine installations that are MSI based differ in which part of the HKEY_CLASSES_ROOT section registered DLL's go into. I would imagine most people don't realize that the HKCR in regedit is not really its own hive, but rather a dynamic merge of the HKLM and HKCU Software\Classes branches. Of course, if you use the self-reg table, all the entries go to the HKLM and you defeat the purpose of the CU/LM distinction. Additionally, the shortcuts and HKCU registry keys are the other differences that I can recall from the top of my head.

7 - Hard drives are cheap, fortunately.

New pet peeves:
1 - I guess you are not going to buy my installation skin builder product :) Seriously (no, I am not making such a product), excellent points. I am a bit saddened by InstallShield's new products that seem to have a minimum size of 1.4 MB to install a 1k text file. Hopefully that is not due to fancy graphics. As far as first impressions, I cringe when I install a Wise packaged product with the ugly full screen setup panel. It is not Wise's fault, but I get that from the bad experiences I have had with products using that system.

2 - I have done that one. At least with MSI's I do it with rollback and uninstall actions that remove the files. The problem is the MSI engine simply does not have out of the starting gate power. If I install a WSDL file, essentially I need to edit it to provide the URI for the web service. The MSI engine does not give me this ability by default, yet I was able to write an action that reads a custom table, installs and edits a file and removes it - with rollback support, file in use support, etc. As for settings files created in the application directory by the application, that is weakly covered by my #18.

3 - I missed this one. HUGE issue! When the IT people at work see that I missed that one, I expect my PC will be smashed by a sledgehammer.

Thanks for the comments, and keep them coming.

Jess Graves said...

One a much more base note...

20 and 19. Least privilege is best but please install to Program Files.

I agree with both but to satisfy 19 the installing user must be a Power User or better. Obviously requiring only Power User rights is much better than Admin rights but is there any better solution?

Seems like right off the bat, your install requires Power User or better and when's the last time an install warned that it must be run by a Power User? I've never seen it.

Am I missing something or just ranting about a minor issue in an imperfect world?

Jess