How to: Deliver an application from the SDK

Put the delivery of an Access application together from its sources, so its users get it through WKL Bootstrapper: the database of each delivery profile with its manifest, the WKL libraries it needs, and the starter.

Requires the WKL Office SDK from 0.3.0, the release packages of WKL Forms Object Library (and WKL Office JSON when the project references it) and of WKL Bootstrapper 2.2 or later on the build machine; recommended is 2.2.4 or later, which refuses older signed deliveries put back on the share (with an older starter deliver warns and delivers). WKL Office JSON 2.0 or later needs the starter 2.3.1 or later, WKL Forms Object Library 2.0 or later the starter 3.1 or later; with an older one deliver stops. For an MSI also the WiX Toolset command line (wix); for editing the starter Bootstrapper Manager, which wkl-office addin install installs with the SDK.

An application built with the SDK reaches its users through the starter, which reads app-manifest.json beside the delivered database and registers the WKL libraries it needs. Writing that delivery by hand is error-prone (checksums, versions, bitness, the packages of both bitnesses).

• A delivery profile says what a delivery contains: the build configuration it is built in (whose mode is the mode of the delivery), the delivery folder and the starter. Each profile is a file delivery\<name>.profile.json. What all profiles share, the version and the release packages, is in delivery\delivery-settings.json (reference).
• In the add-in, you set up both in Project Properties (the Properties button in the Project group).
• wkl-office deliver (or Deliver in the group Delivery of the add-in; the menu lists the profiles of the build configuration chosen in the add-in) builds each profile and writes build\Delivery\<name>: the starter with its project file, and below deploy the database, app-manifest.json and the WKL libraries.
• The starter's project file per profile is a source of the project (delivery\<name>.bootstrapper.json), edited with Bootstrapper Manager (Starter › Set up in Bootstrapper Manager).
• wkl-office msi builds the Windows Installer package of a profile for the IT.

1. Set up the delivery. In the add-in, open Properties, select Delivery profiles in the tree, and click Set up delivery. The dialog adds the profile Production, built in the build configuration Release, and fills in the newest release packages below WKL_PACKAGES; check them under Delivery, then save with OK.

   By hand, you write the same two files, delivery\delivery-settings.json:

   {
     "format": 2,
     "version": "1.0.0",
     "packages": {
       "components": "%WKL_PACKAGES%\\Wkl.Forms.ObjectLibrary\\2.0.0",
       "bootstrapper": "%WKL_PACKAGES%\\Wkl.Bootstrapper\\3.1.0"
     }
   }

   and delivery\Production.profile.json:

   {
     "format": 1,
     "configuration": "Release"
   }

   A profile's build configuration must set a mode: in the project file, <AppMode>Production</AppMode> and <Accde>true</Accde> in the property group of Release (project file); in the dialog, under Build configurations › Release. Set up delivery sets the mode Production when Release has none yet. For a version only administrators get, add another configuration with the mode Administration and a profile built in it.

2. Check what goes along:

   wkl-office deliver Customers.acproj --dependencies

3. Deliver:

   wkl-office deliver Customers.acproj

   The first delivery of a profile writes delivery\<name>.bootstrapper.json from the starter's templates and says so as a warning. Open it with Starter › Set up in Bootstrapper Manager: set source to the share the users read from, the display name and the shortcuts; save. Deliver again.

4. Try a profile without installing anything:

   wkl-office deliver Customers.acproj -p Production --whatif

5. Copy build\Delivery\production\deploy to the share named as source, the database first and app-manifest.json last, and give the users the starter (Wkl.Bootstrapper.exe with bootstrapper.json), or build its package for the IT:

   wkl-office msi Customers.acproj -p Production --version 1.0.0 --sign <thumbprint>

• The delivery is built in a hidden Access of its own, one profile after the other; the database open in the developer's Access stays as it is. When a profile fails, the command stops and neither builds nor delivers the profiles after it.
• Several profiles may deliver the same mode, for example one per customer, each with its own build configuration (connection profile) and its own delivery folder.
• requires follows the build machine: Access records the highest registered version of a referenced library in the database, so a delivery built with Components 1.59 registered needs 1.59 on the users' PCs. Build deliveries on a machine that has the release registered that the users get.
• WKL Bootstrapper Manager is part of the SDK: wkl-office addin install installs it as %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager\<version>\Wkl.Bootstrapper.Manager.accdb (see Install the WKL Office SDK). The SDK opens it with the project file and the starter. It uses the file that WKL_BOOTSTRAPPER_MANAGER (formerly WKL_STARTER_CONFIGURATOR) points to when that file exists, otherwise the highest version below %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager and the former folder %LOCALAPPDATA%\Programs\WKL\Starter Configurator. The arguments are described on the page “Command line of WKL Bootstrapper Manager” in the WKL Bootstrapper Manager documentation.
• 32-bit and 64-bit Office. A profile is delivered for the bitness of the Access that builds it. With "bitness": "any" in the profile (in Project Properties: For 32-bit and 64-bit Office), one build on a 32-bit computer serves 32-bit and 64-bit Office: the delivery is an ACCDB that Access compiles on first start (see delivery-settings.json).
• any or one ACCDE per bitness? It comes down to whether users may read and change the VBA code on their computers. With any they can, because the delivery is an ACCDB.
  • Administration: any is usually fine, since only administrators get this version.
  • Production: use any if open code is acceptable for your application; otherwise deliver one ACCDE per bitness.
  • An ACCDE always has the bitness of the Access that builds it, so a 64-bit ACCDE can only be built on a computer with 64-bit Access (the full version; the Runtime can't create an ACCDE). Add a profile of its own for it, with its own delivery folder, for example Production x64, and deliver it on that computer with -p "Production x64". You distribute the two deliveries separately; the starter refuses a database built for the other bitness with a message instead of opening it.
• Format 1 still works: a delivery-settings.json with targets delivers each target as a profile named after its mode. Project Properties writes it as format 2 once the delivery is changed there (delivery-settings.json).

• Project folder – which file goes where and what is versioned
• Build configurations and delivery profiles – what a configuration and a profile decide
• delivery-settings.json
• Command-line reference: deliver, msi
• Migrate a project of the build tool of WKL Forms Object Library
• “WKL Bootstrapper Manager user guide” in the WKL Bootstrapper Manager documentation: editing the starter's project file