> 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). # Upgrade Führen Sie ein Upgrade von PowerShell Universal sicher durch, indem Sie Daten sichern, die Upgrade-Schritte für MSI, IIS, ZIP oder Modul befolgen und den Server auf Breaking Changes prüfen. ## Überblick Dieses Dokument behandelt den Upgrade-Prozess für Produktivinstanzen von PowerShell Universal. 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 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 ](/powershell-universal/de/licensing.md#developer-license)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. {% hint style="info" %} Wenn Sie eine Deinstallation und anschließend eine Installation über das 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 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](/powershell-universal/de/config/hosting/hosting-iis.md). #### 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. {% hint style="info" %} Wie bei jeder Installation aus einer ZIP-Datei sollten Sie sicherstellen, dass Sie `Get-ChildItem -Recurse | Unblock-File` in einer 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 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. ```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 ``` 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. ```powershell Get-ChildItem -Recurse | Unblock-File ``` 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. ```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, 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. {% hint style="info" %} Wir bemühen uns nach besten Kräften, die Apps aller Benutzer ohne Breaking Changes zu unterstützen. Dennoch ist jede Konfiguration ziemlich einzigartig, daher kümmern wir uns gerne um Probleme, auf die Sie stoßen. Bitte lassen Sie es uns einfach wissen. {% endhint %} ### 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-Diensts Probleme auftreten. Beim Start des Diensts 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 in der Regel Netzwerkprobleme beim Zugriff auf die Websites IronmanSoftware.com oder Devolutions.net zur Aktivierung. Offline-Lizenzschlüssel nutzen das Internet nicht und sind von diesem Problem nicht betroffen. Wenn Sie ein Problem mit einer Lizenz haben, das Sie nicht lösen können, zögern Sie nicht, sich an den [Devolutions Support](mailto:service@devolutions.net) 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. {% 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 bestehenden 5.5.4-Servern fehlschlagen, wenn diese mit 5.6.0-Servern kombiniert werden. {% endhint %} ## Breaking Changes in 5.0 ### Entfernung von Seiten Der Drag-and-Drop-Seitendesigner wurde zugunsten von [Portalseiten](/powershell-universal/de/portal/portal-pages.md) und [Widgets](/powershell-universal/de/portal/portal-widgets.md) 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 Access Controls wurden zugunsten von [Berechtigungen](/powershell-universal/de/sicherheit/enterprise-security/permissions.md) entfernt. Sie können auch das [Portal ](/powershell-universal/portal/portal.md)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](/powershell-universal/de/config/hosting/reverse-proxy.md) ein Problem darstellen und erfordert, dass die richtigen Headerwerte gesendet werden. Weitere Informationen finden Sie in der Dokumentation zum [Modul](/powershell-universal/de/config/module.md). #### 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](/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 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. ```json { "API" : { "URL": "http://localhost:5000" } } ``` #### 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](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 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. ```powershell .\psu.exe db convert --Path "$ENV:ProgramData\UniversalAutomation\database.db" ``` 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. ```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 dazu erforderlichen Schritte. 1. Laden Sie das ZIP-Paket für Windows herunter und extrahieren Sie es in ein lokales Verzeichnis. 2. Stoppen Sie den PowerShell Universal-Dienst 3. Führen Sie den Befehl psu.exe wie oben beschrieben aus dem ZIP-Verzeichnis 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 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. ```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 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. --- # 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.