> 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/it/getting-started/upgrading.md). # Aggiornamento ## Panoramica Questo documento illustrerà il processo di aggiornamento per le istanze di PowerShell Universal in produzione. Tratteremo i seguenti argomenti. 1. Backup dei dati 2. Processo di aggiornamento 3. Convalida dell'aggiornamento I binari dell'applicazione Universal possono in genere essere aggiornati senza dover modificare manualmente la configurazione o il database, ma consigliamo di eseguire il backup dei dati di produzione. ## Raccomandazioni Per gli ambienti di produzione, consigliamo di distribuire PowerShell Universal in un ambiente di staging o di sviluppo prima degli aggiornamenti principali. Ciò consente di effettuare test prima che gli utenti finali ne siano interessati. È possibile utilizzare le [licenze di sviluppo ](/powershell-universal/it/licensing.md#developer-license)per testare le modifiche nelle istanze di PowerShell Universal senza acquistare un'altra licenza. ## 1. Backup dei dati PowerShell Universal utilizza un sistema di configurazione basato su script insieme a un database utilizzato per la conservazione di entità come app token, cronologia dei processi e identità. Se possibile, è consigliabile eseguire il backup di questi elementi prima di eseguire un aggiornamento, per facilitare il rollback nel caso in cui si verifichi un problema durante la convalida. ### Database Il backup del database garantisce che tutti gli apptoken, la cronologia dei processi, le identità e i segreti del database vengano conservati in caso di aggiornamento non riuscito. I database SQL possono anche modificare lo schema del database e potrebbero richiedere un rollback non solo dei dati, ma anche dello schema delle tabelle nel database. #### SQLite Per impostazione predefinita, PowerShell Universal utilizza un database a file singolo chiamato SQLite. Se non configurato diversamente, il database viene archiviato in `%ProgramData%\UniversalAutomation`. Dovrebbero essere presenti un file `database.db` ed eventualmente un `database-log.db`. Entrambi i file devono essere sottoposti a backup. Il servizio deve essere arrestato per poter eseguire il backup dei file. #### SQL Quando si utilizza SQL per la persistenza, eseguire il backup dell'intero database (incluso lo schema). Non è necessariamente richiesto arrestare il servizio PowerShell Universal durante il backup del database, ma quest'ultimo potrebbe continuare a scrivere nel database (ad esempio durante l'esecuzione di processi pianificati) dopo il completamento del backup. ### Script di configurazione Gli script costituiscono i principali dati di configurazione di cui eseguire il backup quando si aggiorna un'istanza di PowerShell Universal in produzione. Per la produzione, consigliamo di utilizzare un sistema di controllo delle versioni. È inoltre possibile sfruttare l'integrazione git integrata. Se si utilizza una sincronizzazione bidirezionale per l'integrazione git di PowerShell Universal, valutare di applicare un tag al ramo git prima dell'aggiornamento per consentire un facile rollback in caso di modifiche impreviste all'interno del repository git. ## 2. Avanzamento dell'aggiornamento Di seguito sono riportate le sezioni per ogni tipo di aggiornamento del sistema e i passaggi da eseguire in base alla modalità di installazione originale di PSU. ### MSI Quando si installa tramite MSI, è necessario seguire le stesse procedure di backup descritte sopra. #### appsettings.json È consigliabile eseguire il backup del file `appsettings.json` archiviato in `%ProgramData%\PowerShellUniversal`. Questo file contiene informazioni come la porta, la posizione di archiviazione dei dati e altre impostazioni del server. In genere, l'MSI non apporta modifiche a questo file una volta creato. Utilizzerà le impostazioni trovate per la versione aggiornata. Detto questo, se necessario, l'MSI apporterà modifiche al file appsettings. Queste modifiche sono considerate incompatibili e saranno elencate nel changelog della versione. #### Account del servizio Quando si esegue un aggiornamento MSI, il servizio PSU non viene disinstallato e quindi l'account del servizio rimarrà impostato all'avvio del servizio. {% hint style="info" %} Se si esegue una disinstallazione e poi un'installazione tramite MSI, l'account del servizio verrà rimosso. {% endhint %} #### Processo di aggiornamento Una volta eseguito il backup di tutti i file di configurazione e del database, è possibile eseguire il nuovo programma di installazione MSI. Il programma di installazione potrebbe richiedere il riavvio della macchina se i file sono bloccati. L'MSI di PSU disinstallerà tutti i file nella directory di installazione e installerà file completamente nuovi. Una volta completato l'MSI, è possibile accedere alla console di amministrazione di PowerShell Universal per eseguire la convalida dell'installazione. ### IIS Di seguito sono riportate informazioni sull'aggiornamento di un'installazione IIS. #### web.config Oltre ai file elencati sopra di cui eseguire il backup, è consigliabile considerare anche il backup del file `web.config`. Se non sono state apportate modifiche a questo file, non è necessario eseguirne il backup. Il file `web.config` incluso nella directory di installazione dell'applicazione verrà sovrascritto durante gli aggiornamenti. Se il file web.config è stato spostato in una posizione alternativa, non verrà sovrascritto. Quando si crea un sito web IIS, è sufficiente includere il file `web.config` nella directory dell'applicazione web e mantenere i [binari archiviati in una posizione diversa](/powershell-universal/it/config/hosting/hosting-iis.md). #### Processo di aggiornamento Quando si esegue l'aggiornamento con IIS, sarà necessario prima arrestare il pool di applicazioni per garantire che i binari utilizzati da IIS non siano più in uso e quindi sostituire i binari con quelli nuovi. Per garantire che l'aggiornamento funzioni come previsto, si consiglia di eliminare tutti i file dell'applicazione e quindi decomprimere i nuovi nella stessa directory per evitare conflitti tra assembly. {% hint style="info" %} Come per qualsiasi installazione da un file ZIP, assicurarsi di eseguire `Get-ChildItem -Recurse | Unblock-File` da un prompt dei comandi con privilegi elevati sui file di PowerShell Universal per garantire che possano essere eseguiti correttamente. {% endhint %} Dopo aver copiato i nuovi file e averli sbloccati, avviare il pool di applicazioni, accedere alla console di amministrazione di PowerShell Universal ed eseguire la convalida dell'installazione. ### Modulo Universal Il modulo Universal può essere utilizzato per aggiornare le installazioni di PowerShell Universal precedentemente installate tramite il modulo. {% hint style="warning" %} Non utilizzare il modulo Universal per aggiornare le istanze installate tramite MSI. {% endhint %} Seguire le procedure di backup descritte sopra ed eseguire quindi l'aggiornamento. Innanzitutto, aggiornare il modulo PowerShell Universal locale e verificare che sia installata la versione prevista. ```powershell Update-Module Devolutions.PowerShellUniversal Import-Module Devolutions.PowerShellUniversal -PassThru ``` Successivamente, eseguire `Update-PSUServer` per scaricare e decomprimere la nuova istanza di PSU. ```powershell Update-PSUServer ``` Al termine dell'aggiornamento, accedere alla console di amministrazione di PowerShell Universal e iniziare la convalida dell'aggiornamento. ### ZIP Eseguire le procedure di backup necessarie e scaricare l'ultimo ZIP di PowerShell Universal. Arrestare il servizio PowerShell Universal. Eliminare i file dell'applicazione PowerShell Universal esistenti. Estrarre i file ZIP nella stessa directory. Infine, eseguire `Unblock-File` sulla directory per garantire che PSU possa essere eseguito correttamente. Eseguire sempre questo comando come amministratore. ```powershell Get-ChildItem -Recurse | Unblock-File ``` Al termine dell'aggiornamento, accedere alla console di amministrazione di PowerShell Universal e iniziare la convalida dell'aggiornamento. ### Database Per impostazione predefinita, il servizio PSU eseguirà la migrazione all'ultima versione del database durante il processo di avvio. Il database può anche essere aggiornato prima di aggiornare l'applicazione. Ciò è consigliato per installazioni di grandi dimensioni che potrebbero richiedere del tempo per l'aggiornamento dello schema. In alcuni ambienti, consentire al servizio di aggiornare il database può causare un timeout, come con Service Control Manager in Windows. Se si utilizza SQL, è possibile trovare i file SQL generati e collocati nella cartella SQL all'interno del supporto di installazione di PSU. Eseguire questi script sul database prima dell'aggiornamento. Tutti i tipi di database supportano lo strumento da riga di comando `psu` per gli aggiornamenti. ```powershell psu db schema latest --connection-string "Data Source=C:\ProgramData\UniversalAutomation\database.db" ``` ## 3. Convalida dell'aggiornamento Dopo aver eseguito un aggiornamento, è necessario eseguire una convalida di base sul server PSU per assicurarsi che sia pienamente funzionante. ### Notifiche Verificare che non siano presenti errori nel menu a discesa delle notifiche. Potrebbero essere un segno di problemi durante l'aggiornamento. ### Moduli Gli aggiornamenti di PowerShell Universal possono modificare le versioni degli assembly delle DLL fornite con la piattaforma. Ciò può causare il mancato caricamento di altri moduli. Anche se all'inizio potrebbe non essere evidente, è consigliabile fare un inventario dei moduli utilizzati nella piattaforma per assicurarsi che le versioni siano coerenti prima e dopo l'aggiornamento, in modo da limitare le modifiche. Se è stata installata una versione del modulo `Universal` al di fuori di PowerShell Universal (ad esempio, con `Install-Module`), è necessario assicurarsi di aggiornare il modulo, altrimenti può entrare in conflitto con quello nuovo installato con PowerShell Universal. ### App I problemi di aggiornamento più comuni derivano da modifiche al framework Universal App. Le app possono essere complesse e le correzioni di bug o le funzionalità a volte possono causare problemi per l'app di un determinato utente mentre risolvono problemi relativi all'app di un altro utente. Legga il changelog prima di eseguire l'aggiornamento per comprendere l'impatto delle modifiche apportate al framework delle app e valuti di testare l'app con dati di sviluppo prima di eseguire l'aggiornamento in produzione. ## Problemi comuni di aggiornamento ### Il pool di applicazioni IIS non si avvia dopo l'aggiornamento Il problema di aggiornamento più comune è che `Unblock-File` non viene chiamato correttamente sui file estratti durante l'aggiornamento di un'installazione ZIP su IIS. Assicurarsi inoltre di eseguire il comando `Unblock-File` in modo ricorsivo e da una sessione amministrativa. Un altro problema comune è l'estrazione dei file sopra quelli esistenti. Ciò può causare conflitti tra assembly e mette l'applicazione in uno stato sconosciuto. Segua la documentazione sull'aggiornamento di IIS ed elimini i file prima di estrarli. ### Errori di comando non trovato Quando vengono aggiunte nuove funzionalità a PowerShell Universal, ciò avviene in genere utilizzando nuovi cmdlet. Se nel sistema sono installate versioni precedenti del modulo PowerShell Universal, ciò può causare conflitti con quello incluso nel supporto di installazione. Si assicuri di aver rimosso le versioni precedenti del modulo `Universal` se riscontra questi errori. ### Errore di tabella\colonna non trovata quando si utilizza la persistenza SQL Ciò può accadere se gli aggiornamenti dello schema SQL non vengono eseguiti durante gli aggiornamenti. Se si imposta `RunMigrations` su `false` in `appsettings.json`, è necessario eseguire manualmente le migrazioni, altrimenti il servizio PowerShell Universal non funzionerà correttamente. ### Modifica incompatibile a un componente dell'app Queste modifiche possono essere visive o funzionali. Si assicuri di esaminare il changelog per elementi che potrebbero essere correlati alla modifica riscontrata. Valuti di pubblicare un messaggio sui forum o di aprire una issue su GitHub per verificare se il problema è voluto e se esiste una soluzione alternativa praticabile. {% hint style="info" %} Facciamo il massimo sforzo possibile per supportare le app di tutti senza modifiche incompatibili. Detto ciò, ogni configurazione è piuttosto unica, quindi siamo più che felici di affrontare i problemi che potrebbe riscontrare. La preghiamo semplicemente di farcelo sapere. {% endhint %} ### Problemi di licenza dopo l'aggiornamento Il modello di licenza di PowerShell Universal offre agli utenti con licenza la possibilità di eseguire l'aggiornamento alla versione più recente, purché dispongano di una licenza perpetua o in abbonamento attiva. Se si tenta di aggiornare un server che non rientra più nella finestra di licenza, il server non funzionerà come previsto. Sarà necessario tornare alla versione precedente per ripristinare la funzionalità. Inoltre, potrebbero verificarsi problemi dovuti al riavvio del servizio PSU. Quando il servizio si avvia, verifica lo stato dell'abbonamento della licenza. Se non riesce a farlo, potrebbe non essere concesso in licenza correttamente e causare altri problemi. La causa principale è in genere costituita da problemi di rete durante il tentativo di accedere ai siti web IronmanSoftware.com o Devolutions.net per l'attivazione. Le chiavi di licenza offline utilizzano internet e non riscontreranno questo problema. Se riscontra un problema con una licenza che non riesce a risolvere, non esiti a contattare il [supporto Devolutions](mailto:service@devolutions.net). ### Versioni miste La combinazione di versioni diverse di server PowerShell Universal con lo stesso database può causare problemi, poiché le modifiche allo schema del database o le modifiche al protocollo nelle API interne potrebbero non corrispondere. Consigliamo di pianificare gli aggiornamenti in modo da eseguire alla fine tutti i server PowerShell Universal con la stessa versione. {% hint style="warning" %} Esiste un problema di compatibilità noto tra PSU 5.5.4 e versioni precedenti e PSU 5.6.0 e versioni successive. Non consigliamo di combinare queste versioni. La pianificazione dei processi potrebbe non riuscire sui server 5.5.4 esistenti quando combinati con server 5.6.0. {% endhint %} ## Modifiche incompatibili in 5.0 ### Rimozione delle pagine Il designer di pagine con trascinamento della selezione è stato rimosso in favore di [Portal Pages](/powershell-universal/it/portale/portal-pages.md) e [Widget](/powershell-universal/it/portale/portal-widgets.md). ### Rimozione del designer di pagine delle app Il designer di pagine con trascinamento della selezione per le app è stato rimosso. Le app create con il designer continueranno a funzionare. ### Rimozione dei controlli di accesso I controlli di accesso sono stati rimossi in favore delle [autorizzazioni](/powershell-universal/it/sicurezza/enterprise-security/permissions.md). È inoltre possibile utilizzare il [portale ](https://github.com/Devolutions/docs/tree/master/translations/it/powershell-universal/getting-started/broken-reference/README.md)per assegnare risorse, come gli script, agli utenti senza la necessità di autorizzazioni complicate. ### Modifiche al canale di comunicazione e all'autorizzazione dei cmdlet Prima della v5, i cmdlet inviavano dati tramite HTTP o utilizzando un canale gRPC interno. Ora, tutti i cmdlet utilizzano un canale gRPC rivolto verso l'esterno protetto da autenticazione e autorizzazione. Non utilizza più le chiamate HTTP standard delle API REST. Questo può rappresentare un problema per le istanze di PowerShell Universal dietro [reverse proxy](/powershell-universal/it/config/hosting/reverse-proxy.md) e richiede che vengano inviati i valori di intestazione corretti. Consulti la documentazione del [modulo ](/powershell-universal/it/config/module.md)per maggiori informazioni. #### Errori comuni dei cmdlet che potrebbe riscontrare durante l'aggiornamento #### Codice di stato HTTP 403 Il cmdlet chiamato non ha accesso alle API di PowerShell Universal. Sarà necessario specificare un parametro -AppToken sui cmdlet per poterli utilizzare. È inoltre possibile abilitare il [modello di sicurezza API permissivo](/powershell-universal/it/config/module.md#authorization-security-model) per consentire i cmdlet chiamati internamente da PowerShell Universal senza la necessità di autorizzazione. #### URI non definito I cmdlet non sono in grado di determinare come chiamare le API di PowerShell Universal. Sarà necessario specificare un parametro -ComputerName oppure configurare l'URL dell'API in appsettings.json. ```json { "API" : { "URL": "http://localhost:5000" } } ``` #### Errore del certificato SSL Se si utilizza un certificato autofirmato, sarà necessario specificare il parametro `-TrustCertificate` dei cmdlet. ### L'ambiente PowerShell 7 non utilizza più Pwsh.exe L'ambiente PowerShell 7 predefinito utilizza una versione .NET dell'eseguibile Universal.Agent.exe che esegue PowerShell 7.5. Ciò consente la massima compatibilità con le librerie di PowerShell Universal e altri moduli. È ancora possibile utilizzare il processo pwsh.exe nelle configurazioni di ambiente personalizzate. ### Pacchetto di hosting IIS Se si esegue l'hosting in IIS, assicurarsi di installare l'[hosting bundle .NET 9.0](https://dotnet.microsoft.com/en-us/download/dotnet/thank-you/runtime-aspnetcore-9.0.4-windows-hosting-bundle-installer). ### Versione di PowerShell dell'ambiente integrato L'ambiente integrato ora utilizza PowerShell 7.5. ### SQLite per impostazione predefinita SQLite è il metodo di persistenza predefinito. Sarà necessario eseguire una conversione manuale da LiteDB prima di installare la versione 5. ### Supporto di LiteDB rimosso LiteDB è stato rimosso come motore di database supportato. Insieme ai file di installazione di PowerShell Universal, troverà `psu.exe`. Può essere utilizzato per convertire un database LiteDB in un database SQLite. Utilizzi la seguente riga di comando. ```powershell .\psu.exe db convert --Path "$ENV:ProgramData\UniversalAutomation\database.db" ``` Lo strumento creerà un file `database.bak` prima di eseguire la conversione. L'avanzamento sarà riportato nella console. Dopo aver convertito il database, sarà necessario aggiornare il file `appsettings.json` per utilizzare il nuovo plugin SQLite e aggiornare la stringa di connessione a un formato SQLite. Di seguito è riportato uno snippet che può applicare al proprio file di configurazione. ```json { "Plugins": [ "SQLite" ], "Data": { "ConnectionString": "Data Source=C:\ProgramData\UniversalAutomation\database.db" } } ``` #### Conversione di un database per un aggiornamento MSI Affinché il programma di installazione di PowerShell Universal venga eseguito correttamente, è necessario aggiornare il database prima di eseguire il programma di installazione MSI. Di seguito sono riportati i passaggi da seguire. 1. Scarichi il pacchetto ZIP per Windows ed estragga il contenuto in una directory locale. 2. Arresti il servizio PowerShell Universal 3. Esegua il comando psudb.exe dalla directory dello ZIP, come indicato sopra, per convertire il file di database in %ProgramData%\UniversalAutomation 4. Aggiorni il file %ProgramData%\PowerShellUniversal\appsettings.json per utilizzare il plugin SQLite anziché il plugin LiteDB 5. Esegua il programma di installazione di PowerShell Universal v5 per aggiornare i file dell'applicazione. ### Modalità desktop rimossa La modalità desktop è stata rimossa. Risorse come tasti di scelta rapida, associazioni di file e collegamenti non sono più supportate. L'MSI ora supporta installazioni con ambito utente che vengono eseguite come utente corrente e si avviano al login. ### Install-PSUServer su Windows installa dall'MSI Nelle versioni precedenti di PowerShell Universal, questo comando eseguiva l'installazione in una directory e creava il servizio manualmente. Ora questo comando esegue l'installazione dall'MSI. Se ha effettuato l'installazione in precedenza con questo modulo, dovrà rimuovere l'installazione esistente con una versione precedente del modulo e poi eseguire l'installazione con la nuova versione del modulo. ```powershell Install-Module Universal -RequiredVersion 4.4.0 Remove-PSUServer ``` Apra un nuovo prompt dei comandi ed esegua quanto segue. ```powershell Uninstall-Module Devolutions.PowerShellUniversal Install-Module Devolutions.PowerShellUniversal Install-PSUServer ``` ### Archiviazione del database Git rimossa PowerShell Universal non supporta più l'archiviazione del repository git direttamente nel database. Consigliamo di utilizzare un provider git remoto come GitHub, GitLab o Gitea. PowerShell Universal v5 supporta i repository git locali senza la necessità di sincronizzarsi con un remoto. Ciò consente di archiviare la cronologia dei file direttamente sul server PowerShell Universal. ### Rimossi heatmap e marker cluster da New-UDMap Le mappe non supportano più le heatmap o i marker cluster. --- # 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/it/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.