How to: Install the WKL Office SDK

Put the WKL Office SDK on a developer machine or a build machine, so wkl-office and dotnet build of an .acproj work there.

Requires Windows 11, Microsoft 365 Access (32-bit or 64-bit) installed for the user who builds, git on the PATH, and the .NET 10 runtime (dotnet --list-runtimes lists Microsoft.NETCore.App 10.x). For dotnet build the .NET 10 SDK. The Access add-in runs inside Access and needs the .NET 10 Desktop Runtime of the bitness of Office (Microsoft.WindowsDesktop.App 10.x; for 32-bit Office the x86 runtime, which C:\Program Files (x86)\dotnet\dotnet.exe --list-runtimes lists).

Supported configuration of this release: Windows 11 with 32-bit or 64-bit Microsoft 365 Access. Access 2016, 2019 and 2021, Windows 10 and a build machine with only the Access Runtime are not supported.

The SDK is a folder: bin holds wkl-office.exe, msbuild the MSBuild tasks and their targets, addin the Access developer add-in in both bitnesses, bootstrapper-manager Bootstrapper Manager that sets up the starter of a delivery, docs/public this documentation, SECURITY.md and MANUFACTURER.md (also in German and Slovenian) how to report a vulnerability, who the manufacturer is and until when the release is supported, and sbom.cdx.json the software bill of materials of the package (CycloneDX 1.6). Nothing is registered by copying it, and no administrator rights are needed; the add-in is registered only on request, for the current user. The tool automates the installed Access out of process, so the same folder serves 32-bit and 64-bit Office.

1. Copy the package folder to a place of your choice, for example C:\Tools\WklOfficeSdk.

2. Put its bin folder on the PATH of your user:

   $bin = 'C:\Tools\WklOfficeSdk\bin'
   [Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ';' + $bin, 'User')

3. Open a new terminal and check the machine against a project:

   wkl-office check C:\Work\Customers\Customers.acproj

   check names the Access it found with its bitness, and every missing reference or ODBC driver.

4. For dotnet build, import the targets at the end of the project file:

     <Import Project="C:\Tools\WklOfficeSdk\msbuild\Wkl.Office.Sdk.targets" />
   </Project>

5. For the ribbon tab and work area in Access, register the add-in while Access is closed (see Use the Access add-in):

   wkl-office addin install

   With the next start of Access, the ribbon shows the tab WKL SDK:

   

   *The tab WKL SDK with its groups 1 to 6; Use the Access add-in describes what they hold.*

   The same command installs Bootstrapper Manager for your user in %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager\<version>; it reports whether it copied it or that version was already there. WKL Bootstrapper Manager needs WKL Forms Object Library 2.0 or later and WKL Office JSON 2.0 or later registered for your user; with older components it shows [key] instead of its texts.

   It also associates project files with the SDK: a double-click on a .acproj in Explorer opens the application in Access for development, without running its start form or AutoExec, and builds it first when there is no database yet (`open`). A double-click on the .accdb still starts the application the way its users see it. The menu of a project file then has the submenu “WKL Office SDK” (in Windows 11 under “Show more options”). At the first double-click, Windows asks once which app opens .acproj files: choose “WKL Office SDK” and “Always”.

• Checking the package. Every program file of the package (EXE and DLL) carries the Authenticode signature of EMSR DATA, D.O.O. with a time stamp, and SHA256SUMS lists the SHA-256 checksum of every file in the package except itself. Before you put the folder on the PATH, check both:

  Get-AuthenticodeSignature C:\Tools\WklOfficeSdk\bin\wkl-office.exe | Format-List Status, SignerCertificate
  Set-Location C:\Tools\WklOfficeSdk
  Get-Content SHA256SUMS | ForEach-Object { $hash, $file = $_ -split '  ', 2; if ((Get-FileHash -LiteralPath $file).Hash -ne $hash) { "changed: $file" } }

  Status must be Valid and the signer EMSR DATA, D.O.O.; the second command prints nothing when every file is unchanged.

• What the SDK runs on your computer. A build runs VBA code of the sources: the finishing function of the project (Finish) and the functions of the WKL models run in the Access of the build. Whoever can change the sources can therefore run code on the computer that builds them: build only sources you trust, and let a build agent build only branches that were reviewed. A database the SDK opens itself (export, validate, call, test) is opened as a copy without its start form, and a database with an AutoExec macro is refused. git, svn, Visual Studio Code and PowerShell are found through the PATH of the user; whoever can change the PATH decides which program starts, as for any command-line tool.
• Build machines. Access has to be installed and activated for the account the build runs under, and the build needs a desktop session of that account (Access does not run as a service): a build agent runs as an interactive process of a signed-in user. The references of the application (WKL Forms Object Library, WKL Office JSON …) must be registered for that account, in the bitness of Access. Modules go into Access in the ANSI code page of Windows (“Language for non-Unicode programs”): the machine needs a code page that holds every character of the modules. With ConnectionProfile, the build connects to the data sources, so it needs the drivers, network access and a login without a prompt. The SDK does not provide an operating procedure for build agents (automatic sign-in, locked screen, monitoring); set it up with the usual means of your build system.
• Update. Replace the folder; the projects do not change, a project names no version of the SDK. When the add-in is registered, close Access first: Access keeps the add-in's files open while it runs. If you put the new release into a folder of its own instead (for example one folder per version), point the PATH entry at its bin folder and remove the old entry; otherwise new terminals keep starting the old version. (Get-Command wkl-office).Source shows which wkl-office.exe a terminal starts. wkl-office addin install puts a newer version of the Starter Configurator into a folder of its own next to the previous one and never overwrites an installed version, because Access saves your changes in that file; the SDK opens the highest version. Run wkl-office addin install from the new version once; the add-in and the double-click on project files then use the new folder.
• Update from the WKL Access SDK (0.4 and earlier). From 0.5 the SDK is called WKL Office SDK and its command is wkl-office; there is no wkl-access.exe any more. Change scripts, .vscode\tasks.json and build definitions that call wkl-access, and an import of Wkl.Access.Sdk.targets into Wkl.Office.Sdk.targets. Projects, commands, options and exit codes stay the same. Run wkl-office addin install once, so the add-in is registered from the new folder.
• Removal. Run wkl-office addin remove --all when the add-in was registered: it removes the add-in and the settings of the SDK for your user (HKEY_CURRENT_USER\Software\The White Knight Labs\Access Framework\Sdk); without --all the settings stay for a later installation. Then delete the folder and its entry from the PATH. wkl-office addin remove leaves Bootstrapper Manager in place; delete %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager to remove it (a version before 2.0 is in %LOCALAPPDATA%\Programs\WKL\Starter Configurator).

• Tutorial: Put an Access application under source control
• How to: Build with dotnet build
• Command-line reference