C# (CSharp) WixSharp Namespace

Nested Namespaces

WixSharp.Bootstrapper
WixSharp.CommonTasks
WixSharp.Controls
WixSharp.Forms
WixSharp.Test
WixSharp.UI

Classes

Name Description
Action Defines generic WiX CustomAction.

This class does not contain any public constructor and is only to be used as a base class for deriving specialized CustomActions (e.g. ) or for declaring heterogeneous collections.

AsmReflector
Assembly Defines assembly file to be installed.

This class is essentially the same as except it has extra member RegisterInGAC to define if the assembly file needs to be registered in GAC during the installation.

AutoElements Automatically insert elements required for satisfy odd MSI restrictions.

- You must set KeyPath you install in the user profile.

- You must use a registry key under HKCU as component's KeyPath, not a file.

- The Component element cannot have multiple key path set.

- The project must have at least one directory element.

- All directories installed in the user profile must have corresponding RemoveDirectory elements.

...

The MSI always wants registry keys as the key paths for per-user components. It has to do with the way profiles work with advertised content in enterprise deployments. The fact that you do not want to install any registry doesn't matter. MSI is the boss.

The following link is a good example of the technique: http://stackoverflow.com/questions/16119708/component-testcomp-installs-to-user-profile-it-must-use-a-registry-key-under-hk

AutoGenerationOptions This class holds the settings for Wix# XML auto-generation: generation of WiX XML elements, which do not have direct representation in the Wix# script. The detailed information about Wix# auto-generation can be found here: http://www.csscript.net/WixSharp/ID_Allocation.html.
Binary Defines binary file to be embedded into MSI (Binary table).

You can use this class to embed any file (e.g. exe, dll, image) to be used during the installation. Note that none of the binary files are installed on the target system. They are just available at installation time for using CustomActions.

BinaryFileAction Defines WiX BinaryFileAction for executing binary (not installed) file.
Certificate This class defines website certificate attributes. It is a close equivalent of Certificate WiX element.
Compiler
Compiler.StringWriterWithEncoding
Compiler.Wildcard Represents a wildcard running on the T:System.Text.RegularExpressions engine.
Condition Defines WiX Condition. Condition is normally associated with CustomActions or WiX elements (e.g. Shortcut).

Condition is nothing else but an XML friendly string wrapper, containing some predefined (commonly used) condition values. You can either use one of the predefined condition values (static members) or define your by specifying full string representation of the required WiX condition when calling the constructor or static method Create.

Dir Defines directory to be installed on target system.

Use this class to define file/directory structure of the deployment solution.

You can use predefined Wix# environment constants for well-known installation locations. They are directly mapped to the corresponding WiX constants:

Wix# - WiX

%WindowsFolder% - [WindowsFolder]

%ProgramFiles% - [ProgramFilesFolder]

%ProgramMenu% - [ProgramMenuFolder]

%AppDataFolder% - [AppDataFolder]

%CommonFilesFolder% - [CommonFilesFolder]

%LocalAppDataFolder% - [LocalAppDataFolder]

%ProgramFiles64Folder% - [ProgramFiles64Folder]

%System64Folder% - [System64Folder]

%SystemFolder% - [SystemFolder]

%TempFolder% - [TempFolder]

%Desktop% - [DesktopFolder]

DirFiles Defines files of a given source directory to be installed on target system. Note that files in subdirectories are not included.

Use this class to define files to be automatically included into the deployment solution if their name matches specified wildcard character pattern (DirFiles.IncludeMask).

You can use DirFiles.ExcludeMasks to exclude certain files from setup if required.

This class is a logical equivalent of Files except that it analyses files in a single directory.

DriverInstaller Defines the file driver installation approach.
DriverInstallerCompiling
ElevatedManagedAction Defines WiX Managed CustomAction, which is to be run with elevated privileges (UAC).

Any CustomAction, which needs elevation must be run with Action.Impersonate set to false and Action.Execute set to Execute.deferred. Thus ElevatedManagedAction is a full equivalent of T:WixSharp.ManagedAction with appropriately adjusted Action.Execute and Action.Impersonate during the instantiation:

public ElevatedManagedAction() : base() { Impersonate = false; Execute = Execute.deferred; }
EmbeddedAssembly Defines assembly file to be embedded into MSI (Binary table).

You can use this class to embed any .NET assembly to be used during the installation. Note that none of the binary files are installed on the target system. They are just available at installation time for using CustomActions.

EnvironmentVariable Defines FileType association to be created for the file extension and the installed file/application (parent T:WixSharp.File).
ExeFileShortcut Defines ExeFileShortcut to be installed.

ExeFileShortcut is a specialized version of the Shortcut designed for using Shortcut as a Dir nested element

There are different ways of defining shortcuts of the Wix# project:

- It can be specified as a nested element of the File. In this case after the installation the shortcut will point to the file it belongs to.

- Alternatively the Shortcut can be specified as a Dir nested element. In this case after the installation the shortcut will point to the file it belongs to.

Extensions Collection of generic WixSharp extension methods
Feature Defines WiX Feature.

All installable WiX components belong to one or more features. By default, if no Features are defined by user, Wix# creates "Complete" feature, which contains all installable components.

FeatureCondition Specialized Condition for conditionally installing WiX Features.
File Defines file to be installed.
FileAssociation Defines FileType association to be created for the file extension and the installed file/application (parent T:WixSharp.File).
FileShortcut Defines FileShortcut to be installed.

FileShortcut is a specialized version of the Shortcut designed for using Shortcut as a File nested element.

There are different ways of defining shortcuts of the Wix# project:

- It can be specified as a nested element of the File. In this case, after the installation, the shortcut will point to the file it belongs to.

- Alternatively the Shortcut can be specified as a File nested element. In this case after the installation the shortcut will point to the file will point to the file it belongs to.

Files Defines all files of a given source directory and all subdirectories to be installed on target system.

Use this class to define files to be automatically included into the deployment solution if their name matches specified wildcard character pattern (Files.IncludeMask).

You can use Files.ExcludeMasks to exclude certain files from setup if required.

This class is a logical equivalent of DirFiles except it also analyses all files in all subdirectories. DirFiles excludes files in subdirectories.

GuidGenerators Collection of the deterministic GUID generation algorithms
IISVirtualDir This class defines IIS Virtual Directory. It is a close equivalent of WebVirtualDirectory WiX element.
Id The unique string identifier of the Wix# project item. The Id is automatically generated by Wix# engine during the MSI build unless it is explicitly specified by a project item constructor parameter.

Id is used to "stamp" every XML element of the WiX source file produced by Wix#.

InstalledFileAction Defines WiX InstalledFileAction for executing installed file.
LaunchCondition Defines WiX Condition. Condition is normally associated with CustomActions or WiX elements (e.g. Shortcut).

Condition is nothing else but an XML friendly string wrapper, containing some predefined (commonly used) condition values. You can either use one of the predefined condition values (static members) or define your by specifying full string representation of the required WiX condition when calling the constructor or static method Create.

MajorUpgrade Simplifies authoring for major upgrades, including support for preventing downgrades.
MajorUpgradeStrategy This class defines the Major Upgrade scenario.
ManagedAction Defines WiX Managed CustomAction.

Managed CustomAction can be defined either in the Wix# script or in the external assembly or C# file. The only requirements for any C# method to be qualified for being Managed CustomAcyion is to have DTF Action signature public static ActionResult MyManagedAction(Session session), and be marked with [CustomAction] attribute.

If Managed CustomAction depends on any assembly, which will not be registered with GAC on the target system such assembly needs to be listed in the ManagedAction.RefAssemblies.

ManagedAction often needs to be executed with the elevated privileges. Thus after instantiation it will have Action.Impersonate set to false and Action.Execute set to Execute.deferred to allow elevating.
ManagedUI
Merge Defines MergeModule to be embedded into MSI.

Note that WiX syntax allows Merge element to belong to the Product element. However the documentation (WiX v3.0.4917.0) explicitly requires it to be nested inside of the Directory element (even if there is no neither technical nor logical reason for this). Thus Wix# simply follows the WiX convention.

NativeBootstrapper Defines native (un-managed) bootstrapper. The primary usage of NativeBootstrapper is to build bootstrappers for automatically installing .NET for executing MSIs containing managed Custom Actions (ManagedAction).

NativeBootstrapper is subject to the following limitations: Only Win32 native bootstrapper can be built. Only one Prerequisite cen be defined.
PathFileAction Defines WiX CustomAction for executing file specified by the path on the target system.
Project Represents Wix# project. This class defines the WiX/MSI entities and their relationships.

Project instance can be compiled into complete MSI or WiX source file with one of the Compiler "Build" methods.

Use Project non-default constructor or C# initializers to specify required installation components.

ProjectValidator
Property Defines WiX custom property.

Traditional property usage involves defining the property by instantiating the Property class (in the Project structure) and then setting it from CustomAction (e.g. SetPropertyAction).

Property value can be analyzed and used in CustomActions or it can be a base for the Condition of item to be installed.

PropertyRef Defines reference to the Wix custom property.

Sometimes it desirable to access WiX properties defined in the extension modules. PropertyRef is designed for such cases. You can use it as an ordinary WiX property but you do not need to set it up (e.g. define initial value) as it is already done in the corresponding extension module.

In a way PropertyRef is similar to C++ #include as it makes possible to access some entities defined in the external modules.

QtCmdLineAction Defines WiX QtExecCmdLineAction CustomAction.

QtCmdLineAction executes specified application with optional arguments. You do not have to specify full path to the application to be executed as long as its directory is well-known (e.g. listed in system environment variable PATH) on the target system.

QtCmdLineAction often needs to be executed with the elevated privileges. Thus after instantiation it will have Action.Impersonate set to false and Action.Execute set to Execute.deferred to allow elevating.
RegFile Defines the registry file (*.reg) containing the entries to be installed.

Compiler uses the data from this class to call T:WixSharp.CommonTasks.ImportRegFile internally and inject imported RegValues into the Project.

RegFileImporter
RegParser Based on Henryk Filipowicz work http://www.codeproject.com/Articles/125573/Registry-Export-File-reg-Parser Licensed under The Code Project Open License (CPOL)
RegValue Defines registry value to be installed.
RegValueProperty Defines WiX custom property assigned by MSI runtime during the installation to the RegistrySearch result.

RegValueProperty is used to set a property from the registry value when accessing the registry is inconvenient for a custom action.

RegistrySearch returns raw data thus data will always contain prefix indicating data type:

DWORD: Starts with '#' optionally followed by '+' or '-'.

REG_BINARY: Starts with '#x' and the installer converts and saves each hexadecimal digit (nibble) as an ASCII character prefixed by '#x'.

REG_EXPAND_SZ: Starts with '#%'.

REG_MULTI_SZ: Starts with '[~]' and ends with '[~]'.

REG_SZ: No prefix, but if the first character of the registry value is '#', the installer escapes the character by prefixing it with another '#'.

ScriptAction Defines WiX CustomAction for executing embedded VBScript.
SetPropertyAction Defines WiX CustomAction for setting MSI property.
Shortcut Defines shortcut to be installed. Shortcut is not supposed to be instantiated directly. Derivative class constructors should be used instead (e.g. FileShortcut, ExeFileShortcut).
ShortcutExtensions
Step Specifies predefined values for Action.Step, which controls order of Custom Action to be executed.

Before or After switch for Custom Action is controlled by When.

UIExtensions
UpgradeStrategyValidationException UpgradeStrategy validation exception class.
User Represents a WixUtilExtension User
ValidationException Generic validation exception class.
VersionRange This class represents a range of product versions. It is designed to be used for Major/Minor upgrade scenarios in conjunction with Upgrade strategy classes (e.g. MajorUpgradeStrategy).

Version is represented as a string to allow for predefined value %this%, which means "version of the product MSI being built".

This class includes predefined ranges for common upgrade scenarios.

WebAppPool This class defines WebAppPool WiX element. It is used to specify the application pool for this application in IIS 6 applications.
WebDirProperties This class defines WebDirProperites WiX element. The class itself has no distinctive behaviour nor schema. It is fully relying on encapsulated T:WixSharp.WixEntity.AttributesDefinition.
WebSite This class defines website attributes. It is a close equivalent of WebSite WiX element.
WebSite.WebAddress This class defines website address. It is a close equivalent of WebAddress WiX element.
Win32 Set of Win32 API wrappers
Win32.RECT
WixCLRDialog Defines System.Windows.Forms.T:System.Windows.Forms.Form, which is to be used as the for custom MSI dialog.

As opposite to the WixSharp.T:WixSharp.WixForm based custom dialogs WixCLRDialog is instantiated not at compile but at run time. Thus it is possible to implement comprehensive deployment algorithms in any of the available Form event handlers.

The usual usability scenario is the injection of the managed Custom Action (for displaying the WixCLRDialog) into the sequence of the standard dialogs (WixSharp.T:WixSharp.CustomUI).

While it is possible to construct T:WixSharp.CustomUI instance manually it is preferred to use Factory methods of T:WixSharp.CustomUIBuilder (e.g. InjectPostLicenseClrDialog) for this.

static public void Main() { ManagedAction showDialog; var project = new Project("CustomDialogTest", showDialog = new ShowClrDialogAction("ShowProductActivationDialog")); project.UI = WUI.WixUI_Common; project.CustomUI = CustomUIBuilder.InjectPostLicenseClrDialog(showDialog.Id, " LicenseAccepted = \"1\""); Compiler.BuildMsi(project); } ... public class CustomActions { [CustomAction] public static ActionResult ShowProductActivationDialog(Session session) { return WixCLRDialog.ShowAsMsiDialog(new CustomDialog(session)); } } ... public partial class CustomDialog : WixCLRDialog { private GroupBox groupBox1; private Button cancelBtn; ...

The all communications with the installation in progress are to be done by modifying the MSI properties or executing MSI actions via Session object.

When closing the dialog make sure you set the DeialogResul properly. WixCLRDialog offers three predefined routines for setting the DialogResult:

- MSINext

- MSIBack

- MSICancel

By invoking these routines from the corresponding event handlers you can control your MSI UI sequence: void cancelBtn_Click(object sender, EventArgs e) { MSICancel(); } void nextBtn_Click(object sender, EventArgs e) { MSINext(); } void backBtn_Click(object sender, EventArgs e) { MSIBack(); }

WixExtension Represents a Wix Extension
WixGuid Wix# wrapper around T:System.Guid. WixGuid allows generation of continuous GUIDs for for composing reproducible WiX source files.
WixGuid.SequentialGuid Class for generation of sequential T:System.Guid.

Based on http://developmenttips.blogspot.com/2008/03/generate-sequential-guids-for-sql.html

This class is used by Wix# engine internally to emit reproducible WiX code.

WixObject Base class for all Wix# types (entities)