In the previous post we’ve taken a look at the WiX solution/project structure and project properties. We’re still playing with our super SuperForm application and today we’ll take a look at the general parts of the main wxs file, SuperForm.wxs, and the wxi include file. For wxs file we’ll just go over the general description of what each part does in the code comments. The more detailed descriptions will be in future posts about features themselves. WXI include file Include files are exactly what their name implies.
To include a wxi file into the wxs file you have
to put the wxi at the beginning of each .wxs file you wish
to include it in. If you’ve ever worked with C++ you can think of the include files as .h files. For example if you include SuperFormVariables.wxi into the SuperForm.wxs, the variables in the wxi won’t be seen in FilesFragment.wxs or RegistryFragment.wxs. You’d have
to include it manually into those two wxs files too. For preprocessor variable $(var.VariableName)
to be seen by every file in the project you have
to include them in the WiX project properties->Build->“Define preprocessor variables” textbox. This is why I’ve chosen not
to go this route because in multi developer teams not everyone has the same directory structure and having a single variable would mean each developer would have
to checkout the wixproj file
to edit the variable. This is pretty much unacceptable by my standards. This is why we’ve added a System Environment variable named SuperFormFilesDir as is shown in the previous Wix Tutorial post. Because the FilesFragment.wxs is autogenerated on every project build we don’t want
to change it manually each time by adding the include wxi at the beginning of the file. This way we couldn’t recreate it in each pre-build event. <?xml version="1.0" encoding="utf-8"?><Include> <!-- Versioning. These have
to be changed for upgrades. It's not enough
to just include newer files. --> <?define MajorVersion="1" ?> <?define MinorVersion="0" ?> <?define BuildVersion="0" ?> <!-- Revision is NOT used by WiX in the
upgrade procedure --> <?define Revision="0" ?> <!-- Full version number
to display --> <?define VersionNumber="$(var.MajorVersion).$(var.MinorVersion).$(var.BuildVersion).$(var.Revision)" ?> <!--
Upgrade code HAS
to be the same for all updates. Once you've chosen it don't change it. --> <?define UpgradeCode="YOUR-GUID-HERE" ?> <!-- Path
to the resources directory. resources don't really need
to be included in the project structure but I like
to include them for for clarity --> <?define ResourcesDir="$(var.ProjectDir)\Resources" ?> <!-- The name of your application exe file. This will be used
to kill the process when updating and creating the desktop shortcut --> <?define ExeProcessName="SuperForm.MainApp.exe" ?></Include>
For now there’s no way
to tell WiX in Visual Studio
to have a wxi include file available
to the whole project, so you have
to include it in each file separately.
Only variables set in “Define preprocessor variables” or System Environment variables are accessible
to the whole project for now.
The main WXS file: SuperForm.wxs
We’ll only take a look at the general structure of the main SuperForm.wxs and not its the details. We’ll cover the details in future posts. The code comments should provide plenty info about what each part does in general.
Basically there are 5 major parts. The update part, the conditions and actions part, the UI install sequence, the directory structure and the features we want
to include.
<?xml version="1.0" encoding="UTF-8"?><!-- Add xmlns:util namespace definition
to be able
to use stuff from WixUtilExtension dll--><Wix xmlns="http://schemas.microsoft.com/wix/2006/wi" xmlns:util="http://schemas.microsoft.com/wix/UtilExtension"> <!-- This is how we include wxi files --> <?include $(sys.CURRENTDIR)Includes\SuperFormVariables.wxi ?> <!-- Id="*" is
to enable upgrading. * means that the product ID will be autogenerated on each build. Name is made of localized product name and version number. --> <Product Id="*" Name="!(loc.ProductName) $(var.VersionNumber)" Language="!(loc.LANG)" Version="$(var.VersionNumber)" Manufacturer="!(loc.ManufacturerName)" UpgradeCode="$(var.UpgradeCode)"> <!-- Define the minimum supported installer version (3.0) and that the install should be done for the whole machine not just the current user --> <Package InstallerVersion="300" Compressed="yes" InstallScope="perMachine"/> <Media Id="1" Cabinet="media1.cab" EmbedCab="yes" /> <!--
Upgrade settings. This will be explained in more detail in a future post --> <Upgrade Id="$(var.UpgradeCode)"> <UpgradeVersion OnlyDetect="yes" Minimum="$(var.VersionNumber)" IncludeMinimum="no" Property="NEWER_VERSION_FOUND" /> <UpgradeVersion Minimum="0.0.0.0" IncludeMinimum="yes" Maximum="$(var.VersionNumber)" IncludeMaximum="no" Property="OLDER_VERSION_FOUND" /> </Upgrade> <!-- Reference the global NETFRAMEWORK35 property
to check if it exists --> <PropertyRef Id="NETFRAMEWORK35"/> <!-- Startup conditions that checks if .Net Framework 3.5 is installed or if we're running the OS higher than Windows XP SP2. If not the installation is aborted. By doing the (Installed OR ...) property means that this condition will only be evaluated if the app is being installed and not on uninstall or changing --> <Condition Message="!(loc.DotNetFrameworkNeeded)"> <![CDATA[Installed OR NETFRAMEWORK35]]> </Condition> <Condition Message="!(loc.AppNotSupported)"> <![CDATA[Installed OR ((VersionNT >= 501 AND ServicePackLevel >= 2) OR (VersionNT >= 502))]]> </Condition> <!-- This custom action in the InstallExecuteSequence is needed
to stop silent install (passing /qb
to msiexec) from going around it. --> <CustomAction Id="NewerVersionFound" Error="!(loc.SuperFormNewerVersionInstalled)" /> <InstallExecuteSequence> <!-- Check for newer versions with FindRelatedProducts and execute the custom action after it --> <Custom Action="NewerVersionFound" After="FindRelatedProducts"> <![CDATA[NEWER_VERSION_FOUND]]> </Custom> <!-- Remove the previous versions of the product --> <RemoveExistingProducts After="InstallInitialize"/> <!-- WixCloseApplications is a built in custom action that uses util:CloseApplication below --> <Custom Action="WixCloseApplications" Before="InstallInitialize" /> </InstallExecuteSequence> <!-- This will ask the user
to close the SuperForm app if it's running while upgrading --> <util:CloseApplication Id="CloseSuperForm" CloseMessage="no" Description="!(loc.MustCloseSuperForm)" ElevatedCloseMessage="no" RebootPrompt="no" Target="$(var.ExeProcessName)" /> <!-- Use the built in WixUI_InstallDir GUI --> <UIRef Id="WixUI_InstallDir" /> <UI> <!-- These dialog references are needed for CloseApplication above
to work correctly --> <DialogRef Id="FilesInUse" /> <DialogRef Id="MsiRMFilesInUse" /> <!-- Here we'll add the GUI logic for installation and updating in a future post--> </UI> <!-- Set the icon
to show next
to the program name in Add/Remove programs --> <Icon Id="SuperFormIcon.ico" SourceFile="$(var.ResourcesDir)\Exclam.ico" /> <Property Id="ARPPRODUCTICON" Value="SuperFormIcon.ico" /> <!-- Installer UI custom pictures. File names are made up. Add path
to your pics. –> <!-- <WixVariable Id="WixUIDialogBmp" Value="MyAppLogo.jpg" /> <WixVariable Id="WixUIBannerBmp" Value="installBanner.jpg" /> --> <!-- the default directory structure --> <Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="ProgramFilesFolder"> <Directory Id="INSTALLLOCATION" Name="!(loc.ProductName)" /> </Directory> </Directory> <!-- Set the default install location
to the value of INSTALLLOCATION (usually c:\Program Files\YourProductName) --> <Property Id="WIXUI_INSTALLDIR" Value="INSTALLLOCATION" /> <!-- Set the components defined in our fragment files that will be used for our feature --> <Feature Id="SuperFormFeature" Title="!(loc.ProductName)" Level="1"> <ComponentGroupRef Id="SuperFormFiles" /> <ComponentRef Id="cmpVersionInRegistry" /> <ComponentRef Id="cmpIsThisUpdateInRegistry" /> </Feature> </Product></Wix>
For more info on what certain attributes mean you should look into the WiX Documentation.
WiX 3 tutorial by Mladen Prajdic navigation
WiX 3 Tutorial: Solution/Project structure and Dev resources
WiX 3 Tutorial: Understanding main wxs and wxi file
WiX 3 Tutorial: Generating file/directory fragments with Heat.exe
