Befehlszeilenreferenz: wkl-office

wkl-office ist das Befehlszeilenwerkzeug des WKL Office SDK. Alle anderen Werkzeuge des SDK (die MSBuild-Tasks, die Tasks von Visual Studio Code) rufen denselben Code auf; ein Befehl entscheidet daher überall gleich, wo er auch läuft.

wkl-office <command> <project.acproj | folder | file> [options]
wkl-office diff <project.acproj> <object | file> [options]
wkl-office call <project.acproj | database> <function> [argument ...] [options]
wkl-office test <project.acproj> [options]
wkl-office texts export | import <project.acproj> [<file.csv>]
wkl-office addin install | remove | status
wkl-office settings list | get <key> | set <key> [<value>]

Eine Option, die ein Befehl nicht annimmt, eine unbekannte Option, ein falscher Wert oder ein fehlendes Argument beendet den Lauf mit Exitcode 1. Auf der Standardfehlerausgabe steht dann eine Zeile, die den Befehl und den Fehler nennt, und ein Hinweis auf wkl-office --help; wkl-office ganz ohne Angaben gibt den vollständigen Verwendungstext aus. wkl-office --help (auch -h, -?, help) gibt den Verwendungstext auf der Standardausgabe aus und endet mit Exitcode 0.

Ein Lauf je Projekt zur selben Zeit. Die schreibenden Befehle (build, rebuild, run, open, validate, accde, export, import, status, sync, commit, roundtrip, deliver, msi, test, texts) halten während ihrer Arbeit die Datei obj/wkl-sdk.lock neben der Projektdatei. Ein zweiter Lauf, der in der Zwischenzeit gestartet wird – aus einem Terminal, aus dotnet build oder aus dem Add-In –, endet sofort mit Exitcode 10 und nennt den Lauf, der das Projekt hält (Prozess-ID, Programm, Befehl, Beginn); es wurde nichts ausgeführt. Die Sperre endet mit dem Lauf, auch wenn er abgebrochen wird; es gibt also nichts aufzuräumen: Die Sperre ist die geöffnete Datei, nicht die Datei selbst. Die Datei bleibt mit den Angaben des letzten Laufs liegen; ohne diesen Lauf bedeutet sie nichts, und der Ordner obj darf gelöscht werden. check, call, changes, diff, push, new, migrate und addin setzen keine Sperre.

Ein Access-Lauf je Computer zur selben Zeit (optional). Teilen sich mehrere Personen oder Sitzungen einen Desktop, stören sich ihre Access-Läufe gegenseitig: Dialoge, der Vordergrund, die Registrierung von Komponenten pro Benutzer. Sie können sich auf eine Sperrdatei einigen und sie mit --lock-file <datei> oder der Umgebungsvariablen WKL_ACCESS_LOCK_FILE angeben. Jeder Befehl, der Access startet (build, rebuild, run, open, validate, accde, export, import, status, sync, commit, roundtrip, migrate, deliver, msi, call, test), legt diese Datei dann an, bevor er Access startet, und hält sie bis zum Ende des Laufs; die MSBuild-Tasks (nur über die Umgebungsvariable) und die Vorgänge des Add-Ins ebenso. Solange ein anderer Lauf oder ein anderes Werkzeug die Datei hält, wartet ein Lauf bis zu --lock-wait Sekunden (Standard 600, MSBuild 600) und nennt den Inhaber einmal auf der Standardfehlerausgabe; besteht die Datei dann noch, endet er mit Exitcode 10, und es wurde nichts ausgeführt. Ein Vorgang des Add-Ins wartet wie auf das Projekt und zeigt Maschinensperre <datei>: <inhaber> an.

• Die Datei enthält je Zeile ein name: wert: holder: (WKL_ACCESS_LOCK_HOLDER, sonst der Benutzername), since: (UTC), purpose: (Befehl und Projekt) und process: (Prozess-ID und Programm).
• Das SDK legt die Datei mit „beim Schließen löschen“ an: Windows löscht sie, wenn der Lauf endet, auch wenn er abgebrochen wird oder abstürzt; es bleibt also keine verwaiste Sperre zurück.
• Auf eine Datei, die ein anderes Werkzeug angelegt hat (ein Skript mit derselben Vereinbarung: Datei vor dem Lauf exklusiv anlegen, danach löschen), wird gewartet; das SDK löscht sie nie.
• Ein Skript, das die Sperre selbst hält und dann wkl-office aufruft, setzt WKL_ACCESS_LOCK_HELD auf den Pfad der Datei; das SDK arbeitet dann unter dieser Sperre, statt auf sie zu warten.
• Solange das SDK die Datei hält, findet Test-Path sie. Lesen kann sie nur ein Programm, das beim Lesen das Löschen der Datei zulässt, in PowerShell [IO.File]::Open($path, 'Open', 'Read', 'ReadWrite, Delete'); Get-Content meldet die Datei als in Verwendung.

Ohne Sperrdatei gilt nichts davon.

wkl-office new <folder> [-n <name>] [--json]

Legt ein leeres Projekt in einem neuen oder leeren Ordner an: <name>.acproj, source/ mit einer leeren references.json, eine .gitignore für build/ und obj/ sowie .vscode/tasks.json. Der Name wird zum Dateinamen der Datenbank und zum Namen ihres VBA-Projekts und muss daher ein gültiger VBA-Bezeichner sein: zuerst ein Buchstabe, dann Buchstaben, Ziffern und _, höchstens 64 Zeichen. Exitcode 1, wenn der Name kein gültiger Bezeichner oder der Ordner nicht leer ist.

Die SDK-Einstellungen unter newProjects bestimmen für ein neues Projekt die Ordner der Quellen, des Builds und der Auslieferung (SourceRoot, BaseOutputPath, DeliveryRoot), die neutrale Sprache, die Bitbreite von Access und die Konfigurationen neben Debug und Release. Nennen die Einstellungen einen Ordner für neue Projekte (newProjects.root), legt wkl-office new Kunden mit einem bloßen Namen das Projekt dort an.

wkl-office check <project.acproj> [-c <name>] [--json]

Liest die Projektdatei und jede Quelle und prüft dann den Rechner. Startet kein Access.

• Quellen: die Projektdatei, references.json, application/properties.json, jedes Tabellenschema (und ob sein Dateiname zur Tabelle passt), die Datendateien von Tabellen mit der Richtlinie SeedData oder FullData Zeile für Zeile, die Beziehungen, die Objektordner (unerwartete Dateien, ein Standard- und ein Klassenmodul desselben Namens), die Seiteneinstellungen von Berichten, die Abschlussfunktion, AppMode und die Platzhalter für WKL-Steuerelemente; hat das Projekt eine Auslieferung, auch delivery-settings.json und jedes Auslieferungsprofil samt dem Modus, den seine Build-Konfiguration setzt (delivery-settings.json).
• Anmeldedaten und Rechnerzustand: jede Objekt-, Daten-, Menüband- und Modelldatei (auch die einer Vorlage), Zeile für Zeile. Ein Kennwort in einem Verbindungstext (PWD= oder Password= mit einem Wert) ist ein Fehler; ein leerer Wert ist keiner, und ein Wert, der mit { beginnt oder an beliebiger Stelle $ enthält, gilt als Platzhalter und wird ebenfalls nicht gemeldet; ein ODBC-Kennwort in geschweiften Klammern (PWD={s3cret}) oder eines mit $ geht daher durch; siehe Ein Kennwort steht in den Quellen. Ein absoluter Pfad in ein Benutzerprofil (C:\Users\<name>\...) ist eine Warnung.
• Rechner: das Access, das COM startet, und seine Bitbreite im Vergleich mit TargetAccess; jeder Verweis im Vergleich mit den registrierten Typbibliotheken (gleiche Hauptversion, gleiche oder höhere Nebenversion, Datei für die Bitbreite von Access vorhanden); jeder ODBC-Treiber, den das Verbindungsprofil der Konfiguration nennt.

Was sich nicht lesen lässt (ein Registrierungsschlüssel ohne Berechtigung), wird als nicht lesbar gemeldet, nie als fehlend. Warnungen halten einen Build nicht auf.

wkl-office build <project.acproj> [-c <name>] [--accde | --no-accde] [--json]

Baut build/<configuration>/<name>.accdb und, wenn die Konfiguration eine vorsieht, <name>.accde. Führt zuerst check aus; findet es einen Fehler, wird nichts erzeugt. Die neue Datenbank entsteht in build/<configuration>/.building/ und ersetzt das vorherige Ergebnis erst, wenn jeder Schritt erfolgreich war; ein fehlgeschlagener Build behält also das letzte gute Ergebnis. ACCDB und ACCDE werden nacheinander verschoben: Ist die vorherige ACCDE geöffnet, hat die neue ACCDB die alte bereits ersetzt, und die neue ACCDE bleibt in .building (Exitcode 5). Liefern Sie nach einem solchen Fehler nicht aus build/<configuration>/ aus; bauen Sie erneut. Die Schritte beschreibt Quellstruktur und Formate.

Lässt sich der VBA-Code nicht kompilieren, nennt der Build die Objekte, die die Kompilierung verhindern (Exitcode 4), ohne einen Dialog anzuzeigen. Ist das vorherige Ergebnis in Access oder einem anderen Programm geöffnet, schlägt der Build mit „Die Datenbank ist geöffnet …“ fehl und behält die neue Datenbank in .building/ (Exitcode 5).

wkl-office rebuild <project.acproj> [-c <name>] [--accde | --no-accde] [--json]

Entfernt die ACCDB, die ACCDE und den Arbeitsordner der Konfiguration und baut dann: Von einem früheren Build bleibt nach einem fehlgeschlagenen nichts übrig. Eine geöffnete Datenbank wird abgelehnt.

wkl-office run <project.acproj> [-c <name>] [--runtime] [--no-build] [--json]

Baut (außer mit --no-build) und öffnet die Datenbank in einem sichtbaren Access, wie es ein Doppelklick täte: Ihr Startformular und ihr Startcode laufen, und dieses Access gehört ab dann dem Entwickler. Mit --runtime startet Access mit /runtime und öffnet die ACCDE, wenn eine gebaut wurde; ohne --runtime erzeugt der Build keine ACCDE. Neben open der einzige Befehl, der ein Fenster anzeigt.

wkl-office open <project.acproj> [-c <name>] [--json]

Diesen Befehl führt ein Doppelklick auf eine Projektdatei im Explorer aus, sobald addin install die Zuordnung eingerichtet hat. open öffnet die zuvor gebaute Datenbank der Konfiguration in einem sichtbaren Access, ohne sie neu zu bauen; in Access gemachte und noch nicht exportierte Änderungen bleiben also erhalten. Nur wenn es diese Datenbank noch nicht gibt (frischer Klon), baut open sie zuerst. Nach einem git pull, der die Quellen geändert hat, führen Sie build oder rebuild selbst aus (exportieren Sie vorher Ihre Änderungen in Access).

Die Datenbank öffnet sich zum Entwickeln, und nichts startet von selbst: Startformular und AutoExec-Makro laufen nicht, und die Starteigenschaften (eigenes Menüband, ausgeblendeter Navigationsbereich, ausgeschaltete Access-Spezialtasten) gelten für diesen Start nicht. Sie sehen also den Navigationsbereich und das Menüband von Access mit der Registerkarte WKL SDK. Dazu entfernt open vor dem Start in einem verborgenen Access die Starteigenschaften und ersetzt AutoExec durch einen Platzhalter, der nur eine TempVar setzt; sobald die Datenbank geöffnet ist, stellt open beides wieder her. AutoExec steht danach unverändert im Navigationsbereich, und Sie können es sofort selbst ausführen. Die üblichen Wege, eine Datenbank in Access zu öffnen, bleiben unverändert: Ein Doppelklick auf die .accdb, Datei › Öffnen und `run` starten Startformular und AutoExec wie gewohnt.

Bis zur Wiederherstellung liegt die Sicherung im Ordner <Datenbank>.wkl-open neben der Datenbank, etwa Kunden.accdb.wkl-open. Endet Access vorher (Absturz, im Task-Manager beendet), bleibt der Ordner liegen, und bis dahin hat die Datenbank den Platzhalter statt Ihres AutoExec und keine Starteigenschaften, auch wenn Sie sie per Doppelklick auf die .accdb öffnen. Der nächste Zugriff des SDK auf diese Datenbank (open, export, sync, Projektwechsel im Add-In) stellt zuerst den ursprünglichen Stand her; so gelangt nie der vorübergehende Stand in die Quellen. Ein Build, der die Datenbank ersetzt, verwirft die Sicherung, weil sie zur alten Datei gehört. Löschen Sie den Ordner nicht von Hand: Er enthält Ihr AutoExec und die Starteigenschaften. Hat Access die Datenbank nach 90 Sekunden noch nicht geöffnet, meldet open eine Warnung und überlässt die Wiederherstellung dem nächsten Zugriff des SDK.

Ein Build führt VBA-Code des Projekts aus, nämlich seine Abschlussfunktion, und zwar in einem verborgenen Access ohne die Sicherheitswarnung, die Access sonst beim Öffnen einer Datenbank zeigt. Ist die Projektdatei als Download aus dem Internet markiert (Mark of the Web; eine per Browser oder Mail empfangene ZIP-Datei gibt die Markierung an die entpackten Dateien weiter), fragt open vor dem Build nach. Bleibt die Antwort aus, auch bei umgeleiteter Standardeingabe, baut open nichts und endet mit Exitcode 8. Ein Klon eines Repositorys trägt keine solche Markierung.

Nach einem Doppelklick bleibt das Konsolenfenster bei einem Fehler offen, bis Sie die Eingabetaste drücken, damit Sie die Meldungen lesen können. Aus einem Terminal gestartet, wartet open nie.

wkl-office validate <project.acproj> [-c <name>] [--json]

Prüft die zuvor gebaute ACCDB: Das VBA-Projekt lässt sich kompilieren, kein Verweis ist defekt, jede Tabelle und jedes Objekt der Quellen ist in der Datenbank vorhanden. Arbeitet mit einer Kopie, deren Starteigenschaften zuerst entfernt werden, sodass weder ein Startformular noch Menübandcode läuft. Eine Datenbank mit einem AutoExec-Makro wird abgelehnt: Das Datenbankmodul kann ein Makro nicht abschalten.

wkl-office accde <project.acproj> [-c <name>] [--json]

Erzeugt die ACCDE aus der zuvor gebauten ACCDB. Access meldet keinen Fehler, wenn es keine erzeugt; der Befehl prüft deshalb anschließend, ob die Datei vorhanden ist, und schlägt andernfalls mit Exitcode 9 fehl. Die Starteigenschaften von AppMode schreibt nur build.

wkl-office export <project.acproj> [-c <name>] [-d <database>] [--changed] [--json]

Schreibt die Datenbank in die Quellen. Eine in Access geöffnete Datenbank wird aus diesem Access exportiert, sonst aus einer Kopie in einem verborgenen Access. Abgelehnt, solange dieses Access einen Dialog anzeigt oder etwas nicht gespeichert ist; jedes betroffene Objekt wird genannt. Eine Datei wird nur neu geschrieben, wenn sich ihr Inhalt geändert hat; Dateien verwalteter Ordner, deren Objekt nicht mehr existiert, werden gelöscht und aufgelistet. Was geschrieben und was ausgelassen wird: Quellstruktur und Formate.

wkl-office import <project.acproj> [-c <name>] [-d <database>] [--changed] [--json]

Lädt die Abfragen, Module, Klassen, Formulare, Berichte und Makros, deren Quelle vom Objekt abweicht, in die in Access geöffnete Datenbank und fügt fehlende Verweise hinzu. Abgelehnt, solange dieses Access einen Dialog anzeigt oder etwas nicht gespeichert ist. Ein zu ersetzendes Objekt muss geschlossen sein. Gelöscht wird nichts; Tabellen, Daten, Beziehungen, Eigenschaften und Modelle werden in einer geöffneten Datenbank nicht geändert. Kompiliert nicht: Verwenden Sie in Access Debuggen › Kompilieren.

wkl-office status <project.acproj> [-c <name>] [-d <database>] [--json]
wkl-office sync   <project.acproj> [object ...] [-c <name>] [-d <database>] [--keep access|source] [--diff] [--json]

Vergleicht jede Abfrage, jedes Modul, jede Klasse, jedes Formular, jeden Bericht und jedes Makro auf beiden Seiten mit dem letzten gemeinsamen Stand, den ein vollständiger export in obj/wkl-state.json schreibt (je Arbeitsplatz, nicht Teil des Repositorys).

status ändert nichts. Nichts, was auf beiden Seiten geändert wurde, wird überschrieben: Solche Objekte beenden den Lauf mit Exitcode 7, bis --keep entscheidet. Objekte, die nach der Projektdatei genannt werden (form:frmKunden, module:basLists, die Schlüssel, die changes --json ausgibt), beschränken sync auf sie: Jedes Objekt wird weiterhin verglichen und aufgelistet, übertragen oder entschieden werden aber nur die genannten; Konflikte lassen sich so einzeln entscheiden. Ein Name, der weder in der Datenbank noch in den Quellen vorkommt, beendet den Lauf mit Exitcode 5 und ändert nichts. Eine Umbenennung wird nur dann als Umbenennung übertragen, wenn genau ein Objekt derselben Art den alten Text hat. Um Änderungen in die Datenbank zu übertragen, muss sie in Access geöffnet sein. Tabellen, Daten, Beziehungen, Verweise, Eigenschaften und Modelle werden nicht Objekt für Objekt verfolgt: Der vollständige export schreibt sie, build erzeugt sie.

wkl-office changes <project.acproj> [-c <name>] [-d <database>] [--json]

Prüft das Projekt sofort und listet in einer Tabelle jedes Objekt und jede Quelldatei auf, die nicht auf demselben Stand sind. Drei Vergleiche werden auseinandergehalten, weil jeder einen anderen Schritt verlangt:

Der nächste Schritt einer Zeile ergibt sich aus den ersten beiden Spalten, in dieser Reihenfolge:

Die erste Zeile nennt den Zeitpunkt der Prüfung. Ist ein Teil der Prüfung fehlgeschlagen (Access hat nicht geantwortet, die Versionsverwaltung hat einen Fehler gemeldet), lautet die erste Zeile NICHT AKTUELL, sie nennt, was fehlgeschlagen ist, und der Exitcode ist 5: Die Liste kann unvollständig sein und bedeutet nie „keine Änderungen“. Die Branch-Zeile verwendet, was der letzte Fetch geliefert hat; changes nimmt keinen Kontakt zum Remote auf.

wkl-office diff <project.acproj> <object | file> [--against access|git] [--part design|code] [-c <name>] [-d <database>] [--json]

Gibt den vollständigen Unterschied (Unified-Format, jede geänderte Zeile mit drei Kontextzeilen) eines Objekts oder einer Quelldatei aus. Nennen Sie das Objekt so, wie changes --json es tut (form:frmKunden, module:basLists), oder die Quelldatei relativ zum Projekt (source/forms/frmKunden.form.txt); das Ende des Pfads genügt, wenn es eindeutig ist.

• --against access vergleicht die Quelle (alt) mit dem Text, den Access jetzt hat (neu): das, was ein Export schreiben würde.
• --against git vergleicht den letzten Commit (alt) mit der Quelldatei (neu): das, was ein Commit festhalten würde.
• --part code behält von einem Formular oder Bericht nur das Modul (ab CodeBehindForm), --part design nur den Rest.

Ohne --against wird ein Objekt, das sich zwischen Access und der Quelle unterscheidet, mit Access verglichen, alles andere mit dem letzten Commit. Gibt kein Unterschied aus, wenn die Texte gleich sind.

wkl-office commit <project.acproj> -m <message> [<file> ...] [-c <name>] [-d <database>] [--json]

Prüft den Stand erneut wie changes und lehnt mit Exitcode 7 ab, ohne etwas zu schreiben, wenn eine Zeile import, entscheiden oder Mergekonflikt lösen verlangt oder die Prüfung fehlgeschlagen ist: Der vollständige Export des Commits würde sonst eine außerhalb von Access geänderte Quelle überschreiben oder einen Merge nur halb committen. Exportiert dann (abgelehnt, solange etwas nicht gespeichert ist), übergibt die Projektdatei, ihre .gitignore und den Quellordner an den Versionsverwaltungsclient im PATH (git oder svn; die nächstgelegene Arbeitskopie oberhalb des Projekts entscheidet) und committet sie. Dateien, die der Export entfernt hat, werden auch in der Versionsverwaltung gelöscht. Andere Dateien der Arbeitskopie werden nicht angetastet, und gepusht wird nicht. Entsprechen die Quellen dem committeten Stand, wird nichts committet.

Dateien, die nach dem Projekt genannt werden (Pfade relativ zum Projektordner, zum Beispiel source/forms/frmKunden.form.txt), committen nur diese: ein Teil-Commit. Prüfung und Export umfassen trotzdem das ganze Projekt; eine Zeile, die import verlangt, blockiert also auch dann, wenn ihre Datei nicht genannt ist; die nicht genannten Dateien bleiben für einen späteren Commit in der Arbeitskopie geändert. Nennen lassen sich nur die Projektdatei, ihre .gitignore und Dateien unterhalb des Quellstammverzeichnisses; jede andere Datei wird mit Exitcode 1 abgelehnt, bevor etwas geschieht. Eine gelöschte Quelle wird wie jede andere Datei genannt und als Löschung committet.

wkl-office push <project.acproj> [--json]

Führt git push für den Branch der Arbeitskopie aus und gibt aus, was git ausgegeben hat. Nie Teil von commit: Die Veröffentlichung bleibt eine eigene Entscheidung. In einer Subversion-Arbeitskopie gibt es nichts zu pushen; der Befehl meldet das.

wkl-office addin install | remove | status [--json]

Registriert das Entwickler-Add-In des SDK für den aktuellen Benutzer (ohne Administrator), entfernt es oder meldet seinen Zustand. install nimmt das Add-In in der Bitbreite des installierten Access aus dem Ordner addin neben dem Ordner bin des SDK oder aus dem Ordner in der Umgebungsvariablen WKL_OFFICE_ADDIN. install kopiert außerdem den Bootstrapper Manager aus dem Ordner bootstrapper-manager neben diesem Add-In-Ordner nach %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager\<version>, sofern diese Version noch nicht installiert ist; remove lässt ihn stehen. Ein Build registriert das Add-In nie; das tut nur dieser Befehl.

install ordnet außerdem Projektdateien (.acproj) für den aktuellen Benutzer dem SDK zu. Ein Doppelklick im Explorer führt `open` aus, und das Menü einer Projektdatei erhält das Untermenü “WKL Office SDK” mit Öffnen, Erstellen und ausführen, Prüfen, Erstellen und Neu erstellen (die Befehle open, run, check, build und rebuild); unter Windows 11 steht es unter “Weitere Optionen anzeigen”. Die Befehle verwenden die wkl-office.exe, mit der Sie installiert haben; die Installation einer neuen Version stellt sie also auf diese um. Windows erlaubt keinem Programm, sich selbst zum Standard zu machen: Beim ersten Doppelklick auf eine .acproj fragt es einmal, mit welcher App sie geöffnet wird; wählen Sie “WKL Office SDK” und “Immer”. Solange Sie noch nicht gewählt haben, weist install darauf hin. Das Untermenü ist vorhanden, gleich welches Programm die Datei öffnet. Projektdateien zeigen das Symbol von Access. Ist .acproj bereits einem anderen Programm zugeordnet, bleibt es dabei, und das SDK steht nur unter “Öffnen mit”. Nach Prüfen, Erstellen und Neu erstellen bleibt das Fenster offen, bis Sie die Eingabetaste drücken, nach Öffnen sowie Erstellen und ausführen nur bei einem Fehler. remove nimmt Zuordnung und Untermenü zurück, status meldet beides (projectFiles und projectFilesChosen in JSON).

install trägt das Add-In außerdem für den VBA-Editor des installierten Office ein, je Benutzer unter HKEY_CURRENT_USER\Software\Microsoft\VBA\VBE\6.0\Addins (bei 64-Bit-Office Addins64), sodass der Editor es beim Öffnen lädt; remove nimmt den Eintrag zurück, status meldet ihn (editorListed und editorLoadBehavior in JSON).

Das Add-In wird beim nächsten Start von Access geladen. Siehe Access-Add-In verwenden.

wkl-office settings list | get <key> | set <key> [<value>] [--json]

Zeigt und ändert die SDK-Einstellungen des aktuellen Benutzers (%APPDATA%\WKL\Office SDK\settings.json), wie es Einstellungen im Add-In tut. list zeigt jede Einstellung, get eine, jeweils mit dem Wert, der gilt, und seiner Herkunft: default, settings oder environment mit dem Namen der Variablen. set schreibt einen Wert; ohne Wert entfernt es den Eintrag, und danach gilt wieder die Vorgabe. Überschreibt eine Umgebungsvariable den geschriebenen Wert, warnt set. Exitcode 1 bei einer unbekannten Einstellung oder einem Wert, der nicht passt, 3, wenn sich die Einstellungsdatei nicht lesen oder schreiben lässt; die Datei bleibt dann, wie sie ist.

wkl-office roundtrip <project.acproj> [-c <name>] [--json]

Kopiert das Projekt in einen temporären Ordner, baut die Kopie, exportiert sie in die Kopie und vergleicht das Ergebnis mit den Quellen. Textdateien werden mit vereinheitlichten Zeilenenden verglichen; bei allen anderen zählt jedes Byte. Jede abweichende Datei wird als changed: <path>:<line>, added: <path> oder removed: <path> aufgelistet, die Kopie bleibt zum Vergleich erhalten, und der Exitcode ist 6. Die Pfade abweichender Dateien sind relativ zum Ordner der Projektdatei (changed: source/forms/frmA.form.txt:3). Führen Sie die Rundlaufprüfung auf Quellen aus, die export geschrieben hat: Der erste Export nach migrate schreibt Dateien einmalig neu. Exitcode 0 zeigt, dass die Quellen stabil sind: Der Export der gebauten Datenbank schreibt genau die Quellen. Er zeigt nicht, dass die Quellen alles enthalten, was die ursprüngliche Datenbank hatte, und auch nicht, dass sich die Anwendung gleich verhält (siehe Was der Export nicht erhält). Die Kopie wird ohne ACCDE und mit dem Verbindungsprofil der Konfiguration gebaut; Warnungen des Exports lassen die Rundlaufprüfung nicht fehlschlagen.

VBA führt für jeden Bezeichner im ganzen Projekt eine einzige Schreibweise, auch über die Module der Vorlage und die Namen der Bibliotheken unter den Verweisen hinweg: Kompiliert die gebaute Datenbank, wird aus Static done As Boolean Static Done As Boolean, wenn Done an anderer Stelle so geschrieben ist. roundtrip meldet dann changed: in einem Modul, das niemand geändert hat. Übernehmen Sie die Schreibweise, die der Export schreibt, oder benennen Sie den Bezeichner um.

wkl-office migrate <old.acproj | access-app.json> -o <folder> [--json]

Wandelt ein Projekt in ein neues Projekt in <folder> um; der Ordner muss leer sein oder darf noch nicht existieren. Jede Einstellung ohne Platz im neuen Projekt wird als Hinweis ausgegeben. Der Befehl startet ein verborgenes Access, um die alten Tabellendefinitionen zu lesen (DATEC) oder die SQL-Skripte auszuführen (Build-Werkzeug). Siehe Projekt des DATEC Access SDK migrieren und Projekt des Build-Werkzeugs der WKL Forms Object Library migrieren.

wkl-office migrate <project.acproj | access-app.json> [--whatif] [--json]

Ohne -o stellt der Befehl das Projekt in seinem Ordner von WKL Forms Object Library 1.x (Typbibliothek WklComponents) auf 2.0 (WklForms) um, ohne Access. Mit Release 2.0 haben Typbibliothek und ProgIDs neue Namen erhalten, die Klassen-IDs sind geblieben. Formulare behalten deshalb ihre Steuerelemente, aber jede Stelle, die die Bibliothek nennt, ändert sich:

• der Verweis in source/references.json (oder in references der access-app.json): Name WklForms, Hauptversion 2, Nebenversion 0;
• der Name WklComponents als ganzes Wort in jeder anderen Textdatei des Projekts: Module, Formulare und Berichte (Class ="WklComponents.TreeView"), Abfragen, Makros, Menübänder, Modelle (aus WklComponents.Texts wird WklForms.Texts);
• packages.components in delivery/delivery-settings.json, wenn es ein Paket von 1.x nennt: das neueste Paket von 2.0 oder höher unter WKL_PACKAGES; ohne ein solches bleibt der Eintrag, mit einem Hinweis.

Dateien behalten Kodierung, Byte Order Mark und Zeilenenden. Nicht geändert, nur in einem Hinweis genannt werden Dokumentation (*.md) und Tabellendaten (source/data). Die Ordner build, out, obj, bin und jeder Ordner, dessen Name mit einem Punkt beginnt (.git, .vs), werden übersprungen. Jede geänderte Datei erscheint als changed: <file> (<count>) mit ihren geänderten Zeilen; --whatif gibt would change: aus und schreibt nichts. Führen Sie den Befehl einmal aus, bauen Sie das Projekt mit registriertem Release 2.0, und committen Sie. Siehe WKL Forms Object Library, „Anwendung auf Release 2.0 umstellen“.

wkl-office deliver <project.acproj> [-p <name>] [--version <x.y.z>] [--dependencies] [--whatif] [--json]

Liefert die Auslieferungsprofile des Projekts (Referenz) nacheinander aus: im Format 2 jede Datei delivery\<name>.profile.json, nach Namen geordnet; im Format 1 jedes Ziel aus delivery\delivery-settings.json, benannt nach seinem Modus. Für jedes Profil baut es die Datenbank in dessen Build-Konfiguration in einem verborgenen Access (eine ACCDE mit den Starteigenschaften des Modus, den die Konfiguration setzt; für Development eine ACCDB) und schreibt dann build\Delivery\<name>:

build\Delivery\production\
  Wkl.Bootstrapper.exe               the starter, from the bootstrapper release named in delivery-settings.json
  bootstrapper.json                  the starter's project file, a copy of delivery\production.bootstrapper.json
  deploy\
    <name>.accde                     the built database
    app-manifest.json                product, version, target, file, SHA-256, size, bitness, runtime, requires, built
    components\x86\, components\x64\  WKL Forms Object Library from its release package, when the project references it
    json\x86\, json\x64\              WKL Office JSON, when the project references it

Einen anderen Auslieferungsordner je Profil legt output in der Profildatei fest (Format 1: targets[].output in delivery-settings.json; absolut, mit Umgebungsvariablen oder relativ zum Projektordner). Der Ordner wird jedes Mal neu geschrieben; ein über output gewählter Ordner wird nur geleert, wenn ihn eine frühere Auslieferung geschrieben hat. Eine fehlende delivery\<name>.bootstrapper.json schreibt der Starter aus seinen Vorlagen (access, components, json); sie bleibt in den Quellen erhalten. Bearbeiten Sie sie mit dem Bootstrapper Manager. Der Starter prüft sie anschließend (/check). requires nennt die Version, die Access beim Build in der Datenbank vermerkt: die höchste auf dem Build-Rechner registrierte Version mit der Hauptversion des Verweises. Jede Angabe nennt außerdem die LIBID der Typbibliothek (guid): Ab WKL Bootstrapper 3.2 erkennt der Starter die Bibliothek daran, ältere Starter übergehen die Angabe. Schlägt ein Profil fehl, bricht der Befehl ab; die folgenden Profile werden weder gebaut noch ausgeliefert. Exitcode 11, wenn die Auslieferung nicht zusammengestellt werden konnte (ein Paket, der Starter oder seine Projektdatei); die Build-Fehler behalten ihre Codes. Siehe Anwendung aus dem SDK ausliefern.

wkl-office msi <project.acproj> -p <name> [--version <x.y.z>] [--sign <thumbprint>] [--json]

Baut das Windows-Installer-Paket eines zuvor ausgelieferten Profils mit tools\New-StarterMsi.ps1 aus dem Release des Bootstrappers: den Starter und seine Projektdatei aus build\Delivery\<name>, die die IT einmal je Computer installiert. Benötigt die Befehlszeile des WiX Toolset (wix) und für --sign das signtool.exe des Windows SDK. Exitcode 11, wenn das Profil nicht ausgeliefert wurde, das Werkzeug fehlt oder es fehlgeschlagen ist; seine Ausgabe wird angezeigt.

wkl-office call <project.acproj | database> <function> [argument ...] [-c <name>] [-t accdb|accde] [--work <folder>] [--timeout <s>] [--json]

Ruft eine öffentliche Funktion eines Standardmoduls der erstellten Datenbank auf und gibt ihren Rückgabewert aus. So kann ein Skript oder ein Testlauf den Code der Anwendung nutzen, ohne sie zu öffnen. Bei einer Projektdatei ist die Datenbank build\<configuration>\<name>.accdb (mit -t accde die .accde); eine Datenbankdatei (.accdb, .accde) wird so verwendet, wie sie angegeben ist. call erstellt nichts: Zuerst build ausführen.

Die Funktion läuft in einem verborgenen Access, in einer Kopie der Datenbank:

• Aus der Kopie werden zuerst die Starteigenschaften entfernt; es startet also weder ein Startformular noch ein Rückruf des Menübands noch ein AutoExec-Makro. Eine Datenbank mit AutoExec-Makro wird abgelehnt (Exitcode 5). Braucht die Funktion die Vorbereitung des Startformulars, ruft sie diesen Code selbst auf.
• Die Datenbank selbst bleibt unverändert. Die Kopie entsteht in einem temporären Ordner und wird danach gelöscht; mit --work <folder> entsteht sie in diesem Ordner und bleibt dort, zusammen mit allem, was die Funktion dort geschrieben hat.
• {work} in einem Argument steht für den vollständigen Pfad des Ordners der Kopie (auch des temporären): wkl-office call app.acproj ExportOrders "{work}\orders.csv" --work out.
• Die Argumente werden als Text übergeben. VBA wandelt sie um, wo die Funktion einen Parameter ByVal ... As Long, ByVal ... As Date usw. deklariert; ein ByRef-Parameter eines anderen Typs als String oder Variant führt dazu, dass Access den Aufruf ablehnt. Höchstens 30 Argumente. Argumente, die mit einem Bindestrich beginnen, stehen nach --: wkl-office call app.acproj Twice -- -5.
• Das SDK übergibt Access keine Umgebungsvariablen. Ob ein so gestartetes Access die des aufrufenden Prozesses sieht, hängt davon ab, wie Windows es startet (unter Windows 11 sieht es sie); eine Funktion darf sich nicht darauf verlassen. Solche Werte als Argumente übergeben.

Der Rückgabewert geht auf die Standardausgabe: Text unverändert, Zahlen mit Dezimalpunkt, True oder False, ein Datum als yyyy-MM-dd (mit THH:mm:ss, wenn es eine Uhrzeit hat), Null für Null, nichts für Empty und die Elemente eines Arrays je auf einer eigenen Zeile.

Dialoge werden ohne Tastatureingabe beantwortet: der VBA-Fehlerdialog mit Beenden, jeder andere Dialog mit Escape und, wenn er offen bleibt, mit Abbrechen, Nein oder OK. Access zeigt einen VBA-Fehlerdialog oder ein Meldungsfenster auch dann auf dem Desktop, wenn es verborgen läuft; es verschwindet nach etwa einer Sekunde. Eine Funktion für call behandelt deshalb ihre Fehler selbst und zeigt keine Dialoge.

wkl-office test <project.acproj> [-c <name>] [-t accdb|accde] [--only <names>] [--timeout <s>] [--work <folder>] [--no-build] [--no-count-guard] [--language <code>] [--json]

Baut die Konfiguration (außer mit --no-build; mit -t accde auch die ACCDE) und führt dann die Testprozeduren der Anwendung in einem verborgenen Access aus, in einer Kopie der Datenbank im Arbeitsordner (Vorgabe build\<configuration>\test). Das Projekt nennt seine Testfunktion in <Test> (Projektdatei); sie gibt die Namen der Testprozeduren zurück. Wie man sie schreibt: Eine Anwendung testen.

Jede Prozedur läuft einzeln, mit dem Zeitlimit von --timeout (Vorgabe 120 Sekunden):

• Ihre Prüfungen (WklTest.Check) werden als OK <procedure>: <check> oder FAIL <procedure>: <check> :: <message> ausgegeben. Eine Prozedur, die ohne eigene Prüfung zurückkehrt, gilt als eine bestandene Zeile.
• Ein Laufzeitfehler, den sie nicht behandelt, ist eine fehlgeschlagene Zeile mit dem Text des VBA-Fehlers; die nächste Prozedur läuft weiter.
• Ein Dialog, der nicht über WklTest.Answer geht, wird wie bei `call` beantwortet und lässt die Prozedur fehlschlagen.
• Überschreitet eine Prozedur ihr Zeitlimit, wird ihr Access beendet; der Lauf hält an.
• Wird Access während einer Prozedur beendet (ein Absturz), hält der Lauf mit „Access ended“ an und nennt die zuletzt geschriebene Zeile.

Im Arbeitsordner bleiben die Kopie, wkl-test-run.jsonl (eine Zeile je Prüfung, sofort geschrieben, sodass die Zeilen vor einem Absturz erhalten bleiben) und wkl-test-report.xml (JUnit-XML für CI-Server, ein Testfall je Prüfung). Eine Summenzeile schließt die Ausgabe ab: <n> OK, <m> FAIL (<k> Testprozeduren).

Anzahl-Wache. Ein Lauf aller Prozeduren mit weniger Prüfungen als der letzte grüne Lauf derselben Konfiguration, desselben Ziels und derselben Sprache schlägt mit der Zeile check count fehl: So fallen Tests auf, die nicht mehr laufen. Die Anzahlen stehen in obj\wkl-test-count.json; --only überspringt die Wache, --no-count-guard schaltet sie ab.

Sprache. --language <code> (jeder Sprachcode wie de oder fr; ein regionaler Code wie sl-SI zählt als seine Sprache) führt die Prozeduren mit den Anwendungstexten und den WKL-Komponenten in dieser Sprache aus, unabhängig von der Sprache von Office: Das SDK setzt WklTexts.Language einmal zu Beginn des Laufs. Das setzt die WKL Forms Object Library 1.65 oder höher voraus, ein anderer Code als en, de, sl, hr und it 1.67 oder höher; mit einem älteren Release hält der Lauf mit Exitcode 2 an.

wkl-office texts export <project.acproj> [<file.csv>] [--language <code>]
wkl-office texts import <project.acproj> [<file.csv> ...] [--replace]

Tauscht die Texte der Anwendung (source/texts/*.json, Format) mit CSV-Dateien aus, die Excel direkt öffnet. Braucht kein Access.

• export schreibt eine Zeile je Schlüssel irgendeiner Sprache mit der Spalte key, danach einer Spalte je vorhandener Sprache, neutral zuerst (key,neutral,de,fr); Standarddatei ist texts.csv neben der Projektdatei. Eine leere Zelle bedeutet “kein Text in dieser Sprache”.
• export --language <code> schreibt stattdessen das Übersetzungspaket einer Sprache (Standard texts.<code>.csv): eine Zeile je Schlüssel der Anwendung mit den Spalten key, source (der neutrale Text, sonst der englische), der Sprache und review (bei einer zur Prüfung markierten Übersetzung die Vorlage, nach der sie entstand). Für neutral gibt es kein Paket.
• import führt eine oder mehrere CSV-Dateien zusammen, Pakete oder vollständige Exporte, in beliebiger Reihenfolge (Standard texts.csv). Geschrieben werden nur die Sprachspalten, source und review nicht. Eine leere Zelle und eine fehlende Zeile ändern nichts, und kein Schlüssel wird entfernt. Ein Schlüssel, den die Anwendung nicht hat, wird mit einer Warnung übergangen; neue Schlüssel kommen nur aus der Spalte neutral (oder en in einem Projekt ohne neutrale Texte). Liefern zwei Dateien für denselben Schlüssel und dieselbe Sprache verschiedene Texte, wird nichts geschrieben. Eine Übersetzung, deren source vom jetzigen neutralen Text abweicht, und jede Übersetzung eines Schlüssels, dessen neutralen Text der Import ändert, wird in source/texts/review.<code>.json zur Prüfung markiert. Je Sprache nennt eine Zeile, wie viele Texte neu, geändert, noch unübersetzt und zur Prüfung markiert sind.
• import --replace <file.csv> nimmt genau eine CSV-Datei als ganzen Bestand: Ein Schlüssel, der in ihr fehlt, wird entfernt. Eine Sprachspalte, die in jeder Zeile leer ist, lässt ihre Datei unverändert. Je Sprache nennt eine Zeile die Zahl der Texte und wie viele neu, geändert und entfernt sind.
• Alle Dateien sind UTF-8; export schreibt eine Bytereihenfolgemarke, Kommas und CR LF, import liest durch Kommas oder Semikolons getrennte Dateien, wie Excel sie in den Regionaleinstellungen von Windows speichert. Jede Textdatei wird in ihrer kanonischen Form geschrieben, nur wenn sich ihr Inhalt ändert.
• Exitcode 2, wenn sich die Textdateien oder eine CSV-Datei nicht lesen lassen (keine Kopfzeile, die mit key beginnt, eine Spalte, die weder Sprachcode noch neutral, source oder review ist, ein Schlüssel zweimal), wenn Dateien einander widersprechen oder wenn die CSV-Datei von --replace weder neutrale noch englische Texte hat. Exitcode 1 für --replace mit mehr als einer Datei.

Codes, die ein Befehl über 0, 1 und 10 hinaus verwendet:

Mit --json gibt ein Befehl statt Text ein JSON-Objekt auf der Standardausgabe aus. Ausnahmen:

• Eine Befehlszeile, die der Parser zurückweist, gibt den Fehler auf der Standardfehlerausgabe aus und kein JSON (Exitcode 1). new und addin mit einer unbekannten Aktion enden ebenfalls mit Exitcode 1, geben aber ihr JSON aus; commit mit einer Datei außerhalb des Projekts gibt eine Zeile error: auf der Standardfehlerausgabe aus, keinen Verwendungstext und kein JSON (Exitcode 1).
• diff --against access gibt Text aus, wenn Access und die Quelle des Objekts auf demselben Stand sind (Exitcode 0) oder die Prüfung fehlgeschlagen ist (Exitcode 2).
• Strg+C gibt nur die Abbruchmeldung auf der Standardfehlerausgabe aus (Exitcode 8).

Die Felder unterscheiden sich je Befehl:

Ohne --json werden Probleme als <severity> [<phase>] <object>, <file>: <cause> ausgegeben; ein leerer Teil entfällt. Mit --format msbuild ist jedes Problem eine Zeile <file>(<line>): <error|warning> WKL<nnn>: <object>: <cause> mit vollständigem Pfad, die Visual Studio Code und andere Editoren an ihrer Stelle auflisten. Die Nummer ist die Phase, dieselbe wie in den MSBuild-Tasks:

• Keine Dialoge. Außer run und open zeigt kein Befehl ein eigenes Fenster an. Access läuft verborgen; ein Dialog, den es während eines Schritts anzeigt, wird mit seinem Text festgehalten und mit Esc abgebrochen, und der Schritt schlägt fehl. Im Access eines Entwicklers (siehe unten) gilt dasselbe für einen Dialog, der sich während des Schritts öffnet; Dialoge, die vorher schon geöffnet waren, bleiben bestehen.
• Zeitlimits. Jeder Schritt hat ein festes, nicht konfigurierbares Limit: 60 Sekunden für die meisten Schritte, 90 für das Übertragen eines Objekts, 120 für Modelle, den Export und das Öffnen einer Kopie, 180 für das Kompilieren und das Erzeugen der ACCDE, 5 Minuten für die Daten einer Tabelle und für die Abschlussfunktion. Zeitlimits und Dialogüberwachung gelten für die Schritte in Access: git und svn laufen wie auf der Befehlszeile ohne Zeitlimit, und eine Abfrage von Anmeldedaten, ein Fenster einer Anmeldeinformationsverwaltung oder ein Hook kann commit oder push anhalten. Richten Sie auf Build-Rechnern eine Authentifizierung ein, die keine Eingabe benötigt. Überschreitet ein Schritt des verborgenen Access sein Limit, wird dieses Access sofort beendet, und der Schritt schlägt fehl. Ein Schritt im Access des Entwicklers wird nicht unterbrochen: Der Lauf wartet, bis Access antwortet, und meldet dann, dass der Schritt länger als sein Limit gedauert hat.
• Kein Access bleibt zurück. Jedes Access, das das SDK startet, wird beendet, wenn der Lauf endet: Es wird zum Beenden aufgefordert und erst nach 30 Sekunden hart beendet (mit Meldung). Wird wkl-office abgebrochen oder stürzt es ab, beendet Windows auch sein Access (über ein Auftragsobjekt; weigert sich Windows, Access ihm hinzuzufügen – was bisher nicht beobachtet wurde –, fehlt dieses Netz). Windows startet Access über COM, und das SDK nimmt es in das Auftragsobjekt auf, sobald Access antwortet, innerhalb etwa einer Sekunde: Wird wkl-office in diesem ersten Moment abgebrochen, läuft sein Access weiter und muss von Hand geschlossen werden. Strg+C fordert das Access des Laufs zum Schließen auf und endet sofort mit Exitcode 8. Ein Access, das ein Entwickler geöffnet hat, wird nie beendet.
• Nach einem unterbrochenen Lauf (Strg+C, ein abgebrochener Prozess, ein Zeitlimit): export hinterlässt die Dateien, die er geschrieben hat, möglicherweise eine davon abgeschnitten, und löscht weder veraltete Dateien noch schreibt er den gemeinsamen Stand; sync schreibt den gemeinsamen Stand erst am Ende, Objekte, die es bereits übertragen hatte, erscheinen daher als auf beiden Seiten geändert; build hinterlässt .building, das der nächste Build entfernt; commit kann Dateien zum Commit vorgemerkt, aber nicht committet hinterlassen; import in das Access des Entwicklers hinterlässt die bis dahin geladenen Objekte. Führen Sie wkl-office changes aus. Nach einem unterbrochenen Export oder einer unterbrochenen Synchronisierung führen Sie einen vollständigen wkl-office export aus, während Access den gewünschten Stand enthält, oder entscheiden die Zeilen mit sync --keep; nach einem unterbrochenen Build bauen Sie erneut; nach einem unterbrochenen Commit prüfen Sie git status und führen commit erneut aus.
• Die in Access geöffnete Datenbank. export, import, status, sync und commit finden das Access, das die Datenbank geöffnet hat, über die Running Object Table anhand des vollständigen Pfads der Datenbank (ohne Berücksichtigung der Groß- und Kleinschreibung) und arbeiten darin. changes und diff suchen ebenfalls dort. Gefunden wird nur ein Access desselben Benutzers (keines, das als Administrator gestartet wurde). Dieses Access wird nie beendet, auch nicht, wenn ein Schritt länger als sein Zeitlimit dauert.
• Terminal-Host. wkl-office terminal-host wird vom Terminal des Add-Ins verwendet und ist nicht für den Aufruf von Hand gedacht.
• Bitbreite. Das Werkzeug automatisiert Access prozessübergreifend (out of process); eine Installation bedient daher 32-Bit- und 64-Bit-Office.

• Überblick
• Referenz der Projektdatei
• Quellstruktur und Formate
• Problembehandlung