Aggiornamento
Panoramica
Questo documento illustrerà il processo di aggiornamento per le istanze di PowerShell Universal in produzione. Tratteremo i seguenti argomenti.
Backup dei dati
Processo di aggiornamento
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 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.
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.
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.
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.
Non utilizzare il modulo Universal per aggiornare le istanze installate tramite MSI.
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.
Successivamente, eseguire Update-PSUServer per scaricare e decomprimere la nuova istanza di PSU.
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.
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.
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.
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.
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.
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.
Modifiche incompatibili in 5.0
Rimozione delle pagine
Il designer di pagine con trascinamento della selezione è stato rimosso in favore di Portal Pages e Widget.
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. È inoltre possibile utilizzare il portale 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 e richiede che vengano inviati i valori di intestazione corretti.
Consulti la documentazione del modulo 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 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.
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.
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.
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.
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.
Scarichi il pacchetto ZIP per Windows ed estragga il contenuto in una directory locale.
Arresti il servizio PowerShell Universal
Esegua il comando psudb.exe dalla directory dello ZIP, come indicato sopra, per convertire il file di database in %ProgramData%\UniversalAutomation
Aggiorni il file %ProgramData%\PowerShellUniversal\appsettings.json per utilizzare il plugin SQLite anziché il plugin LiteDB
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.
Apra un nuovo prompt dei comandi ed esegua quanto segue.
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.
Ultimo aggiornamento
È stato utile?