Tutorial: Eine Access-Anwendung vom Lieferordner bis zur geprüften Installation

In diesem Tutorial machen Sie aus einer fertigen Access-Anwendung ein Installationspaket und prüfen das Ergebnis mit einer Testinstallation. Sie brauchen dafür keine Kenntnisse über WKL Bootstrapper; was Sie wissen müssen, erklärt das Tutorial an der Stelle, an der Sie es brauchen. Rechnen Sie mit etwa 30 Minuten.

Das Beispiel ist eine Kassenanwendung der (erfundenen) Muster GmbH. Am Anfang liegen drei Dinge vor:

• Kasse.accde – die Anwendung, Version 3.2.0,
• der Ordner bin mit zwei Hilfsbibliotheken (Kasse.Drucker.dll, Kasse.Waage.dll),
• der Ordner Berichte mit einer Berichtsvorlage (Tagesabschluss.pdf).

Am Ende haben Sie das Paket Kasse-1.0.0.msi und wissen, dass es auf einem Rechner das Richtige tut: Die Anwendung landet im Profil des Benutzers, die Berichte in seinen Dokumenten, auf dem Desktop liegt eine Verknüpfung, und Access startet die Kasse.

Bevor Sie beginnen, lohnt ein Blick auf die Arbeitsteilung, denn das Paket enthält nicht die Anwendung selbst:

Daraus folgt: Das MSI-Paket bringt die Projektdatei auf den Rechner, die Anwendung holt sich der Starter selbst. Wie eine neue Version der Kasse ankommt, hängt deshalb davon ab, wo die Version steht – siehe Wie es weitergeht.

• Der WKL Bootstrapper Manager ist eingerichtet und startet; siehe So richten Sie den Bootstrapper Manager ein und starten ihn.
• Ein Release von WKL Bootstrapper mit Wkl.Bootstrapper.exe und tools\New-StarterMsi.ps1.
• Die WiX-Kommandozeile ab Version 6, etwa mit dotnet tool install --global wix.
• Für die Testinstallation ein Testrechner oder eine virtuelle Maschine mit Microsoft Access (oder der Access-Runtime) und einem Konto mit Administratorrechten. Das Paket installiert für alle Benutzer; installieren Sie es nicht zum Ausprobieren auf Ihrem Arbeitsrechner.

Ziel: Alles, was zur Auslieferung gehört, liegt in einem Ordner beisammen.

Vorgehen:

1. Legen Sie den Ordner C:\Lieferung\Kasse an und darin den Unterordner deploy.
2. Kopieren Sie Kasse.accde und die Ordner bin und Berichte nach C:\Lieferung\Kasse\deploy.
3. Kopieren Sie Wkl.Bootstrapper.exe nach C:\Lieferung\Kasse und den Ordner tools des Releases mit New-StarterMsi.ps1 nach C:\Lieferung\Kasse\tools.

Ergebnis:

C:\Lieferung\Kasse\
+- Wkl.Bootstrapper.exe
+- tools\New-StarterMsi.ps1
+- deploy\                      < der Lieferordner
   +- Kasse.accde
   +- bin\Kasse.Drucker.dll
   +- bin\Kasse.Waage.dll
   +- Berichte\Tagesabschluss.pdf

Hintergrund: Der Bootstrapper Manager sucht den Starter neben der Projektdatei, die Sie in Schritt 1 anlegen, und das MSI-Skript im Ordner tools neben dem Starter. In der Praxis liegt der Lieferordner auf einer Freigabe, etwa \\server\Kasse\deploy; für dieses Tutorial genügt ein lokaler Ordner.

Ziel: Es gibt die Projektdatei C:\Lieferung\Kasse\bootstrapper.json, und der Bootstrapper Manager bearbeitet sie.

Vorgehen:

1. Wählen Sie auf der Seite Projekte die Pfeilschaltfläche neben Neu und dann Leeres Projekt.
2. Wählen Sie im Dialogfeld Neue Projektdatei des Starters den Ordner C:\Lieferung\Kasse und übernehmen Sie den vorgeschlagenen Namen bootstrapper.json.
3. Die Meldung Neu nennt, was noch zu tun ist (der Starter formuliert sie englisch): den Lieferordner prüfen, die Version und das Startziel eintragen. Schließen Sie sie mit OK.

Ergebnis: Das Projekt Kasse steht in der Liste und ist gewählt. Die Produktkennung „Kasse“ hat der Bootstrapper Manager vom Namen des Ordners übernommen.

Kontrolle: Wählen Sie Prüfen. Die Seite Probleme öffnet sich und meldet version needs either value or from. Das ist hier richtig: Die Version tragen Sie im nächsten Schritt ein.

Hintergrund: Die Vorlage Access-Anwendung, die Neu ohne Auswahl verwendet, setzt eine Datei app-manifest.json im Lieferordner voraus, die das WKL Office SDK oder das Bauwerkzeug von WKL Access Components schreibt. Eine Anwendung, die ohne diese Werkzeuge entsteht, wie die Kasse hier, beginnt mit Leeres Projekt.

Ziel: Das Projekt kennt Version, Lieferordner und Namen der Anwendung.

Vorgehen:

1. Wählen Sie in der Navigation Projekt > Allgemein und tragen Sie ein:

   

   Feld	Wert	Warum
   (1) Version	3.2.0	Die Version der Kasse. Der Starter legt jede Version in einen eigenen Ordner und erkennt daran eine neue Lieferung
   (2) Quelle	C:\Lieferung\Kasse\deploy	Der Lieferordner. Im Betrieb die Freigabe, etwa \\server\Kasse\deploy

   Produkt bleibt Kasse. Die übrigen Felder bleiben leer; dann gelten die Vorgaben des Starters, unter anderem der Installationsort %LOCALAPPDATA%\WKL\Kasse im Profil des Benutzers.

2. Wählen Sie Darstellung und tragen Sie ein: Name Kassensystem, Herausgeber Muster GmbH, Text beim Einrichten Das Kassensystem wird eingerichtet, Sprache de.

Ergebnis: Oben rechts steht Nicht gespeichert; die Änderungen sind im Bootstrapper Manager, aber noch nicht in der Projektdatei.

Kontrolle: Wählen Sie auf Projekte den Befehl Vorschau. Der Bootstrapper Manager speichert das Projekt und zeigt ein Bild des Fensters, das der Benutzer beim Einrichten sieht, mit dem Namen „Kassensystem“ und dem Herausgeber „Muster GmbH“.

Das Logo zeigt die Abbildung, weil das Beispiel der übrigen Seiten zusätzlich eine Datei logo.png einträgt (Feld Logo); ohne Logo bleibt die Fläche leer. Die Zeile unter dem Text und der Fortschritt sind Beispiele des Starters.

Hintergrund – warum ein vollständiger Pfad als Quelle: Ein relativer Pfad wie deploy gilt ab dem Ordner des Starters. Das passt, solange der Starter in C:\Lieferung\Kasse liegt. Nach der Installation durch das MSI-Paket liegt er aber in C:\Program Files (x86)\WKL\Kasse, und dort gibt es keinen Ordner deploy. Für ein Projekt, das Sie als MSI-Paket ausliefern, tragen Sie deshalb immer einen vollständigen Pfad oder eine Freigabe ein.

Hintergrund – die Produktkennung: Nach dem Wert von Produkt benennt der Starter den Ordner der Anwendung im Profil und ihren Eintrag bei den Apps von Windows. Ändern Sie ihn nach der ersten Auslieferung nicht mehr; eine neue Produktkennung ist für Windows eine andere Anwendung. Was der Benutzer sieht, ist der Name von der Seite Darstellung.

Ziel: Das Projekt nennt jede Datei, die der Starter installieren soll.

Vorgehen:

1. Wählen Sie Installation > Dateien.
2. Wählen Sie Dateien hinzufügen. Das Dialogfeld zeigt den Lieferordner. Wählen Sie Kasse.accde.
3. Wählen Sie Ordner hinzufügen und dann den Ordner bin.
4. Wählen Sie noch einmal Ordner hinzufügen und dann den Ordner Berichte.

Statt der Befehle können Sie die Dateien und Ordner auch aus dem Explorer auf die Liste ziehen.

Ergebnis: Die Liste hat drei Zeilen. Der Bootstrapper Manager hat für jede die Quelle relativ zum Lieferordner eingetragen und als Ziel denselben Unterordner unter [VersionDir]:

Kontrolle: Der Zielbaum links zeigt unter [VersionDir] die Unterordner bin und Berichte.

Hintergrund: Nur was in dieser Liste steht, kommt beim Benutzer an, auch wenn weitere Dateien im Lieferordner liegen. Ein Ordner bringt alles mit, was darunter liegt. [VersionDir] ist ein Platzhalter: Auf dem Rechner des Benutzers ersetzt der Starter ihn durch den Ordner der Version, %LOCALAPPDATA%\WKL\Kasse\Frontends\3.2.0.

Ziel: Die Berichte landen dort, wo der Benutzer sie findet, und der Starter installiert nur, wenn Access vorhanden ist.

Vorgehen:

1. Ändern Sie auf der Seite Dateien in der Zeile Berichte das Ziel in [Documents]\Kassensystem\Berichte.
2. Wählen Sie Installation > Bedingungen und tragen Sie in der letzten Zeile unter Art access ein. Wert und Erwartet bleiben leer.

Ergebnis: Der Zielbaum zeigt Berichte jetzt unter [Documents], und die Liste Bedingungen hat eine Zeile mit der Art access:

Kontrolle: Erst in Schritt 6, mit dem Probelauf, der jede Zeile des Plans mit dem tatsächlichen Pfad zeigt.

Hintergrund: Der Ordner der Version ist für die Anwendung da: Kommt Version 3.3.0, legt der Starter einen neuen Ordner an und entfernt alte Versionen nach und nach. Dateien, die der Benutzer selbst öffnet, gehören deshalb in einen festen Ordner wie [Documents] (die Dokumente des Benutzers). Eine Bedingung prüft der Starter vor jeder Installation; die Bedingung access ohne Wert verlangt irgendein Access, mit dem Wert full ein vollständiges Access statt der Runtime. Ist sie nicht erfüllt, installiert der Starter nichts und meldet, was fehlt.

Ziel: Auf dem Desktop des Benutzers liegt eine Verknüpfung, und der Starter öffnet am Ende Kasse.accde.

Vorgehen:

1. Wählen Sie Installation > Verknüpfungen und tragen Sie in der letzten Zeile ein: Ordner [Desktop], Name Kassensystem, Ziel [Starter].
2. Wählen Sie Projekt > Startziel und tragen Sie ein: Datei oder Programm [VersionDir]\Kasse.accde, Access: /runtime auto.

Ergebnis: Die Liste Verknüpfungen hat eine Zeile, die Seite Startziel nennt die Kasse.

Hintergrund: Als Ziel steht [Starter] und nicht Kasse.accde: Nur ein Start über den Starter prüft, ob eine neue Version vorliegt, und installiert sie. Eine Verknüpfung direkt auf die Datei würde den Benutzer dauerhaft bei der Version festhalten, die er zuerst bekommen hat. /runtime auto öffnet eine ACCDE in der Laufzeitumgebung, also ohne Entwurfsansicht und ohne Menüband von Access. Den Eintrag im Startmenü legt das MSI-Paket an; die Desktop-Verknüpfung legt der Starter beim ersten Start für jeden Benutzer an.

Ziel: Der Starter hält die Projektdatei für gültig, und ein Start würde auf diesem Rechner gelingen.

Vorgehen:

1. Drücken Sie Strg+S. Unten rechts erscheint „Gespeichert in bootstrapper.json“, Nicht gespeichert verschwindet.
2. Wählen Sie auf Projekte den Befehl Prüfen.
3. Wählen Sie Probelauf.

Ergebnis: Prüfen zeigt unten rechts diese Benachrichtigung:

Die Meldung Probelauf beginnt mit 0 Ok und listet den Plan, mit den Pfaden Ihres Kontos:

0 Ok
version 3.2.0 (x86) into C:\Users\<Konto>\AppData\Local\WKL\Kasse\Frontends\3.2.0
1 file(s) into C:\Users\<Konto>\AppData\Local\WKL\Kasse\Frontends\3.2.0
  C:\Lieferung\Kasse\deploy\Kasse.accde -> C:\Users\<Konto>\AppData\Local\WKL\Kasse\Frontends\3.2.0\Kasse.accde
2 file(s) into C:\Users\<Konto>\AppData\Local\WKL\Kasse\Frontends\3.2.0\bin
  ...
1 file(s) into C:\Users\<Konto>\Documents\Kassensystem\Berichte
  ...
shortcut C:\Users\<Konto>\Desktop\Kassensystem.lnk
start C:\Users\<Konto>\AppData\Local\WKL\Kasse\Frontends\3.2.0\Kasse.accde

Kontrolle: Vergleichen Sie den Plan mit den Schritten 3 bis 5: drei Einträge, die Berichte unter Documents, die Verknüpfung auf dem Desktop, gestartet wird Kasse.accde. Der Probelauf ändert nichts auf dem Rechner.

Wenn etwas gemeldet wird: Prüfen öffnet die Seite Probleme mit einer Zeile je Problem, im Wortlaut des Starters (englisch). Ein Doppelklick auf die Zeile öffnet die Seite und markiert das Feld oder die Zeile, die zu ändern ist. Ändern Sie den Wert, speichern Sie und wählen Sie erneut Prüfen. Beginnt die Meldung des Probelaufs nicht mit 0, nennt sie Code und Ursache, etwa einen fehlenden Lieferordner; die Codes beschreibt Fehlercodes des Starters (Dokumentation von WKL Bootstrapper). Einzelheiten: So prüfen Sie ein Projekt und beheben Probleme.

Ziel: Es gibt das Paket Kasse-1.0.0.msi, und eine Installation auf einem Testrechner liefert das erwartete Ergebnis.

Paket erstellen:

1. Wählen Sie auf Projekte den Befehl MSI erstellen.

2. Übernehmen Sie im Dialogfeld MSI erstellen die Version 1.0.0 mit OK.

   

   Die Paketversion ist nicht die Version der Kasse: Sie zählt die Pakete, die die IT verteilt, und beginnt bei 1.0.0.

Ergebnis: Nach einigen Sekunden nennt die Meldung das Paket:

Kontrolle des Inhalts (ohne Installation, ohne Administratorrechte):

msiexec /a C:\Lieferung\Kasse\Kasse-1.0.0.msi /qn TARGETDIR=C:\Lieferung\msi-inhalt

Unter C:\Lieferung\msi-inhalt\PFiles\WKL\Kasse liegen genau Wkl.Bootstrapper.exe und bootstrapper.json. Die Anwendung ist nicht im Paket – sie kommt beim Start aus dem Lieferordner.

Testinstallation:

1. Stellen Sie sicher, dass der Testrechner den Lieferordner erreicht. Für dieses Tutorial kopieren Sie C:\Lieferung\Kasse\deploy an denselben Ort auf dem Testrechner; im Betrieb ist das die Freigabe.

2. Installieren Sie das Paket als Administrator:

   msiexec /i Kasse-1.0.0.msi

3. Melden Sie sich als normaler Benutzer an und starten Sie Kassensystem aus dem Startmenü.

Ergebnis: Für einen Moment erscheint das Fenster des Starters mit „Das Kassensystem wird eingerichtet“, dann öffnet Access die Kasse.

Kontrolle:

Unter Installierte Apps stehen danach zwei Einträge namens „Kassensystem“: das MSI-Paket (der Starter, für alle Benutzer, Version 1.0.0) und die Anwendung im Profil dieses Benutzers (Version 3.2.0). Was jeder der beiden entfernt, beschreibt Starter per MSI verteilen (Dokumentation von WKL Bootstrapper).

Testinstallation zurücknehmen: Deinstallieren Sie zuerst als Benutzer den Eintrag mit der Version 3.2.0; der Starter entfernt dann die Version, die Berichte, die Verknüpfung und den Eintrag. Das Protokoll im Ordner Logs bleibt liegen. Deinstallieren Sie danach als Administrator das MSI-Paket (msiexec /x Kasse-1.0.0.msi).

• Neue Version der Kasse: In diesem Tutorial steht die Version fest in der Projektdatei (Feld Version). Für Version 3.3.0 legen Sie die neue Kasse.accde in den Lieferordner, tragen 3.3.0 ein und erstellen ein neues MSI-Paket mit höherer Paketversion, etwa 1.1.0, denn die Rechner lesen die Projektdatei aus dem Paket. Ohne neues Paket kommt eine neue Version an, wenn der Starter sie aus der Lieferung liest: Das WKL Office SDK und das Bauwerkzeug der WKL Forms Object Library schreiben dazu neben die Anwendung eine Datei app-manifest.json, und das Projekt nennt sie im Feld Version aus Datei (die Vorlage Access-Anwendung richtet das ein). Dann genügt es, den Lieferordner auszutauschen; siehe So stellen Sie Produkt, Version, Darstellung und Startziel ein.
• Anwendung aus dem WKL Office SDK: Entsteht die Anwendung mit dem SDK, stellt wkl-office deliver den Lieferordner mit Manifest und die Projektdatei des Starters zusammen; den Bootstrapper Manager öffnet das SDK dann mit dieser Datei. Siehe Anwendung aus dem SDK ausliefern (Dokumentation des WKL Office SDK).
• Paket für die IT: signieren und verteilen beschreibt Starter per MSI verteilen (Dokumentation von WKL Bootstrapper).
• Weitere Einträge wie Registrierungswerte oder Dateitypen: So richten Sie Verknüpfungen, Registrierungswerte und weitere Einträge ein.

• So legen Sie fest, welche Dateien wohin kommen
• So testen Sie ein Projekt vorab und erstellen das MSI-Paket
• Die Projektdatei (Format 2) (Dokumentation von WKL Bootstrapper) – jedes Feld der Projektdatei