> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/getting-started/upgrading.md). # Aktualisieren ## Überblick Dieses Dokument behandelt den Upgrade-Prozess für PowerShell Universal-Produktionsinstanzen. Wir behandeln die folgenden Themen. 1. Datensicherung 2. Upgrade-Prozess 3. Upgrade-Validierung Die Universal-Anwendungsbinärdateien können in der Regel aktualisiert werden, ohne dass die Konfiguration oder Datenbank manuell geändert werden muss, wir empfehlen jedoch Backups der Produktionsdaten. ## Empfehlungen Für Produktionsumgebungen 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 ](/powershell-universal/de/licensing.md#developer-licenses)verwenden, um Änderungen in PowerShell Universal-Instanzen zu testen, ohne eine weitere Lizenz zu kaufen. ## 1. Datensicherung PowerShell Universal verwendet ein skriptbasiertes Konfigurationssystem sowie eine Datenbank zur Aufbewahrung von Entitäten wie App-Tokens, Auftragsverlauf und Identitäten. Wenn möglich, sollten Sie diese Elemente vor der Durchführung eines Upgrades sichern, um im Falle eines Problems während der Validierung ein einfaches Rollback durchführen 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. Bei SQL-Datenbanken kann sich außerdem das Schema der Datenbank ändern, sodass nicht nur ein Rollback der Daten, sondern auch des Schemas der Tabellen in der Datenbank erforderlich sein kann. #### SQLite Standardmäßig verwendet PowerShell Universal eine Einzeldatei-Datenbank namens SQLite. Sofern nicht anders konfiguriert, wird die Datenbank in `%ProgramData%\UniversalAutomation` gespeichert. Sie sollten eine `database.db` und möglicherweise eine `database-log.db` haben. Beide Dateien sollten gesichert werden. Der Dienst muss gestoppt 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 stoppen, aber er schreibt möglicherweise weiterhin in die Datenbank (zum Beispiel beim Ausführen geplanter Aufträge), nachdem die Sicherung abgeschlossen wurde. ### Konfigurationsskripte Skripte stellen die wichtigsten Konfigurationsdaten dar, die beim Upgrade einer PowerShell Universal-Produktionsinstanz gesichert werden sollten. Für die Produktion empfehlen wir die Verwendung eines Versionskontrollsystems. Sie können auch die integrierte Git-Integration nutzen. Wenn Sie eine bidirektionale Synchronisierung für die PowerShell Universal-Git-Integration verwenden, sollten Sie erwägen, Ihren Git-Branch vor dem Upgrade zu taggen, um ein einfaches Rollback bei unerwarteten Änderungen im Git-Repository zu ermöglichen. ## 2. Upgrade-Fortschritt Nachfolgend finden Sie Abschnitte für jeden Typ von Systemupgrade und die Schritte, die Sie abhängig von Ihrer ursprünglichen PSU-Installation durchführen sollten. ### MSI Bei der Installation über die MSI sollten Sie die gleichen Backup-Verfahren wie oben befolgen. #### appsettings.json Sie sollten die Datei `appsettings.json` sichern, die in `%ProgramData%\PowerShellUniversal` gespeichert ist. Diese Datei enthält Informationen wie Port, Datenspeicherort und andere Servereinstellungen. Normalerweise nimmt die MSI keine Änderungen an dieser Datei vor, nachdem sie erstellt wurde. Sie verwendet die Einstellungen, die für die aktualisierte Version gefunden werden. Dennoch nimmt die MSI, falls erforderlich, Änderungen an der appsettings-Datei vor. Diese Änderungen gelten als Breaking Changes und werden im Changelog für das Release aufgeführt. #### Dienstkonto Beim Durchführen eines MSI-Upgrades wird der PSU-Dienst nicht deinstalliert, sodass das Dienstkonto weiterhin gesetzt ist, sobald der Dienst startet. {% hint style="info" %} Wenn Sie eine Deinstallation und anschließend eine Installation über die MSI durchführen, wird das Dienstkonto entfernt. {% endhint %} #### 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 Computers an, wenn Dateien gesperrt sind. Die PSU-MSI deinstalliert alle Dateien im Installationsverzeichnis und installiert vollständig neue Dateien. Sobald die 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 `web.config`-Datei, die im Installationsverzeichnis der Anwendung enthalten ist, wird während Upgrades überschrieben. Wenn Sie Ihre web.config-Datei an einen anderen Ort verschoben haben, wird sie nicht überschrieben. Beim Erstellen einer IIS-Website können Sie die `web.config`-Datei einfach in das Verzeichnis der Webanwendung legen und die [Binärdateien an einem anderen Ort speichern](/powershell-universal/de/config/hosting/hosting-iis.md). #### Upgrade-Prozess Beim Upgrade mit IIS müssen Sie zunächst Ihren Anwendungspool stoppen, um sicherzustellen, dass die von IIS verwendeten Binärdateien nicht mehr in Verwendung sind, und dann die Binärdateien durch die neuen ersetzen. Um sicherzustellen, dass das Upgrade wie erwartet funktioniert, wird empfohlen, alle Anwendungsdateien zu löschen und anschließend die neuen in dasselbe Verzeichnis zu entpacken, um Assembly-Konflikte zu vermeiden. {% hint style="info" %} Wie bei jeder Installation aus einer ZIP-Datei sollten Sie sicherstellen, dass Sie `Get-ChildItem -Recurse | Unblock-File` über eine Eingabeaufforderung mit erhöhten Rechten für die PowerShell Universal-Dateien ausführen, damit diese ordnungsgemäß ausgeführt werden können. {% endhint %} 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. {% hint style="warning" %} Verwenden Sie das Universal-Modul nicht, um Instanzen zu aktualisieren, die über MSI installiert wurden. {% endhint %} Befolgen Sie die oben beschriebenen Backup-Verfahren 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. ```powershell Update-Module Devolutions.PowerShellUniversal Import-Module Devolutions.PowerShellUniversal -PassThru ``` Führen Sie als Nächstes `Update-PSUServer` aus, um die neue PSU-Instanz herunterzuladen und zu entpacken. ```powershell Update-PSUServer ``` Navigieren Sie nach Abschluss des Upgrades zur PowerShell Universal-Administrationskonsole und beginnen Sie mit der Upgrade-Validierung. ### ZIP Führen Sie die notwendigen Backup-Verfahren durch und laden Sie die neueste ZIP-Datei von PowerShell Universal herunter. Stoppen 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. ```powershell Get-ChildItem -Recurse | Unblock-File ``` Navigieren Sie nach Abschluss des Upgrades zur PowerShell Universal-Administrationskonsole und beginnen Sie 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 einem Timeout 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 Datenbanktypen unterstützen das Befehlszeilentool `psu` für Upgrades. ```powershell psu db schema latest --connection-string "Data Source=C:\ProgramData\UniversalAutomation\database.db" ``` ## 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, ob 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 Inventur 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 andernfalls 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 Bugfixes oder Funktionen können manchmal Probleme in der App eines bestimmten Benutzers verursachen, während sie Probleme in der App eines anderen Benutzers beheben. Bitte lesen Sie das Changelog vor dem Upgrade, um die Auswirkung der am App-Framework vorgenommenen Änderungen zu verstehen, und ziehen Sie in Erwägung, die App mit Entwicklungsdaten zu testen, bevor Sie in der Produktion aktualisieren. ## 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 innerhalb einer administrativen Sitzung ausführen. Ein weiteres häufiges Problem ist das Extrahieren der Dateien über die vorhandenen Dateien. Dies kann Assembly-Konflikte verursachen und die Anwendung in einen unbekannten Zustand versetzen. Befolgen Sie die IIS-Upgrade-Dokumentation und löschen Sie die Dateien, bevor Sie sie extrahieren. ### Fehler „Befehl nicht gefunden“ Wenn PowerShell Universal neue Funktionalität hinzugefügt wird, geschieht dies typischerweise über neue 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 „Tabelle\Spalte nicht gefunden“ bei Verwendung von SQL-Persistenz Dies kann auftreten, wenn SQL-Schemaupgrades 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 visuell oder funktional sein. Bitte stellen Sie sicher, dass Sie das Changelog auf Einträge überprüfen, die mit der von Ihnen beobachteten Änderung zusammenhängen könnten. Ziehen Sie in Erwägung, im Forum zu posten oder ein GitHub-Issue zu eröffnen, um herauszufinden, ob das Problem so beabsichtigt ist und ob es eine praktikable Problemumgehung gibt. {% hint style="info" %} Wir bemühen uns bestmöglich, die Apps aller Benutzer ohne Breaking Changes zu unterstützen. Dennoch ist jede Konfiguration einzigartig, weshalb wir Probleme, auf die Sie stoßen, gerne beheben. Teilen Sie es uns einfach mit. {% endhint %} ### Lizenzprobleme nach dem Upgrade Das Lizenzmodell von PowerShell Universal bietet lizenzierten Benutzern die Möglichkeit, auf die jeweils neueste Version zu aktualisieren, solange sie eine aktive Dauer- oder Abonnementlizenz besitzen. Wenn Sie versuchen, einen Server zu aktualisieren, der sich nicht mehr innerhalb des Lizenzzeitraums befindet, funktioniert der Server nicht wie erwartet. Sie müssen dann ein Downgrade auf die vorherige Version durchführen, um die Funktionalität wiederherzustellen. Darüber hinaus können aufgrund des Neustarts des PSU-Dienstes Probleme auftreten. Beim Start des Dienstes wird der Status des Lizenzabonnements überprüft. Wenn dies nicht möglich ist, ist der Dienst möglicherweise nicht ordnungsgemäß lizenziert und verursacht weitere Probleme. Die Ursache sind typischerweise Netzwerkprobleme beim Versuch, für die Aktivierung auf die Website IronmanSoftware.com zuzugreifen. Offline-Lizenzschlüssel kontaktieren die IMS-Website nicht zur Aktivierung und sind von diesem Problem nicht betroffen. ### 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 nicht übereinstimmen können. Wir empfehlen, Ihre Upgrades so zu staffeln, dass letztlich alle PowerShell Universal-Server in derselben Version ausgeführt werden. {% hint style="warning" %} 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 vorhandenen 5.5.4-Servern fehlschlagen, wenn diese mit 5.6.0-Servern kombiniert werden. {% endhint %} ## Breaking Changes in 5.0 ### Entfernung von Pages Der Drag-and-Drop-Seitendesigner wurde zugunsten von [Portal Pages](/powershell-universal/de/portal/portal-pages.md) und [Widgets](/powershell-universal/de/portal/portal-widgets.md) entfernt. ### Entfernung des App Pages-Designers Der Drag-and-Drop-Seitendesigner für Apps wurde entfernt. Mit dem Designer erstellte Apps funktionieren weiterhin. ### Entfernung von Access Controls Access Controls wurden zugunsten von [Berechtigungen](/powershell-universal/de/sicherheit/enterprise-security/permissions.md) entfernt. Sie können auch das [Portal ](https://github.com/Devolutions/docs/tree/master/translations/de/powershell-universal/getting-started/broken-reference/README.md)verwenden, um Benutzern Ressourcen wie Skripte zuzuweisen, ohne komplizierte Berechtigungen zu benötigen. ### Änderungen am Kommunikationskanal und der Autorisierung von Cmdlets Vor v5 sendeten Cmdlets Daten über HTTP oder über einen internen gRPC-Kanal. Nun verwenden alle Cmdlets einen extern ausgerichteten gRPC-Kanal, der durch Authentifizierung und Autorisierung geschützt ist. Es werden keine standardmäßigen REST-API-HTTP-Aufrufe mehr verwendet. Dies kann für PowerShell Universal-Instanzen hinter [Reverse-Proxys](/powershell-universal/de/config/hosting/reverse-proxy.md) ein Problem darstellen und erfordert, dass die korrekten Header-Werte gesendet werden. Weitere Informationen finden Sie in der [Modul](/powershell-universal/de/config/module.md)-Dokumentation. #### Häufige Cmdlet-Fehler, die während des Upgrades auftreten 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](/powershell-universal/de/config/module.md#authorization-security-model) aktivieren, um intern aufgerufene Cmdlets von PowerShell Universal ohne Autorisierung zuzulassen. #### URI nicht definiert Die Cmdlets können nicht ermitteln, wie die PowerShell Universal-APIs aufgerufen werden sollen. Sie müssen entweder einen -ComputerName-Parameter angeben oder die API-URL in appsettings.json einrichten. ```json { "API" : { "URL": "http://localhost:5000" } } ``` #### SSL-Zertifikatsfehler Wenn Sie ein selbstsigniertes Zertifikat verwenden, müssen Sie den Parameter `-TrustCertificate` der Cmdlets angeben. ### PowerShell 7-Umgebung verwendet Pwsh.exe nicht mehr 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ößte 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](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-9.0.4-windows-hosting-bundle-installer) installieren. ### PowerShell-Version der integrierten Umgebung Die integrierte Umgebung verwendet nun 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. ```powershell .\psu.exe db convert --Path "$ENV:ProgramData\UniversalAutomation\database.db" ``` Das Tool 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. Unten finden Sie ein Snippet, das Sie auf Ihre Konfigurationsdatei anwenden können. ```json { "Plugins": [ "SQLite" ], "Data": { "ConnectionString": "Data Source=C:\ProgramData\UniversalAutomation\database.db" } } ``` #### 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 dafür erforderlichen Schritte. 1. Laden Sie das ZIP-Paket für Windows herunter und extrahieren Sie es in ein lokales Verzeichnis. 2. Beenden Sie den PowerShell Universal-Dienst 3. Führen Sie den Befehl psudb.exe aus dem ZIP-Verzeichnis wie oben angegeben aus, um die Datenbankdatei in %ProgramData%\UniversalAutomation zu konvertieren 4. Aktualisieren Sie die Datei %ProgramData%\PowerShellUniversal\appsettings.json, um das SQLite-Plugin anstelle des LiteDB-Plugins zu verwenden 5. Führen Sie das Installationsprogramm von PowerShell Universal v5 aus, um die Anwendungsdateien zu aktualisieren. ### Desktop-Modus entfernt Der Desktop-Modus wurde entfernt. Ressourcen wie Hotkeys, Dateizuordnungen und Verknüpfungen werden nicht mehr unterstützt. Die MSI unterstützt nun 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 nun aus der MSI. Wenn Sie zuvor mit diesem Modul installiert haben, müssten Sie die bestehende Installation mit einer früheren Version des Moduls entfernen und dann mit der neuen Version des Moduls installieren. ```powershell Install-Module Universal -RequiredVersion 4.4.0 Remove-PSUServer ``` Öffnen Sie eine neue Eingabeaufforderung und führen Sie Folgendes aus. ```powershell Uninstall-Module Devolutions.PowerShellUniversal Install-Module Devolutions.PowerShellUniversal Install-PSUServer ``` ### Git-Datenbankspeicherung entfernt PowerShell Universal unterstützt das Speichern des Git-Repositorys direkt 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/de/getting-started/upgrading.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.