Moduli

La pagina Moduli fornisce informazioni sui moduli installati nel sistema.

Visualizzazione dei moduli

È possibile visualizzare e cercare i moduli accessibili da PowerShell Universal visitando la pagina Platform \ Modules. La ricerca fornisce un risultato con caratteri jolly dei moduli trovati in ciascuno degli ambienti definiti all'interno di PowerShell Universal.

Installare moduli dalla Gallery

I moduli possono essere installati dalla PowerShell Gallery. Per cercare un modulo, è possibile cambiare il menu a discesa accanto alla casella di ricerca da Local a PowerShell Gallery. Le ricerche effettuate verranno eseguite sulla Gallery anziché localmente.

Una volta trovato un modulo, sarà possibile fare clic sul pulsante Install per salvarlo localmente. I moduli installati con questo metodo verranno installati nella directory Repository sotto Modules.

Sorgenti di pacchetti

PowerShell Universal si integra con il modulo PackageManagement v3 e rileverà automaticamente le sorgenti di pacchetti registrate. Ad esempio, è possibile registrare una sorgente di pacchetti con il comando seguente.

Register-PSResourceRepository -Name MyNuGet -Uri https://www.nuget.org/api/v2

Una volta registrata la sorgente, verrà mostrata all'interno del menu a discesa nella pagina dei moduli.

Creazione di moduli

È inoltre possibile 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 su Platform \ Modules e faccia clic su Create New Module. Definisca il nome e la versione del modulo.

Una volta creato, il modulo verrà elencato sotto Universal Modules con l'opzione di modificare proprietà e contenuto, nonché di eliminare il modulo.

Durante la modifica del modulo, si aprirà un editor di codice in cui è possibile definire funzioni, variabili e alias da esportare.

Moduli con risorse Universal

Un modulo di esempio è disponibile qui.

Installazione

I moduli possono contenere risorse di PowerShell Universal come script, API e app. L'aggiunta di questi moduli al proprio ambiente aggiungerà automaticamente queste risorse all'istanza di PowerShell Universal. Queste risorse saranno di sola lettura all'interno dell'ambiente. Per rimuoverle, sarà necessario rimuovere il modulo.

Nella Admin Console, faccia clic su Platform \ Modules e quindi selezioni PowerShell Universal Modules.

PowerShell Universal Modules

Faccia clic sul pulsante di download sul lato sinistro del modulo per installarlo. Una volta installate, le risorse di sola lettura verranno aggiunte al suo ambiente.

App Windows System Information

È inoltre possibile salvare i moduli direttamente nella cartella del repository di PowerShell Universal.

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.

Ad esempio, il file scripts.ps1 di cui sopra dovrebbe essere scritto in questo modo.

New-PSUScript -Module 'PSUModule' -Command 'Start-MyScript'

All'interno di PSUModule.psm1, sarà necessario definire la funzione Start-MyScript. Questa è la funzione che verrà chiamata durante l'esecuzione dello script.

function Start-MyScript {

}

Pubblicazione

Quando si creano moduli che estendono PowerShell Universal, è possibile includere il tag PowerShellUniversal nel manifest del modulo affinché siano elencati nella pagina PowerShell Universal Modules e nella console di amministrazione di PSU.

Pubblichi i moduli sulla PowerShell Gallery per condividerli con altri.

Modulo radice

È possibile definire un modulo radice come configurazione di PowerShell Universal. Ciò consente configurazioni riproducibili basate su moduli pubblicati. Un modulo radice viene definito all'interno delle impostazioni dell'applicazione per il server PowerShell Universal. All'avvio, PowerShell Universal caricherà automaticamente questo modulo e le relative 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, è possibile assicurarsi che versioni specifiche delle risorse siano pacchettizzate e distribuite alle proprie istanze di PowerShell Universal.

Il modulo radice può trovarsi ovunque all'interno del PSModulePath registrato per il suo server o account di servizio. Può inoltre risiedere nella cartella dei moduli del suo repository. L'esempio seguente utilizza percorsi relativi.

ARD.Core

Il modulo ARD.Core definisce alcune funzioni e un ambiente che viene utilizzato da altri moduli. Ecco un esempio di definizione di un ambiente di base.

Modules\ARD.Core\1.0.0\.universal\environments.ps1

New-PSUEnvironment -Name 'ARD.Core' -Path pwsh.exe -Type PowerShell7

Le funzioni sono definite nel file PSM1 del modulo.

Modules\ARD.Core\1.0.0\ARD.Core.psm1

function Get-ARDCore {
    @{
        Name = "ARD.Core"
        Description = "This is a test function result"
    }
}

Il manifest del modulo esporta la funzione e fornisce alcuni metadati di base.

Modules\ARD.Core\1.0.0\ARD.Core.psd1

@{
    RootModule = "ARD.Core.psm1"
    Description = "ARD.Core is the base module for other modules"
    Version = "1.0.0"
    FunctionsToExport = @("Get-ARDCore")
}

ARD.Endpoints

Il modulo ARD.Endpoints è strutturato in modo simile al modulo ARD.Core ma espone un endpoint anziché 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.

Modules\ARD.Endpoints\1.0.0\.universal\endpoints.ps1

New-PSUEndpoint -Url /ard.endpoint -Module 'ARD.Endpoints' -Command "Get-ARDResponse" -Environment 'ARD.Core'

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.

Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psm1

function Get-ARDResponse {
    Get-ARDCore
}

Il file ARD.Endpoints.psd1 esporterà la funzione e prevederà anche una dipendenza da ARD.Core per garantire che tale modulo venga caricato per primo, poiché l'endpoint necessita dell'esistenza sia della funzione sia dell'ambiente.

Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psd1

@{
    RootModule = "ARD.Endpoints.psm1"
    Description = "Sample endpoints"
    Version = "1.0.0"
    RequiredModules = @("ARD.Core")
    FunctionsToExport = @("Get-ARDResponse")
}

ARD.Root

Il modulo radice verrà caricato per primo da PowerShell Universal. Prevede una dipendenza sia dal modulo core sia da quello endpoints, ma non definisce alcuna funzionalità propria. PowerShell Universal determinerà l'ordine di caricamento corretto e caricherà quindi le risorse durante l'avvio.

@{
    Description = "A PowerShell Universal configuration"
    Version = "1.0.0"
    RequiredModules = @("ARD.Core", "ARD.Endpoints")
}

All'interno delle impostazioni dell'applicazione, è possibile selezionare il modulo radice e la versione.

appsettings.json

{
    "Data": {
        "Module": "ARD.Root",
        "ModuleVersion": "1.0.0"
    }
}

È inoltre possibile configurarlo tramite variabili d'ambiente. La modifica del file o delle variabili d'ambiente richiederà il riavvio di PowerShell Universal.

$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 all'interno di 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 impiegato il livello di compatibilità Windows durante l'esecuzione dei comandi in PowerShell 7 e nell'ambiente Integrated. Ciò può causare problemi all'interno di 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 1 delle 2 soluzioni alternative disponibili:

• Includa il parametro -SkipEditionCheck con Import-Module durante l'importazione del modulo ActiveDirectory
• Utilizzi l'ambiente Windows PowerShell 5.1 anziché Integrated/PowerShell Core

Approfondimenti

Increased Windows Modules coverage with PowerShell Core 6.1 - PowerShell TeamPowerShell Team

Exchange

Microsoft Exchange on-premises può essere gestito utilizzando sessioni remote in PowerShell. Se utilizza le sessioni nelle app, dovrà considerare di gestire la sessione in modo da evitare di dover aprire una nuova sessione per ogni richiesta. Ciò 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.

$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 riportate di seguito sono state convalidate con PowerShell Universal. La convalida dei moduli garantisce che tali 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