about_Scripts
Descrizione breve
Descrive come eseguire e scrivere script in PowerShell.
Descrizione lunga
Uno script è un file di testo normale che contiene uno o più comandi di PowerShell.
Gli script di PowerShell hanno un'estensione di .ps1 file.
L'esecuzione di uno script è molto simile all'esecuzione di un cmdlet. Digitare il percorso e il nome file dello script e usare i parametri per inviare i dati e impostare le opzioni. È possibile eseguire script nel computer o in una sessione remota in un computer diverso.
La scrittura di uno script salva un comando per un uso successivo e semplifica la condivisione con altri utenti. Soprattutto, consente di eseguire i comandi semplicemente digitando il percorso dello script e il nome file. Gli script possono essere semplici come un singolo comando in un file o come un programma complesso.
Gli script hanno funzionalità aggiuntive, ad esempio il #Requires commento speciale, l'uso di parametri, il supporto per le sezioni di dati e la firma digitale per la sicurezza.
È anche possibile scrivere argomenti della Guida per gli script e per qualsiasi funzione nello script.
Come eseguire uno script
Prima di poter eseguire uno script in Windows, è necessario modificare i criteri di esecuzione predefiniti di PowerShell. I criteri di esecuzione non si applicano a PowerShell in esecuzione su piattaforme non Windows.
I criteri di esecuzione predefiniti, Restricted, impediscono l'esecuzione di tutti gli script, inclusi gli script scritti nel computer locale. Per ulteriori informazioni, vedere about_Execution_Policies.
I criteri di esecuzione vengono salvati nel Registro di sistema, quindi è necessario modificarlo una sola volta in ogni computer.
Per modificare i criteri di esecuzione, utilizzare la procedura seguente.
Al prompt dei comandi digitare:
Set-ExecutionPolicy AllSigned
or
Set-ExecutionPolicy RemoteSigned
Le modifiche saranno effettive immediatamente.
Per eseguire uno script, digitare il nome completo e il percorso completo del file di script.
Ad esempio, per eseguire lo script Get-ServiceLog.ps1 nella directory C:\Scripts digitare:
C:\Scripts\Get-ServiceLog.ps1
Per eseguire uno script nella directory corrente, digitare il percorso della directory corrente oppure usare un punto per rappresentare la directory corrente, seguito da una barra rovesciata del percorso (.\).
Ad esempio, per eseguire lo script ServicesLog.ps1 nella directory locale, digitare:
.\Get-ServiceLog.ps1
Se lo script include parametri, digitare i parametri e i valori dei parametri dopo il nome file dello script.
Ad esempio, il comando seguente usa il parametro ServiceName dello script Get-ServiceLog per richiedere un log dell'attività del servizio WinRM.
.\Get-ServiceLog.ps1 -ServiceName WinRM
Come funzionalità di sicurezza, PowerShell non esegue script quando si fa doppio clic sull'icona dello script in Esplora file o quando si digita il nome dello script senza un percorso completo, anche quando lo script si trova nella directory corrente. Per altre informazioni sull'esecuzione di comandi e script in PowerShell, vedere about_Command_Precedence.
Esegui con PowerShell
A partire da PowerShell 3.0, è possibile eseguire script da Esplora file.
Per usare la funzionalità "Esegui con PowerShell":
Eseguire Esplora file, fare clic con il pulsante destro del mouse sul nome file dello script e quindi scegliere "Esegui con PowerShell".
La funzionalità "Esegui con PowerShell" è progettata per eseguire script che non hanno parametri obbligatori e non restituiscono l'output al prompt dei comandi.
Per altre informazioni, vedere about_Run_With_PowerShell.
Esecuzione di script in altri computer
Per eseguire uno script in uno o più computer remoti, usare il parametro FilePath del Invoke-Command cmdlet .
Immettere il percorso e il nome file dello script come valore del parametro FilePath . Lo script deve trovarsi nel computer locale o in una directory a cui il computer locale può accedere.
Il comando seguente esegue lo Get-ServiceLog.ps1 script nei computer remoti denominati Server01 e Server02.
Invoke-Command -ComputerName Server01,Server02 -FilePath `
C:\Scripts\Get-ServiceLog.ps1
Ottenere assistenza per gli script
Il cmdlet Get-Help ottiene gli argomenti della Guida per gli script, nonché per i cmdlet e altri tipi di comandi. Per ottenere l'argomento della Guida per uno script, digitare Get-Help seguito dal percorso e dal nome file dello script. Se il percorso dello script si trova nella Path variabile di ambiente, è possibile omettere il percorso.
Ad esempio, per ottenere assistenza per lo script ServicesLog.ps1, digitare:
get-help C:\admin\scripts\ServicesLog.ps1
Come scrivere uno script
Uno script può contenere qualsiasi comando di PowerShell valido, inclusi singoli comandi, comandi che usano la pipeline, le funzioni e le strutture di controllo, ad esempio istruzioni If e cicli For.
Per scrivere uno script, aprire un nuovo file in un editor di testo, digitare i comandi e salvarli in un file con un nome file valido con l'estensione di .ps1 file.
L'esempio seguente è uno script semplice che ottiene i servizi in esecuzione nel sistema corrente e li salva in un file di log. Il nome file di log viene creato dalla data corrente.
$date = (get-date).dayofyear
get-service | out-file "$date.log"
Per creare questo script, aprire un editor di testo o un editor di script, digitare questi comandi e quindi salvarli in un file denominato ServiceLog.ps1.
Parametri negli script
Per definire i parametri in uno script, usare un'istruzione Param. L'istruzione Param deve essere la prima istruzione in uno script, ad eccezione dei commenti e delle #Require istruzioni.
I parametri script funzionano come i parametri della funzione. I valori dei parametri sono disponibili per tutti i comandi nello script. Tutte le funzionalità dei parametri di funzione, incluso l'attributo Parameter e i relativi argomenti denominati, sono valide anche negli script.
Quando si esegue lo script, gli utenti dello script digitano i parametri dopo il nome dello script.
Nell'esempio seguente viene illustrato uno Test-Remote.ps1 script con un parametro ComputerName . Entrambe le funzioni script possono accedere al valore del parametro ComputerName .
param ($ComputerName = $(throw "ComputerName parameter is required."))
function CanPing {
$error.clear()
$tmp = test-connection $computername -erroraction SilentlyContinue
if (!$?)
{write-host "Ping failed: $ComputerName."; return $false}
else
{write-host "Ping succeeded: $ComputerName"; return $true}
}
function CanRemote {
$s = new-pssession $computername -erroraction SilentlyContinue
if ($s -is [System.Management.Automation.Runspaces.PSSession])
{write-host "Remote test succeeded: $ComputerName."}
else
{write-host "Remote test failed: $ComputerName."}
}
if (CanPing $computername) {CanRemote $computername}
Per eseguire questo script, digitare il nome del parametro dopo il nome dello script. Ad esempio:
C:\PS> .\test-remote.ps1 -computername Server01
Ping succeeded: Server01
Remote test failed: Server01
Per altre informazioni sull'istruzione Param e sui parametri della funzione, vedere about_Functions e about_Functions_Advanced_Parameters.
Scrittura della Guida per gli script
È possibile scrivere un argomento della Guida per uno script usando uno dei due metodi seguenti:
Guida basata su commenti per gli script
Creare un argomento della Guida usando parole chiave speciali nei commenti. Per creare una Guida basata su commenti per uno script, i commenti devono essere inseriti all'inizio o alla fine del file di script. Per altre informazioni sulla Guida basata su commenti, vedere about_Comment_Based_Help.
Guida basata su XML per gli script
Creare un argomento della Guida basato su XML, ad esempio il tipo che viene in genere creato per i cmdlet. Se si convertono argomenti della Guida in più lingue, è necessaria la Guida basata su XML.
Per associare lo script all'argomento della Guida basata su XML, utilizzare . Parola chiave commento della Guida ExternalHelp. Per altre informazioni sulla parola chiave ExternalHelp, vedere about_Comment_Based_Help. Per altre informazioni sulla Guida basata su XML, vedere How to Write Cmdlet Help.For more information about XML-based help, see How to Write Cmdlet Help.
Restituzione di un valore di uscita
Per impostazione predefinita, gli script non restituiscono uno stato di uscita al termine dello script. È necessario usare l'istruzione exit per restituire un codice di uscita da uno script. Per impostazione predefinita, l'istruzione exit restituisce 0. È possibile specificare un valore numerico per restituire uno stato di uscita diverso. Un codice di uscita diverso da zero segnala in genere un errore.
In Windows è consentito qualsiasi numero compreso tra [int]::MinValue e [int]::MaxValue .
In Unix sono consentiti solo numeri positivi compresi tra [byte]::MinValue (0) e [byte]::MaxValue (255). Un numero negativo nell'intervallo di -1 da a -255 viene convertito automaticamente in un numero positivo aggiungendo 256. Ad esempio, -2 viene trasformato in 254.
In PowerShell l'istruzione exit imposta il valore della $LASTEXITCODE variabile. Nella shell dei comandi di Windows (cmd.exe), l'istruzione exit imposta il valore della %ERRORLEVEL% variabile di ambiente.
Qualsiasi argomento non numerico o esterno all'intervallo specifico della piattaforma viene convertito nel valore di 0.
Ambito dello script e origine dei punti
Ogni script viene eseguito nel proprio ambito. Le funzioni, le variabili, gli alias e le unità create nello script esistono solo nell'ambito dello script. Non è possibile accedere a questi elementi o ai relativi valori nell'ambito in cui viene eseguito lo script.
Per eseguire uno script in un ambito diverso, è possibile specificare un ambito, ad esempio Global o Local, oppure è possibile usare il punto di origine dello script.
La funzionalità dot sourcing consente di eseguire uno script nell'ambito corrente anziché nell'ambito dello script. Quando si esegue uno script con origine punto, i comandi nello script vengono eseguiti come se fossero stati digitati al prompt dei comandi. Le funzioni, le variabili, gli alias e le unità create dallo script vengono create nell'ambito in cui si sta lavorando. Dopo l'esecuzione dello script, è possibile usare gli elementi creati e accedere ai relativi valori nella sessione.
Per aggiungere un punto a uno script, digitare un punto (.) e uno spazio prima del percorso dello script.
Ad esempio:
. C:\scripts\UtilityFunctions.ps1
or
. .\UtilityFunctions.ps1
Dopo l'esecuzione dello UtilityFunctions.ps1 script, le funzioni e le variabili create dallo script vengono aggiunte all'ambito corrente.
Ad esempio, lo UtilityFunctions.ps1 script crea la New-Profile funzione e la $ProfileName variabile .
#In UtilityFunctions.ps1
function New-Profile
{
Write-Host "Running New-Profile function"
$profileName = split-path $profile -leaf
if (test-path $profile)
{write-error "Profile $profileName already exists on this computer."}
else
{new-item -type file -path $profile -force }
}
Se si esegue lo UtilityFunctions.ps1 script nel proprio ambito di script, la New-Profile funzione e la $ProfileName variabile esistono solo durante l'esecuzione dello script. Quando lo script viene chiuso, la funzione e la variabile vengono rimosse, come illustrato nell'esempio seguente.
C:\PS> .\UtilityFunctions.ps1
C:\PS> New-Profile
The term 'new-profile' is not recognized as a cmdlet, function, operable
program, or script file. Verify the term and try again.
At line:1 char:12
+ new-profile <<<<
+ CategoryInfo : ObjectNotFound: (new-profile:String) [],
+ FullyQualifiedErrorId : CommandNotFoundException
C:\PS> $profileName
C:\PS>
Quando si dota lo script ed eseguirlo, lo script crea la New-Profile funzione e la $ProfileName variabile nella sessione nell'ambito. Dopo l'esecuzione dello script, è possibile usare la New-Profile funzione nella sessione, come illustrato nell'esempio seguente.
C:\PS> . .\UtilityFunctions.ps1
C:\PS> New-Profile
Directory: C:\Users\juneb\Documents\WindowsPowerShell
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 1/14/2009 3:08 PM 0 Microsoft.PowerShellISE_profile.ps1
C:\PS> $profileName
Microsoft.PowerShellISE_profile.ps1
Per altre informazioni sull'ambito, vedere about_Scopes.
Script nei moduli
Un modulo è un set di risorse di PowerShell correlate che possono essere distribuite come unità. È possibile usare moduli per organizzare script, funzioni e altre risorse. È anche possibile usare i moduli per distribuire il codice ad altri utenti e per ottenere codice da origini attendibili.
È possibile includere script nei moduli oppure creare un modulo di script, ovvero un modulo costituito interamente o principalmente da uno script e risorse di supporto. Un modulo script è solo uno script con estensione psm1.
Per altre informazioni sui moduli, vedere about_Modules.
Altre funzionalità di script
PowerShell include molte funzionalità utili che è possibile usare negli script.
#Requires- È possibile usare un'istruzione#Requiresper impedire l'esecuzione di uno script senza moduli o snap-in specificati e una versione specificata di PowerShell. Per altre informazioni, vedere about_Requires.$PSCommandPath: contiene il percorso completo e il nome dello script in esecuzione. Questo parametro è valido in tutti gli script. Questa variabile automatica viene introdotta in PowerShell 3.0.$PSScriptRoot: contiene la directory da cui viene eseguito uno script. In PowerShell 2.0 questa variabile è valida solo nei moduli di script (.psm1). A partire da PowerShell 3.0, è valido in tutti gli script.$MyInvocation- La$MyInvocationvariabile automatica contiene informazioni sullo script corrente, incluse le informazioni su come è stato avviato o "richiamato". È possibile usare questa variabile e le relative proprietà per ottenere informazioni sullo script durante l'esecuzione. Ad esempio, .$MyInvocationLa variabile MyCommand.Path contiene il percorso e il nome file dello script.$MyInvocation. La riga contiene il comando che ha avviato lo script, inclusi tutti i parametri e i valori.A partire da PowerShell 3.0,
$MyInvocationinclude due nuove proprietà che forniscono informazioni sullo script che ha chiamato o richiamato lo script corrente. I valori di queste proprietà vengono popolati solo quando il chiamante o il chiamante è uno script.PSCommandPath contiene il percorso completo e il nome dello script che ha chiamato o richiamato lo script corrente.
PSScriptRoot contiene la directory dello script che ha chiamato o richiamato lo script corrente.
A differenza delle
$PSCommandPathvariabili e$PSScriptRootautomatiche, che contengono informazioni sullo script corrente, le proprietà PSCommandPath e PSScriptRoot della$MyInvocationvariabile contengono informazioni sullo script che ha chiamato lo script corrente.Sezioni di dati: è possibile usare la
Dataparola chiave per separare i dati dalla logica negli script. Le sezioni dei dati possono anche semplificare la localizzazione. Per altre informazioni, vedere about_Data_Sections e about_Script_Internationalization.Firma script: è possibile aggiungere una firma digitale a uno script. A seconda dei criteri di esecuzione, è possibile usare firme digitali per limitare l'esecuzione di script che potrebbero includere comandi non sicuri. Per altre informazioni, vedere about_Execution_Policies e about_Signing.
