View source

{{WixNav}}
__TOC__
{{Clear Table}}
= Wix version 2.x =

== Properties ==
'''Declare:'''
<code xml>
<Property Id="PropertyName" Value="PropertyValue" />
<Property Id="PropertyName"       >PropertyValue</Property>
</code>

{| Width=100%
| VAlign=Top |
'''Use:'''
{| {{TableShade Format}}
|- {{TableShade Header}}
! To Get || Syntax
|- {{TableShade}}
| Property                                     || <tt><nowiki>[PropertyName]</nowiki></tt>
|- {{TableShade}}
| Environment Variable (Case insensitive) || <tt><nowiki>[%VarName]</nowiki></tt>
|- {{TableShade}}
| Component Action State                  || <tt><nowiki>[$ComponentName]</nowiki></tt>
|- {{TableShade}}
| Component Installed State               || <tt><nowiki>[?ComponentName]</nowiki></tt>
|- {{TableShade}}
| Feature Action State                    || <tt><nowiki>[&FeatureName]</nowiki></tt>
|- {{TableShade}}
| Feature Installed State                 || <tt><nowiki>[!FeatureName]</nowiki></tt>
|}

| VAlign=Top |
'''Action State and Installed State Values:'''
{| {{TableShade Format}}
|- {{TableShade Header}}
! Value || Meaning
|- {{TableShade}}
| -1 || no action to be taken
|- {{TableShade}}
| 1 || advertised (only for components)
|- {{TableShade}}
| 2 || not present
|- {{TableShade}}
| 3 || on the local computer
|- {{TableShade}}
| 4 || run from the source
|}

|}

Examples:
<pre>
<!-- FeatureName is to be installed locally -->
<Condition>(&FeatureName = 3)                           </Condition>

<!-- FeatureName not installed locally -->
<Condition>                       NOT (!FeatureName = 3)</Condition>

<!-- Run action only if the product will be installed locally. Do not run action on a reinstallation. -->
<Condition>(&FeatureName = 3) AND NOT (!FeatureName = 3)</Condition> 

<!-- Run action only if the feature will be uninstalled. -->
<Condition>(&FeatureName = 2) AND (!FeatureName = 3)</Condition> 
</pre>

=== Modify a Property (Custom Action) ===
This adds a custom action that will change the value of a property.

<code xml>
 <Property Id="PropertyName" 
   Value="Initial Property Value. Things in brackets are not evaulated, like [AnotherProperty]." />

 <Property Id="AnotherProperty" Value="Another Property's Value" />

 <CustomAction Id="SetPropertyValue" Property="PropertyName" 
   Value="New Value. Brackets are evaulated, like [AnotherProperty]." Return="check" />
</code>

before the custom action <tt>PropertyName</tt> is equal to "''Initial Property Value. Things in brackets are not evaulated, like [AnotherProperty].''".

After the custom action <tt>PropertyName</tt> is equal to "''New Value. Brackets are evaulated, like Another Property's Value.''"

=== Global Properties ===
If a properties ID is in all caps, this means it is a Global Property. Most of the time it makes no difference at all weather the property is global or not; on occasion, it will.

Some situations where a property needs to be global:
# When writing a property who's value has changed since the installer started out to an XML file using the <tt><nowiki><XMLFile ... ></nowiki></tt> element. 
#* If the property is not global, it will not write the latest value of the property.

=== Add/Remove Programs Settings Special Properties ===
<code xml>
<Property Id='ARPCOMMENTS'     >any comments</Property>
<Property Id='ARPCONTACT'      >contact info</Property>
<Property Id='ARPHELPLINK'     >URL for technical support</Property>
<Property Id='ARPURLINFOABOUT' >URL for general info about the product</Property>
<Property Id='ARPURLUPDATEINFO'>URL for product updates</Property>
<Property Id='ARPHELPTELEPHONE'>URL for technical support</Property>
<Property Id='ARPREADME'       >Path to Readme Document</Property>
<Property Id='ARPSIZE'         >app size in kilobytes</Property>

<Icon Id="appicon.ico" SourceFile="Application.ico" />
<Property Id='ARPPRODUCTICON'>appicon.ico</Property>

<!-- To suppress the Modify button -->
<Property Id='ARPNOMODIFY'>1</Property>

<!-- To disable the Remove button -->
<Property Id='ARPNOREMOVE'>1</Property>

<!-- remove the application altogether from this list -->
<Property Id='ARPSYSTEMCOMPONENT'>1</Property>

<!-- suppress the Repair functionality -->
<Property Id='ARPNOREPAIR'>1</Property>
</code>

== Directories ==
The directories section describes how source files map to target files on the target computer.

Note: if you reference a folder, even a predefined 'System Folder Property', you must include it in your directory section.

In the examples below assume each is property under a <tt><nowiki><Wix ... ></nowiki></tt> and <tt><nowiki><Product ... ></nowiki></tt> tag

=== Predefined Folders ===
Here are some of the predefined folders. 
<code xml>
<Directory Id="TARGETDIR" Name="SourceDir">
    <Directory Id="ProgramFilesFolder"  />
    <Directory Id="CommonAppDataFolder" />
    <Directory Id="SystemFolder"        />
    <Directory Id="StartupFolder"       />
    <Directory Id="DesktopFolder"       />
    <Directory Id="ProgramMenuFolder"   />
</Directory>
</code>

=== System Folder Properties ===
This list is from [http://msdn2.microsoft.com/en-gb/library/aa372057.aspx System Folder Properties] under the [http://msdn2.microsoft.com/en-gb/library/aa372845.aspx Windows Installer Guide] on MSDN.

{| {{TableShade_Format}}
|- {{TableShade_Header}}
! Property             || System Default Path (En-US) || Description
|- {{TableShade}}
| AdminToolsFolder     || || The full path to the directory that contains administrative tools.
|- {{TableShade}}
| AppDataFolder        || <tt><nowiki>C:\Documents and Settings\[UserName]\Application Data</nowiki></tt> || The full path to the Roaming folder for the current user.
|- {{TableShade}}
| CommonAppDataFolder  || <tt><nowiki>C:\Documents and Settings\All Users\Application Data</nowiki></tt> || The full path to application data for all users.
|- {{TableShade}}
| CommonFiles64Folder  || || The full path to the predefined 64-bit Common Files folder.
|- {{TableShade}}
| CommonFilesFolder    || || The full path to the Common Files folder for the current user.
|- {{TableShade}}
| DesktopFolder        || <tt><nowiki>C:\Documents and Settings\[UserName]\Desktop</nowiki></tt> || The full path to the Desktop folder.
|- {{TableShade}}
| FavoritesFolder      || <tt><nowiki>C:\Documents and Settings\[UserName]\Favorites</nowiki></tt> || The full path to the Favorites folder for the current user.
|- {{TableShade}}
| FontsFolder          || <tt><nowiki>C:\WINDOWS\Fonts</nowiki></tt> || The full path to the Fonts folder.
|- {{TableShade}}
| LocalAppDataFolder   || || The full path to the folder that contains local (nonroaming) applications.
|- {{TableShade}}
| MyPicturesFolder     || <tt><nowiki>C:\Documents and Settings\[UserName]\My Documents\My Pictures</nowiki></tt> || The full path to the Pictures folder.
|- {{TableShade}}
| PersonalFolder       || || The full path to the Documents folder for the current user.
|- {{TableShade}}
| ProgramFiles64Folder || || The full path to the predefined 64-bit Program Files folder.
|- {{TableShade}}
| ProgramFilesFolder   || <tt><nowiki>C:\Program Files</nowiki></tt> || The full path to the predefined 32-bit Program Files folder.
|- {{TableShade}}
| ProgramMenuFolder    || <tt><nowiki>C:\Documents and Settings\[UserName]\Start Menu\Programs</nowiki></tt> || The full path to the Program Menu folder.
|- {{TableShade}}
| SendToFolder         || <tt><nowiki>C:\Documents and Settings\[UserName]\SendTo</nowiki></tt> || The full path to the SendTo folder for the current user.
|- {{TableShade}}
| StartMenuFolder      || <tt><nowiki>C:\Documents and Settings\[UserName]\Start Menu</nowiki></tt> || The full path to the Start menu folder.
|- {{TableShade}}
| StartupFolder        || <tt><nowiki>C:\Documents and Settings\[UserName]\Start Menu\Programs\Startup</nowiki></tt> || The full path to the Startup folder.
|- {{TableShade}}
| System16Folder       || || The full path to folder for 16-bit system DLLs.
|- {{TableShade}}
| System64Folder       || || The full path to the predefined System64 folder.
|- {{TableShade}}
| SystemFolder         || || The full path to the System folder for the current user.
|- {{TableShade}}
| TempFolder           || || The full path to the Temp folder.
|- {{TableShade}}
| TemplateFolder       || || The full path to the Template folder for the current user.
|- {{TableShade}}
| WindowsFolder        || <tt><nowiki>C:\WINDOWS</nowiki></tt> || The full path to the Windows folder.
|- {{TableShade}}
| WindowsVolume        || || The volume of the Windows folder.
|}

=== Custom Folders ===
Here is how you create a folder under program files.
<code xml>
<Directory Id="TARGETDIR" Name="SourceDir">
    <Directory Id="ProgramFilesFolder"  />
        <Directory Id="INSTALLDIR" Name="SFN1" LongName="Some Folder Name 1">
        </Directory>
    </Directory>
</Directory>
</code>

The directory structure under after this is installed would look like this: <tt><nowiki>C:\Program Files\Some Folder Name 1</nowiki></tt>

== Conditions ==

=== Detecting the OS Version ===
<code xml>
<Condition Message='Windows 95'          >Version9X = 400                          </Condition>
<Condition Message='Windows 95 OSR2.5'   >Version9X = 400 AND WindowsBuild = 1111  </Condition>
<Condition Message='Windows 98'          >Version9X = 410                          </Condition>
<Condition Message='Windows 98 SE'       >Version9X = 410 AND WindowsBuild = 2222  </Condition>
<Condition Message='Windows ME'          >Version9X = 490                          </Condition>
<Condition Message='Windows NT4'         >VersionNT = 400                          </Condition>
<Condition Message='Windows NT4 SPn'     >VersionNT = 400 AND ServicePackLevel = n </Condition>
<Condition Message='Windows 2000'        >VersionNT = 500                          </Condition>
<Condition Message='Windows 2000 SPn'    >VersionNT = 500 AND ServicePackLevel = n </Condition>
<Condition Message='Windows XP'          >VersionNT = 501                          </Condition>
<Condition Message='Windows XP SPn'      >VersionNT = 501 AND ServicePackLevel = n </Condition>
<Condition Message='Windows Server 2003' >VersionNT = 502                          </Condition>
</code>

=== Detecting the Microsoft .NET Framework ===
''This will only check the Highest version of the .NET Framework installed.''
<code xml>
<Condition Message=".Net Framework 2.0">MsiNetAssemblySupport >= "2.0.50727"</Condition>
</code>

== Launch an application (Custom Action) ==
This adds a custom action that will launch an external application

<code xml>
 <CustomAction Id="LaunchApp" Directory="SystemFolder" ExeCommand="calc.exe" Return="asyncNoWait" />
</code>

:'''Directory''': Can be any directory predefined by the Windows Installer 3.1 or one you define under your <tt><nowiki><Directory ... ></nowiki></tt> section.
:'''ExeCommand''': Any executable file name. No path. Parameters can be included by adding a space after the exe file and then placing the parameters (just like you would type it in a DOS prompt).

== Modify an XML File ==
These examples show how to manipulate XML files using the WiX tool.

In order to use the XML custom actions, you have to add a reference to the WiX General Custom Actions (WixCA) library:
{|
|
 wixca.wixlib
|}

The below examples use the following '''settings.xml''' code as the baseline:
{|
|
<code xml>
 <?xml version="1.0" encoding="utf-8"?>
 <configuration>
    <appSettings>
        <add key="Setting1" value="SettingValue1" />
        <add key="Setting2" value="SettingValue2" />
        <add key="Setting3" value="SettingValue3" />
        <add key="Setting4" value="SettingValue4" />
    </appSettings>
 </configuration>
</code>
|}

: '''Note:''' If you examine the examples below closely, you will notice that the structure does not change in modified files, but the whitespace does. Depending on what you do, some line feeds and spaces will disappear. This is almost always irrelevant, but is good to know.

{{Clear Table}}
=== Create an Element ===
Assume that this code is property under a <tt><Directory Id="DesktopFolder"></tt> element in a WiX file.
<code xml>
 <Component ... >
    <File Id="SettingsXmlFile" Name="SETTINGS.XML" LongName="Settings.xml" Source="settings.xml" DiskId="1" Vital="yes" />
	
    <XmlFile Id="xmlModifyTest2.1" Action="createElement" 
      ElementPath="/configuration/appSettings" Name="add" 
      File="[DesktopFolder]Settings.xml" Sequence="10" />
 </Component>
</code>

:Modified Settings File: '''settings.xml'''
<code xml>
 <?xml version="1.0" encoding="utf-8"?>
 <configuration>
    <appSettings>
        <add key="Setting1" value="SettingValue1"/>
        <add key="Setting2" value="SettingValue2"/>
        <add key="Setting3" value="SettingValue3"/>
        <add key="Setting4" value="SettingValue4"/>
        <add/></appSettings>
 </configuration>
</code>

=== Modify an Element Attribute ===
This code will modify a specific attribute in a specific element with a specific attribute value. Here, there are 4 <tt><add </tt> elements and we want to modify specific ones; the <tt>key="Settings2"</tt> and <tt>key="Settings3"</tt>, the middle two.

Assume that this code is property under a Directory element in a WiX file.
<code xml>
 <Component ... >
    <File Id="SettingsXmlFile" Name="SETTINGS.XML" LongName="Settings.xml" Source="settings.xml" DiskId="1" Vital="yes" />

    <XmlFile Id="xmlModifyTest2.2aa" Action="setValue" 
      ElementPath="/configuration/appSettings/add[\[]@key='Setting2'[\]]" Name="value" Value="Written Value 2.2aa" 
      File="[DesktopFolder]Settings.xml" Sequence="11" />

    <XmlFile Id="xmlModifyTest2.3aa" Action="setValue" 
      ElementPath="/configuration/appSettings/add[\[]@key='Setting3'[\]]" Name="value" Value="Written Value 2.3aa" 
      File="[DesktopFolder]Settings.xml" Sequence="12" />
 </Component>
</code>

:Modified Settings File: '''settings.xml'''
<code xml>
 <?xml version="1.0" encoding="utf-8"?>
 <configuration>
    <appSettings>
        <add key="Setting1" value="SettingValue1"/>
        <add key="Setting2" value="Written Value 2.2aa"/>
        <add key="Setting3" value="Written Value 2.3aa"/>
        <add key="Setting4" value="SettingValue4"/>
    </appSettings>
 </configuration>
</code>

= Wix version 3.x =