Aktualisieren
Überblick
Dieses Dokument behandelt den Upgrade-Prozess für Produktivinstanzen von PowerShell Universal. Wir behandeln die folgenden Themen.
Datensicherung
Upgrade-Prozess
Upgrade-Validierung
Die Universal-Anwendungsbinärdateien können in der Regel aktualisiert werden, ohne dass die Konfiguration oder die Datenbank manuell geändert werden muss, wir empfehlen jedoch Sicherungen der Produktivdaten.
Empfehlungen
Für Produktivumgebungen empfehlen wir, PowerShell Universal vor größeren Upgrades in einer Staging- oder Entwicklungsumgebung bereitzustellen. So können Tests durchgeführt werden, bevor Endbenutzer betroffen sind. Sie können Entwicklungslizenzen verwenden, um Änderungen in PowerShell Universal-Instanzen zu testen, ohne eine weitere Lizenz zu erwerben.
1. Datensicherung
PowerShell Universal verwendet ein skriptbasiertes Konfigurationssystem zusammen mit einer Datenbank, in der Entitäten wie App-Tokens, Auftragsverlauf und Identitäten aufbewahrt werden. Wenn möglich, sollten Sie diese Elemente vor der Durchführung eines Upgrades sichern, um im Falle eines Problems während der Validierung einfach zurückrollen zu können.
Datenbank
Das Sichern der Datenbank stellt sicher, dass alle App-Tokens, der Auftragsverlauf, Identitäten und Datenbankgeheimnisse im Falle eines fehlgeschlagenen Upgrades erhalten bleiben. SQL-Datenbanken können außerdem das Schema der Datenbank anpassen und erfordern möglicherweise ein Zurückrollen nicht nur der Daten, sondern auch des Schemas der Tabellen in der Datenbank.
SQLite
Standardmäßig verwendet PowerShell Universal eine Einzeldatei-Datenbank namens SQLite. Sofern nicht anders konfiguriert, wird die Datenbank unter %ProgramData%\UniversalAutomation gespeichert. Sie sollten eine database.db und möglicherweise eine database-log.db haben. Beide Dateien sollten gesichert werden. Der Dienst muss beendet werden, um die Dateien sichern zu können.
SQL
Wenn Sie SQL für die Persistenz verwenden, sichern Sie die gesamte Datenbank (einschließlich Schema). Es ist nicht zwingend erforderlich, den PowerShell Universal-Dienst beim Sichern der Datenbank zu beenden, aber er schreibt möglicherweise weiterhin in die Datenbank (zum Beispiel beim Ausführen geplanter Aufträge), nachdem die Sicherung abgeschlossen wurde.
Konfigurationsskripte
Skripte bilden die wichtigsten Konfigurationsdaten, die beim Upgrade einer Produktivinstanz von PowerShell Universal gesichert werden sollten. Für den Produktivbetrieb empfehlen wir die Verwendung eines Versionskontrollsystems. Sie können auch die integrierte Git-Integration nutzen. Wenn Sie eine bidirektionale Synchronisierung für die Git-Integration von PowerShell Universal verwenden, sollten Sie in Erwägung ziehen, Ihren Git-Branch vor dem Upgrade zu taggen, um ein einfaches Zurückrollen bei unerwarteten Änderungen innerhalb des Git-Repositorys zu ermöglichen.
2. Upgrade-Fortschritt
Nachfolgend finden Sie Abschnitte für jede Art von System-Upgrade und die Schritte, die Sie je nach ursprünglicher Installation von PSU ausführen sollten.
MSI
Bei der Installation über das MSI sollten Sie dieselben oben beschriebenen Sicherungsverfahren befolgen.
appsettings.json
Sie sollten die Datei appsettings.json sichern, die unter %ProgramData%\PowerShellUniversal gespeichert ist. Diese Datei enthält Informationen wie Port, Datenspeicherort und andere Servereinstellungen. Normalerweise nimmt das MSI keine Änderungen an dieser Datei vor, nachdem sie erstellt wurde. Es verwendet die für die aktualisierte Version gefundenen Einstellungen. Falls erforderlich, nimmt das MSI jedoch Änderungen an der appsettings-Datei vor. Diese Änderungen gelten als Breaking Changes und werden im Änderungsprotokoll der Version aufgeführt.
Dienstkonto
Beim Ausführen eines MSI-Upgrades wird der PSU-Dienst nicht deinstalliert, und somit ist das Dienstkonto weiterhin gesetzt, sobald der Dienst startet.
Upgrade-Prozess
Sobald alle Konfigurationsdateien und die Datenbank gesichert sind, können Sie das neue MSI-Installationsprogramm ausführen.
Das Installationsprogramm fordert möglicherweise einen Neustart des Rechners an, wenn Dateien gesperrt sind. Das PSU-MSI deinstalliert alle Dateien im Installationsverzeichnis und installiert vollständig neue Dateien.
Sobald das MSI abgeschlossen ist, können Sie zu Ihrer PowerShell Universal-Administrationskonsole navigieren, um die Installationsvalidierung durchzuführen.
IIS
Nachfolgend finden Sie Informationen zum Upgrade einer IIS-Installation.
web.config
Zusätzlich zu den oben aufgeführten zu sichernden Dateien sollten Sie auch in Erwägung ziehen, Ihre web.config-Datei zu sichern. Wenn Sie keine Änderungen an dieser Datei vorgenommen haben, müssen Sie sie nicht sichern.
Die im Anwendungsinstallationsverzeichnis enthaltene web.config-Datei wird bei Upgrades überschrieben. Wenn Sie Ihre web.config-Datei an einen anderen Speicherort verschoben haben, wird sie nicht überschrieben. Beim Erstellen einer IIS-Website können Sie die web.config-Datei einfach in das Verzeichnis der Web-App aufnehmen und die Binärdateien an einem anderen Speicherort ablegen.
Upgrade-Prozess
Beim Upgrade mit IIS müssen Sie zuerst Ihren Anwendungspool beenden, um sicherzustellen, dass die von IIS verwendeten Binärdateien nicht mehr in Verwendung sind, und diese anschließend durch die neuen ersetzen. Um sicherzustellen, dass das Upgrade wie erwartet funktioniert, wird empfohlen, alle Anwendungsdateien zu löschen und die neuen dann in dasselbe Verzeichnis zu entpacken, um Assembly-Konflikte zu vermeiden.
Sobald Sie die neuen Dateien kopiert und entsperrt haben, starten Sie den Anwendungspool, navigieren Sie zur PowerShell Universal-Administrationskonsole und führen Sie die Installationsvalidierung durch.
Universal-Modul
Das Universal-Modul kann verwendet werden, um Installationen von PowerShell Universal zu aktualisieren, die zuvor über das Modul installiert wurden.
Verwenden Sie das Universal-Modul nicht, um Instanzen zu aktualisieren, die über MSI installiert wurden.
Befolgen Sie die oben beschriebenen Sicherungsverfahren und führen Sie dann das Upgrade durch.
Aktualisieren Sie zunächst das lokale PowerShell Universal-Modul und überprüfen Sie, ob die erwartete Version installiert ist.
Führen Sie als Nächstes Update-PSUServer aus, um die neue PSU-Instanz herunterzuladen und zu entpacken.
Nach Abschluss des Upgrades navigieren Sie zur PowerShell Universal-Administrationskonsole und beginnen mit der Upgrade-Validierung.
ZIP
Führen Sie die notwendigen Sicherungsverfahren durch und laden Sie das neueste ZIP von PowerShell Universal herunter.
Beenden Sie den PowerShell Universal-Dienst. Löschen Sie die vorhandenen PowerShell Universal-Anwendungsdateien. Extrahieren Sie die ZIP-Dateien in dasselbe Verzeichnis. Führen Sie schließlich Unblock-File für das Verzeichnis aus, um sicherzustellen, dass PSU ordnungsgemäß ausgeführt werden kann. Führen Sie diesen Befehl immer als Administrator aus.
Nach Abschluss des Upgrades navigieren Sie zur PowerShell Universal-Administrationskonsole und beginnen mit der Upgrade-Validierung.
Datenbank
Standardmäßig migriert der PSU-Dienst während des Startvorgangs auf die neueste Datenbankversion.
Die Datenbank kann auch vor dem Upgrade der Anwendung aktualisiert werden. Dies wird für größere Installationen empfohlen, bei denen die Schemaaktualisierung einige Zeit in Anspruch nehmen kann. In manchen Umgebungen kann es zu einer Zeitüberschreitung führen, wenn der Dienst die Datenbank aktualisiert, wie zum Beispiel beim Service Control Manager in Windows.
Wenn Sie SQL verwenden, finden Sie generierte SQL-Dateien im SQL-Ordner innerhalb des PSU-Installationsmediums. Führen Sie diese Skripte vor dem Upgrade für Ihre Datenbank aus.
Alle Arten von Datenbanken unterstützen das Befehlszeilenwerkzeug psu für Upgrades.
3. Upgrade-Validierung
Nach der Durchführung eines Upgrades sollten Sie eine grundlegende Validierung Ihres PSU-Servers durchführen, um sicherzustellen, dass er voll funktionsfähig ist.
Benachrichtigungen
Überprüfen Sie, dass im Benachrichtigungs-Dropdown keine Fehler vorhanden sind. Diese können ein Anzeichen für Probleme während des Upgrades sein.
Module
Upgrades von PowerShell Universal können die Assembly-Versionen der mit der Plattform ausgelieferten DLLs ändern. Dies kann dazu führen, dass andere Module nicht geladen werden können. Auch wenn dies zunächst nicht offensichtlich ist, sollten Sie in Erwägung ziehen, eine Bestandsaufnahme der in Ihrer Plattform verwendeten Module vorzunehmen, um sicherzustellen, dass die Versionen vor und nach dem Upgrade konsistent sind, um Änderungen zu begrenzen.
Wenn Sie eine Version des Universal-Moduls außerhalb von PowerShell Universal installiert haben (zum Beispiel mit Install-Module), müssen Sie sicherstellen, dass Sie das Modul aktualisieren, da es sonst mit dem neuen, mit PowerShell Universal installierten Modul in Konflikt geraten kann.
Apps
Die häufigsten Upgrade-Probleme entstehen durch Änderungen am Universal App Framework. Apps können komplex sein, und Fehlerbehebungen oder Funktionen können sich manchmal auf die App eines bestimmten Benutzers auswirken, während Probleme in der App eines anderen Benutzers behoben werden. Bitte lesen Sie vor dem Upgrade das Änderungsprotokoll, um die Auswirkung der am App-Framework vorgenommenen Änderungen zu verstehen, und erwägen Sie, die App mit Entwicklungsdaten zu testen, bevor Sie in der Produktion ein Upgrade durchführen.
Häufige Upgrade-Probleme
IIS-Anwendungspool startet nach dem Upgrade nicht
Das häufigste Upgrade-Problem besteht darin, dass Unblock-File bei einem Upgrade einer IIS-ZIP-Installation nicht ordnungsgemäß für die extrahierten Dateien aufgerufen wird. Stellen Sie außerdem sicher, dass Sie den Befehl Unblock-File rekursiv und aus einer administrativen Sitzung heraus ausführen.
Ein weiteres häufiges Problem ist das Extrahieren der Dateien über die vorhandenen Dateien hinweg. Dies kann Assembly-Konflikte verursachen und versetzt die Anwendung in einen unbekannten Zustand. Befolgen Sie die IIS-Upgrade-Dokumentation und löschen Sie die Dateien, bevor Sie sie extrahieren.
Fehler „Command Not Found“
Wenn PowerShell Universal um neue Funktionalität erweitert wird, geschieht dies typischerweise mit neuen Cmdlets. Wenn ältere Versionen des PowerShell Universal-Moduls auf dem System installiert sind, kann dies zu Konflikten mit dem im Installationsmedium enthaltenen Modul führen. Stellen Sie sicher, dass Sie ältere Versionen des Universal-Moduls entfernt haben, wenn Sie auf diese Fehler stoßen.
Fehler „Table\Column Not Found“ bei Verwendung von SQL-Persistenz
Dies kann passieren, wenn SQL-Schema-Upgrades während der Upgrades nicht ausgeführt werden. Wenn Sie die Einstellung RunMigrations in appsettings.json auf false setzen, müssen Sie die Migrationen manuell ausführen, andernfalls funktioniert der PowerShell Universal-Dienst nicht ordnungsgemäß.
Breaking Change bei App-Komponenten
Diese Änderungen können visueller oder funktionaler Natur sein. Bitte stellen Sie sicher, dass Sie das Änderungsprotokoll auf Einträge überprüfen, die mit der von Ihnen beobachteten Änderung zusammenhängen könnten. Erwägen Sie, im Forum zu posten oder ein GitHub-Issue zu eröffnen, um zu erfahren, ob das Verhalten beabsichtigt ist und ob es eine praktikable Problemumgehung gibt.
Lizenzprobleme nach dem Upgrade
Das Lizenzmodell von PowerShell Universal ermöglicht es lizenzierten Benutzern, auf die jeweils neueste Version zu aktualisieren, solange sie über eine aktive unbefristete Lizenz oder Abonnementlizenz verfügen. Wenn Sie versuchen, einen Server zu aktualisieren, der sich nicht mehr innerhalb des Lizenzzeitraums befindet, funktioniert der Server nicht wie erwartet. Sie müssen auf die vorherige Version zurückstufen, um die Funktionalität wiederherzustellen.
Darüber hinaus können durch den Neustart des PSU-Dienstes Probleme auftreten. Beim Starten des Dienstes wird der Status des Lizenzabonnements überprüft. Schlägt dies fehl, ist der Dienst möglicherweise nicht ordnungsgemäß lizenziert, was weitere Probleme verursachen kann. Die Ursache sind typischerweise Netzwerkprobleme beim Zugriff auf die Websites IronmanSoftware.com oder Devolutions.net zur Aktivierung. Offline-Lizenzschlüssel nutzen das Internet und werden dieses Problem nicht verursachen.
Wenn Sie ein Problem mit einer Lizenz haben, das Sie nicht lösen können, zögern Sie nicht, sich an den Devolutions Support zu wenden.
Gemischte Versionen
Das Mischen von Versionen von PowerShell Universal-Servern mit derselben Datenbank kann zu Problemen führen, da Schemaänderungen in der Datenbank oder Protokolländerungen in internen APIs möglicherweise nicht übereinstimmen. Wir empfehlen, Ihre Upgrades so zu staffeln, dass letztendlich alle PowerShell Universal-Server dieselbe Version ausführen.
Es gibt ein bekanntes Kompatibilitätsproblem zwischen PSU 5.5.4 und früher sowie PSU 5.6.0 und später. Wir empfehlen nicht, diese Versionen zu mischen. Das Planen von Aufträgen kann auf bestehenden 5.5.4-Servern fehlschlagen, wenn diese mit 5.6.0-Servern kombiniert werden.
Breaking Changes in 5.0
Entfernung von Seiten
Der Drag-and-Drop-Seitendesigner wurde zugunsten von Portalseiten und Widgets entfernt.
Entfernung des App-Seitendesigners
Der Drag-and-Drop-Seitendesigner für Apps wurde entfernt. Mit dem Designer erstellte Apps funktionieren weiterhin.
Entfernung von Zugriffskontrollen
Zugriffskontrollen wurden zugunsten von Berechtigungen entfernt. Sie können auch das Portal verwenden, um Benutzern Ressourcen wie Skripte zuzuweisen, ohne komplizierte Berechtigungen zu benötigen.
Änderungen am Cmdlet-Kommunikationskanal und an der Autorisierung
Vor v5 sendeten Cmdlets Daten über HTTP oder über einen internen gRPC-Kanal. Jetzt verwenden alle Cmdlets einen extern zugänglichen gRPC-Kanal, der durch Authentifizierung und Autorisierung geschützt ist. Es werden keine standardmäßigen REST-API-HTTP-Aufrufe mehr verwendet.
Dies kann bei PowerShell Universal-Instanzen hinter Reverse-Proxys ein Problem darstellen und erfordert, dass die richtigen Headerwerte gesendet werden.
Weitere Informationen finden Sie in der Dokumentation zum Modul.
Häufige Cmdlet-Fehler, auf die Sie während des Upgrades stoßen können
HTTP-Statuscode 403
Das von Ihnen aufgerufene Cmdlet hat keinen Zugriff auf die PowerShell Universal-APIs. Sie müssen einen -AppToken-Parameter für die Cmdlets angeben, um sie verwenden zu können.
Sie können auch das permissive API-Sicherheitsmodell aktivieren, um intern aufgerufene Cmdlets von PowerShell Universal ohne Autorisierung zuzulassen.
URI nicht definiert
Die Cmdlets können nicht bestimmen, wie die PowerShell Universal-APIs aufgerufen werden sollen. Sie müssen entweder einen -ComputerName-Parameter angeben oder die API-URL in appsettings.json einrichten.
SSL-Zertifikatsfehler
Wenn Sie ein selbstsigniertes Zertifikat verwenden, müssen Sie den Parameter -TrustCertificate der Cmdlets angeben.
Die PowerShell 7-Umgebung verwendet nicht mehr Pwsh.exe
Die standardmäßige PowerShell 7-Umgebung verwendet eine .NET-Version der ausführbaren Programmdatei Universal.Agent.exe, die PowerShell 7.5 ausführt. Dies ermöglicht die größtmögliche Kompatibilität mit PowerShell Universal-Bibliotheken und anderen Modulen.
Es ist weiterhin möglich, den pwsh.exe-Prozess in benutzerdefinierten Umgebungskonfigurationen zu verwenden.
IIS-Hosting-Paket
Wenn Sie in IIS hosten, stellen Sie sicher, dass Sie das .NET 9.0 Hosting Bundle installieren.
PowerShell-Version der integrierten Umgebung
Die integrierte Umgebung verwendet jetzt PowerShell 7.5.
SQLite standardmäßig
SQLite ist die standardmäßige Persistenzmethode. Sie müssen eine manuelle Konvertierung von LiteDB durchführen, bevor Sie Version 5 installieren.
LiteDB-Unterstützung entfernt
LiteDB wurde als unterstützte Datenbank-Engine entfernt. In den Installationsdateien von PowerShell Universal finden Sie psu.exe. Damit kann eine LiteDB-Datenbank in eine SQLite-Datenbank konvertiert werden. Verwenden Sie die folgende Befehlszeile.
Das Werkzeug erstellt eine database.bak-Datei, bevor die Konvertierung durchgeführt wird. Der Fortschritt wird in der Konsole angezeigt.
Nach der Konvertierung der Datenbank müssen Sie die Datei appsettings.json aktualisieren, um das neue SQLite-Plugin zu verwenden, und die Verbindungszeichenfolge auf ein SQLite-Format aktualisieren. Nachfolgend finden Sie einen Ausschnitt, den Sie auf Ihre Konfigurationsdatei anwenden können.
Konvertieren einer Datenbank für ein MSI-Upgrade
Damit das PowerShell Universal-Installationsprogramm erfolgreich ausgeführt werden kann, müssen Sie die Datenbank aktualisieren, bevor Sie das MSI-Installationsprogramm ausführen. Nachfolgend finden Sie die dazu erforderlichen Schritte.
Laden Sie das ZIP-Paket für Windows herunter und extrahieren Sie es in ein lokales Verzeichnis.
Stoppen Sie den PowerShell Universal-Dienst
Führen Sie den Befehl psudb.exe aus dem ZIP-Verzeichnis wie oben beschrieben aus, um die Datenbankdatei in %ProgramData%\UniversalAutomation zu konvertieren
Aktualisieren Sie die Datei %ProgramData%\PowerShellUniversal\appsettings.json, um das SQLite-Plugin anstelle des LiteDB-Plugins zu verwenden
Führen Sie das PowerShell Universal v5-Installationsprogramm aus, um die Anwendungsdateien zu aktualisieren.
Desktop-Modus entfernt
Der Desktop-Modus wurde entfernt. Ressourcen wie Tastenkombinationen, Dateizuordnungen und Verknüpfungen werden nicht mehr unterstützt. Die MSI unterstützt jetzt Installationen im Benutzerbereich, die als aktueller Benutzer ausgeführt werden und beim Anmelden starten.
Install-PSUServer unter Windows installiert aus der MSI
In früheren Versionen von PowerShell Universal installierte dieser Befehl in ein Verzeichnis und erstellte den Dienst manuell. Dieser Befehl installiert jetzt aus der MSI. Wenn Sie zuvor mit diesem Modul installiert haben, müssen Sie die bestehende Installation mit einer früheren Version des Moduls entfernen und dann mit der neuen Version des Moduls installieren.
Öffnen Sie eine neue Eingabeaufforderung und führen Sie Folgendes aus.
Git-Datenbankspeicherung entfernt
PowerShell Universal unterstützt das direkte Speichern des Git-Repositorys in der Datenbank nicht mehr. Wir empfehlen die Verwendung eines Remote-Git-Anbieters wie GitHub, GitLab oder Gitea. PowerShell Universal v5 unterstützt lokale Git-Repositorys, ohne dass eine Synchronisierung mit einem Remote erforderlich ist. Dies ermöglicht das Speichern des Dateiverlaufs direkt auf dem PowerShell Universal-Server.
Heatmap und Marker-Cluster aus New-UDMap entfernt
Karten unterstützen keine Heatmaps oder Marker-Cluster mehr.
Zuletzt aktualisiert
War das hilfreich?