Neuere Versionen installieren
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.
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
Entpacken Sie
Portal v<version>.zipin einen eigenen Ordner, z. B.C:\Installers\Portal-v<version>. Entpacken Sie es nicht in den Ordner der Website.Doppelklicken Sie auf
upgrade.batim 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.Beantworten Sie die Fragen der Prüfungen (siehe unten). Es wird nichts geändert, bevor alle Prüfungen bestanden sind.
Warten Sie, bis das Skript fertig ist, und lesen Sie dann den Bericht
upgrade-report.txtim Sicherungsordner. Lesen Sie ihn nach jedem Upgrade — er listet die Warnungen auf, z. B. beibehaltene Dateien oder manuelle Schritte, die noch erforderlich sind.
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.configkann 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
Defaultist 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
- Es merkt sich die neueste Datenbank-Migration der Host-Datenbank, damit die Datenbanken später auf diesen Stand zurückmigriert werden können.
- 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ßerdembackup-manifest.json,revert.batundupgrade.ps1. - 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. - Es kopiert das Paket in die Website:
binund 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.configundbin\DataMigrationPageSizes.json,- Plugin-DLLs, die im Abschnitt
<plugins>derweb.configgenannt 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.
- 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 derruntimes.xmldes Pakets übernommen (Sie müssen sie nicht mehr von Hand kopieren), - die Änderungen von 1.80:
targetFramework="4.8", die Referenz aufnetstandard,maxQueryString/maxQueryStringLengthvon32768(siehe Änderungen an der web.config), TrustServerCertificate=Truewird an den Connection-StringDefaultangehängt, sofern erTrustServerCertificatenoch 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.
- die Assembly-Binding-Redirects in
- Es startet den Anwendungspool direkt nach dem Kopieren der Dateien wieder und führt dann den Datenbank-Migrator aus (dasselbe wie
migrate_databases.bat).
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.configundNLog.configin<backup>\config-before-revert-<time>\ab, - startet den Anwendungspool wieder.
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
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.
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 desPortalDbContext(einschließlich seines<databaseInitializer>) durch das folgende Element. Ab jetzt migriert das Portal die Datenbanken beim Start nicht mehr — das macht nur nochmigrate_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
Yund drücken Sie Enter.
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 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.
- Das neue Paket nicht über die bestehende Installation entpacken.
- Entpacken Sie das neue
Dox42Host v{version}.zipin einen frischen Ordner (z. B.C:\Installers\Dox42Host-v{version}). - Führen Sie
upgrade.batals 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" - 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, NLoglogDir) 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.
- den Dienst
- Falls die neue Version zusätzliche betreiberseitige Einstellungen einführt, führen Sie anschließend
config.batim Installationsordner aus, um diese zu prüfen.