Xiao Ling

Posted on Nov 23, 2023 • Edited on Aug 20, 2024 • Originally published at dynamsoft.com

How to Create A Windows Installer for Dynamsoft Service and .NET Document Scanner Application

#windows #installer #wix #msi

Using the Dynamsoft Service RESTful API significantly simplifies the creation of document scanning applications. However, distributing these as desktop applications can be somewhat challenging. Users are required to install both the developer's application and the Dynamsoft Service. Bundling them together in a single installation package would greatly improve the user experience. In this article, we will demonstrate how to use WiX Toolset to create a Windows installer that incorporates both the Dynamsoft Service and the document scanner application.

Downloading Dynamsoft Service for Windows

Dynamsoft Service for Windows

What is WiX Toolset?

The WiX Toolset is an open-source project that allows developers to create Windows installation packages from XML source code.

Installing WiX Tools in Visual Studio

Install the HeatWave extension for VS2022 from the Visual Studio Marketplace.
Open the project creation window and select WiX from the All languages dropdown to display all available WiX project templates.

Building .NET Windows Desktop Application for TWAIN Document Scanning

Get the source code of the .NET document scanning application from GitHub.
Request a free trial license and update the license key in the Form1.cs file.
```
private static string licenseKey = "LICENSE-KEY";
```
Build the application to generate the necessary files, which will be located in the bin\Release\net7.0-windows folder.
```
dotnet build -c Release    
```
The following list enumerates all the files required for the application:
```
Twain.Wia.Sane.Scanner.dll
WinFormsDocScan.deps.json
WinFormsDocScan.dll
WinFormsDocScan.exe
WinFormsDocScan.pdb
WinFormsDocScan.runtimeconfig.json
```

Creating an MSI Installer Package for the .NET Document Scanning Application

Select the MSI Package (WiX v4) option to create a new WiX project. The structure of the project is displayed below.

Open the ExampleComponents.wxs file and add all the files associated with the document scanner application.

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
  <Fragment>
    <ComponentGroup Id="ExampleComponents" Directory="INSTALLFOLDER">
      <Component Guid="485f0a38-7e1e-4597-a68d-27e96642c12c">
        <File Source="..\WinFormsDocScan\bin\Release\net7.0-windows\WinFormsDocScan.exe" KeyPath="yes"/>
        <File Source="..\WinFormsDocScan\bin\Release\net7.0-windows\Twain.Wia.Sane.Scanner.dll"/>
        <File Source="..\WinFormsDocScan\bin\Release\net7.0-windows\WinFormsDocScan.deps.json"/>
        <File Source="..\WinFormsDocScan\bin\Release\net7.0-windows\WinFormsDocScan.dll"/>
        <File Source="..\WinFormsDocScan\bin\Release\net7.0-windows\WinFormsDocScan.pdb"/>
        <File Source="..\WinFormsDocScan\bin\Release\net7.0-windows\WinFormsDocScan.runtimeconfig.json"/>
      </Component>
    </ComponentGroup>
  </Fragment>
</Wix>

Note: The project will fail to build if a GUID (Globally Unique Identifier) is not provided.

You can generate a valid GUID using the following PowerShell command:

[guid]::NewGuid()

When you build the project, it will generate the following files: cab1.cab, PackageDocScan.msi and PackageDocScan.wixpdb.

cab1.cab contains all the files of the document scanner application.
PackageDocScan.msi is the installer package.
PackageDocScan.wixpdb is the project database file.

Since we want to keep the installer package and the application files together, we need to modify the Package.wxs file to include the application files in the installer package.

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
  <Package Name="PackageDocScan" Manufacturer="Dynamsoft" Version="1.0.0.0" UpgradeCode="d79d6f4a-f2ec-41ff-9445-b6219ae8f99a">
    <MajorUpgrade DowngradeErrorMessage="!(loc.DowngradeError)" />

    <Feature Id="Main">
      <ComponentGroupRef Id="ExampleComponents" />
    </Feature>
    <Media Id="1" Cabinet="cab1.cab" EmbedCab="yes"/>
  </Package>
</Wix>

Rebuild the project, and you will notice that only two files are generated: PackageDocScan.msi and PackageDocScan.wixpdb. To install the application, double-click on the PackageDocScan.msi file. The application will be installed in the C:\Program Files\Dynamsoft PackageDocScan directory.

The installation is successful, but it lacks user-friendly interaction during the process. To enhance this, we need to add a user interface to the installer package.
Open the NuGet Package Manager and install the WixToolset.UI.wixext WiX package for WiX.

Then add the following code to the Package.wxs file.
```
<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs"
      xmlns:ui="http://wixtoolset.org/schemas/v4/wxs/ui">

...
    <ui:WixUI
      Id="WixUI_InstallDir"
      InstallDirectory="INSTALLFOLDER"
    />
...
```
After rebuilding the project, you will notice that the installer package now includes a user interface, similar to what is typically seen when installing Windows applications.

Creating a Bundle for Dynamsoft Service and .NET Document Scanner Application

Now that the MSI package is ready, we can proceed to create a Bundle (WiX v4) project that will include both the Dynamsoft Service and the document scanner application.

The Bundle.wxs file is as belows.

<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs" xmlns:bal="http://wixtoolset.org/schemas/v4/wxs/bal">
  <Bundle Name="BundleDocScan" Manufacturer="TODO Manufacturer" Version="1.0.0.0" UpgradeCode="8515efd9-92c0-4232-bd0f-a572a0ccbce5">
    <BootstrapperApplication>
      <bal:WixStandardBootstrapperApplication 
          LicenseUrl="https://www.dynamsoft.com/company/license-agreement/" 
          Theme="hyperlinkLicense" 
          LogoFile="logo.png"/>
    </BootstrapperApplication>

    <Chain>
        <MsiPackage SourceFile="..\PackageDocScan\bin\x64\Release\en-US\PackageDocScan.msi" />
        <MsiPackage SourceFile="msi\DynamsoftServiceSetup.msi" />
    </Chain>

  </Bundle>
</Wix>

It contains two MsiPackage elements. The SourceFile attribute specifies the path to the installer package, while the LogoFile attribute defines the path to the logo image.

Running the bundle's executable file will install both the Dynamsoft Service and the document scanner application.