Zum Hauptinhalt springen
Version: 4.1 (2026 H2)

Aktualisierung primedocs-Server

hinweis

Diese Seite betrifft die OnPremises-Variante.
Bei der "Software as a Service"-Variante sind keine Serveraktualisierungen durch den Kunden notwendig.

Vor dem Update:

Voraussetzungen​

  • Bestehende Installation: Voraussetzung für die Aktualisierung des primedocs-Servers ist eine vollständige primedocs Installation (durchgeführt wie hier beschrieben).
  • Backup erstellen: Vor dem Update ein Backup der folgenden Komponenten erstellen:
    • SQL-Datenbanken (primedocs- und Operation-Datenbank, z. B. via Full Database Backup)
    • primedocs.config
    • cert.pfx (bzw. das Signing-Zertifikat, falls im Zertifikat-Store)
    • Data-Protection-Keys (key-*.xml)
    • nlog.config (falls angepasst)
  • .NET 10 Hosting Bundle: Ein Update auf primedocs 4.1 setzt das installierte .NET 10 Windows Hosting Bundle voraus (siehe Systemvoraussetzung).
  • Rollback: Schlägt das Update fehl, kann der vorherige Zustand wiederhergestellt werden, indem das Backup zurückgespielt wird (Applikationsdateien und Konfigurationsdateien zurückkopieren, Datenbanken per Restore wiederherstellen).

Aktualisierung​

Im Installationspaket ist ein PowerShell-Skript "Update.ps1" enthalten, welches eine bestehende Installation aktualisiert. Das Skript muss als Administrator ausgeführt werden.

Preflight

Vor dem Ausführen des Skripts sicherstellen:

  • Geprüfter Wiederherstellungspunkt bzw. Backup vorhanden (siehe Voraussetzungen).
  • Korrektes Installationsverzeichnis gewählt — es muss die primedocs.config enthalten.
  • Keine externen Prozesse sperren Dateien im Installationsverzeichnis: den vom Installer eingerichteten JobHost-Task stoppen und weitere Zugriffe auf das Verzeichnis beenden. Das Update-Skript stoppt zwar Website und App-Pools, den JobHost jedoch nicht.
  • Kurzes Wartungsfenster eingeplant — Website und App-Pools werden während des Updates gestoppt, in der Regel für einige Minuten. Der Desktop Client kann in dieser Zeit im Offline-Modus weiterarbeiten; Web-App und Add-ins sind nicht erreichbar.

Beim Aktualisieren werden die Applikationsdateien über Robocopy gespiegelt. Dabei bleiben nur bestimmte Konfigurationen erhalten:

  • Die zentrale primedocs.config wird nicht ersetzt.
  • nlog.config wird für die betroffenen Anwendungen gesichert und zurückkopiert.
  • Die Web.config der DataSourceAdminApp wird bei der erkannten On-Premises-Variante erhalten.

Andere web.config-Dateien werden nicht generell geschützt und können durch die Spiegelung überschrieben werden. Individuell angepasste Werte darin vor dem Update sichern.

hinweis

HINWEIS
Das Aktualisierungsskript ("Update.ps1") ist für die Aktualisierung von genau einer primedocs-Umgebung auf einem Server ausgelegt. Wenn mehrere primedocs-Umgebungen auf demselben Server laufen, muss das Skript für jede Umgebung separat mit dem jeweiligen Installationspfad aufgerufen werden.

Kopierfehler unterbrechen das Update

Robocopy wird bei einem Fehler einmal wiederholt. Bleibt der Fehler bestehen, beendet sich das Skript mit Exitcode 1, bevor Website und App-Pools wieder gestartet werden. In diesem Fall Exitcode, Skriptausgabe und den IIS-Zustand prüfen — Website und App-Pools können gestoppt bleiben und müssen dann manuell wieder gestartet werden.

App-Pools werden auf 64-Bit umgestellt

Der primedocs-Server läuft ausschliesslich als 64-Bit-Anwendung. Das Update-Skript setzt deshalb bei allen primedocs-App-Pools enable32BitAppOnWin64 auf false, bevor es sie wieder startet — auch bei bestehenden Pools, die bisher im 32-Bit-Modus liefen. Schlägt das Setzen für einen Pool fehl, erscheint eine Warnung und das Update läuft weiter; der betroffene Pool ist dann manuell auf 64-Bit umzustellen.

Skript ausführen​

Die Installations-Zip-Datei muss vorgängig entpackt werden.

Die Update.ps1 ist signiert und kann mit den Argumenten aufgerufen werden. Diese sind in der Datei in einem grossen Kommentar beschrieben (unter "Usages").

Standardaufruf (hierfür muss zuvor ins Installationsverzeichnis navigiert werden, z. B. mit cd "C:\temp\primedocs_Install_Package"), wenn primedocs unter c:\inetpub\wwwroot\primedocs installiert wurde:

.\Update.ps1

Weitere Aufrufmöglichkeiten sind in "Update.ps1" unter "Usages" beschrieben.

Update via Neuinstallation​

Um bei vollautomatischen primedocs-Deployments sicherzustellen, dass die IdentityServer-Signatur (cert.pfx) und die ASP.NET Core Data-Protection-Keys über Neuinstallationen hinweg erhalten bleiben und damit bestehende OIDC-Sessions / Tokens weiterhin akzeptiert werden, sind folgende Schritte notwendig:

  1. Vor der Neuinstallation: Sicherung der relevanten Dateien/Artifacts:

Um zu verhindern, dass die Dateien bei einer Neuinstallation überschrieben oder gelöscht werden, sollten sie ausserhalb des Installationsverzeichnisses abgelegt werden.

  • primedocs.config
  • cert.pfx (oder vorhandenes Signing-Zertifikat, wenn im Store)
  • Data-Protection Keys (key-*.xml)
  • nlog.config (falls angepasst)
  1. Neuinstallation / Installationsskript ausführen
  2. Gesicherte Dateien an ihre vorherigen Orte zurückspielen bzw. Zertifikat in Store importieren

Datenbank Migrationen​

Nach einer Aktualisierung sollte die DataSourceAdminApp aufgerufen werden um etwaige Datenbank-Migrationen auszuführen.

Nach dem Update​

Nach erfolgreichem Update den Betrieb verifizieren:

  1. Ausstehende Datenbank-Migrationen anwenden (siehe Datenbank Migrationen).
  2. Den Funktionstest ausführen.
  3. Das Monitoring und aktuelle Anwendungsfehler prüfen; bei Problemen das Troubleshooting beiziehen.