> 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/piattaforma/modules.md). # Moduli Gestisca i moduli PowerShell in PowerShell Universal, con installazioni dalla Gallery, origini dei pacchetti, creazione di moduli personalizzati e configurazione del modulo radice. La pagina Moduli fornisce informazioni sui moduli installati nel sistema. ## Visualizzazione dei moduli Può visualizzare e cercare i moduli accessibili da PowerShell Universal in **Manage > Modules > Installed**. La ricerca fornisce un risultato con caratteri jolly dei moduli trovati in ciascuno degli ambienti definiti in PowerShell Universal. ## Installare moduli dalla Gallery I moduli possono essere installati dalla PowerShell Gallery in **Manage > Modules > Discover**. Selezioni un'origine accanto alla casella di ricerca per cercare in quell'origine invece che localmente. Una volta trovato un modulo, potrà fare clic sul pulsante Install per salvarlo localmente. I moduli installati con questo metodo verranno installati nella directory Repository sotto Modules. ## Origini dei pacchetti PowerShell Universal si integra con il modulo `PackageManagement v3` e rileverà automaticamente le origini dei pacchetti registrate. Per esempio, può registrare un'origine dei pacchetti con il comando seguente. ```powershell Register-PSResourceRepository -Name MyNuGet -Uri https://www.nuget.org/api/v2 ``` Le origini dei pacchetti registrate sono elencate in **Manage > Modules > Sources** e sono disponibili durante l'individuazione dei moduli. ## Creazione di moduli Può anche creare moduli direttamente in PowerShell Universal. Questi moduli verranno creati nella directory Repository sotto Modules. Questi moduli saranno disponibili in tutti gli ambienti. Per creare un nuovo modulo, si porti in **Manage > Modules > Custom Modules** e faccia clic su Create New Module. Definisca il nome e la versione del modulo. Una volta creato, il modulo sarà elencato in Universal Modules con l'opzione di modificarne proprietà e contenuto, nonché di eliminarlo. Quando si modifica il modulo, si aprirà un editor di codice in cui può definire funzioni, variabili e alias da esportare. ## Moduli con risorse Universal {% hint style="info" %} Un modulo di esempio è [disponibile qui](https://github.com/ironmansoftware/universal-modules). {% endhint %} ### Installazione I moduli possono contenere risorse di PowerShell Universal come script, API e app. L'aggiunta di questi moduli al suo ambiente aggiungerà automaticamente queste risorse alla sua istanza di PowerShell Universal. Queste risorse saranno di sola lettura all'interno dell'ambiente. Per rimuoverle, dovrà rimuovere il modulo. Nella Admin Console, apra **Manage > Modules > Installed**. Faccia clic sul pulsante di download sul lato sinistro del modulo per installarlo. Una volta installato, le risorse di sola lettura verranno aggiunte al suo ambiente. Può anche salvare i moduli direttamente nella cartella del repository di PowerShell Universal. ```powershell Save-Module Universal.Apps.WindowsSystemInformation -Path $Env:ProgramData\UniversalAutomation\Repository\Modules ``` ### Creazione Di seguito è riportato un esempio della struttura di un modulo Universal. Se il modulo contiene la cartella `.universal`, le risorse verranno caricate automaticamente da essa. ``` .universal scripts.ps1 PSUModule.psd1 PSUModule.psm1 ``` Le risorse non possono utilizzare percorsi e devono utilizzare il nome del modulo e del comando per associare le risorse ai rispettivi script. Per esempio, il file `scripts.ps1` di cui sopra dovrebbe essere scritto in questo modo. ```powershell New-PSUScript -Module 'PSUModule' -Command 'Start-MyScript' ``` In `PSUModule.psm1`, dovrà definire la funzione `Start-MyScript`. Questa è la funzione che verrà chiamata durante l'esecuzione dello script. ```powershell function Start-MyScript { } ``` ### Pubblicazione Quando crea moduli che estendono PowerShell Universal, può includere il tag `PowerShellUniversal` nel manifest del modulo affinché vengano elencati nella [pagina Moduli di PowerShell Universal](/powershell-universal/it/readme.md) e nella console di amministrazione PSU. [Pubblichi i moduli nella PowerShell Gallery](https://jeffbrown.tech/how-to-publish-your-first-powershell-gallery-package/) per condividerli con altri. ## Modulo radice Può definire un modulo radice come configurazione di PowerShell Universal. Ciò consente configurazioni riproducibili basate su moduli pubblicati. Un modulo radice è definito nelle impostazioni dell'applicazione per il server PowerShell Universal. All'avvio, PowerShell Universal caricherà automaticamente questo modulo e le sue dipendenze. Il modulo radice deve trovarsi nel PSModulePath o nella cartella Modules del Repository. ### Esempio Di seguito è riportato un esempio di utilizzo di un modulo radice e delle dipendenze per definire una configurazione di PowerShell Universal. Le risorse fornite dai moduli sono di sola lettura all'interno della piattaforma. Utilizzando i moduli, può garantire che versioni specifiche delle risorse vengano pacchettizzate e distribuite alle sue istanze di PowerShell Universal. {% hint style="success" %} Il modulo radice può trovarsi in qualsiasi punto del PSModulePath registrato per il suo server o account di servizio. Può anche risiedere nella cartella dei moduli del suo repository. L'esempio seguente utilizza percorsi relativi. {% endhint %} #### ARD.Core Il modulo ARD.Core definisce alcune funzioni e un ambiente utilizzato da altri moduli. Ecco un esempio di definizione di un ambiente di base. {% code title="Modules\ARD.Core\1.0.0.universal\environments.ps1" %} ```powershell New-PSUEnvironment -Name 'ARD.Core' -Path pwsh.exe -Type PowerShell7 ``` {% endcode %} Le funzioni sono definite nel file PSM1 del modulo. {% code title="Modules\ARD.Core\1.0.0\ARD.Core.psm1" %} ```powershell function Get-ARDCore { @{ Name = "ARD.Core" Description = "This is a test function result" } } ``` {% endcode %} Il manifest del modulo esporta la funzione e fornisce alcuni metadati di base. {% code title="Modules\ARD.Core\1.0.0\ARD.Core.psd1" %} ```powershell @{ RootModule = "ARD.Core.psm1" Description = "ARD.Core is the base module for other modules" Version = "1.0.0" FunctionsToExport = @("Get-ARDCore") } ``` {% endcode %} #### ARD.Endpoints Il modulo ARD.Endpoints ha una struttura simile al modulo ARD.Core ma espone un endpoint invece di un ambiente. Questo endpoint di esempio chiama la funzione `Get-ARDResponse` quando viene richiamato l'URL `ard.endpoint`. Si noti che l'endpoint utilizza l'endpoint ARD.Core fornito dal modulo di cui sopra. {% code title="Modules\ARD.Endpoints\1.0.0.universal\endpoints.ps1" %} ```powershell New-PSUEndpoint -Url /ard.endpoint -Module 'ARD.Endpoints' -Command "Get-ARDResponse" -Environment 'ARD.Core' ``` {% endcode %} Il file ARD.Endpoints.psm1 definisce la funzione da esportare che possiamo utilizzare anche per l'endpoint. L'endpoint utilizza la funzione di ARD.Core per restituire una risposta. Questo funziona perché sono tutti semplici moduli PowerShell normali. {% code title="Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psm1" %} ```powershell function Get-ARDResponse { Get-ARDCore } ``` {% endcode %} Il file ARD.Endpoints.psd1 esporterà la funzione e avrà anche una dipendenza da ARD.Core per garantire che quel modulo venga caricato per primo, perché l'endpoint richiede l'esistenza sia della funzione sia dell'ambiente. {% code title="Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psd1" %} ```powershell @{ RootModule = "ARD.Endpoints.psm1" Description = "Sample endpoints" Version = "1.0.0" RequiredModules = @("ARD.Core") FunctionsToExport = @("Get-ARDResponse") } ``` {% endcode %} #### ARD.Root Il modulo radice verrà caricato per primo da PowerShell Universal. Ha una dipendenza sia dal modulo core sia dal modulo endpoints, ma non definisce alcuna funzionalità in sé. PowerShell Universal determinerà il corretto ordine di caricamento e poi caricherà le risorse durante l'avvio. ```powershell @{ Description = "A PowerShell Universal configuration" Version = "1.0.0" RequiredModules = @("ARD.Core", "ARD.Endpoints") } ``` Nelle impostazioni dell'applicazione, può selezionare il modulo radice e la versione. {% code title="appsettings.json" %} ```json { "Data": { "Module": "ARD.Root", "ModuleVersion": "1.0.0" } } ``` {% endcode %} Può anche eseguire la configurazione tramite variabili di ambiente. La modifica del file o delle variabili di ambiente richiederà il riavvio di PowerShell Universal. ```powershell $ENV:Data__Module = "ARD.Root" $ENV:Data__ModuleVersion = "1.0.0" ``` ## Installare manualmente i moduli PowerShell Universal aggiungerà la directory `Modules` del repository al `$ENV:PSModulePath` per tutti gli ambienti. L'aggiunta di moduli a questa directory garantirà che il modulo sia disponibile per qualsiasi processo PowerShell in esecuzione con PowerShell Universal. ## Informazioni sui moduli Questa sezione include informazioni su determinati moduli e sul loro utilizzo in PowerShell Universal. ### ActiveDirectory Il modulo `ActiveDirectory` supporta nativamente PowerShell 7 quando si utilizza la versione 1.0.1.0. Quando si utilizza la versione 1.0.0.0, viene utilizzato il livello di compatibilità Windows durante l'esecuzione dei comandi in PowerShell 7 e nell'ambiente Integrated. Questo può causare problemi in PowerShell Universal. Le nostre indicazioni per questo modulo sono le seguenti. #### Windows Server 2019 e versioni successive Aggiorni il modulo `ActiveDirectory` alla versione 1.0.1.0, che supporta PowerShell Core #### Windows Server 2016 e versioni precedenti Scelga una delle 2 soluzioni alternative disponibili: * Includa il parametro `-SkipEditionCheck` con **Import-Module** quando importa il modulo ActiveDirectory * Utilizzi l'ambiente Windows PowerShell 5.1 invece di Integrated/PowerShell Core #### Approfondimenti {% embed url="" %} ### Exchange Microsoft Exchange on-premises può essere gestito utilizzando sessioni remote in PowerShell. Se utilizza sessioni nelle app, è opportuno considerare di gestire la sessione in modo da evitare di dover aprire una nuova sessione per ogni richiesta. Questo migliora notevolmente le prestazioni. L'esempio seguente utilizza l'ambito `$Cache:` per rendere persistente la sessione tra le richieste. Sebbene questo esempio utilizzi PSSession ed Exchange, potrebbe utilizzare lo stesso schema per altri tipi di connessioni persistenti. ```powershell $Cache:ExchangeServer = '' $Cache:ExchangeCredential = '' $Cache:ExchangeSessionInfo = @{ Authentication = 'Kerberos' ConfigurationName = 'Microsoft.Exchange' ConnectionUri = 'https://{0}/PowerShell/' -f $Cache:ExchangeServer Credential = $Cache:ExchangeCredential WarningAction = 'SilentlyContinue' } #region PRIVATE FUNCTIONS Function Script:Connect-ExchServer { $exchSession = New-PSSession @Cache:ExchangeSessionInfo Import-PSSession $exchSession -WarningAction 'SilentlyContinue' } Function Script:Test-ExchConnected { $Current = Get-PSSession | Where-Object { $_.ConfigurationName -eq 'Microsoft.Exchange' } if ($Current.State -eq 'Opened' -and $Current.Availability -eq 'Available') { $true } else { $false } } #endregion #region PUBLIC FUNCTIONS Function Clear-ExchConnection { # called publicly in "End{}" blocks. Get-PSSession | Where-Object { $_.ConfigurationName -eq 'Microsoft.Exchange' } | Remove-PSSession -ErrorAction $Cache:ErrorAction Get-Module | Where-Object { $_.Description -match $Cache:ExchangeServer } | Remove-Module -Force -ErrorAction $Cache:ErrorAction } Function Confirm-ExchConnected { # called publicly in "Begin{}" blocks, or just before Exhange actions in functions or scripts. if (!( Test-ExchConnected )) { Clear-ExchConnection Connect-ExchServer } } #endregion function Invoke-ExampleExchFunction { Param ( $something ) Begin { $null = Confirm-ExchConnected } Process { return $something } End { Clear-ExchConnection } } ``` ## Versioni dei moduli convalidate Le versioni dei moduli seguenti sono state convalidate con PowerShell Universal. La convalida dei moduli garantisce che questi moduli vengano caricati e interagiscano con i rispettivi servizi. | Modulo | Versione del modulo | Versione PSU | Ambienti PSU | | ------------------------------ | ------------------- | ------------ | ------------------------ | | Microsoft.Graph.Authentication | 2.26.1 | 5.5.2 | PowerShell 7 | | ExchangeOnlineManagement | 3.7.2 | 5.5.2 | PowerShell 7 | | MicrosoftTeams | 6.9.0 | 5.5.2 | PowerShell 7 | | Az.Accounts | 4.1.0 | 5.5.2 | PowerShell 7, Integrated | --- # 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/piattaforma/modules.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.