access-app.json

The project file of an Access application built by tools/build/Build-AccessApp.ps1: what the application consists of and where its text sources are. The repository is the source; the ACCDB and ACCDE are build artifacts.

New projects: the WKL Office SDK builds, exports and checks Access applications from sources with more steps than this build tool (status and sync with the open Access, roundtrip, MSBuild, an Access add-in), and takes access-app.json over with wkl-office migrate access-app.json -o <folder> (documentation of the WKL Office SDK, „How to: Migrate a project of the build tool“). This build tool keeps working for existing projects.

{
  "name": "Kunden",
  "output": "out",
  "references": [
    { "library": "WklForms", "major": 2, "minor": 0 },
    { "library": "WklJSON", "major": 1, "minor": 0 },
    { "guid": "{00025E01-0000-0000-C000-000000000046}", "major": 5, "minor": 0 }
  ],
  "tables": "src/tables",
  "modules": "src/modules",
  "macros": "src/macros",
  "theme": { "folder": "src/theme", "name": "Riviera" },
  "ribbons": "src/ribbons",
  "queries": "src/queries",
  "forms": "src/forms",
  "reports": "src/reports",
  "controlBlocks": "src/controls",
  "properties": { "AppTitle": "Kunden", "StartUpForm": "frmShell", "CustomRibbonID": "AppRibbon", "StartUpShowDBWindow": false },
  "appModel": "src/app/app-model.json",
  "accde": true,
  "deploy": { "folder": "deploy", "version": "1.4.0", "targets": ["Administration", "Production"] }
}

Names the application and its source folders. Every entry except name is optional; a folder that is not named is not built. Paths are relative to the folder of the project file; an absolute path (for example themes/riviera of the release package) is taken as it is, by the build and by the export alike.

An entry the script does not know is refused with the list of known entries, so a mistyped name does not leave a part of the application out silently.

• Order of the build: references, tables, modules and macros, compile, theme (embedded, database opened again, checked), ribbons, ribbon model, queries, forms, reports, navigation pane model, properties, application model, the finish function, compile, ACCDE, delivery. Forms come after the theme because Access applies an embedded theme only to forms created after the database was opened again.
• Which version a reference records: major and minor are the lowest version the build asks for, not the one the database keeps. Access records the highest version of that type library registered on the build machine with the same major version: with Release 2.3 registered, { "library": "WklForms", "major": 2, "minor": 0 } gives a reference to 2.3 in the ACCDB and in the ACCDE. A lower minor therefore does not make the ACCDE run on PCs with an older release; what an ACCDE built against a newer release does on such a PC is described under „Order of an update“ in deploy-to-user-pcs. To keep a database usable with an older release, build it on a machine where that release is registered. The build writes the recorded version into requires of app-manifest.json and warns when it is above major.minor.
• Placeholders for WKL controls: a rectangle in a form whose Tag (Marke) is wkl:<Kind> - wkl:Grid, wkl:TreeList, wkl:ToggleSwitch … as the file names in docs/control-blocks - is replaced by that control with the rectangle's name, position and size, and with its anchors (HorizontalAnchor, VerticalAnchor) when the rectangle has them. Needed only for forms a script creates; a form edited in Access and saved with SaveAsText already contains its WKL controls.
• The finishing function must handle its errors. An error it does not handle opens the runtime error dialog of VBA, which the hidden Access never shows: the build then ends at the time limit (-TimeoutSeconds). Catch errors and return them as text.
• The VBA project must compile. The build stops when it does not (IsCompiled), naming the step; a compile error that waits for a dialog ends at the time limit.
• Ribbon model and export: Export-AccessApp writes the model back into the ribbonModel file byte for byte (the database keeps its canonical text) and leaves out what the model owns: the module basWklRibbon and the model's ribbons in USysRibbons are not written as files. A hand-edited model comes back in the canonical form after the first build and export. The context menu assignments stay in the model; the exported form and report texts carry the ShortcutMenuBar the build wrote, so a second build writes nothing new.
• Navigation pane model and export: Export-AccessApp writes the model back into the navPaneModel file byte for byte; Access's own pane tables are not exported. Groups and entries with conditions are written for the build machine (an ACCDB); an application whose pane differs per environment calls WklNavPane.Apply when it starts.
• Delivery without opening the application: the startup properties of a target are written into its copy with DAO; the copy is never opened, so its start form does not run during the build. The properties act when the copy is opened the first time (Access reads most of them only at opening). AppIcon is removed from the copy - it would name a file of the build computer - and written by WklApplication.EnsureApplication at the first start; the icon acts at once.
• What deploy does not do: it installs nothing, registers nothing and sets no trusted location. The folder is what a bootstrapper or an administrator places on the user's computer.
• Application model and export: Export-AccessApp writes the model back into the appModel file byte for byte, and the stored icon as the file next to it.
• Template and export: Export-AccessApp writes no object of the template into the application, unless the application already keeps a file of that name (which replaces the template's object). To change an object of the template for one application, put a file of the same name into the application's folder first.
• Text encodings: modules and ribbons UTF-8; forms, reports, queries and macros as SaveAsText writes them (UTF-16), forms also UTF-8 with byte order mark.

A project with a shell and one page, the WKL Forms Object Library 1.38 and a custom ribbon:

{
  "name": "Kunden",
  "references": [ { "library": "WklForms", "major": 2, "minor": 0 } ],
  "tables": "src/tables",
  "modules": "src/modules",
  "ribbons": "src/ribbons",
  "forms": "src/forms",
  "properties": { "AppTitle": "Kunden", "StartUpForm": "frmShell", "CustomRibbonID": "AppRibbon" }
}

None