Anwendung aus dem SDK ausliefern

Sie stellen die Auslieferung einer Access-Anwendung aus ihren Quellen zusammen, sodass ihre Benutzer sie über den WKL Bootstrapper erhalten: die Datenbank jedes Auslieferungsprofils mit ihrem Manifest, die benötigten WKL-Bibliotheken und den Starter.

Voraussetzungen: das WKL Office SDK ab 0.3.0 sowie auf dem Build-Rechner die Release-Pakete der WKL Forms Object Library (und von WKL Office JSON, wenn das Projekt darauf verweist) und von WKL Bootstrapper 2.2 oder höher; empfohlen ist 2.2.4 oder höher, das ältere signierte Auslieferungen abweist, die jemand auf die Freigabe zurücklegt (mit einem älteren Starter warnt deliver und liefert aus). WKL Office JSON ab 2.0 braucht den Starter 2.3.1 oder höher, WKL Forms Object Library ab 2.0 den Starter 3.1 oder höher; mit einem älteren bricht deliver ab. Für ein MSI zusätzlich die Befehlszeile des WiX Toolset (wix); zum Bearbeiten des Starters der Bootstrapper Manager, den wkl-office addin install mit dem SDK installiert.

Eine mit dem SDK gebaute Anwendung erreicht ihre Benutzer über den Starter, der app-manifest.json neben der ausgelieferten Datenbank liest und die benötigten WKL-Bibliotheken registriert. Diese Auslieferung von Hand zu schreiben ist fehleranfällig (Prüfsummen, Versionen, Bitbreite, die Pakete beider Bitbreiten).

• Ein Auslieferungsprofil legt fest, was eine Auslieferung enthält: die Build-Konfiguration, in der sie gebaut wird (deren Modus ist der Modus der Auslieferung), den Auslieferungsordner und den Starter. Jedes Profil ist eine Datei delivery\<name>.profile.json. Was alle Profile gemeinsam haben, die Version und die Release-Pakete, steht in delivery\delivery-settings.json (Referenz).
• Im Add-In richten Sie beides in den Projekteigenschaften ein (Schaltfläche Eigenschaften in der Gruppe Projekt).
• wkl-office deliver (oder Ausliefern in der Gruppe Herausgabe des Add-Ins; das Menü zeigt die Profile der im Add-In gewählten Build-Konfiguration) baut jedes Profil und schreibt build\Delivery\<name>: den Starter mit seiner Projektdatei und unterhalb von deploy die Datenbank, app-manifest.json und die WKL-Bibliotheken.
• Die Projektdatei des Starters je Profil ist eine Quelle des Projekts (delivery\<name>.bootstrapper.json) und wird mit dem Bootstrapper Manager bearbeitet (Starter › Im Bootstrapper Manager einrichten).
• wkl-office msi baut das Windows-Installer-Paket eines Profils für die IT.

1. Legen Sie die Auslieferung an. Im Add-In öffnen Sie Eigenschaften, wählen im Baum Auslieferungsprofile und klicken auf Lieferung einrichten. Der Dialog legt das Profil Production an, das in der Build-Konfiguration Release gebaut wird, und trägt die neuesten Release-Pakete unterhalb von WKL_PACKAGES ein; prüfen Sie diese unter Auslieferung, und speichern Sie mit OK.

   Von Hand schreiben Sie dieselben zwei Dateien, delivery\delivery-settings.json:

   {
     "format": 2,
     "version": "1.0.0",
     "packages": {
       "components": "%WKL_PACKAGES%\\Wkl.Forms.ObjectLibrary\\2.0.0",
       "bootstrapper": "%WKL_PACKAGES%\\Wkl.Bootstrapper\\3.1.0"
     }
   }

   und delivery\Production.profile.json:

   {
     "format": 1,
     "configuration": "Release"
   }

   Die Build-Konfiguration eines Profils muss einen Modus setzen: in der Projektdatei <AppMode>Production</AppMode> und <Accde>true</Accde> in der Eigenschaftsgruppe von Release (Projektdatei), im Dialog unter Build-Konfigurationen › Release. Lieferung einrichten setzt den Modus Production, wenn Release noch keinen hat. Für eine Fassung, die nur Administratoren erhalten, legen Sie eine weitere Konfiguration mit dem Modus Administration an und ein Profil, das darin gebaut wird.

2. Prüfen Sie, was mitgeliefert wird:

   wkl-office deliver Kunden.acproj --dependencies

3. Liefern Sie aus:

   wkl-office deliver Kunden.acproj

   Die erste Auslieferung eines Profils schreibt delivery\<name>.bootstrapper.json aus den Vorlagen des Starters und meldet das als Warnung. Öffnen Sie die Datei mit Starter › Im Bootstrapper Manager einrichten: Setzen Sie source auf die Freigabe, aus der die Benutzer lesen, und legen Sie den Anzeigenamen und die Verknüpfungen fest; speichern Sie. Liefern Sie erneut aus.

4. Probieren Sie ein Profil aus, ohne etwas zu installieren:

   wkl-office deliver Kunden.acproj -p Production --whatif

5. Kopieren Sie build\Delivery\production\deploy auf die als source angegebene Freigabe, die Datenbank zuerst und app-manifest.json zuletzt, und geben Sie den Benutzern den Starter (Wkl.Bootstrapper.exe mit bootstrapper.json), oder bauen Sie sein Paket für die IT:

   wkl-office msi Kunden.acproj -p Production --version 1.0.0 --sign <thumbprint>

• Die Auslieferung wird in einem eigenen verborgenen Access gebaut, ein Profil nach dem anderen; die im Access des Entwicklers geöffnete Datenbank bleibt unverändert. Schlägt ein Profil fehl, bricht der Befehl ab; die folgenden Profile werden weder gebaut noch ausgeliefert.
• Mehrere Profile dürfen denselben Modus ausliefern, etwa eines je Kunde, jedes mit eigener Build-Konfiguration (Verbindungsprofil) und eigenem Auslieferungsordner.
• requires richtet sich nach dem Build-Rechner: Access vermerkt in der Datenbank die höchste registrierte Version einer Bibliothek, auf die verwiesen wird; eine Auslieferung, die mit registrierten Components 1.59 gebaut wurde, benötigt also 1.59 auf den Rechnern der Benutzer. Bauen Sie Auslieferungen auf einem Rechner, auf dem das Release registriert ist, das die Benutzer erhalten.
• Der Bootstrapper Manager gehört zum SDK: wkl-office addin install installiert ihn als %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager\<version>\Wkl.Bootstrapper.Manager.accdb (siehe WKL Office SDK installieren). Das SDK öffnet ihn mit der Projektdatei und dem Starter. Es nimmt die Datei, auf die WKL_BOOTSTRAPPER_MANAGER (früher WKL_STARTER_CONFIGURATOR) zeigt, wenn es sie gibt, sonst die höchste Version unterhalb von %LOCALAPPDATA%\Programs\WKL\Bootstrapper Manager und des früheren Ordners %LOCALAPPDATA%\Programs\WKL\Starter Configurator. Die Argumente beschreibt die Seite „Command line of WKL Bootstrapper Manager“ (Englisch) in der Dokumentation von WKL Bootstrapper Manager.
• 32-Bit- und 64-Bit-Office. Ein Profil wird für die Bitbreite des bauenden Access ausgeliefert. Mit "bitness": "any" im Profil (in den Projekteigenschaften: Für 32- und 64-Bit-Office) dient ein Bau auf einem 32-Bit-Rechner für 32-Bit- und 64-Bit-Office: Ausgeliefert wird eine ACCDB, die Access beim ersten Start kompiliert (siehe delivery-settings.json).
• any oder eine ACCDE je Bitbreite? Entscheidend ist, ob der VBA-Code auf den Rechnern der Benutzer lesbar und änderbar sein darf; mit any ist er es, weil eine ACCDB ausgeliefert wird.
  • Administration: any genügt meist, denn diese Fassung erhalten nur Administratoren.
  • Production: any, wenn offener Code für Ihre Anwendung hinnehmbar ist; sonst eine ACCDE je Bitbreite.
  • Eine ACCDE je Bitbreite trägt immer die Bitbreite des Access, das sie baut: Eine 64-Bit-ACCDE entsteht nur auf einem Rechner mit 64-Bit-Access (Vollversion; die Runtime erzeugt keine ACCDE). Legen Sie dafür ein eigenes Profil mit eigenem Auslieferungsordner an, etwa Production x64, und liefern Sie es auf diesem Rechner mit -p "Production x64" aus. Die beiden Auslieferungen werden getrennt verteilt; der Starter lehnt eine Datenbank der falschen Bitbreite mit einer Meldung ab, statt sie zu öffnen.
• Format 1 bleibt gültig: Eine delivery-settings.json mit targets liefert jedes Ziel als Profil mit dem Namen seines Modus aus. Die Projekteigenschaften schreiben sie im Format 2, sobald die Auslieferung dort geändert wird (delivery-settings.json).

• Projektordner – welche Datei wo liegt und was versioniert wird
• Build-Konfiguration und Auslieferungsprofil – was eine Konfiguration und ein Profil festlegen
• delivery-settings.json
• Befehlszeilenreferenz: deliver, msi
• Projekt des Build-Werkzeugs der WKL Forms Object Library migrieren
• „Benutzerhandbuch WKL Bootstrapper Manager“ in der Dokumentation von WKL Bootstrapper Manager: die Projektdatei des Starters bearbeiten