Zum Hauptinhalt springen

Neuere Versionen installieren

Für 1.80+ sind zusätzliche manuelle Schritte erforderlich

1.80 bringt tiefgreifende Änderungen mit sich (neues Authentifizierungssystem, SQL 2017+, Änderungen an der web.config, WSFED-Neukonfiguration). upgrade.bat nimmt die Änderungen an der web.config automatisch vor und weist Sie auf die Schritte hin, die es nicht für Sie erledigen kann. Lesen Sie Upgrade auf iCL Portal 1.80+ und führen Sie die übrigen dort beschriebenen Schritte zusätzlich zum unten beschriebenen Upgrade-Ablauf aus.

Upgrade des Web-Frontends​

Das Release-Paket Portal v<version>.zip enthält upgrade.bat, das eine iCL-Portal-Website im IIS in einem Durchgang aktualisiert: Es prüft den Server, sichert die Dateien der Website, ersetzt sie, aktualisiert die web.config und migriert die Datenbanken. Dies ist der empfohlene Weg für ein Upgrade. Enthält das Paket kein upgrade.bat (ältere Versionen) oder kann upgrade.bat nicht verwendet werden, folgen Sie dem manuellen Upgrade.

Sichern Sie zuerst die Datenbanken

upgrade.bat sichert die Datenbanken nicht. Sichern Sie die SQL-Datenbanken von iCL Portal (die Host-Datenbank und alle Tenant-Datenbanken) und stellen Sie sicher, dass eine Wiederherstellung tatsächlich funktioniert, bevor Sie das Upgrade starten. Das Skript fragt Sie, ob Sie dies getan haben.

Upgrade mit upgrade.bat​

  1. Entpacken Sie Portal v<version>.zip in einen eigenen Ordner, z. B. C:\Installers\Portal-v<version>. Entpacken Sie es nicht in den Ordner der Website.

  2. Doppelklicken Sie auf upgrade.bat im entpackten Ordner. Es fordert Administratorrechte an.

    Optional können Sie den Ordner der Website als Argument übergeben:

    upgrade.bat "C:\inetpub\iCLPortal"

    Ohne Argument sucht das Skript das iCL Portal im IIS. Findet es eines, bestätigen Sie es mit ENTER; findet es mehrere, wählen Sie eines über seine Nummer aus. Findet es keines, fragt es nach dem Ordner.

  3. Beantworten Sie die Fragen der Prüfungen (siehe unten). Es wird nichts geändert, bevor alle Prüfungen bestanden sind.

  4. Warten Sie, bis das Skript fertig ist, und lesen Sie dann den Bericht upgrade-report.txt im Sicherungsordner. Lesen Sie ihn nach jedem Upgrade — er listet die Warnungen auf, z. B. beibehaltene Dateien oder manuelle Schritte, die noch erforderlich sind.

Mit einem Benutzer ausführen, der die Datenbanken migrieren darf

upgrade.bat verbindet sich mit dem SQL Server des Connection-Strings Default als der Windows-Benutzer, der es ausführt — ebenso der Datenbank-Migrator, den es startet. Führen Sie es mit dem Benutzer aus, mit dem Sie auch migrate_databases.bat ausführen würden.

Was upgrade.bat prüft​

Bevor etwas geändert wird, prüft das Skript Folgendes. Schlägt eine Prüfung fehl, bricht es ab und es wird nichts geändert.

  • Es wurde aus einem entpackten Release-Paket (nicht aus dem Ordner einer Website) und mit Administratorrechten gestartet.
  • .NET Framework 4.8 ist installiert.
  • Der Ordner ist eine iCL-Portal-Website und ihre web.config kann gelesen werden.
  • Die Versionen: Ein Downgrade (das Paket ist älter als die Website) muss bestätigt werden. Ist die Website älter als 1.80, weist es Sie auf die manuellen Schritte von 1.80 hin (Client-Credentials neu erstellen, WSFED / Azure Entra ID pro Tenant konfigurieren, Salesforce-Authentifizierung entfernt — siehe Upgrade auf iCL Portal 1.80+).
  • Der Anwendungspool der IIS-Anwendung wird von keiner anderen Anwendung verwendet. Falls doch, werden Sie gefragt, ob Sie fortfahren möchten.
  • Der SQL Server des Connection-Strings Default ist mit dem Benutzer erreichbar, der das Skript ausführt, und es ist SQL Server 2017 oder neuer.
  • Es fragt: „Haben Sie die Datenbanken gesichert (und geprüft, dass eine Wiederherstellung funktioniert)?“

Was upgrade.bat macht​

  1. Es merkt sich die neueste Datenbank-Migration der Host-Datenbank, damit die Datenbanken später auf diesen Stand zurückmigriert werden können.
  2. Es sichert die Dateien der Website in einen Ordner daneben, <site>.backup-<yyyyMMdd-HHmmss>-net48 (z. B. C:\inetpub\iCLPortal.backup-20261119-153000-net48). App_Data, die Logs und eine Dateiablage (FileBlobStorageRoot) innerhalb der Website werden nicht gesichert — das Upgrade verändert sie nicht. Der Sicherungsordner enthält außerdem backup-manifest.json, revert.bat und upgrade.ps1.
  3. Es hält den Anwendungspool an — nur solange die Dateien ersetzt werden — und wartet, bis seine Worker-Prozesse (w3wp.exe) beendet sind. Läuft einer weiter und sperrt die Dateien, fragt es, ob er beendet werden soll (Standard: ja). Wird eine Datei von einem anderen Prozess gesperrt, bricht das Upgrade ab und es wird nichts geändert.
  4. Es kopiert das Paket in die Website: bin und die anderen Ordner der Website entsprechen danach denen des Pakets (DLLs, die nicht mehr Teil des Pakets sind, werden entfernt). Erhalten bleiben:
    • web.config, NLog.config und bin\DataMigrationPageSizes.json,
    • Plugin-DLLs, die im Abschnitt <plugins> der web.config genannt sind — der Bericht erinnert Sie daran, zu prüfen, ob sie mit der neuen Version kompatibel sind,
    • Ihre eigenen Dateien und Ordner, die nicht Teil des Pakets sind (als Warnung im Bericht aufgeführt),
    • App_Data, die Logs und die Dateiablage.
  5. Es aktualisiert die web.config — nur wo nötig. Werte werden nie verringert, alles andere einschließlich der Connection-Strings und Passwörter bleibt unverändert:
    • die Assembly-Binding-Redirects in <runtime> werden aus der runtimes.xml des Pakets übernommen (Sie müssen sie nicht mehr von Hand kopieren),
    • die Änderungen von 1.80: targetFramework="4.8", die Referenz auf netstandard, maxQueryString / maxQueryStringLength von 32768 (siehe Änderungen an der web.config),
    • TrustServerCertificate=True wird an den Connection-String Default angehängt, sofern er TrustServerCertificate noch nicht enthält,
    • der Datenbank-Initializer von Entity Framework wird entfernt (disableDatabaseInitialization="true"), damit nur noch der Migrator die Datenbanken migriert — nie das Portal beim Start.
  6. Es startet den Anwendungspool direkt nach dem Kopieren der Dateien wieder und führt dann den Datenbank-Migrator aus (dasselbe wie migrate_databases.bat).
Datenmigrationen können dauern

Ab iCL Portal 1.80 führt der Migrator zusätzlich zu den Schema-Migrationen auch Datenmigrationen aus. Diese können bei großen Mandanten (Tenants) erhebliche Zeit in Anspruch nehmen. Das System ist bereits betriebsbereit und kann während der laufenden Datenmigrationen verwendet werden.

Wenn das Upgrade fehlschlägt​

  • Schlägt das Kopieren der Dateien fehl, wird die Website automatisch auf die Sicherung zurückgesetzt.
  • Schlägt der Migrator fehl, bietet das Skript an, das Upgrade rückgängig zu machen (Standard: ja). Es migriert die Datenbanken auf die Migration zurück, die es vor dem Upgrade festgehalten hat (mit dem Migrator der neuen Version, der seine eigenen Migrationen rückgängig machen kann), und stellt die Dateien aus der Sicherung wieder her. Daten, die von bereits gelaufenen Datenmigrationen geschrieben wurden, werden nicht rückgängig gemacht — stellen Sie bei Bedarf Ihre Datenbanksicherung wieder her.
  • Bricht der Migrator mit „The COMMIT TRANSACTION request has no corresponding BEGIN TRANSACTION“ ab, starten Sie den Migrator direkt wie unter Migrator bricht mit „The COMMIT TRANSACTION request has no corresponding BEGIN TRANSACTION“ ab beschrieben.
  • Sind PowerShell-Skripte durch eine Richtlinie blockiert oder ist die IIS-Verwaltung (Windows-Feature IIS-Verwaltungskonsole) nicht installiert, führen Sie das Upgrade manuell durch.

Zurücksetzen mit revert.bat​

Jeder Sicherungsordner enthält ein revert.bat. Um zur Version vor dem Upgrade zurückzukehren, doppelklicken Sie auf revert.bat im Sicherungsordner (keine Argumente nötig). Alternativ können Sie es aus dem Release-Paket starten und die Website sowie optional den Sicherungsordner übergeben (Standard: die neueste Sicherung der Website):

revert.bat "C:\inetpub\iCLPortal" "C:\inetpub\iCLPortal.backup-20261119-153000-net48"

Das Skript

  • migriert zuerst die Datenbanken auf die vor dem Upgrade festgehaltene Migration zurück (Sie werden gefragt),
  • hält den Anwendungspool an und stellt die Dateien der Website aus der Sicherung wieder her (App_Data, die Logs und die Dateiablage werden nicht verändert),
  • legt die aktuelle web.config und NLog.config in <backup>\config-before-revert-<time>\ ab,
  • startet den Anwendungspool wieder.
Hinweis

Daten, die von Datenmigrationen geschrieben wurden, macht revert.bat nicht rückgängig. Wenn sie rückgängig gemacht werden müssen, stellen Sie Ihre Datenbanksicherung wieder her.

Manuelles Upgrade (Fallback)​

Verwenden Sie diese Schritte, wenn upgrade.bat nicht verwendet werden kann oder fehlschlägt.

  • Sichern Sie die SQL-Datenbanken von iCL Portal und stellen Sie sicher, dass eine Wiederherstellung tatsächlich funktioniert
  • Sichern Sie Ihre aktuelle Web.config und NLog.config des iCL Portal Web Front-end
  • Löschen Sie alle Dateien im bin-Ordner der Website außer App_Data, Web.config und NLog.config
app-pool recyceln

Falls eine Datei nicht gelöscht werden kann, weil sie von einem anderen Prozess (IIS) verwendet wird, öffnen Sie den IIS-Manager und recyceln Sie den Anwendungspool der iCL Portal-Website.

DO NOT RESTART IIS

Starten Sie IIS nicht neu, da dies alle anstehenden Anfragen unterbricht und zu Datenbeschädigung und/oder Datenverlust führen kann!

  • Entpacken Sie das Archiv iCL.Portal.xxxx.zip in den Ordner der Website.

  • Öffnen Sie die Datei web.config und ersetzen Sie das Element <runtime>...</runtime> durch das im Paket enthaltene Element (runtimes.xml)

  • Entfernen Sie in der web.config den Datenbank-Initializer von Entity Framework: Ersetzen Sie unter <entityFramework> / <contexts> das <context>-Element des PortalDbContext (einschließlich seines <databaseInitializer>) durch das folgende Element. Ab jetzt migriert das Portal die Datenbanken beim Start nicht mehr — das macht nur noch migrate_databases.bat.

<context type="iCL.Portal.EntityFramework.PortalDbContext, iCL.Portal.EntityFramework, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" disableDatabaseInitialization="true" />
  • Wenn Sie von einer Version älter als 1.80 aktualisieren, nehmen Sie die Änderungen an der web.config von 1.80 vor.

  • Führen Sie schließlich die Datei "migrate_databases.bat" aus. Dieser Schritt ist zwingend erforderlich. Sie wird Sie fragen, ob Sie alle ausstehenden DB-Schemaänderungen auf alle Tenant-Datenbanken des iCL-Portals anwenden möchten.

  • Bestätigen Sie mit Y und drücken Sie Enter.

Datenmigrationen können dauern

Ab iCL Portal 1.80 führt migrate_databases.bat zusätzlich zu den Schema-Migrationen auch Datenmigrationen aus. Diese können bei großen Mandanten (Tenants) erhebliche Zeit in Anspruch nehmen.

Das System bleibt während der Datenmigration verwendbar

Das System ist bereits betriebsbereit und kann während der laufenden Datenmigrationen verwendet werden. Benutzer können weiterarbeiten; es ist nicht notwendig, sie bis zum Abschluss der Migrationen auszusperren.

  • Befolgen Sie die zusätzlichen Anweisungen in der mitgelieferten Readme-Datei (z. B. Änderungen an der Web.config) im zugehörigen Upgrade-Handbuch.

Upgrade des dox42-Hosts​

Der dox42-Host wird als eigenständiger Windows-Dienst (iCLPortalDox42) ausgeliefert. Die Release-Pakete enthalten leere Werte für betreiberseitige Einstellungen — ein direktes Kopieren eines neuen Pakets über die bestehende Installation würde daher Verbindungsstrings, iKey, Tags und Log-Ordner überschreiben. Verwenden Sie stattdessen upgrade.bat.

  1. Das neue Paket nicht über die bestehende Installation entpacken.
  2. Entpacken Sie das neue Dox42Host v{version}.zip in einen frischen Ordner (z. B. C:\Installers\Dox42Host-v{version}).
  3. Führen Sie upgrade.bat als Administrator aus dem entpackten Ordner aus und übergeben Sie den Pfad der bestehenden Installation (oder geben Sie ihn bei Aufforderung ein):
    upgrade.bat "C:\Program Files\iCLPortalDox42"
  4. Das Skript wird:
    • den Dienst iCL.Portal.Reporting.Dox42$dox42_<MACHINE> anhalten,
    • das neue bin\-Verzeichnis über das alte spiegeln (entfernte DLLs werden bereinigt),
    • die bestehenden betreiberseitigen Werte (Default-Verbindungsstring, StorageConnectionString, iKey, ApplicationInsights-Tags customer/environment, NLog logDir) aus den alten Config-Dateien in die neuen übernehmen,
    • die aktualisierten Root-Skripte (install.bat, uninstall.bat, config.bat, start.bat, upgrade.bat, upgrade.ps1) kopieren,
    • anbieten, den Dienst neu zu starten.
  5. Falls die neue Version zusätzliche betreiberseitige Einstellungen einführt, führen Sie anschließend config.bat im Installationsordner aus, um diese zu prüfen.