Share via


Tao of the Windows Installer, Part 1

Ever agreed to something you thought was a quick favour, just to see it balloon into a massive project?

Well, towards the end of last year a customer asked me for a list of "best practices" for the Installer. Being helpful, I agreed to send one and started looking for a list. Now, as the Installer was released last millenium, I assumed that someone would have created such a list by now and my search would be short. How wrong I was.

After much hunting, I couldn't find any document solely devoted to Installer best practices. Sure, there are recommendations and advice scattered around various sources - from my own experience and that of other Installer users in Microsoft to white papers and the SDK - but nothing dedicated to giving straight advice on what to do and what not to do with the Installer.

Having agreed to provide the list, I had to get one somewhere, so I decided to create my own from the many individual bits and pieces I gathered in my search. This is where things just seemed to take on a life of their own. I had envisioned a short (1-2 page) list, but some months later ended up with a 30+ page document!

Once I had this in reasonable shape, someone pointed out that it would probably be useful to the whole Installer community and not just one customer. So here it is - or at least here is the first part.

I initially looked into publishing the list as a white paper for download from the Microsoft web site. Unfortunately, the process of editing and reviewing white papers can take a while, so I decided to post here on the Installer blog first. Mainly so that the information can be made available quicker, but also just as importantly, so you can give some feedback to help improve the final white paper.

The paper is currently divided into various section, including a brief description of Installer functionality, troubleshooting advice, etc. However, the bulk of it is a series of "rules" (that is, the "best practices"), split into the following subtopics:

This week, I'll cover the short Fundamentals section, with the other sections following on an approximately weekly schedule. Feel free to point out the good, bad and ugly in the list - your feedback will make sure that the final whitepaper will be as accurate and as useful as possible.

Fundamentals Rule 1: Learn the Windows Installer Technology
The importance of this rule cannot be overstated. If you only follow one rule, this is the one to choose. Microsoft Product Support often speak to Installer users who are installing packages which they created with a sophisticated high-level re-packaging tool, without any understanding of how the Installer actually works. While these tools are excellent at what they do and they abstract the user from the details on a day-to-day basis, the lack of Installer knowledge becomes a real problem when the package does not work as expected. Setup authoring is not simply about copying files. The Installer offers extensive functionality and complexity; understand it before you start authoring packages. Start with this guide, then read the white papers, books, etc mentioned in the Resources section, then follow Rule 2.
Rule 2: Know Your Way Around the Installer SDK
The best resource to help with Rule 1 is the Windows Installer SDK (usually just called “the SDK”). It is the definitive guide to the Installer technology and covers all aspects of creating packages, including detailed descriptions of database tables, properties, custom actions, etc. The SDK is designed as a reference and so you shouldn’t try to read it from start to finish. However, it does contain many tutorials and specific examples you may want to follow and try out for yourself. In any case, you should make yourself familiar with its contents and use it as your first port of call when you need to know something about the Installer.
Rule 3: Use the “Windows Logo” Program as a Basis For Good Practices

The "Designed for Windows XP" Logo Program is designed to help give users confidence in the software and hardware they buy to work with Windows. The logo ensures that any software conforms to a Microsoft-defined set of criteria that are designed to provide a consistent, high quality software experience. So, even if you do not intend to submit your application to the logo program, you can still use the guidelines to help make your Installer packages better. Many of the logo requirements for software are covered if you use the Installer as your installation mechanism. Some of these rules are shown below, with more details available on the logo program website.

  • Do not attempt to replace files that are protected by Windows File Protection
  • Migrate from earlier versions of Windows
  • Do not overwrite non-proprietary files with older versions
  • Do not require a reboot inappropriately
  • Install to Program Files by default
  • Install any shared files that are not side-by-side to the correct locations
  • Support Add or Remove Programs properly
  • Support “All Users” installs
  • Support Autorun for CDs and DVDs
Rule 4: Always Use the Latest Version of the Installer

Using the latest version of the Installer gives three important benefits:

  • Extra features. Version 3.1 is the Installer version at the time of writing. This contains many new and enhanced features over earlier editions. In particular, from version 3.0 of the Installer, patching and patch management was greatly improved.
  • Bug fixes. Using the latest code, and keeping this patched with current updates from Microsoft Update, ensures that you are more secure and will avoid known problems.
  • Support. Microsoft does not support or issue bugfixes for older Installer versions, such as v1.1. Always using the latest version means that Microsoft Product Support will be able to assist with problems and supply updates and patches.
Rule 5: Build Setup Into Your Application Development from the Start

Installation absolutely should not be an afterthought in the development process. Many developers don’t like the idea that “setup” should influence the design of a product, but when using the Installer it is crucial to develop the two in parallel. Thinking up-front about how an application will be installed makes it easier to take advantage of the idea of “features”, “self-repair”, etc. So, rather than forcing the software into some artificial split or limiting very large applications to a single feature, you will end up with a more user-friendly and resilient install. Remember that:

  • The developer writing the code knows better on what, how and where the configuration data for thier application/module should be
  • It is better to grow the stability and confidence of the product setup along with the confidence in the product itself: a poor product setup will leave lasting bitterness with the user
Rule 6: Get to Know ORCA
ORCA is an MSI package editing tool that ships with the Installer SDK. It has a basic GUI interface but supports advanced editing of Installer Databases. It is possible to create a new package completely with ORCA, but this would be very tedious and error prone; equivalent to writing the Microsoft.com website in Notepad - possible, but not something you’d really want to do. Where ORCA excels is in letting you quickly view and edit package contents for troubleshooting and testing. This reason alone should be enough reason to become familiar with using ORCA, but it also provides a convenient way to validate your packages - a vital step during package creation and testing.

[Author: Richard Macdonald]

This posting is provided "AS IS" with no warranties, and confers no rights.

Comments

  • Anonymous
    May 02, 2006
    The comment has been removed
  • Anonymous
    May 02, 2006
    The comment has been removed
  • Anonymous
    May 02, 2006
    I've loved the concept of the Windows Installer technology since the day I saw it.  From my past years at MS though I think there needs to be some time spent spreading the news of how cool it is internally to the product groups.  The Visual Studio folks should really get around to leveraging the stuff that shipped in WI3.x for the Setup Projects!
  • Anonymous
    May 02, 2006
    Please reorder - Number 5 should be number 1!

    Developers who are not familiar/interested in installer really need to understand the HUGE impact a install experience can have on the perception of their product.
  • Anonymous
    May 02, 2006
    The comment has been removed
  • Anonymous
    May 02, 2006
    Michael, the WiX toolset (http://wix.sourceforge.net) is an alternative to using Orca.  You have the ability to stay very close to the Windows Installer technology without having to worry about every itty-bitty detail (like keeping foreign keys cased correctly).  It is also free like the rest of the Platform SDK.
  • Anonymous
    May 02, 2006
    "read the white papers, books, etc mentioned in the Resources section"

    Where's that?
  • Anonymous
    May 03, 2006
    thanks, Rob. I know about the WiX toolset (and that some internal Microsoft projects are using it - though i don't know how big they are). Especially the "Clickthrough" subproject seems promising (but don't have the time to test how stable it already is).
    I were just wondering if the VS2005 MSI Support is really the only easy-to-use tool to created msi packages from Microsoft.

    I like the integrated with the build approach from WiX (it should be on the list as a MSI best practice :-) ), because VS2005 MSI seems not to scale for projects with about more than 5-10 people.
    WiX certainly would.
  • Anonymous
    May 03, 2006
    I'm a long-time install developer who grew up on InstallShield's InstallScript. Switching to WI was painful. There was no way I could have made the switch without using a tool like InstallShield to create the package. In many ways WI provides a lot of standardization and consistency that I value. In other ways, I'm frustrated by the fact that I seem to be creating dozens of custom actions for most of my installs and that some seemingly simple things aren't built into WI that ought to be.
    I'm looking very much forward to the rest of your doc. Thank you!
  • Anonymous
    May 03, 2006
    The comment has been removed
  • Anonymous
    May 04, 2006
    I don't think I've encountered many installers that can't manage an "All Users" install (whether the application uses the right data folders is another matter), however packages that actually work in all three deployment scenarios (user/computer assigned & published) is another matter.
  • Anonymous
    May 04, 2006
    I think you should rename the rules to be "Guidelines until we (Microsoft) decide to change our minds again".  
  • Anonymous
    May 05, 2006
    I disagree with rule 4 (always use the highest version):
    1. Older versions support a wider range of platforms, eg. Windows Me and Windows NT.
    2. Upgrading system software on a target system may require a reboot, which could be costly for certain customers.
    3. Upgrading system software on a target system may break down other applications that were authored poorly.

    An example of #3 is MDAC: I once had an app that required MDAC 2.6 or higher. The manager decided to install 2.8. So we did, and dozens of customers complained that their ERP software (present on the same systems) became unreliable after installing our software.

    The mentioned 'pro' reasons are :
    * new features: Only use this reason if you intend to use these features.
    * bug fixes/security: This reason is only valid when these fixes have an impact on your software.
    * Support: Like older versions, support for WI 3.1 will end sooner or later, probably long before you withdraw your product from the market.

    In my opinion, the only true reason for using the latest version is a reduction your testing efforts - you have less versions to test. For everything else, use the lowest version that suits the needs of your product and your customers.

    Zweitze.
  • Anonymous
    May 07, 2006
    I've given up on msiwish myself.  Seriouly, Windows Installer came out with Windows 2000  and 7 years later LockPermissions STILL can't properly handle ACL's.   That's just one example of a time that custom actions need to be written instead of just authoring table data.

  • Anonymous
    May 08, 2006
    The comment has been removed
  • Anonymous
    May 08, 2006
    The comment has been removed
  • Anonymous
    May 08, 2006
    The comment has been removed
  • Anonymous
    May 10, 2006
    While I agree entirely with your Rule #1, the biggest problem for a developer trying to learn the Windows Installer is "Where do I begin?"

    Believe me, I want to understand the installer as much as possible (as I'm sure most developers would), but by just looking at your post for resources you reference a Knowledge Base article and a link on MSDN.  The problem with these 2 links?  They are also pages that contain more references to other resources, newsgroups, blogs, etc.

    The most detailed part of the installer we have is the SDK documentation.  But as you pointned out, "The SDK is designed as a reference and so you shouldn’t try to read it from start to finish."

    Why can't there just be one resource that we CAN read from start to finish?  

    The books & white papers in the Microsoft Patterns & Practices are great.  You can read them from start to finish and have a better understanding about the topic being covered.  A good example of an excellent document is the Team Development with Visual Studio .NET and Visual SourceSafe.

    If there were that one book or resource we could go to I'm sure most developers would try to follow your other rules.

  • Anonymous
    May 10, 2006
    The comment has been removed
  • Anonymous
    May 11, 2006
    I know my last post sounded like a rant, but I also wanted to thank you for starting this article.  Your post was one of those "finally, I found it" type of blogs.

    Maybe when this is complete it will be the resource to reference? ;-)  Good luck with the rest!
  • Anonymous
    June 08, 2006
    It's important that you run ICE validation on your MSIs and MSMs, and that you fix any and all ICE errors, treating warnings subjectively.
  • Anonymous
    July 08, 2006
    I recently noticed a series of in-depth articles that have been posted on the Windows Installer team...
  • Anonymous
    September 11, 2006
    If you're following this article, you must be interested in modifying how an MSI produced by a Visual...
  • Anonymous
    September 18, 2006
    PingBack from http://blogs.msdn.com/windows_installer_team/archive/2006/07/28/681358.aspx
  • Anonymous
    September 18, 2006
    PingBack from http://blogs.msdn.com/windows_installer_team/archive/2006/06/27/648447.aspx