Buy me a cup of coffee 

Software development is powered by coffee... if you use any of our open source pojects, it would make my day if you'd buy me a cup (or several). Just click on the coffee cup.

WiX Custom Actions for ASCOM

Tags: open-source, free software, ASCOM, astronomy, WiX, installer, software

enter image description here

NuGet package | Source code

Description

This package provides three custom actions that assist with the installation of ASCOM (Astronomy Common Object Model) drivers:

  • EnumerateAscomDeviceProfiles processes a custom data table, whose rows represent ASCOM drivers to be registered with (or unregistered from) the ASCOM Platform. This action is scheduled in Immediate Mode and runs with standard user permissions. The action checks for existing registrations and (if present) exports their settings. It packages up this data in a format suitable for use by the Deferred Mode actions that will run with elevated permissions.

  • UnregisterAscomDeviceProfiles deletes device profiles as directed by the data passed from EnumerateAscomDeviceProfiles. This action is scheduled in Deferred Mode and runs with elevated permissions. The action normally runs during uninstall, repair or upgrade operations.

  • RegisterAscomDeviceProfiles creates new device profiles as directed by the data passed from EnumerateAscomDeviceProfiles. If settings data is present, then it is imported into the newly-created profile. Existing profiles are not overwritten. This action is scheduled in Deferred Mode and runs with elevated permissions. It is normally run during install, repair and upgrade operations.

For an overview of Windows Installer setup phases and the difference between Immediate Mode and Deferred Mode, please see http://en.wikipedia.org/wiki/WindowsInstaller#Setupphases

Limitations

These custom actions are only concerned with the ASCOM device profiles, that is, the part of ASCOM that stores the driver's settings and makes it show up in the ASCOM Chooser component. It does not:

  • perform COM registration within the Windows Registry
  • install any files

These actions must be achieved in other ways. Typically, the COM registration is performed by supplying <RegistryKey> and <RegistryValue> elements, while file copying is done by specifying <Component> and <File> elements elsewhere in the WiX source.

Usage

Once the custom action assembly has been referenced (either from the NuGet package or from another project in the solution) then some items need to be added to the WiX source.

  1. The custom action DLL must be declared in a <File> element so that it is added to the Binary table.
  2. The custom actions' entry points must be declared, using the correct IDs and referencing the <File> item already declared.
  3. The custom actions must be scheduled to run at appropriate places in the install process, by specifying entries within an <InstallExecuteSequence> element.
  4. A list of the ASCOM devices to be registered or unregistered must be provided by creating a <CustomTable> element.

More details and example WiX source fragments follow.

Declaring the Custom Actions

Communication between the custom actions and the source data is based on the WiX ID of the various objects. Therefore, it is imporatnt to use the correct identifiers for all items. The custom actions should be declared like so:

  <Fragment>
    <Binary Id="AscomCustomActions"
            SourceFile="..\packages\TA.Ascom.WixCustomActions.0.0.0-alpha1\lib\net40\TA.Ascom.WixCustomActions.CA.dll" />
    <CustomAction Id="caPrepareAscomDeviceProfiles"
                  BinaryKey="AscomCustomActions" 
                  DllEntry="EnumerateAscomDeviceProfiles"
                  Execute="immediate"
                  Return="check" />
    <CustomAction Id="caRegisterDrivers"
                  BinaryKey="AscomCustomActions"
                  DllEntry="RegisterAscomDeviceProfiles"
                  Execute="deferred" 
                  Return="check" />
    <CustomAction Id="caUnregisterDrivers" 
                  BinaryKey="AscomCustomActions" 
                  DllEntry="UnregisterAscomDeviceProfiles"
                  Execute="deferred"
                  Return="ignore" />
    <InstallExecuteSequence>
      <Custom Action="caPrepareAscomDeviceProfiles" Before="InstallInitialize" />
      <Custom Action="caUnregisterDrivers" After="RemoveFiles">Installed OR MaintenanceMode="Modify" OR UPGRADINGPRODUCTCODE</Custom>
      <Custom Action="caRegisterDrivers" Before="InstallFiles">NOT REMOVE OR Installed</Custom>
    </InstallExecuteSequence>
  </Fragment>

AscomDeviceProfiles Custom Table

The source data that the custom actions operate on is supplied via a custom table definition, which must have the ID of AscomDeviceProfiles. Each row in the table represents a device to be registered with the ASCOM Platform. The table is constructed as follows:

<Fragment>
  <!--
  The following property is needed because WiX doesn't have a CustomTableRef, so we need some other way to reference the fragment.
  You must reference this property from somewhere within your <Product/> element or the entire fragment will be optimized away.
  -->
  <Property Id="IncludeAscomDriverTypesTable" Value="1"></Property>
  <CustomTable Id="AscomDeviceProfiles">
    <Column Id="Id" Category="Identifier" PrimaryKey="yes" Type="int" Width="4" Description="Unique row ID" />
    <Column Id="DriverId" Category="Text" Type="string" PrimaryKey="no" />
    <Column Id="ChooserName" Category="Text" Type="string" PrimaryKey="no" Description="The name that will appear in the ASCOM Chooser"/>

    <!-- List your drivers each in its own <Row/>. -->
    <Row>
      <Data Column="Id">1</Data>
      <Data Column="DriverId">ASCOM.MyDriver.Telescope</Data>
      <Data Column="ChooserName">My whizzy new telescope driver</Data>
    </Row>
  </CustomTable>
</Fragment>

NuGet

A NuGet package of pre-built binaries is available from http://nuget.org

A future release will include template WiX sources and will automatically add them to the project when installed from NuGet.

TeamCity Build Status

Let Us Help You

Find us on Facebook