Beginner’s Guide to Windows Installer XML (WiX)

1. Beginner’s Guide toWindows Installer XML (WiX)[WiX v3.5]Alek Davishttp://alekdavis.blogspot.comMarch 2011

2. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]DisclaimerFrom Want to sell books to Americans? Eliminate all traces of self-doubt by Ezra KleinGillian Tett [author of Fool's Gold] describes the difference between packaging a book for the American and British markets: "Initially I planned to start the book by admitting that I was not a true expert on high finance: instead I crashed into this world in 2005, after a background spent in journalism-cum-social anthropology – making me a well-intentioned amateur, but without complete knowledge. My friends in the British publishing world loved that honesty; in the UK, self-deprecation sells, particularly for "well-meaning amateurs" such as the writer Bill Bryson. But my American friends hated it. In New York, I was sternly told, absolutely nobody wants to listen to self-doubt. If you are going to write a book – let alone stand on a political platform or run a company – you must act as if you are an expert, filled with complete conviction. For the US version, the preface was removed entirely."I am not a "true expert" on Windows Installer3/2/2011

3. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]IntroductionExperienceProgrammingInstaller-relatedTools and articlesStreamline Your Database Setup Process with a Custom Installer (MSDN Magazine, September 2004)Follow-up: Database installer revised (Blog)Commercial database deployment softwareDude, where is your installer? (Blog)Microsoft ate my uninstaller (Blog)More posts on my blog3/2/2011

4. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]What to expect?AgendaBasic Windows Installer (MSI) conceptsOverview of Windows Installer XML (WiX)Using WiX to build simple installersCommon advanced WiX techniquesTools and resources3/2/2011

5. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Installer tools and technologiesRelevanceDo you build installers?What do you use?Tools and technologiesWindows Installer (MSI)Visual Studio Installer (discontinued)InstallShieldWise Installation StudioInstallAware for Windows InstallerAdvanced InstallerAnd moreOtherInstallShield engineNullSoft Scriptable Install SystemInno SetupClickOnceAnd more3/2/2011

6. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Installation challengesConsiderError in the middle of setupPer-user or per-machine installationRoaming profiles and folder redirectionx86, x64, any CPU32-bit, 64-bit OSPatches and upgradesConditional installations…3/2/2011

7. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Windows Installer (MSI)What is Windows Installer?Msiexec.exe (see command-line options)Windows Installer APIWindows Installer SDKHistoryStarted around 1999 (Office 2000)Current version: 5 (Windows 7, Server 2008 R2)ProsTransactional, merge modules, discovery, automation, APIs, localization, restart management, package validation, declarative, …ConsComplexity, upgrades, architecture (one key [file] per component, …), shortcuts, command line, touches registry and file system, tools, …FAQsWindows Installer FAQ – Part 1 (see parts 2, 3, 4, etc)3/2/2011

8. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Windows Installer setup processInstallation sequence(courtesy to Jeffrey Sharp)Installation (uninstallation/upgrade/etc) events occur in sequence3/2/2011InstallUISequenceInstallExecuteSequence(Part 1: Script Generation)IMMEDIATEInstallExecuteSequence(Part 2: Script Execution)DEFERREDFindRelatedProducts

9. AppSearch

10. LaunchConditions

11. PrepareDlg

12. DefaultTargetDir

13. ValidateProductID

14. CostInitialize

15. FileCost

16. CostFinalize

17. WelcomeDlg

18. ResumeDlg

19. MaintWelcomeDlg

20. ProgressDlg

21. ExecuteAction

22. AppSearch

23. CostInitialize

24. ResolveSource

25. FileCost

26. CostFinalize

27. InstallValidate

28. InstallInitialize

29. AllocateRegistrySpace

30. ProcessComponents

31. CreateFolders

32. InstallFiles

33. MsiPublishAssemblies

34. CreateShortcuts

35. WriteRegistryValues

36. PublishComponents

37. PublishFeatures

38. PublishProduct

39. InstallFinalize

40. Execute generated install script, saving undo steps as installation progresses.

41. No errors? Complete.

42. Rollback: Execute accumulated undo actions.Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Windows Installer basicsMajor constructsProductDeployed as a packageMade of feature(s)FeatureMade of component(s)ComponentMade of installable(s)InstallablesFiles, directories, shortcutsRegistry keys, registry valuesODBC data sources…3/2/2011PackageProductFeature 3Feature 1Feature 2Component1Component 3Component 5Component 2Component 4Component 6File 1File 2File 5File 3File 4File 6

43. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Windows Installer package (MSI file)What is it?COM structured storage fileSummary info stream (product name, package GUID, MSI version, …)Database (tables: product description, install sequence, dialogs, …)Data streams (files: product files, support files, icons, …)DeclarativeTypesMSIStandard setup packageMSMMerge moduleMSPUpdate patchMSTTransform package3/2/2011

44. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5] MSI tablesRequiredComponentConditionControlCustomActionDialogDirectoryFeatureFile…OptionalNot defined in the specificationApps can use to store app-specific info3/2/2011

45. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5] Windows Installer SDK toolsOrca.exeMSI database viewer and editorScriptsWiRunSQL.vbsUpdates tables in MSI database (can be used in a post-build step)MoreSee C:\Program Files\Microsoft SDKs\Windows\v7.0\Samples\sysmgmt\msi\scripts3/2/2011

46. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX projectOpen-sourceStarted in 1999"Sponsored" by MicrosoftLead by Rob MenschingCurrent version: 3.5Home pagesCodeplex (distributions)SourceForge (documentation, bug tracking)3/2/2011

47. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX definedWindows Installer XML (WiX)XML syntax Defines Windows Installer (MSI) packageDeclarativeTools3/2/2011

48. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX toolsWiX ToolsetCommand-line tools that convert WiX source files to MSI packagesCandle.exeLight.exe…Utilities and documentationVotiveIntegrates WiX Toolset with Visual StudioWiX project templatesIntelliSense3/2/2011

49. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX/Votive vs. Visual Studio InstallerCons (WiX/Votive)Steeper learning curveRequires understanding of Windows InstallerNo drag-and-dropNo automatic dependency inclusionDoes not build bootstrappers (setup.exe)Web sitePros (WiX/Votive)More flexibleMore powerfulProduces cleaner MSI packageXML-basedClean syntax3/2/2011

50. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX project templatesVisual Studio projectsWindows Installer XMLSetup ProjectCreates MSI packageMerge Module ProjectCreates MSM packageLibrary ProjectCreates WIXLIB package for use by other WiX projects(C# | VB | C++) Custom Action ProjectCreates a module implementing a custom action3/2/2011

51. FilesSolution file: .slnProject file: .wixprojSource file(s): .wxsInclude file(s): .wxi(optional)Localization file(s): .wxl(optional)Build process (simplified)Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX project3/2/2011Source(.wxs)Source(.wxs)CandleLightMSIfileSource(.wxs)Source(.wxs)Library(.wixlib)Source(.wxs)Intermediate(.wixobj)Include(.wxi)

52. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX source fileBasic structure3/2/2011<?xmlversion="1.0" encoding="UTF-8"?><Wixxmlns="http://schemas.microsoft.com/wix/2006/wi"><Product …> <Package … /> <Media … /> <DirectoryId="TARGETDIR" Name="SourceDir"> <DirectoryId="ProgramFilesFolder"> <DirectoryId="APPLICATIONFOLDER" Name="WiX Demo"/> </Directory> </Directory> <DirectoryRefId="APPLICATIONFOLDER"> <ComponentId="C_ID" Guid="ABCDEF01-2345-6789-ABCDEF01234576" …> <File …/> </Component> </DirectoryRef> <Feature Id="F_ID" …> <ComponentRefId="C_ID"/> </Feature></Product>Product.wxs

53. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Product, package, mediaProduct elementId (GUID, identifies product/version/edition/etc)UpgradeCode (GUID, identifies product upgrade path)NameManufacturerVersionLanguage (LCID, e.g. "1033")Package elementPlatform (x86, x64, ia64)InstallScope (perUser, perMachine)InstallerVersion (100, 200, 300, 301, 405, 500)DescriptionMedia elementImportant only when CAB file is not embedded in MSI (EmbedCab="no")Use default values3/2/2011

54. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Package typesPlatformx86, x64, ia64See Advanced Installer Package TypesSee Define platform variables for x86 and x64 buildsScopeUserAVOID IF POSSIBLE!Machine3/2/2011

55. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]DirectoriesDirectory elementNested directory structureUnder <Directory Id="TARGETDIR" Name="SourceDir">PropertiesId (primary key)System: ProgramFilesFolder, ProgramFiles64Folder, SystemFolder, System64Folder, StartMenuFolder, StartupFolder, …See A gentle introduction to Windows Installer XML ToolsetUser-defined: make sure it does not conflict with system namesName/LongName (of the folder: 8.3/long name)Not required for system directoriesLongName requires Name to be definedCaveats32-bit vs 64-bit (see Advanced Installer Package Types)User profile-specific folders ("All Users", etc)DirectoryRef elementReferences already defined directory3/2/2011

56. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]FeaturesFeature elementCan contain other featuresPropertiesId (text)Level (0 – disables feature; 1, 2, … - enables feature; can be modified by conditions)Title (short description/name)Description (longer description)ConfigurableDirectory(non-default directory; must be ID of a PUBLIC property)Absent (allow to exclude from installation: disallow, allow)AllowAdvertise(yes, no, system [=yes, except…])FeatureRef elementReferences already defined feature3/2/2011

57. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Install levelsPurposeAllow selective feature installationValues 0 : feature will not be installed 1 : default installation level>1 : use for selective installation3/2/2011

58. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Feature advertisementPurposeInstalls features on demand (when user first tries to run them)See Windows Installer – Overview of Windows Installer - Advertisement3/2/2011

59. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]ComponentsComponent elementOne (key) installable (file, registry value, …) per componentPropertiesId (text)GuidComponentRef elementReferences already defined componentComponentGroup elementGroups related components3/2/2011

60. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]FilesFile elementOne key file per componentPropertiesId (text)Name (name of the file once it is installed)If ID specifies file name, Name can be omittedSource (location on the build system)KeyPath (should be "yes"; otherwise it will not be repaired)Assembly".net" – will copy assembly file (.dll) to GACIt will ignore the Directory element settings"win32" – will not copy file to GACAssemblyApplicationDefines the main executable for a .NET DLL; if it is specified, the .NET DLL will be copied next to this executable3/2/2011

61. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Files (continued)Example3/2/2011<Component …> <File Id="MyApp.exe" KeyPath="yes" Vital="yes" Assembly=".net" Checksum="yes" /></Component><Component …> <File Id="MyPrivateLib.dll" KeyPath="yes" Vital="yes" Assembly=".net" AssemblyApplication="MyApp.exe" /></Component><Component …> <File Id="MySharedLib.dll" KeyPath="yes" Vital="yes" Assembly=".net" /></Component><Component …> <File Id="readme.txt" KeyPath="yes" Vital="yes" /></Component>

62. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]ShortcutsShortcut elementUnder the Start menu (or Desktop) folderTypesAdvertised (references a component; launches setup; self-repairs)Non-advertised (default; references a file)Must includeRemoveFolder elementRegistryValue element (defining KeyPath for component)PropertiesId (text)Name (as it appears)Description (tooltip text; optional)Target (references a file on target system)Arguments (optional command-line arguments)Icon (references Icon element that must be defined; optional)Icon element must be defined and point to a file on the build system3/2/2011

63. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]IconsIcon elementPropertiesId (text; must contain an extension, e.g. "program.exe")SourceFile(on the build system; can be .exe, .ico file)CaveatsIf icon element ID does not contain extension, it may not workIcons are not always necessary3/2/2011

64. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Shortcuts (continued)Example3/2/2011<DirectoryId="TARGETDIR" Name="SourceDir"> <DirectoryId="ProgramFilesFolder"> <DirectoryId="APPLICATIONFOLDER" Name="WiX Demo"/> </Directory> <DirectoryId="ProgramMenuFolder"> <DirectoryId="ShortcutsFolder" Name="WiX Demo"/> </Directory></Directory>…<DirectoryRefId="ShortcutsFolder"> <ComponentId="ProgramShortcut" Guid="ABCDEF01-2345-6789-ABCDEF01234576" …> <Shortcut Id="ClientShortcut" Name="WiX Demo Client GUI" Description="Launch WiX Demo Client GUI"Target="[APPLICATIONFOLDER]Client.exe" WorkingDirectory="APPLICATIONFOLDER" Icon="Client.exe"> <IconId="Client.exe" SourceFile="..\..\Release\bin\Client.exe"/> </Shortcut> <RemoveFolderId="ClientShortcutRemoveFolder" On="uninstall"/> <RegistryValueRoot="HKCU" Key="Software\WiX Demo\Client" Name="installed" Type="integer"Value="1" KeyPath="yes"/> </Component></DirectoryRef>

65. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]RegistryRegistryKey elementPropertiesId (text)Action (none, create, createAndRemoveOnUninstall)Root (HKLM, HKCU, …)Key (path, e.g.: SOFTWARE\MyCompany\MyProduct)RegistryValue elementDefined under RegistryKey element (or must specify the key)One key path per componentPropertiesId (text)Action (append, prepend, write)Name (name of the value)Value (path, e.g.: SOFTWARE\MyCompany\MyProduct)Type (data type: string, multiString, integer, binary, …)KeyPath(yes/no; one key path per component)3/2/2011

66. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Registry (continued)RemoveRegistryKey elementRemoves key and all of its subkeys from the RegistryPropertiesId (text)Action (removeOnInstall, removeOnUninstall)Root (HKLM, HKCU, …)Key (path, e.g.: SOFTWARE\MyCompany\MyProduct)RemoveRegistryValue elementRemoves value from registry keyPropertiesId (text)Root (HKLM, HKCU, …)Key (path, e.g.: SOFTWARE\MyCompany\MyProduct)Name (name of the value)3/2/2011

67. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Registry (continued)Example3/2/2011<Component …> <RegistryKeyRoot="HKLM" Key="Software\MyCompany"> <RegistryValue Action="write" Name="Some Name" Type="string"Value="Some Value" KeyPath="yes" /> </RegistryKey></Component>

68. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Windows servicesServiceInstall elementCreates a Windows service for the specified executablePropertiesId (text)Name (service name)DisplayName (service name displayed in the Services Control Panel)Description (service description)ServiceControl elementControls when a service must get started, stopped or uninstalledPropertiesId (text)Name (name of the service; same as in ServiceInstall)Start, Stop, Remove (control when service must be started, stopped or uninstalled: install, uninstall, both)3/2/2011

69. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Windows services (continued)Example3/2/2011<Component …> <File …/> <ServiceInstall Id="SI_MyService" Name="mysvc" DisplayName="My Service" Description="Demo service that does not do anything"Start="auto" ErroControl="normal" Type="ownProcess" /> <ServiceControl Id="SC_MyService" Name="mysvc" Start="install"Stop="both" Remove="uninstall" Wait="yes" /></Component>

70. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]What else can you install?InstallablesFolders, files, shortcutsWindows servicesRegistry keys, registry valuesCOM registration infoCOM+ applicationsDriversFile extensionsODBC data sourcesConfig filesIIS web sitesIIS virtual directories…3/2/2011

71. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]GUIDsImportanceIdentify product, upgrade path, features, componentsNEVER CHANGE UPGRADE CODE (GUID)… unless…Explicit (hard-coded)Generate via Visual Studio's Tools – Create GUID menuUse the registry format (can be used with or without braces)Implicit (auto-generated)Use the asterisk (Guid="*")For product: generated anew on each build.For component: hashes the full key path (stable as long as inputs do not change). File: path + file name (can use well-known and computed names).Registry: key [+ value name]. Hashing algorithm can change if you enable/disable FIPS mode. Use with care during development.3/2/2011

72. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]FragmentsPurposeLet you to split elements of the WiX document between multiple wxs filesExample3/2/2011<?xmlversion="1.0" encoding="UTF-8"?><Wixxmlns="http://schemas.microsoft.com/wix/2006/wi"><Fragment…> <ComponentId="C_ID1" Guid="ABCDEF01-2345-6789-ABCDEF01234576" …><File …/></Component> <ComponentId="C_ID2" Guid="01ABCDEF-2345-6789-ABCDEF01234576" …><File …/></Component></Fragment> ClientFiles.wxs<?xmlversion="1.0" encoding="UTF-8"?><Wixxmlns="http://schemas.microsoft.com/wix/2006/wi"><Product …> … <DirectoryRefId="APPLICATIONFOLDER"> <ComponentRefId="C_ID1"/> <ComponentRefId="C_ID2"/> </DirectoryRef> <Feature Id="F_ID" …> <ComponentRefId="C_ID1"/> <ComponentRefId="C_ID2"/> </Feature></Product> Product.wxs

73. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]PropertiesDefinitionGlobal variables that Windows Installer uses during installationIDs are case-sensitive (MyProperty ≠ MYPROPERTY)TypesPublicCan be set and changed outside of MSI database (e.g. via command line or UI)ID in UPPERCASE:MY.CUSTOM.PROPERTYPrivateSet and used only internally (in the MSI database)ID in MixedCase: My.Custom.PropertyCommon Windows Installer propertiesTARGETDIR, ALLUSERS, Installed, SourceDir, …Reference See Windows Installer Guide – Properties - Property Reference3/2/2011

74. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Properties (continued)Property element<Property Id="Greeting" Value="Hello!"/>Using properties[PropertyX] : Returns value of PropertyX[[PropertyX]] : Returns value of the property named by value of PropertyX<PropertyId="PropertyX" Value="PropertyY"/><PropertyId="PropertyY" Value="Hello!"/>[[PropertyX]] = "Hello!"3/2/2011

75. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Formatted stringsAboutResolved during installationWindows Installer Reference – Installer Database – Installer Database Reference – Database Tables – Column Data Types – FormattedExamples[%EnvVariableName] - value of environment variable[#FileId] - full path of file (if installed)[!FileId] - full path of file in 8.3 format (if installed)…3/2/2011

76. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]VariablesAboutResolved at compile/build timeFormat: $(TYPE.Name)Typesvar(defined in WiX source in define element; referenced projects)$(var.ProductVersion)  <?defineProductVersion="…"/>env (environment variable)$(env.PATH) : gets %PATH% environment variablesys (pre-defined system variable)$(sys.CURRENTDIR): current dir of build process$(sys.SOURCEFILEDIR ): dir containing file being processed$(sys.SOURCEFILEPATH ) : full path to file being processed$(sys.BUILDARCH ): Package element's Platform attribute (Intel, x64, Intel64)wix (defined via WixVariable element or passed via command line)$(wix.Foo)  <WixVariableId="Foo"Value="Bar"/>loc (gets a localized string from a loc[alization] file)$(loc.WelcomeMessage)3/2/2011

77. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Include filesPurposeShare code between multiple projectsUsage3/2/2011<?xmlversion="1.0" encoding="UTF-8"?><Include> <?define ProductVersion="1.0.0.0"/></Include><Path_to_Solution>\Common\Common.wxi<?xmlversion="1.0" encoding="UTF-8"?><Wixxmlns="http://schemas.microsoft.com/wix/2006/wi"> <?include $(sys.SOURCEFILEDIR)..\Common\Common.wxi/> … <Product Version="$(var.ProductVersion)" …> … </Product></Wix><Path_to_Solution>\ProjectDir\Product.wxs

78. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Preprocessor directivesDefine variable<?define Foo="bar"?>Conditional blocks<?if …?><?elseif…?><?else?><?endif?>Checking for defined variables<?ifdefFoo?><?ifndefFoo?>Include a file<?include File.wxs?>Iteration block<?foreachFoo in "x;y;z"?><?endforeach?>3/2/2011

79. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Preprocessor expressionsWhen using with if, ifelse, ifdef and ifndefLiterals (can be in quotes [quotes are optional])Grouping (using parentheses) Variables (using regular variable syntax)Comparison (< > <= >= = != ~= not and or)Example3/2/2011<?definemyValue="3" ?><?define system32=$(env.windir)\system32 ?><?define B="good var" ?><?define C=3 ?><?defineIExist ?><?if $(var.Iexist) ?><?endif?><?if $(var.myValue)=6 ?><?endif?><?if $(var.myValue)!=3 ?><?endif?><?if not "x"="y"?><?endif?><?if $(env.systemdrive)=a ?><?endif?><?if 3<$(var.myValue)?><?endif?><?if $(var.B)="good VAR"?><?endif?><?if $(var.A) and not $(env.MyEnvVariable) ?><?endif?><?if $(var.A) Or ($(var.B) And $(var.myValue) >=3)?><?endif?><?ifdefIExist ?> <?else?><?endif?>

80. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Launch conditionsPurposeUse rules to enforce prerequisites for installing product, features or componentsCondition elementProduct conditionsMessage attribute (message displayed when condition is not met)<Product …><Condition Message="…"><![CDATA[Installed OR VersionNT >= 600]]></Condition></Product>Feature conditionsLevel attribute (if condition is met, this level will be set for the parent feature)<Feature Level="1" …> <Condition Level="0">%PROCESSOR_ARCHITECTURE = "x86"</Condition></Component>Component conditions<Component …> <Condition><![CDATA[VersionNT < 500]]></Condition></Component>3/2/2011

81. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Action statesPurposeDetermine whether the user requested a particular feature or component to be installedSyntaxAmpersand + ID of feature&FeatureA = 3Dollar sign + ID of component$ComponentX = 1Values-1 : Unknown (no action will be taken) 1 : Advertised (feature will be installed on demand) 2 : Absent (feature/component will not be installed) 3 : Local (feature/component will be installed on a local hard drive) 4 : Source (feature/component will run from source, e.g. CD)3/2/2011

82. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Installed statesPurposeDetermine whether a particular feature or component is installedSyntaxFeatures: Exclamation mark + ID of feature!FeatureA = 3Components: Question mark + ID of component?ComponentX = 3Values-1 : Unknown 1 : Advertised (feature was installed as advertised) 2 : Absent (feature/component was not installed) 3 : Local (feature/component was installed on a local hard drive) 4 : Source (feature/component runs from source, e.g. CD)3/2/2011

83. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Installation phasesUI sequence (InstallUISequence table)Preparation stepsSearching for installed componentsChecking conditionsVerifying disk spaceSelecting type of setup (install/upgrade/repair/etc)Execution sequence (InstallExecuteSequence table)System modificationsPerformed in two sessionsClient side: UI operations; runs as interactive userServer side: system changes (copying files/etc); runs as LocalSystem userPhasesImmediate phase (preparation to execution; generates rollback script)Deferred phase (only actions performed in this phase can be rolled back; mutexed)Custom Actions (CAs) that change the system must be performed in this phase3/2/2011

84. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Custom actions (CAs) in Windows InstallerPurposeExecute custom code or operationCAs and installation phasesSee Installation Phases and In-Script Execution Options for Custom Actions in Windows Installer by Stefan Krueger (pay attention to rules)CA types for various artifactsBinary table: 1 (DLL), 2 (EXE), 5 (Jscript), 6 (VBScript)Copied during installation: 17 (DLL), 18 (EXE), 21 (Jscript), 22 (VBScript)Referencing directory: 34 (EXE)Referencing property: 50 (EXE), 53 (Jscript), 54 (VBScript)Literal code in MSI database: 37 (Jscript), 38 (VBScript)Display error and terminate setup: 19Set a property: 51…3/2/2011

85. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Custom actions in WiXCustomAction elementPropertiesId (text)Return (asyncNoWait: run in parallel with setup;asyncWait: run in parallel, but installer will wait for return code at the end of the execution sequence; check: run sequentially and check for success; ignore: run sequentially, but don't check for success)CaveatsAccessing a property from a CA executed in a deferred phaseConditional executionCAs in merge modulesDetailed explanation and examplesSee From MSI to WiX, Part 5 - Custom actions: Introduction by Alex Shevchuk3/2/2011

86. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Custom Action exampleRegistering a COM executable via a Custom Action (CA)3/2/2011<CustomActionId="RegisterComServer"FileKey="MyComSrv.exe"ExeCommand=" /RegServer"Execute="deferred"Impersonate="no"Return="check" /><CustomActionId="UnregisterComServer"FileKey="MyComSrv.exe" ExeCommand=" /UnRegServer"Execute="deferred"Impersonate="no"Return="check" />…<InstallExecuteSequence> <CustomAction="RegisterComServer"After="InstallFiles"> NOT Installed </Custom> <CustomAction="UnregisterComServer"Before="RemoveFiles"> Installed AND NOT UPGRADINGPRODUCTCODE </Custom></InstallExecuteSequence>

87. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]User interface (UI) in WiXDefault projectNo UI (no dialogs/UI wizards)To add UI wizardsAdd reference to WiXUIExtensions.dllAdd UIRef element with name of specific wizardDefine properties expected by the wizardWizardsWixUI_Minimal (EULA)WixUI_Advanced (scope: single or all users; program folder; feature tree)WixUI_FeatureTree (like WixUI_Advanced; default program folder only) WixUI_InstallDIr (allows to change program folder)WixUI_Mondo (Typical, Complete, or Custom setup)3/2/2011<Property Id="ApplicationFolderName"Value="WiX Demo" /><Property Id="WixAppFolder"Value="WiXxperMachineFolder" /><UI Id="UISequence"><UIRefId="WixUI_Advanced"/></UI>

88. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Customizing UIChange existing dialogMinor adjustments (define bitmaps, license agreements, default folder, etc)Examples: Customizing Built-in WixUI Dialog SetsMajor changes (remove, add, customize, move controls)Example: Add a checkbox to the exit dialog to launch the app, or the helpfileModify existing wizard (dialog sequence)Example: WiX: How to skip LicenseAgreementDlg – more elegant solutionCreate your own dialogsExample: How do I create a custom dialog in WiX for user input?3/2/2011

89. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]WiX extensionsAboutDistributed with WiX toolkit (in the Bin folder)Similar to .NET class librariesTo use, add to project referencesPopularWixUIExtension.dll (UI wizards)WixIisExtension.dll (IIS configuration)WixSqlExtension.dll (SQL operations)WixUtilExtension.dll (custom actions and more)3/2/2011

90. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]ToolsWiX ToolkitHeat.exeGenerates WiX sources from various input formats: projects, DLLs, MSIs, etcSee List of ToolsOtherParaffin by John Robbins (alternative to Heat)3/2/2011

91. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]UpgradesMinorDon't use (unless you know why and how)PatchDon't use (unless you know why and how)MajorChange package code (GUID)Change product version (only first 3 numbers in ProductVersion matter)1.0.0.0 == 1.0.0.11.0.0.1 != 1.0.1.1Retain original upgrade code (GUID)How-to:StackOverflow: How to implement WiX installer upgrade? (read all answers and comments)StackOverflow: Wix Major Upgrade: how do I prevent Windows service reinstallation?3/2/2011

92. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]Upgrade examplesExample #1 (typical)3/2/2011<Product…> <MajorUpgradeAllowDowngrade="no"AllowSameVersionUpgrades="no"Schedule="afterInstallInitialize"DowngradeErrorMessage="A later version of [ProductName] is already installed." /></Product>Example #2 (more complex)<Product…> <MajorUpgradeAllowDowngrade="no"AllowSameVersionUpgrades="no"MigrateFeatures="yes"Schedule="afterInstallFinalize"DowngradeErrorMessage="A later version of [ProductName] is already installed." /> … <InstallExecuteSequence> <DeleteServices>NOT UPGRADINGPRODUCTCODE</DeleteServices> </InstallExecuteSequence></Product>

93. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]DebuggingUse log fileWhen installingmsiexec/i "<PathToMsi>" /L*v "<PathToLogFile>"When uninstallingmsiexec/x "<PathToMsi>" /L*v "<PathToLogFile>"3/2/2011

94. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]LimitationsBootstrapper/chainer(setup.exe)Promised via the BURN tool in WiX3.5 3.6(?) (work in progress)Project output file inclusionCan be done manually (somewhat automated via the HEAT tool)COM registration info extractionFrom executablesMoreStackOverflow: What are limitations of WiX and WiX Toolset?3/2/2011

95. Beginner's Guide to Windows Installer XML (WiX) [WiX v3.5]ResourcesBookWiX: A Developer's Guide to Windows Installer XML by Nick RamirezPresentationSetup With Windows Installer and WiX by Jeff Sharp (video and slides)BlogsJoy of Setup by Bob Arnson (check out blog roll)HelpStackOverflowWiX Project Support at SourceForgeTipsStackOverflow: WiX Tips and TricksMoreLearning WiX from ground up by Alek Davis (see also other parts of the series)3/2/2011

Beginner’s Guide to Windows Installer XML (WiX)

More Related Content

Viewers also liked (7)

Similar to Beginner’s Guide to Windows Installer XML (WiX) (20)

Recently uploaded (20)

Beginner’s Guide to Windows Installer XML (WiX)