Quellstruktur und Formate

<name>.acproj
source/
  queries/<name>.query.txt   modules/<name>.bas        classes/<name>.cls
  forms/<name>.form.txt      reports/<name>.report.txt macros/<name>.macro.txt
                             reports/<name>.print.json
  tables/<name>.table.json   data/<name>.jsonl         relations/relations.json
                             data/<name>.files/<key>/...
  references.json            application/properties.json
  themes/<name>/...          resources/images/<name>.png
  ribbons/<name>.xml         ribbons/ribbon.json       navigation/navpane.json
  application/app-model.json (+ its icon)
  texts/<lang>.json          texts/terms.<lang>.json
build/<configuration>/       (results, not sources)
obj/wkl-state.json           (change tracking, per workstation, not sources)

Jeder Teil einer Access-Anwendung hat ohne weitere Angabe unterhalb des Quellstammverzeichnisses einen festen Platz, derselbe für Export, Build, Prüfungen und Änderungsverfolgung. Quellelemente der Projektdatei legen eine Art von Quellen an einen anderen Ort (Projektdatei: Quellelemente). Jede Quelldatei ist UTF-8-codiert. Objektnamen mit Zeichen, die in Dateinamen nicht zulässig sind, werden codiert (%2F …).

tables/<table>.table.json ist ein einzelnes Objekt; jeder andere Schlüssel wird abgelehnt:

{
  "version": 1,
  "name": "tblKunde",
  "fields": [
    { "name": "Id", "type": "Long", "autoNumber": true },
    { "name": "Name", "type": "Text", "size": 80, "required": true, "allowZeroLength": true },
    { "name": "Credit", "type": "Decimal", "precision": 12, "scale": 2 },
    { "name": "Active", "type": "Boolean", "properties": { "DisplayControl": "106" } }
  ],
  "indexes": [
    { "name": "PrimaryKey", "fields": [ "Id" ], "primary": true },
    { "name": "ByName", "fields": [ "Name", { "name": "Id", "descending": true } ], "unique": true }
  ]
}

Ein Index besteht aus name, fields (ein Feldname für aufsteigende Reihenfolge oder { "name": ..., "descending": true }) und den Kennzeichen primary, unique (bei einem Primärschlüssel weggelassen, der ohnehin eindeutig ist) und ignoreNulls, jeweils standardmäßig false.

Jeder Eintrag von fields ist ein Objekt mit diesen Schlüsseln; ein Schlüssel mit seinem Standardwert wird weggelassen.

Nachschlageeigenschaften haben keine eigenen Schlüssel; sie stehen unter properties mit dem Namen, den Access verwendet, und dem Wert als Text. Ein Ja/Nein-Feld, das Access in den Datenblättern von Tabellen und Abfragen als Kontrollkästchen anzeigt:

{ "name": "Assigned", "type": "Boolean", "properties": { "DisplayControl": "106" } }

DisplayControl nimmt die Nummer des Access-Steuerelementtyps an (106 Kontrollkästchen, 109 Textfeld, 110 Listenfeld, 111 Kombinationsfeld). Ein Schlüssel displayControl neben type wird als unbekannt abgelehnt.

Die Migrationen setzen allowZeroLength für jedes Textfeld der übernommenen Tabellen auf true (DATEC SDK, Build-Werkzeug der WKL Forms Object Library), weil die alten Builds Felder erzeugten, die leere Texte akzeptieren.

Ein JSON-Objekt je Datensatz, die Schlüssel in der Reihenfolge des Tabellenschemas, die Datensätze nach dem Primärschlüssel sortiert. Jedes Feld des Schemas muss in jedem Datensatz vorkommen; ein fehlendes Feld ist ein Fehler. Jeder Wert trägt seinen Typ, ohne von den Ländereinstellungen des Rechners abzuhängen:

Nicht-ASCII-Zeichen werden unverändert (UTF-8) geschrieben, nicht als Escapesequenzen. Lange Binärdaten (OLE-Objekt) und Anlagen sind eigene Dateien, ein Ordner je Datensatz, benannt nach seinem Primärschlüssel: data/<table>.files/<key>/<field>.bin und data/<table>.files/<key>/<field>/<file name>. Eine Anlagedatei enthält genau die Bytes der angefügten Datei. Ein mehrwertiges Feld ist ein Array seiner Werte, sortiert, weil Access sie als Menge führt. Eine Tabelle ohne Primärschlüssel verwendet die Position des Datensatzes (row000001), die sich verschiebt, wenn davor Datensätze eingefügt werden. Eine Datendatei kann keine Datei außerhalb des Datenordners benennen.

references.json ist ein Array in der Prioritätsreihenfolge des VBA-Projekts; jeder Eintrag hat genau name, guid (in geschweiften Klammern, Großbuchstaben), major und minor (die Version, die die Anwendung benötigt):

[ { "name": "WklForms", "guid": "{A37D549E-FCD0-48EC-8B14-C7323B747E4F}", "major": 2, "minor": 0 } ]

Der Bau legt jeden Verweis mit dieser Version an. Access trägt die höchste auf dem Bau-PC registrierte Version der Typbibliothek mit demselben major ein: Mit registrierter WKL Forms Object Library 2.3 ergibt "minor": 0 in ACCDB und ACCDE einen Verweis auf 2.3. export behält das minor der Quellen, solange die Datenbank dasselbe major und kein niedrigeres minor führt; sonst schreibt er die Version der Datenbank. So nennt references.json weiter, was die Anwendung braucht, während die gebaute Datenbank die Version braucht, die auf dem Bau-PC registriert war.

application/properties.json ist ein nach Namen sortiertes Array; jeder Eintrag hat name, value (immer eine Zeichenfolge) und bei jedem Typ außer Text type mit dem Namen des DAO-Eigenschaftstyps (Boolean, Byte, Integer, Long, …):

[ { "name": "AppTitle", "value": "Kunden" }, { "name": "AllowBypassKey", "value": "False", "type": "Boolean" } ]

relations/relations.json ist ein Objekt mit version (1) und relations, nach Namen sortiert; jede Beziehung hat name, table (die Primärtabelle), foreignTable, fields (Paare aus field und foreignField) und attributes, die Namen der gesetzten DAO-Beziehungskennzeichen (Unique, DontEnforce, Inherited, UpdateCascade, DeleteCascade, Left, Right); eine leere Liste ist eine Beziehung mit referenzieller Integrität ohne Weitergabe.

In allen drei Dateien wird jeder andere Schlüssel abgelehnt.

Die Texte, die eine Anwendung über WklTexts der WKL Forms Object Library (1.67 oder höher) zeigt – Meldungen, Beschriftungen, Rückfragen –, liegen als eine Datei je Sprache in texts/. neutral.json enthält sie in der Sprache, in der die Anwendung geschrieben ist; zur Laufzeit zeigt ein Schlüssel ohne Text in der Sprache der Sitzung den neutralen Text, danach den englischen. <code>.json enthält eine Übersetzung, für jeden Sprachcode aus zwei oder drei Buchstaben (de.json, fr.json, pl.json). neutral.json oder en.json ist Pflicht, sobald es eine Textdatei gibt; die erste vorhandene ist die Vorlage der Prüfungen. Jede Datei ist ein flaches JSON-Objekt aus Schlüssel und Text, die Schlüssel ordinal sortiert, UTF-8 ohne Bytereihenfolgemarke:

{
  "orders.count": "{0} orders",
  "orders.title": "Orders"
}

• Schlüssel sind klein geschrieben und nach Formular oder Thema gegliedert (orders.title); sie werden ohne Rücksicht auf Groß- und Kleinschreibung verglichen, ein Schlüssel zweimal in einer Datei hält den Build an. Schlüssel, die mit wkl. beginnen, sind die Standardtexte der Komponenten und lassen sich von der Anwendung nicht festlegen.
• Platzhalter {0}, {1:N2} werden aus den Argumenten von WklTexts.Text gefüllt.
• Der Build schreibt die Texte in die erzeugte Tabelle USysWklTexts (ID, TextKey, Language, TextValue) der ACCDB und der ACCDE; der Export schreibt die Tabelle nie zurück. Eine Tabelle USysWklTexts in tables/ neben Textdateien hält den Build an.
• Die neutrale Sprache (optional): Die Projekteigenschaft NeutralLanguage (Projektdatei) nennt die Sprache von neutral.json, zum Beispiel sl. Diese Sprache braucht dann keine eigene Datei, und Schlüssel, die in ihr fehlen, werden nicht gemeldet.
• Prüfungen (Warnungen, der Build läuft weiter): Schlüssel der Vorlage, die in einer anderen Sprache fehlen, Schlüssel ohne neutralen oder englischen Text, Übersetzungen mit anderen Platzhaltern als in der Vorlage, Schlüssel, die der VBA-Code ohne neutralen oder englischen Text verlangt, zur Prüfung markierte Übersetzungen und Textdateien einer Sprache, die außerhalb von texts/ liegen (der Build liest sie nicht; es zählen nur Dateien namens neutral oder nach einem Code nach ISO 639-1, die ein Objekt aus Texten enthalten, und Ordner, deren Name mit einem Punkt beginnt, werden nicht durchsucht).
• Schlüssel, die der Code verlangt, werden in Modulen, Klassenmodulen, Formularen und Berichten in zwei Formen gefunden: .Text("a.b") an einem beliebigen Objekt (WklTexts oder einer Hilfsfunktion der Anwendung wie Tx.Text("a.b", n)) und Text("a.b") oder Texts("a.b") (das Standardmitglied), in beliebiger Schreibweise. Es zählt nur ein wörtlicher Schlüssel mit mindestens einem Punkt; ein zur Laufzeit gebildeter Schlüssel (texts.Text(prefix & ".title")) wird nicht geprüft. Kommentare werden übersprungen: ein Apostroph außerhalb einer Zeichenfolge, Rem und Kommentarzeilen, die mit _ fortgesetzt werden.
• Terminologie (optional): texts/terms.<lang>.json ordnet einem bevorzugten Begriff Varianten zu, die nicht verwendet werden sollen, { "podatkovna zbirka": [ "zbirka podatkov" ] }; ein Text mit einer Variante ist eine Warnung.
• Prüfmarken: texts/review.<code>.json ordnet einem Schlüssel den neutralen (oder englischen) Text zu, nach dem seine Übersetzung entstand, wenn sich dieser Text inzwischen geändert hat. texts import schreibt und entfernt die Marken; jede ist eine Warnung, bis eine Übersetzung des aktuellen Texts zurückkommt.
• Für Übersetzer schreibt wkl-office texts export --language <code> das Übersetzungspaket einer Sprache, und texts import führt beliebig viele zurückgekommene Pakete auf einmal zusammen (Befehlszeile).

SaveAsText schreibt den Drucker eines Berichts als Binärblöcke (PrtMip, PrtDevMode, PrtDevNames und ihre W-Formen). Sie enthalten Name, Treiber und private Treiberdaten des Druckers auf dem Rechner, der den Bericht gespeichert hat, und unterscheiden sich auf jedem Rechner; Access liest einen gekürzten Block mit unbrauchbaren Zeichen im Geräte- und Formularnamen, daher lassen sie sich nicht bereinigen. Der Export lässt sie aus dem Text des Berichts weg und schreibt die Seiteneinstellungen daneben:

{
  "useDefaultPrinter": true,
  "orientation": 2,
  "paperSize": 11,
  "leftMargin": 1440,
  "topMargin": 1440,
  "rightMargin": 1440,
  "bottomMargin": 1440,
  "itemsAcross": 2,
  "columnSpacing": 360,
  "rowSpacing": 0,
  "defaultSize": true,
  "itemSizeWidth": 0,
  "itemSizeHeight": 0,
  "itemLayout": 1953,
  "dataOnly": false
}

Die Werte sind die des Printer-Objekts von Access: Ränder, Abstände und Elementgröße in Twips (1440 je Zoll); orientation 1 Hochformat, 2 Querformat; paperSize als AcPrintPaperSize (9 A4, 11 A5, 1 Letter); itemLayout 1953 erst quer, dann nach unten, 1954 erst nach unten, dann quer. Der Build setzt sie über das Printer-Objekt des Berichts. Der Name eines bestimmten Druckers wird nicht erhalten, weil er zu einem Rechner gehört. Mit "useDefaultPrinter": true druckt der Bericht auf dem jeweiligen Standarddrucker; mit false speichert der Build ihn mit einem festen Drucker, nämlich dem Standarddrucker des bauenden Rechners. Ein Bericht ohne diese Datei wird mit den Standardwerten von Access gebaut. check meldet ungültiges JSON als Fehler und eine .print.json ohne ihren Bericht als Warnung.

1. check (Quellen und Rechner); findet es einen Fehler, wird nichts erzeugt.
2. Eine neue Datenbank unter ihrem endgültigen Namen in build/<configuration>/.building/, die erst dann nach build/<configuration>/ verschoben wird, wenn jeder Schritt erfolgreich war.
3. Verweise in der Reihenfolge von references.json, Datenbankeigenschaften mit ihren Typen, Tabellen mit Indizes, die Daten der Tabellen mit SeedData und FullData, die Anwendungstexte (USysWklTexts), Beziehungen.
4. Das Design (die Datenbank wird erneut geöffnet, weil Access ein Design nur an danach erstellte Formulare vergibt), gemeinsam genutzte Bilder, von Hand geschriebene Menübänder, das Menübandmodell mit seinem Callback-Modul.
5. Abfragen, Standardmodule, Klassenmodule, Formulare (Platzhalter ersetzt), Berichte (Seiteneinstellungen angewendet), Makros.
6. Zuordnungen der Kontextmenüs, das Modell des Navigationsbereichs, die Starteigenschaften, das Anwendungsmodell, die Verknüpfungen des Verbindungsprofils der Konfiguration, die Abschlussfunktion.
7. Kompilieren und prüfen: Das VBA-Projekt lässt sich kompilieren, kein Verweis ist defekt, jede Tabelle und jedes Objekt der Quellen ist in der Datenbank vorhanden.
8. Die ACCDE, wenn die Konfiguration eine vorsieht, mit den Starteigenschaften von AppMode.

Die Modelle wendet die WKL Forms Object Library selbst an (über ihre Methoden Save und Apply), und zwar über ein Hilfsmodul, das nur während des Builds in der Datenbank existiert.

• Tabellen: das Schema jeder lokalen Tabelle (keine System-, temporären oder verknüpften Tabellen; zu verknüpften Tabellen gibt es keine Warnung) und die Daten der Tabellen mit der Richtlinie SeedData oder FullData; Ignore lässt die Tabelle aus. Der Datenblattzustand des Benutzers (Spaltenbreiten und -reihenfolge, Sortierung, Filter, Schriftarten) wird ausgelassen. Eine Tabellen- oder Feldeigenschaft, die weder auf der Liste der Quelleigenschaften steht noch als Benutzerzustand bekannt ist, wird nicht exportiert: Der Export meldet sie als Warnung („Die Eigenschaft ist noch keine Quelle und wurde nicht exportiert“), und eine aus den Quellen gebaute Datenbank hat sie nicht. Dasselbe gilt für eine Datenbankeigenschaft eines DAO-Typs, den properties.json nicht aufnehmen kann. Diese Warnungen lassen weder Export noch Build noch Rundlaufprüfung fehlschlagen; behandeln Sie jede als Verlust, der zu melden ist.
• Kennwörter (PWD, Password) in den Parametern der Verbindungszeilen des Linked Tables Managers werden entfernt, jedes mit einer Warnung.
• Verweise: Ein Verweis behält die Version, die references.json bereits verlangt, wenn die Datenbank dieselbe Hauptversion und eine nicht ältere Version bindet. Access bindet einen Verweis an die auf dem Rechner registrierte Version; deren Nummer zu übernehmen, würde die Anforderung mit jeder Aktualisierung des Build-Rechners anheben.
• Datenbankeigenschaften: Werte des Datenbankmoduls, Benutzerzustand des Navigationsbereichs, Standardwerte jeder neuen Datenbank sowie Werte, die zum Design gehören oder von einem Modell gesetzt werden, werden ausgelassen.
• Design: das Design, das die Datenbank nennt (nicht „Office“, das jede Datenbank hat).
• Modelle: Die Modelldateien sind die einzige Quelle; die Tabellen, die sie enthalten (USysWklApp, USysWklNavPane, USysWklRibbon, USysRibbons), werden nicht als Tabellen exportiert, ebenso wenig USysWklTexts, das der Build aus den Textdateien schreibt. USysWklLayout (die Anordnung, die jeder Benutzer gewählt hat) und das generierte Modul basWklRibbon sind ebenfalls keine Quellen.

Eine Datei wird nur neu geschrieben, wenn sich ihr Inhalt geändert hat. Dateien der verwalteten Ordner, deren Objekt nicht mehr existiert, werden gelöscht und aufgelistet; andere Dateien (eine README neben den Formularen) bleiben erhalten. Nach einem Fehler wird nichts gelöscht.

Der erste Export nach migrate schreibt Formulare und Module einmalig so neu, wie Access sie schreibt: VBA schreibt jeden Bezeichner im ganzen Projekt gleich, und Access ergänzt Formulareigenschaften wie PublishOption. Ab dann schreibt ein build mit anschließendem export keine Datei mehr.

Werte, die wie Rauschen aussehen, aber Zustand des Objekts sind, bleiben erhalten: LayoutCached* (Access schreibt sie nach dem Laden nicht erneut) und PublishOption (Access schreibt wieder denselben Wert).

OleData eines ActiveX-Steuerelements (seine gespeicherten Eigenschaften) ist ein OLE-Speicher und bleibt bis auf seine beiden Zeitstempel Byte für Byte erhalten; diese setzt der Export auf 0 (siehe Tabelle). Ein Formular, das aus seinem Text neu erzeugt wird, ergibt so beim nächsten Export denselben Text. Access lädt einen solchen Text ohne Fehler, behält die Eigenschaften des Steuerelements und gibt die Nullen beim nächsten Export unverändert aus.

Neben den oben genannten Werten, die der Export bewusst entfernt, gelangen diese Teile einer Access-Anwendung nie in die Quellen. Eine aus den Quellen gebaute Datenbank hat sie nicht, und roundtrip kann ihr Fehlen nicht bemerken.

• Öffnen Sie eine gebaute Datenbank mit Startformular nicht aus einem Skript über OpenCurrentDatabase, um sie anzusehen: Das Startformular läuft, selbst wenn AutomationSecurity Makros deaktiviert. Lesen Sie sie mit DBEngine.OpenDatabase.
• Ein mehrwertiges Textfeld hat in den Quellen keine Größe: DAO meldet 4 (die Breite seines Schlüssels), und seine Werte fassen 255 Zeichen, gleich mit welcher Größe es angelegt wurde.

• Projektordner – welche Datei wo liegt und was versioniert wird
• Referenz der Projektdatei
• Befehlszeilenreferenz