The Definitive Guide - Springer

The Definitive Guide to Windows Installer PHIL WILSON

APress Media, LLC

The Definitive Guide to Windows Installer Copyright © 2004 by Phil Wilson All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying. recording, or by any information storage or retrieval system, without the prior written permission of the copyright owner and the publisher.

ISBN 978-1-59059-297-7 DOI 10.1007/978-1-4302-0676-7

ISBN 978-1-4302-0676-7 (eBook)

Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. Lead Editor: Dan Appleman Technical Reviewers: Chris Gouge, Carolyn Napier Editorial Board: Steve Anglin, Dan Appleman, Ewan Buckingham, Gary Cornell, Tony Davis, Iason Gilmore, Ionathan Hassell, Chris Mills, Dominic Shakeshaft, Iim Sumser Project Manager: Tracy Brown Collins Copy Manager: Nicole LeClerc Copy Editor: Susannah Pfalzer Production Manager: Kari Brooks Compositor: Vijay Nicole Imprints Proofreader: Uz Welch Indexer: Carol Burbo Cover Designer: Kurt Krames Manufacturing Manager: Tom Debolski Distributed to the book trade in the United States by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor, New York, NY 10013 and outside the United States by Springer-Verlag GmbH & Co. KG, Tiergartenstr. 17,69112 Heidelberg, Germany. In the United States: phone 1-800-SPRINGER, e-mail [email protected]. or visit http://www.springer-ny.com. Outside the United States: fax +496221345229, e-mail [email protected], or visit http://www.springer.de. For information on translations, please contact Apress directly at 2560 Ninth Street, Suite 219, Berkeley, CA 94710. Phone 510-549-5930, fax 510-549-5939, e-mail [email protected], or visit http://www.apress.com. The information in this book is distributed on an "as is" basis, without warranty. Although every precaution has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the information contained in this work. The source code for this book is available to readers at http://www.apress.comin the Downloads section.

Contents at a Glance About the Author ................................................. .xiii Acknowledgements .................................................. .xv Introduction .................................................... .xvii Chapter

1

Installations Past, Present, and Future ........... 1

Chapter 2

Building an MSI File: Visual Studio and Orca ....13

Chapter 3

COM in the Windows Installer World ...............31

Chapter 4 Chapter 5

Searches and Conditions ........................... .49 Sequences of Events and Custom Actions ... ........ 67

Chapter 6

How Do You Fix It? ................................ 111

Chapter 7

ASP.NET Setups ..................................... 129

Chapter 8

Installing .NET Assemblies ....................... 141

Chapter 9

Installation Design ................................ 169

Chapter 10

Windows Services ................................... 185

Chapter 11

The GAC and Updating Assemblies ..................201

Chapter 12

Updates Using Patches .............................213

Chapter 13

Installation Environments ........................ .227

Chapter 14

How- Tos, Tips, and Gotchas .......................241

Chapter 15

Exploring the Installer APIs .....................265

Chapter 16

Tools and Futures ..................................277

Index ..............................................................283

iii

Contents About the Author ................................................. .xiii Acknowledgements .................................................. .xv Introduction .................................................... .xvii

Chapter

1

Installations Past, Present, and Future ... 1

Background . .......................................................... 1 Where the Files Go .................................................. 1 Redistributing Supporting Files .......................................2 Installing Windows Services ......................................... .2 Files in Use ........................................................ 2 Security and the Target User ......................................... 3 Maintaining the Product ............................................. 3 Environments ...................................................... 3 The One-Way Nature ofInstallations ................................. .4 Development Ease and the Installation ............................... .4 Development Installs vs. Production Installs .......................... .4

Introducing Windows Installer .....................................5

Transactional Behavior .............................................. 5 Repair ............................................................. 6 64-bit ............................................................. 6 Sharing Files ....................................................... 7 System Integration .................................................. 7 .NET .............................................................. 7 For the System or for Current User .................................... 8 Security ofInstallation vs. Security of Product .......................... 8 Updating and Deploying New Versions ................................ 8 Advertisement ..................................................... 9 Running Your Own Code ............................................ 9 The Tools ............................................................ 9 Summary ............................................................ .10

v

Contents

Chapter

2

Building an MSI File: Visual Studio and Orca ........................ 13

Background . ......................................................... 13 Building a Package ................................................ 14 A First Look at Shortcuts ............................................ 18 More About Properties ............................................ .20 GUIDs: Product, Upgrade, and Package Codes .........................22 Into the Package with Programming ...............................25 Summary .............................................................30

Chapter 3 COM in the Windows Installer World ....... 31 LetJs All Share ....................................................31 Installing a COM Server ...........................................33 Type Libraries .....................................................36 InprocServer32 Entries and Repair ................................... 38 COM Server Dependencies ......................................... 38 Windows Installer Sharing ........................................ 38 Merge Modules and Sharing ........................................39 Building a Merge Module .......................................... .40 Relative Paths and Side-by-Side COM Components ............... .42 A Detour: Locating Components .................................... .43 Back to Side by Side ............................................... .44 Summary .............................................................48

Chapter 4 Searches and Conditions ....................... 49 Searches and Launch Conditions .................................. .49 File Search ........................................................ 52 Registry Search .................................................... 55 Component Search ................................................ 58

More Uses for Conditions ......................................... 59 Conditions and Transitive Components ............................ 60 Persisting Properties ............................................. 63 Summary ............................................................. 65

Chapter 5 Sequences of Events and Custom Actions ................................... 67 The UI Sequence .................................................... 67 AppSearch and LaunchConditions Actions ............................ 68 IsolateComponents Action .......................................... 69 The Forms ........................................................ 69 vi

Contents

The Execute Sequence .............................................. 69 The Windows Installer Service .................................... 74 Using the Windows Installer Log ................................ 74 Custom Actions ................................................... 79 Creating a Custom Action .......................................... 79 Calling a Custom Action DLL ....................................... 86 Passing Data to a Deferred Custom Action ........................... .90 Executable Programs As Custom Actions .............................. 94 Security and Custom Actions ...................................... 96 Preserving the Installation Location with a Custom Action .... 97 Custom Actions in the UI Sequence ............................... 98 Custom Action Scheduling ......................................... 100 Uninstall Custom Actions and Conditions ...................... .101 Commit Custom Actions ............................................ 101 Rollback Custom Actions .......................................... 102

Type 19: Terminating the Installation .......................... 102 Installing and Embedding Other MSI Packages ................... 103

Using TYPe 7 and TYPe 39 ......................................... .103 Using TYPe 50: Launching an Executable to Install a Package ........... 106 Calling Custom Actions with MsiDoAction ...................... .107 Conditions on Custom Actions .................................... 108 Installed ........................................................ .108 REMOVE ....................................................... .108 Component and Feature Conditions ............................... .109 The Interaction of Properties, Conditions, and Installation State ........ 109 Summary .................................................. ......... .110

Chapter 6 How Do You Fix It? ............................ 111 The Major Upgrade ................................................ 111 Preserving Data Across Major Upgrades .......................... 118 Minor Upgrade by Reinstalling ................................... 119 Component Rules and the Minor Upgrade ........................... 122 Versions and Version Lying ......................................... 123 Minor Upgrades and Data Files ..................................... 123 Companion Files ................................................. 126 Uses of Minor Upgrades ........................................... 127 Summary ............................................................ 128

Chapter 7 ASP. NET Setups .................................. 129 The Web Project ................................................... 129 which Web Site Is Used? ......................................... 138 vii

Contents

But I DonJt Want to Use the IIS WWWRoot Folder ............... 138 lIS and Its WMI Provider ........................................ 138 Summary ............................................................ 139

Chapter 8 Installing •NET Assemblies .................. 141 Assemblies and Sharing ........................................... 141 Installer Tables and Assemblies .................................142 Component ...................................................... 142 Feature .......................................................... 143 File_Manifest .................................................... 143 File_Application .................................................. 143 Attributes ....................................................... 143 Installing Assemblies ............................................ 144 What About Gacutil.exe? ........................................... 146 Why Use the GAC at All? ........................................... 147

Exposing . NET Class Libraries to COM Clients .................. 150

Downstream Dependent Assemblies ................................ 155 Creating Side-by-Side .NET COM Components ....................... 155 Assemblies and CAs ............................................... 162 Summary . ........................................................... 166

Chapter 9 Installation Design ............................ 169 Installation Prerequisites ...................................... 169 Does the Application Need It or Does the Installation Program Need It? ...............................169 What Does the Application Do If the Prerequisites Aren't Met? .......... 171 Redistributables As Programs .................................... 171 Other External Installations .................................... 174

Merge Modules ..................................................... 175 The User Interface ............................................... 176

Use Windows Installer Public Properties ............................. 176 Use Transforms to Specify Install Behavior ........................... 176 Delay Collecting Application Data Until the User Runs the Application .. 177 Collect the Information Before the Install Runs ....................... 179 Application Design and the Install ............................. 179 The Application Must Return Meaningful Error Messages .............. 181

Features and Components ..........................................182 Summary ............................................................ 184

viii

Contents

Chapter 10 Windows Services ............................... 185 Service Installation ............................................. 185 StopServices ..................................................... 186 DeleteServices ................................................... 186 InstallServices .................................................... 186 StartServices ..................................................... 186 Installing Win32 Services ....................................... 186 ServiceInstall Table ............................................... 187 ServiceControl Table .............................................. 189 What Could Go Wrong? ............................................ 191 Other Ways to Control Services ..................................... 192

Installing .NET Services ......................................... 192 Should You Use .NET Installer Classes? ........................ 197 Summary ............................................................ 199

Chapter 11 The GAC and Updating Assemblies ........... 201 The GAC ........................................................... .201 Why Use the GAC? ............................................... .202 Why Is Assembly Version Important? ............................... .203 Major Upgrade into the GAC ...................................... .203 Minor Upgrade into the GAC ...................................... .204 Using File Version to Update a GAC Assembly ....................... .208

Policies and Redirection ........................................ .209 Summary ............................................................210

Chapter 12 Updates Using Patches ....................... 213 What Is a Patch? .................................................213 Creating a Patch ..................................................213 Creating the Administrative Install Images ........................... 214 Creating the PCP File .............................................215 Running MsiMsp.exe ............................................. .220 Applying the Patch ............................................... 221 Patching Mul tiple Products ......................................223 Patching Tips .....................................................223 Uninstalling Patches .............................................225 Transforms . ........................................................225

Summary ............................................................226

ix

Contents

Chapter 13 Installation Environments ................... 227 Advertised Installations .........................................227 Privileges and Managed Applications ............................230 Installing from the Internet ....................................231 Security and Advertising with Transforms ..................... .232 SDK Internet Tools: MsiStuff.exe and Setup.exe .............. .233 Installing on Terminal Server ...................................234 Installing on Windows 64-Bit ....................................235 64-Bit Installer Packages ........................................... 236 64-Bit Custom Actions and Searches ................................ 237 64-Bit Folder Properties ........................................... 237 COM Registration and Packaging Tools .............................. 238 Embedded DLLs ................................................. 238 What About 64-Bit.NET Assemblies? " ................... " ., ...... .239 Summary ............................................................239

Chapter 14 How- Tos, Tips, and Gotchas .................. 241 How To ... ..........................................................241 Find Dependent DLLs ............................................ 241 Prevent Repair with a Null Component GllD ........................242 Show FilesInUse Dialog .......................................... .242 Find In-Use Files in the Log ................................. , ..... .244 Uninstall Broken Packages ......................................... 244 List Windows Protected Files ....................................... 245 Install Performance Counters ..................................... .246 Use Properties in the Standard Dialogs .............................. 246 Log an Uninstall .................................................. 247 Stream Data from the Binary Table ................................. 247 Find Updated Files in the Log ...................................... 248 Disable All Advertised Shortcuts ...................................249 Check for Privileges and Administrative Rights .......................249 Validate a CD Key Serial Number .................................. .250 Run a Program at the End of the Install .............................. 254 Advice .............................................................254 Use ARPINSTALLLOCATION to Save the Install Location .............. 255 Custom Action DLLs Are Versatile and Easy ......................... .255 Ignore Dialog Errors in Logs ....................................... 255 VBScript Custom Actions Are Easy .................................. 256 Common Errors and Why You Get Them ............................ 256 Test the Install on a Clean System ..................................258 Look at XML for User Settings .....................................259

x

Contents

Warnings .......................................................... .260 VBScript Custom Actions Are Not Windows Script Host ............... .260 Msiexec Command Line Is Picky ................................... .260 Services and Environment Variables ................................ .260 Changing the Product's Uninstall Behavior .......................... .261 Services and Remote Computers ................................... 261 ResolveSource and the Original Install Package ...................... .261 Your Custom Action Won't Run As System Account ................... .262 Bootstrappers and Temp Folders ................................... 262 Raising Privileges During Custom Actions ........................... .263 Use Unique Property Names ....................................... 263 Summary ............................................................264

Chapter 15 Exploring the Installer APIs ............... 265 WMI .................................................................265 UsingWMI to Install a Product ..................................... 267 Listing Products with WMI and the .NET Framework .................. 268 WMI or the Installer APIs .......................................... 269

The Installer APIs .............................................. .270 Types of Installer APIs ......................................... .275 Summary ............................................................276

Chapter 16 Tools and Futures ............................. 277 Development Tools ................................................ .277 What About Visual Studio? ....................................... 279 Futures ........................................................... .280 Where Are Improvements Needed? ............................... .280 Summary ............................................................281 Index ..............................................................283

xi

About the Author Phil Wilson graduated from the University of Aston, Birmingham, England, with a BSc in chemistry, but preferred computers to test tubes and eventually worked for 15 years on developing operating systems for Burroughs and Unisys mainframes. Phil started programming for Windows in the early 1990s and has developed in MFC, ATL, COM, Visual Basic, and C#. He has been involved in installation design and technology for about eight years, and became a Microsoft MostValuable Professional for Windows Installer in 2003. To get away from computers, he plays and records guitar, and enjoys camping in the California desert. Phil works for Unisys Corporation in Mission Viejo, California.

xiii

Acknowledgments Many thanks to the people at Apress for giving me this opportunity, especially Dan Appleman. Thanks to Tracy Brown Collins, Susannah PfaIzer, and Kari Brooks for getting me through it all. A lot probably goes on in this process that they kept me blissfully unaware of; all I had to do was keep writing. My heartfelt thanks go to Chris Gouge and Carolyn Napier of Microsoft for their technical review. They patiently corrected my misunderstandings, and the book is much better for their review. I can't imagine what it must feel like to have someone write a book about the software that you work on every day, so to them and the rest of the Window Installer team: I hope I've done a good job. Thanks also to R. Michael Sanford for his early review work. Finally, thanks to my family for their patience while I was holed up evenings and weekends for the duration, and thanks to my friends M.G., AK., and Y.R. for believing in me.

xv

Introduction Installing new software is perhaps the most adrenalin-inducing experience you'll have on a computer, aside from whatever games you might play. It's not hard to see why. You give over control of the system to a program that often demands Administrator privilege and that then starts updating some of the most fragile parts of your system. You might know the actual product being installed quite well, but there's rarely any documentation about what the installation of it will do to your system. It might install kernel drivers or Services, it might alter your personal settings without your permission, and it might result in other applications on your system no longer working. For a company building and shipping software, the installation might be the first time the customer has seen your product or your company, and it's your opportunity to make a lasting impression one way or the other. An unreliable installation will affect the customer's image of you for a long time. The goal of this book is to show you how to build safe and secure installations. Its focus is Windows Installer technology on the Windows NT series of operating systems for Windows 2000 and above, and you'll build example projects as Visual Studio Setup and Deployment Projects. Aside from the actual nuts and bolts of building Windows Installer-based installations, I'll offer advice on how to build a reliable installation and what you should and shouldn't do. The integration of installer technology as part of the Windows operating system means that the dividing line between an application and its installation has become much less sharp, and the book will cover how you need to design applications to integrate properly with Windows Installer. The book starts with basic principles and drills down deeper in later chapters. I start with the installation equivalent of the "Hello World" program, and then gradually get deeper into the contents of installer MSI files, including installation in the .NET Framework world. Along the way I'll stop to look at best practices and how to keep your installation reliable. Where I show use of the installer APls, I'll use VBScript for the sake of simplicity and clarity, but I'll also point you at the Win32 equivalents and show you a couple of ways to call them from the .NET Framework language C#. As is often the case when you try to explain something, you find that you test your understanding, and if you're lucky you learn something new at the same time. I hope you learn as much from reading this book as I did writing it.

xvii