How to Create A Windows Installer for Dynamsoft Service and .NET Document Scanner Application
Tags: windows, installer, wix, msi
Published: 2023-11-23 02:54:03

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](https://demo.dynamsoft.com/DWT/DWTResources/dist/DynamsoftServiceSetup.msi)

## What is WiX Toolset?
The [WiX Toolset](https://wixtoolset.org/) is an open-source project that allows developers to create Windows installation packages from XML source code. 

## Installing WiX Tools in Visual Studio
1. Install the HeatWave extension for VS2022 from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=FireGiant.FireGiantHeatWaveDev17).
2. Open the project creation window and select `WiX` from the `All languages` dropdown to display all available WiX project templates.
    
    ![WiX project templates](https://www.dynamsoft.com/codepool/img/2023/11/wix-project-template.png)


## Building .NET Windows Desktop Application for TWAIN Document Scanning
1. Get the source code of the .NET document scanning application from [GitHub](https://github.com/yushulx/dotnet-twain-wia-sane-scanner/tree/main/examples/WinFormsDocScan).
2. Request a [free trial license](https://www.dynamsoft.com/customer/license/trialLicense?product=dwt) and update the license key in the `Form1.cs` file.
    
    ```csharp
    private static string licenseKey = "LICENSE-KEY";
    ```
3. Build the application to generate the necessary files, which will be located in the `bin\Release\net7.0-windows` folder.
    
    ```bash
    dotnet build -c Release    
    ```

    The following list enumerates all the files required for the application:
    
    ```bash
    Twain.Wia.Sane.Scanner.dll
    WinFormsDocScan.deps.json
    WinFormsDocScan.dll
    WinFormsDocScan.exe
    WinFormsDocScan.pdb
    WinFormsDocScan.runtimeconfig.json
    ```

    ![windows dotnet desktop document scanner](https://www.dynamsoft.com/codepool/img/2023/11/windows-dotnet-desktop-document-scanner.png)

## Creating an MSI Installer Package for the .NET Document Scanning Application
1. Select the `MSI Package (WiX v4)` option to create a new WiX project. The structure of the project is displayed below.
    
    ![WiX MSI project structure](https://www.dynamsoft.com/codepool/img/2023/11/wix-msi-project-structure.png)

2. Open the `ExampleComponents.wxs` file and add all the files associated with the document scanner application.
    
    ```xml
    <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.
    
    ![WiX GUID error](https://www.dynamsoft.com/codepool/img/2023/11/wix-guid-error.png)

    You can generate a valid GUID using the following PowerShell command:
    
    ```powershell
    [guid]::NewGuid()
    ```
    
3. 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.
    
    ```xml
    <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>
    ```
4. 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.
    
    ![Document scanner application installed](https://www.dynamsoft.com/codepool/img/2023/11/msi-installation.png)

    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.

5. Open the `NuGet Package Manager` and install the `WixToolset.UI.wixext WiX` package for WiX.
    
    ![wix toolset ui](https://www.dynamsoft.com/codepool/img/2023/11/wix-toolset-ui.png)
    
    Then add the following code to the `Package.wxs` file.
    
    ```xml
    <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.

    ![docscan-msi-installer](https://www.dynamsoft.com/codepool/img/2023/11/docscan-msi-installer.png)
    
## 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. 
    
```xml
<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. 

![wix bundle](https://www.dynamsoft.com/codepool/img/2023/11/wix-bundle.png)


With this setup, the .NET document scanner application can now be distributed to any Windows user for installation and use.

## Source Code
[https://github.com/yushulx/dotnet-twain-scanner-installer](https://github.com/yushulx/dotnet-twain-scanner-installer)