Tutorial: Take an Access application from source folder to verified installation

In this tutorial, you turn a finished Access application into an installation package and then prove that the package works with a test installation. You don't need to know anything about WKL Bootstrapper beforehand; each step explains what you need right where you need it. Plan on about 30 minutes.

The example is a point-of-sale app for Muster GmbH, a fictitious company. You start with three items:

• Kasse.accde, the application, version 3.2.0
• a bin folder with two helper libraries (Kasse.Drucker.dll and Kasse.Waage.dll)
• a Berichte (reports) folder with a report template (Tagesabschluss.pdf)

By the end, you'll have Kasse-1.0.0.msi and you'll know that it does the right thing on a PC: the application lands in the user's profile, the report templates land in the user's Documents folder, a shortcut appears on the desktop, and Access opens the app.

The screenshots show Bootstrapper Manager with its German user interface; in English, the pages, commands, and fields are in the same places and carry the labels this tutorial uses.

Before you start, it helps to know who does what, because the package doesn't contain the application itself:

In short, the MSI package puts the project file on the computer, and the starter fetches the application on its own. How a new version of the app reaches users therefore depends on where the version number is stored; see What's next.

• WKL Bootstrapper Manager is set up and starts; see How to: Set up and start Bootstrapper Manager.
• A WKL Bootstrapper release that includes Wkl.Bootstrapper.exe and tools\New-StarterMsi.ps1.
• The WiX command-line tool, version 6 or later. For example: dotnet tool install --global wix.
• For the test installation: a test PC or virtual machine with Microsoft Access (or the Access runtime) and an account with administrator rights. The package installs for all users, so don't install it on your own workstation just to try it out.

Goal: Everything that belongs to the release is in one place.

Steps:

1. Create the folder C:\Lieferung\Kasse with a subfolder named deploy.
2. Copy Kasse.accde and the bin and Berichte folders to C:\Lieferung\Kasse\deploy.
3. Copy Wkl.Bootstrapper.exe to C:\Lieferung\Kasse, and copy the release's tools folder (with New-StarterMsi.ps1) to C:\Lieferung\Kasse\tools.

Result:

C:\Lieferung\Kasse\
+- Wkl.Bootstrapper.exe
+- tools\New-StarterMsi.ps1
+- deploy\                      < the source folder
   +- Kasse.accde
   +- bin\Kasse.Drucker.dll
   +- bin\Kasse.Waage.dll
   +- Berichte\Tagesabschluss.pdf

Background: Bootstrapper Manager looks for the starter next to the project file you create in step 1, and for the MSI script in the tools folder next to the starter. In production, the source folder lives on a share such as \\server\Kasse\deploy; for this tutorial, a local folder is fine.

Goal: The project file C:\Lieferung\Kasse\bootstrapper.json exists, and Bootstrapper Manager is editing it.

Steps:

1. On the Projects page, select the arrow next to New, and then select Empty project.
2. In the save dialog box, browse to C:\Lieferung\Kasse and keep the suggested name, bootstrapper.json.
3. The New message lists what's left to do: check the source folder, and enter the version and the launch target. Select OK to close it.

Result: The Kasse project appears in the list and is selected. Bootstrapper Manager took the product ID “Kasse” from the folder name.

Check: Select Check. The Problems page opens and reports version needs either value or from. That's expected; you enter the version in the next step.

Background: The Access application template, which New uses when you don't pick one, expects an app-manifest.json file in the source folder. The WKL Office SDK or the build tool of the WKL Forms Object Library writes that file. An application built without these tools, like the one in this example, starts from an empty project.

Goal: The project knows the version, the source folder, and the application's name.

Steps:

1. In the navigation pane, select Project > General, and enter these values:

   

   Field	Value	Why
   (1) Version	3.2.0	The app's version. The starter installs each version in its own folder and uses the number to recognize a new release
   (2) Source	C:\Lieferung\Kasse\deploy	The source folder. In production, a share such as \\server\Kasse\deploy

   Leave Product ID set to Kasse, and leave the other fields blank. Blank fields use the starter's defaults, including the install location %LOCALAPPDATA%\WKL\Kasse in the user's profile.

2. Select Appearance, and enter: Name Kassensystem, Publisher Muster GmbH, Text while setting up Das Kassensystem wird eingerichtet, and Language de.

Result: Not saved appears in the upper-right corner. Your changes are in the Bootstrapper Manager but not yet in the project file.

Check: On the Projects page, select Preview. Bootstrapper Manager saves the project and shows a picture of the window the user sees during setup, with the name “Kassensystem” and the publisher “Muster GmbH.”

The logo appears because the example on the other pages of this guide also sets a logo.png file (the Logo field); without one, that area stays empty. The line under the text and the progress bar are samples drawn by the starter.

Background: why the source needs a full path. A relative path such as deploy is resolved from the starter's folder. That works as long as the starter sits in C:\Lieferung\Kasse. Once the MSI package installs it, though, the starter lives in C:\Program Files (x86)\WKL\Kasse, and there's no deploy folder there. For any project you ship as an MSI package, always enter a full path or a share.

Background: the product ID. The starter uses the value of Product ID to name the app's folder in the user's profile and its entry in Windows Installed apps. Don't change it after the first release; Windows treats a new product ID as a different app. What users see is the Name from the Appearance page.

Goal: The project lists everything the starter should install.

Steps:

1. Select Installation > Files.
2. Select Add files. The dialog box opens in the source folder. Select Kasse.accde.
3. Select Add folder, and then select the bin folder.
4. Select Add folder again, and then select the Berichte folder.

You can also drag files and folders from File Explorer onto the list instead of using the commands.

Result: The list has three rows. For each one, Bootstrapper Manager entered the source relative to the source folder and, as the target, the same subfolder under [VersionDir]:

Check: The target tree on the left shows bin and Berichte under [VersionDir].

Background: Users get only what's on this list, even if the source folder contains other files. A folder brings along everything inside it. [VersionDir] is a placeholder: on the user's computer, the starter replaces it with the version folder, %LOCALAPPDATA%\WKL\Kasse\Frontends\3.2.0.

Goal: The report templates end up where users can find them, and the starter installs only when Access is present.

Steps:

1. On the Files page, in the Berichte row, change Target to [Documents]\Kassensystem\Berichte.
2. Select Installation > Conditions, and in the last row, enter access under Type. Leave Value and Expected blank.

Result: The target tree now shows Berichte under [Documents], and the condition list has one row of kind access:

Check: You'll verify this in step 6 with the trial run, which shows the actual path for every entry.

Background: The version folder belongs to the application. When version 3.3.0 arrives, the starter creates a new folder and gradually removes old versions. Files that users open themselves therefore belong in a fixed folder such as [Documents] (the user's Documents folder). The starter checks conditions before every installation. The access condition with no value requires any Access; with the value full, it requires full Access rather than the runtime. If a condition isn't met, the starter installs nothing and reports what's missing.

Goal: A shortcut appears on the user's desktop, and the starter finally opens Kasse.accde.

Steps:

1. Select Installation > Shortcuts, and in the last row, enter Folder [Desktop], Name Kassensystem, and Target [Starter].
2. Select Project > Launch target, and enter File or program [VersionDir]\Kasse.accde and Access: /runtime auto.

Result: The shortcut list has one row, and the Launch target page names the app.

Background: The shortcut targets [Starter], not Kasse.accde. Only a launch through the starter checks for a new version and installs it; a shortcut that points straight at the file would keep the user on whatever version they got first. /runtime auto opens an ACCDE in runtime mode, without Design view and without the Access ribbon. The MSI package creates the Start menu entry; the starter creates the desktop shortcut for each user on first launch.

Goal: The starter accepts the project file as valid, and a launch would succeed on this computer.

Steps:

1. Press Ctrl+S. The notification “Saved to bootstrapper.json” appears in the lower-right corner, and Not saved goes away.
2. On the Projects page, select Check.
3. Select Trial run.

Result: Check shows this notification in the lower-right corner, meaning the starter found no problems:

The Trial run message starts with 0 Ok and lists the plan, using the paths for your account:

0 Ok
version 3.2.0 (x86) into C:\Users\<account>\AppData\Local\WKL\Kasse\Frontends\3.2.0
1 file(s) into C:\Users\<account>\AppData\Local\WKL\Kasse\Frontends\3.2.0
  C:\Lieferung\Kasse\deploy\Kasse.accde -> C:\Users\<account>\AppData\Local\WKL\Kasse\Frontends\3.2.0\Kasse.accde
2 file(s) into C:\Users\<account>\AppData\Local\WKL\Kasse\Frontends\3.2.0\bin
  ...
1 file(s) into C:\Users\<account>\Documents\Kassensystem\Berichte
  ...
shortcut C:\Users\<account>\Desktop\Kassensystem.lnk
start C:\Users\<account>\AppData\Local\WKL\Kasse\Frontends\3.2.0\Kasse.accde

Check: Compare the plan with steps 3 through 5: three entries, the reports under Documents, the shortcut on the desktop, and Kasse.accde as what gets launched. The trial run doesn't change anything on the computer.

If something is reported: Check opens the Problems page with one row per problem, worded as the starter reports it (in English). Double-click a row to open the page and highlight the field or row to fix. Correct the value, save, and select Check again. If the trial run message doesn't start with 0, it gives a code and the cause, such as an unreachable source folder; Error codes of the starter (WKL Bootstrapper documentation) describes the codes. For details, see How to: Check a project and fix problems.

Goal: You have Kasse-1.0.0.msi, and installing it on a test computer gives the expected result.

Build the package:

1. On the Projects page, select Build MSI.

2. In the Build MSI dialog box, keep the package version 1.0.0 and select OK.

   

   The prompt asks for the package version: two or three numbers, higher than the last package you distributed. The package version isn't the app's version; it counts the packages IT deploys and starts at 1.0.0.

Result: After a few seconds, a message names the package:

Check the contents (no installation, no admin rights needed):

msiexec /a C:\Lieferung\Kasse\Kasse-1.0.0.msi /qn TARGETDIR=C:\Lieferung\msi-inhalt

C:\Lieferung\msi-inhalt\PFiles\WKL\Kasse contains exactly Wkl.Bootstrapper.exe and bootstrapper.json. The application isn't in the package; it comes from the source folder at launch.

Run the test installation:

1. Make sure the test computer can reach the source folder. For this tutorial, copy C:\Lieferung\Kasse\deploy to the same location on the test computer; in production, that's the share.

2. Install the package as an administrator:

   msiexec /i Kasse-1.0.0.msi

3. Sign in as a standard user, and start Kassensystem from the Start menu.

Result: The starter's window briefly shows “Das Kassensystem wird eingerichtet,” and then Access opens the app.

Check:

Installed apps now lists two entries named “Kassensystem”: the MSI package (the starter, for all users, version 1.0.0) and the application in this user's profile (version 3.2.0). For what each entry removes, see How to: Roll out the starter with an MSI (WKL Bootstrapper documentation).

Undo the test installation: First, as the user, uninstall the entry with version 3.2.0; the starter removes the version, the report templates, the shortcut, and the entry. The log in the Logs folder stays. Then, as an administrator, uninstall the MSI package (msiexec /x Kasse-1.0.0.msi).

• A new version of the app: In this tutorial, the version is stored in the project file (the Version field). For version 3.3.0, put the new Kasse.accde in the source folder, enter 3.3.0, and build a new MSI package with a higher package version, such as 1.1.0, because computers read the project file from the package. To ship new versions without a new package, let the starter read the version from the source folder instead: the WKL Office SDK and the WKL Forms Object Library build tool write an app-manifest.json file next to the app, and the project names it in the Version from file field, which is how the Access application template sets up a project. Then updating the source folder is all it takes; see How to: Set the product, version, appearance, and launch target.
• An application from the WKL Office SDK: If you build the app with the SDK, wkl-office deliver puts together the source folder with its manifest and the starter project file, and the SDK then opens Bootstrapper Manager with that file. See How to: Deliver an application from the SDK (WKL Office SDK documentation).
• Package for IT: How to: Roll out the starter with an MSI (WKL Bootstrapper documentation) explains how to sign and deploy the package.
• More entries, such as registry values or file types: How to: Set up shortcuts, registry values, and other entries.

• How to: Choose which files to install and where
• How to: Test a project and build an MSI package
• The project file (format 2) (WKL Bootstrapper documentation): every field of the project file