Client aktualisieren

Eine bestehende Installation des primedocs Desktop Clients lässt sich auf zwei Wegen aktualisieren: über die zentrale Softwareverteilung mit dem MSI-Paket oder über den Updater, den der Server auf seiner Downloadseite bereitstellt. Diese Seite beschreibt den Updater.

Der Updater (primedocsInstaller.exe) ist dasselbe Programm, das auch für die Neuinstallation verwendet wird. Beim Start erkennt er eine vorhandene Installation und wechselt in den Update-Modus.

Wann kommt der Updater in Frage?

Situation	Empfehlung
Keine zentrale Softwareverteilung, Benutzer dürfen selbst aktualisieren	Updater
Zentrale Softwareverteilung (z.B. Intune, Configuration Manager, GPO)	MSI-Paket verteilen, siehe MSI-Parameter
Terminal Server oder Citrix	MSI-Paket verteilen, siehe Terminal-Server-Installation

Nicht mit zentraler Softwareverteilung kombinieren

Ist der Download auf dem Server freigeschaltet, können Clients sich selbst aktualisieren. Zusammen mit einer zentralen Softwareverteilung führt das zu konkurrierenden Installationen. Entweder den Updater freigeben oder zentral verteilen.

Auf einem Windows-Server-Betriebssystem prüft der Client nicht auf neue Versionen. Der Update-Hinweis erscheint dort nicht, auch wenn der Download konfiguriert ist.

Voraussetzungen

Auf dem Server

• Der Abschnitt windowsClient ist in der primedocs.config konfiguriert, inklusive updaterLocation und der MSI-Pfade. Ohne diese Konfiguration liefert die Downloadseite keinen Updater. Siehe primedocs.config: Client-Download und Update.
• Ein OIDC-Client für die Windows-Anmeldung ist registriert (userAuthType="FromLogin" ohne redirectUri).
• Updater und MSI-Paket auf dem Server stammen aus derselben Version. Weichen sie ab, bricht der Updater mit einer entsprechenden Meldung ab.

Auf dem Arbeitsplatz

• Der primedocs Client ist bereits installiert. Ohne bestehende Installation verlangt der Updater einen Setup-Code und führt eine Neuinstallation durch.
• Der primedocs Server ist erreichbar. Der Updater ermittelt das Paket über die konfigurierte Serviceadresse und lädt es von dort herunter. Ist die Serviceadresse mit HTTPS konfiguriert, lädt er nur über HTTPS, auch nach Weiterleitungen (höchstens zehn). Eine Weiterleitung auf eine HTTP-Adresse bricht den Download ab. HTTP ist nur zulässig, wenn die Serviceadresse selbst HTTP verwendet.
• Die TLS-Version handelt der Updater wie der Desktop Client mit Windows aus. Er legt sich nicht auf TLS 1.1 oder 1.2 fest und funktioniert deshalb auch gegen Server und Reverse Proxies, die nur TLS 1.3 anbieten, sofern Windows TLS 1.3 unterstützt.
• Microsoft Office ab Version 2013, durchgehend in derselben Bitigkeit. Sind 32- und 64-Bit-Produkte gemischt installiert, bricht der Updater ab.
• Bei einer Installation für alle Benutzer («Per-Machine») sind Administratorrechte nötig. Der Updater fordert sie über die Benutzerkontensteuerung selbst an. Wird die Abfrage abgelehnt, erklärt er auf einer eigenen Seite, warum die Rechte nötig sind, und bietet «Als Administrator ausführen» für einen neuen Versuch an. Eine reine Benutzerinstallation kommt ohne Administratorrechte aus, auch bei einer Neuinstallation.
• Die Anwendungen, die Dateien von primedocs verwenden, lassen sich schliessen. Andernfalls wird ein Neustart von Windows nötig.

Ablauf

1. Die Downloadseite https://your-url.example.com/app/web/download öffnen und den Updater herunterladen.

2. Den Updater starten. Er vergleicht die installierte Version mit der eigenen:

   Installierte Version	Verhalten
   Keine Installation vorhanden	Neuinstallation, Setup-Code erforderlich
   Älter als der Updater	Update
   Identisch	Meldung «primedocs ist bereits installiert», nur Start möglich
   Neuer als der Updater	Downgrade als Ersatzinstallation
   Installiert, aber die Programmdatei fehlt	Reparatur als Ersatzinstallation, unabhängig von der Version

3. Mit «Update» (bzw. «Downgrade» oder «Reparieren») startet der Vorgang. Der Updater lädt das MSI-Paket und prüft es, siehe Prüfung des Pakets.

4. Ein laufendes primedocs beendet der Updater selbst. Haben danach noch andere Anwendungen Dateien aus dem Installationsordner von primedocs geladen, zum Beispiel Outlook oder Word mit den primedocs-Add-ins, listet er sie auf. Office-Anwendungen ohne geladene primedocs-Dateien blockieren das Update nicht, sofern der Windows Restart Manager verfügbar ist. «Anwendungen schliessen und fortfahren» schliesst sie. Sofern Windows es unterstützt (Restart Manager), sichert Office dabei ungespeicherte Änderungen zur Wiederherstellung und die Anwendungen werden nach dem Setup wieder geöffnet. Alternativ die Anwendungen selbst schliessen, das Setup fährt dann automatisch fort. Erkannt werden nur Anwendungen der eigenen Windows-Sitzung.

5. Danach führt der Updater die Installation aus und zeigt dabei den aktuellen Schritt und den Fortschritt in Prozent an. Wurden Dateien während der Installation noch verwendet, verlangt er einen Neustart von Windows. Bis dahin bleibt die bisherige Version aktiv. Zu einem Neustart von Office fordert er nur auf, wenn er die Office-Anwendungen nicht selbst geschlossen und wieder geöffnet hat.

Beim Update ist kein Setup-Code nötig. Serviceadresse, Client-ID und Client-Secret, Standard-Datenquelle, Cache- und SSO-Einstellungen, die Ribbon-Konfiguration, eigene Ordner für Cache, Einstellungen und Protokolle, der Installationsordner (ausser bei einer alten OneOffixx-Installation) sowie der installierte Funktionsumfang werden aus der bestehenden Installation übernommen. Die Werte stammen ausschliesslich aus der Konfiguration der erkannten Installation. Reste einer früheren Installation im anderen Kontext überschreiben sie nicht.

Fehlt in der bestehenden Konfiguration die Serviceadresse, fehlt die Datei primedocs.exe.config oder ist sie kein gültiges XML, verlangt der Updater einen Setup-Code. Der Code ersetzt nur die Verbindungsdaten, alle übrigen Einstellungen bleiben erhalten.

Installationskontext

Der Updater aktualisiert eine bestehende Installation immer im selben Kontext: Eine Benutzerinstallation («Per-User») bleibt eine Benutzerinstallation, auch wenn der Updater mit Administratorrechten läuft, und eine Installation für alle Benutzer («Per-Machine») bleibt eine solche. Die Update-Seite nennt den erkannten Kontext. Ob und in welchem Kontext primedocs installiert ist, ermittelt der Updater über Windows Installer. Die Registry zieht er nur heran, wenn Windows Installer keine Auskunft gibt.

Bei einer Neuinstallation entscheiden die Rechte, mit denen der Updater läuft: mit Administratorrechten für alle Benutzer, sonst für den aktuellen Benutzer.

Ist primedocs auf dem Gerät sowohl für den aktuellen Benutzer als auch für alle Benutzer installiert, bricht der Updater mit einer Meldung ab. Eine der beiden Installationen in den Windows-Einstellungen unter Apps entfernen und den Updater erneut starten.

Downgrade, Reparatur und Option «Neuinstallation»

Bei einem Downgrade, einer Reparatur und mit der Option «Neuinstallation» ersetzt der Updater die bisherige Installation: Er entfernt die bisherige Version und installiert anschliessend die neue. Beim Downgrade und bei der Reparatur ist die Option zwingend gesetzt.

Beide Schritte laufen in einer gemeinsamen Windows-Installer-Transaktion. Schlägt die Installation fehl oder wird sie abgebrochen, stellt Windows Installer die bisherige Version wieder her. Kann der Updater keine Transaktion starten, bricht er ab, bevor er etwas entfernt. Einstellungen, Cache, Signaturen und verteilte Vorlagen des Benutzers bleiben bei der Ersatzinstallation erhalten. Diese Daten entfernt erst eine reguläre Deinstallation über die Windows-Einstellungen.

Prüfung des Pakets

Bevor der Updater das heruntergeladene MSI-Paket installiert, prüft er der Reihe nach:

1. Die Authenticode-Signatur des Pakets ist gültig.
2. Das Paket ist ein primedocs-Paket (gleicher UpgradeCode).
3. Die Version des Pakets entspricht der Version des Updaters.
4. Das Paket ist mit demselben Zertifikat signiert wie der Updater.

Schlägt eine Prüfung fehl, installiert der Updater nichts. Die Prüfung des Zertifikats lässt sich nicht abschalten.

Hinweis auf eine neue Version im Client

Sind in der primedocs.config minimumVersion oder maximumVersion gesetzt, prüft der Desktop Client beim Verbinden die eigene Version. Liegt sie ausserhalb des Bereichs, zeigt er den konfigurierten Hinweistext mit einem Link auf die Downloadseite.

Wenn das Update fehlschlägt

Meldung	Ursache und Vorgehen
«Die Version des Installers stimmt nicht mit der Version des Installationspakets überein.»	Der lokale Updater ist älter oder neuer als das Paket auf dem Server. Über «Downloadseite öffnen» den aktuellen Updater beziehen.
Hinweis, dass primedocs zweimal installiert ist	Die Installation für den aktuellen Benutzer oder jene für alle Benutzer in den Windows-Einstellungen unter Apps entfernen, danach den Updater erneut starten.
Seite zu fehlenden Administratorrechten	Die Installation gilt für alle Benutzer. «Als Administrator ausführen» wählen und die Abfrage der Benutzerkontensteuerung bestätigen.
Fehler zur Signatur oder zum Zertifikat des Pakets	Das Paket auf dem Server stammt nicht aus derselben Lieferung wie der Updater oder wurde verändert. Updater und MSI-Pakete derselben primedocs-Version auf dem Server ablegen.
Fehler, weil eine Adresse kein HTTPS verwendet	Ein Download-Pfad oder eine Weiterleitung zeigt auf eine HTTP-Adresse, obwohl die Serviceadresse HTTPS verwendet. Absolute Pfade in windowsClient, bei relativen Pfaden die Adresse der App in der primedocs.config, sowie allfällige Weiterleitungen auf HTTPS umstellen.
«Nicht alle Anwendungen konnten geschlossen werden.»	Die Arbeit speichern und die verbleibenden Anwendungen von Hand schliessen. Das Setup fährt danach fort.
Hinweis auf verschiedene Office-Bit-Versionen	Auf dem Gerät sind 32- und 64-Bit-Office-Produkte gemischt installiert. Office bereinigen, danach das Update wiederholen.
Hinweis auf eine zu alte Office-Version	primedocs setzt Office 2013 oder neuer voraus.
Allgemeiner Fehler beim Herunterladen oder Installieren	Die Protokolle auswerten, siehe Protokolle bei fehlgeschlagenen Updates.