about_Scripts

Breve descrizione

Viene descritto 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 .ps1 di 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 l'uso successivo e semplifica la condivisione con altri utenti. Più importante, 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 dispongono di funzionalità aggiuntive, ad esempio il commento speciale, l'uso #Requires di parametri, il supporto per le sezioni 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 di PowerShell predefiniti. I criteri di esecuzione non si applicano a PowerShell in esecuzione in piattaforme non Windows.

Il criterio di esecuzione predefinito, Restricted, impedisce l'esecuzione di tutti gli script, inclusi gli script scritti nel computer locale. Per altre 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, usare la procedura seguente.

Al prompt dei comandi digitare:

Set-ExecutionPolicy AllSigned

oppure

Set-ExecutionPolicy RemoteSigned

La modifica è effettiva 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:\Script 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, seguita da una barra rovesciata del percorso (.\).

Ad esempio, per eseguire lo script ServicesLog.ps1 nella directory locale digitare:

.\Get-ServiceLog.ps1

Se lo script ha parametri, digitare i parametri e i valori dei parametri dopo il nome del file di 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.

Esecuzione 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 del file di 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 tutti i comandi di PowerShell validi, inclusi i singoli comandi, i 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 del .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 del 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 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 di commenti e #Require istruzioni.

I parametri di script funzionano come parametri di funzione. I valori dei parametri sono disponibili per tutti i comandi nello script. Tutte le funzionalità dei parametri di funzione, tra cui l'attributo Parameter e i relativi argomenti denominati, sono validi 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 script con un Test-Remote.ps1 parametro ComputerName . Entrambe le funzioni di 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 Comment-Based 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 sui commenti, vedere about_Comment_Based_Help.

• Guida XML-Based per gli script

  Creare un argomento della Guida basato su XML, ad esempio il tipo che viene in genere creato per i cmdlet. La Guida basata su XML è necessaria se si stanno traducendo gli argomenti della Guida in più lingue.

Per associare lo script all'argomento della Guida basata su XML, usare . Parola chiave del 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 (Procedura per la scrittura del cmdlet).

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 tra [int]::MinValue e [int]::MaxValue .

In Unix sono consentiti solo numeri positivi tra [byte]::MinValue (0) e [byte]::MaxValue (255). Un numero negativo nell'intervallo -1-255 di tramite viene convertito automaticamente in un numero positivo aggiungendo 256. Ad esempio, -2 viene trasformato in 254.

In PowerShell l'istruzione exit$LASTEXITCODE imposta il valore della variabile. In Windows Command Shell (cmd.exe), l'istruzione %ERRORLEVEL% exit imposta il valore della variabile di ambiente.

Qualsiasi argomento non numerico o esterno all'intervallo specifico della piattaforma viene convertito nel valore di 0.

Ambito script e origine 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 dotare lo 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 dot, 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

o

. .\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 funzione e la $ProfileNameNew-Profile 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 funzione e la $ProfileNameNew-Profile 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 funzione e la New-Profile$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 gli script, le funzioni e altre risorse. È anche possibile usare moduli per distribuire il codice ad altri e 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 offre molte funzionalità utili che è possibile usare negli script.

• #Requires - È possibile usare un'istruzione per impedire l'esecuzione di uno #Requires 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 $MyInvocation variabile automatica contiene informazioni sullo script corrente, incluse 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, . $MyInvocation La 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, $MyInvocation sono disponibili 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 $PSCommandPath variabili e $PSScriptRoot automatiche, che contengono informazioni sullo script corrente, le proprietà PSCommandPath e PSScriptRoot della $MyInvocation variabile contengono informazioni sullo script che ha chiamato lo script corrente.

• Sezioni dati: è possibile usare la Data parola 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.

Vedi anche

• about_Command_Precedence
• about_Comment_Based_Help
• about_Execution_Policies
• about_Functions
• about_Modules
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Command