about_Scripts

Kurze Beschreibung

Beschreibt, wie Skripts in PowerShell ausgeführt und geschrieben werden.

Lange Beschreibung

Ein Skript ist eine Nur-Text-Datei, die mindestens einen PowerShell-Befehl enthält. PowerShell-Skripts haben eine .ps1 Dateierweiterung.

Das Ausführen eines Skripts ähnelt dem Ausführen eines Cmdlets. Sie geben den Pfad und dateinamen des Skripts ein und verwenden Parameter zum Senden von Daten und Festlegen von Optionen. Sie können Skripts auf Ihrem Computer oder in einer Remotesitzung auf einem anderen Computer ausführen.

Das Schreiben eines Skripts speichert einen Befehl für die spätere Verwendung und erleichtert die Freigabe für andere Personen. Vor allem können Sie die Befehle einfach ausführen, indem Sie den Skriptpfad und den Dateinamen eingeben. Skripts können so einfach wie ein einzelner Befehl in einer Datei oder so umfangreich wie ein komplexes Programm sein.

Skripts verfügen über zusätzliche Features, z. B. den #Requires speziellen Kommentar, die Verwendung von Parametern, die Unterstützung für Datenabschnitte und die digitale Signatur für Sicherheit. Sie können auch Hilfethemen für Skripts und für alle Funktionen im Skript schreiben.

Ausführen eines Skripts

Bevor Sie ein Skript unter Windows ausführen können, müssen Sie die Standardmäßige PowerShell-Ausführungsrichtlinie ändern. Die Ausführungsrichtlinie gilt nicht für PowerShell, die auf Nicht-Windows-Plattformen ausgeführt wird.

Die Standardausführungsrichtlinie verhindert, Restricteddass alle Skripts ausgeführt werden, einschließlich Skripts, die Sie auf dem lokalen Computer schreiben. Weitere Informationen finden Sie unter Informationen zu Ausführungsrichtlinien.

Die Ausführungsrichtlinie wird in der Registrierung gespeichert, daher müssen Sie sie nur einmal auf jedem Computer ändern.

Verwenden Sie zum Ändern der Ausführungsrichtlinie das folgende Verfahren.

Geben Sie an der Eingabeaufforderung Folgendes ein:

Set-ExecutionPolicy AllSigned

oder

Set-ExecutionPolicy RemoteSigned

Die Änderung wird sofort wirksam.

Geben Sie zum Ausführen eines Skripts den vollständigen Namen und den vollständigen Pfad zur Skriptdatei ein.

Wenn Sie beispielsweise das Skript Get-ServiceLog.ps1 im Verzeichnis C:\Scripts ausführen möchten, geben Sie Folgendes ein:

C:\Scripts\Get-ServiceLog.ps1

Um ein Skript im aktuellen Verzeichnis auszuführen, geben Sie den Pfad zum aktuellen Verzeichnis ein, oder verwenden Sie einen Punkt, um das aktuelle Verzeichnis darzustellen, gefolgt von einem Pfad umgekehrter Schrägstrich (.\).

Um beispielsweise das Skript ServicesLog.ps1 im lokalen Verzeichnis auszuführen, geben Sie Folgendes ein:

.\Get-ServiceLog.ps1

Wenn das Skript Parameter enthält, geben Sie die Parameter und Parameterwerte nach dem Skriptdateinamen ein.

Der folgende Befehl verwendet beispielsweise den ServiceName-Parameter des Get-ServiceLog-Skripts, um ein Protokoll der WinRM-Dienstaktivität anzufordern.

.\Get-ServiceLog.ps1 -ServiceName WinRM

Als Sicherheitsfeature führt PowerShell keine Skripts aus, wenn Sie auf das Skriptsymbol in Explorer doppelklicken oder wenn Sie den Skriptnamen ohne vollständigen Pfad eingeben, auch wenn sich das Skript im aktuellen Verzeichnis befindet. Weitere Informationen zum Ausführen von Befehlen und Skripts in PowerShell finden Sie unter about_Command_Precedence.

Mit PowerShell ausführen

Ab PowerShell 3.0 können Sie Skripts aus Explorer ausführen.

So verwenden Sie das Feature "Mit PowerShell ausführen":

Führen Sie Explorer aus, klicken Sie mit der rechten Maustaste auf den Dateinamen des Skripts, und wählen Sie dann "Mit PowerShell ausführen" aus.

Das Feature "Mit PowerShell ausführen" wurde entwickelt, um Skripts auszuführen, die nicht über erforderliche Parameter verfügen und die Ausgabe nicht an die Eingabeaufforderung zurückgeben.

Weitere Informationen finden Sie unter about_Run_With_PowerShell.

Ausführen von Skripts auf anderen Computern

Verwenden Sie den FilePath-Parameter des Invoke-Command Cmdlets, um ein Skript auf einem oder mehreren Remotecomputern auszuführen.

Geben Sie den Pfad und dateinamen des Skripts als Wert des FilePath-Parameters ein. Das Skript muss sich auf dem lokalen Computer oder in einem Verzeichnis befinden, auf das der lokale Computer zugreifen kann.

Mit dem folgenden Befehl wird das Get-ServiceLog.ps1 Skript auf den Remotecomputern "Server01" und "Server02" ausgeführt.

Invoke-Command -ComputerName Server01,Server02 -FilePath `
  C:\Scripts\Get-ServiceLog.ps1

Hilfe zu Skripts abrufen

Das Cmdlet "Get-Help" ruft die Hilfethemen für Skripts sowie für Cmdlets und andere Arten von Befehlen ab. Um das Hilfethema für ein Skript abzurufen, geben Sie Get-Help gefolgt vom Pfad und Dateinamen des Skripts ein. Wenn sich der Skriptpfad in Ihrer Path Umgebungsvariable befindet, können Sie den Pfad weglassen.

Um z. B. Hilfe für das Skript ServicesLog.ps1 zu erhalten, geben Sie Folgendes ein:

get-help C:\admin\scripts\ServicesLog.ps1

Schreiben eines Skripts

Ein Skript kann alle gültigen PowerShell-Befehle enthalten, einschließlich einzelner Befehle, Befehle, die die Pipeline, Funktionen und Steuerelementstrukturen wie If-Anweisungen und For-Schleifen verwenden.

Um ein Skript zu schreiben, öffnen Sie eine neue Datei in einem Text-Editor, geben Sie die Befehle ein, und speichern Sie sie in einer Datei mit einem gültigen Dateinamen mit der .ps1 Dateierweiterung.

Das folgende Beispiel ist ein einfaches Skript, das die Dienste abruft, die auf dem aktuellen System ausgeführt werden, und speichert sie in einer Protokolldatei. Der Protokolldateiname wird aus dem aktuellen Datum erstellt.

$date = (get-date).dayofyear
get-service | out-file "$date.log"

Um dieses Skript zu erstellen, öffnen Sie einen Text-Editor oder einen Skript-Editor, geben Sie diese Befehle ein, und speichern Sie sie dann in einer Datei mit dem Namen ServiceLog.ps1.

Parameter in Skripts

Verwenden Sie zum Definieren von Parametern in einem Skript eine Param-Anweisung. Die Param Anweisung muss die erste Anweisung in einem Skript sein, mit Ausnahme von Kommentaren und anweisungen #Require .

Skriptparameter funktionieren wie Funktionsparameter. Die Parameterwerte sind für alle Befehle im Skript verfügbar. Alle Features von Funktionsparametern, einschließlich des Parameter-Attributs und der benannten Argumente, sind auch in Skripts gültig.

Beim Ausführen des Skripts geben Skriptbenutzer die Parameter nach dem Skriptnamen ein.

Das folgende Beispiel zeigt ein Test-Remote.ps1 Skript mit einem ComputerName-Parameter . Beide Skriptfunktionen können auf den ComputerName-Parameterwert zugreifen.

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}

Geben Sie zum Ausführen dieses Skripts den Parameternamen nach dem Skriptnamen ein. Zum Beispiel:

C:\PS> .\test-remote.ps1 -computername Server01

Ping succeeded: Server01
Remote test failed: Server01

Weitere Informationen zur Param-Anweisung und den Funktionsparametern finden Sie unter about_Functions und about_Functions_Advanced_Parameters.

Schreiben von Hilfe für Skripts

Sie können ein Hilfethema für ein Skript schreiben, indem Sie eine der beiden folgenden Methoden verwenden:

• Kommentarbasierte Hilfe für Skripts

  Erstellen Sie ein Hilfethema mithilfe spezieller Schlüsselwort (keyword) in den Kommentaren. Um eine kommentarbasierte Hilfe für ein Skript zu erstellen, müssen die Kommentare am Anfang oder Ende der Skriptdatei platziert werden. Weitere Informationen zur kommentarbasierten Hilfe finden Sie unter about_Comment_Based_Help.

• XML-basierte Hilfe für Skripts

  Erstellen Sie ein XML-basiertes Hilfethema, z. B. den Typ, der normalerweise für Cmdlets erstellt wird. Xml-basierte Hilfe ist erforderlich, wenn Sie Hilfethemen in mehrere Sprachen übersetzen.

Um das Skript dem XML-basierten Hilfethema zuzuordnen, verwenden Sie die . ExternalHelp-Hilfekommentar Schlüsselwort (keyword). Weitere Informationen zum ExternalHelp-Schlüsselwort (keyword) finden Sie unter about_Comment_Based_Help. Weitere Informationen zur XML-basierten Hilfe finden Sie in der Hilfe zum Schreiben von Cmdlets.

Zurückgeben eines Ausgangswerts

Standardmäßig geben Skripts keinen Beendigungsstatus zurück, wenn das Skript beendet wird. Sie müssen die exit Anweisung verwenden, um einen Ausgangscode aus einem Skript zurückzugeben. Standardmäßig gibt die exit Anweisung zurück 0. Sie können einen numerischen Wert angeben, um einen anderen Beendigungsstatus zurückzugeben. Ein Nichtzero-Beendigungscode signalisiert in der Regel einen Fehler.

Unter Windows ist eine beliebige Zahl zwischen [int]::MinValue und [int]::MaxValue ist zulässig.

Auf Unix sind nur positive Zahlen zwischen [byte]::MinValue (0) und [byte]::MaxValue (255) zulässig. Eine negative Zahl im Bereich von -1 durch -255 wird automatisch in eine positive Zahl übersetzt, indem 256 hinzugefügt wird. Beispiel: -2 wird in 254.

In PowerShell legt die exit Anweisung den Wert der $LASTEXITCODE Variablen fest. In der Windows-Befehlsshell (cmd.exe) legt die Exit-Anweisung den Wert der %ERRORLEVEL% Umgebungsvariable fest.

Jedes Argument, das nicht numerisch oder außerhalb des plattformspezifischen Bereichs ist, wird in den Wert von 0übersetzt.

Skriptbereich und Punkt-Beschaffung

Jedes Skript wird in einem eigenen Bereich ausgeführt. Die Funktionen, Variablen, Aliase und Laufwerke, die im Skript erstellt werden, sind nur im Skriptbereich vorhanden. Sie können nicht auf diese Elemente oder deren Werte im Bereich zugreifen, in dem das Skript ausgeführt wird.

Wenn Sie ein Skript in einem anderen Bereich ausführen möchten, können Sie einen Bereich angeben, z. B. global oder lokal, oder Sie können das Skript mit punktieren.

Mit dem Dot Sourcing-Feature können Sie ein Skript im aktuellen Bereich anstelle des Skriptbereichs ausführen. Wenn Sie ein Skript ausführen, das punktiert ist, werden die Befehle im Skript so ausgeführt, als hätten Sie sie an der Eingabeaufforderung eingegeben. Die Funktionen, Variablen, Aliase und Laufwerke, die das Skript erstellt, werden in dem Bereich erstellt, in dem Sie arbeiten. Nachdem das Skript ausgeführt wurde, können Sie die erstellten Elemente verwenden und in Ihrer Sitzung auf deren Werte zugreifen.

Um ein Skript zu dotieren, geben Sie einen Punkt (.) und ein Leerzeichen vor dem Skriptpfad ein.

Zum Beispiel:

. C:\scripts\UtilityFunctions.ps1

oder

. .\UtilityFunctions.ps1

Nachdem das UtilityFunctions.ps1 Skript ausgeführt wurde, werden die vom Skript erstellten Funktionen und Variablen dem aktuellen Bereich hinzugefügt.

Beispielsweise erstellt das UtilityFunctions.ps1 Skript die New-Profile Funktion und die $ProfileName Variable.

#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 }
}

Wenn Sie das UtilityFunctions.ps1 Skript in einem eigenen Skriptbereich ausführen, sind die New-Profile Funktion und die $ProfileName Variable nur vorhanden, während das Skript ausgeführt wird. Wenn das Skript beendet wird, werden die Funktion und Variable entfernt, wie im folgenden Beispiel gezeigt.

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>

Wenn Sie das Skript mit punktieren und ausführen, erstellt das Skript die New-Profile Funktion und die $ProfileName Variable in Ihrer Sitzung in Ihrem Bereich. Nachdem das Skript ausgeführt wurde, können Sie die New-Profile Funktion in Ihrer Sitzung verwenden, wie im folgenden Beispiel gezeigt.

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

Weitere Informationen zum Bereich finden Sie unter about_Scopes.

Skripts in Modulen

Ein Modul ist eine Reihe verwandter PowerShell-Ressourcen, die als Einheit verteilt werden können. Sie können Module verwenden, um Skripts, Funktionen und andere Ressourcen zu organisieren. Sie können auch Module verwenden, um Ihren Code an andere zu verteilen und Code aus vertrauenswürdigen Quellen abzurufen.

Sie können Skripts in Ihre Module einschließen oder ein Skriptmodul erstellen, bei dem es sich um ein Modul handelt, das vollständig oder hauptsächlich aus einem Skript und unterstützenden Ressourcen besteht. Ein Skriptmodul ist nur ein Skript mit der Dateierweiterung PSM1.

Weitere Informationen zu Modulen finden Sie unter about_Modules.

Weitere Skriptfeatures

PowerShell verfügt über viele nützliche Features, die Sie in Skripts verwenden können.

• #Requires – Sie können eine #Requires Anweisung verwenden, um zu verhindern, dass ein Skript ohne bestimmte Module oder Snap-Ins und eine angegebene Version von PowerShell ausgeführt wird. Weitere Informationen finden Sie unter about_Requires.

• $PSCommandPath - Enthält den vollständigen Pfad und namen des skripts, das ausgeführt wird. Dieser Parameter ist in allen Skripts gültig. Diese automatische Variable wird in PowerShell 3.0 eingeführt.

• $PSScriptRoot - Enthält das Verzeichnis, aus dem ein Skript ausgeführt wird. In PowerShell 2.0 ist diese Variable nur in Skriptmodulen (.psm1) gültig. Ab PowerShell 3.0 ist sie in allen Skripts gültig.

• $MyInvocation - Die $MyInvocation automatische Variable enthält Informationen zum aktuellen Skript, einschließlich Informationen darüber, wie sie gestartet oder "aufgerufen" wurde. Sie können diese Variable und die zugehörigen Eigenschaften verwenden, um Während der Ausführung Informationen zum Skript abzurufen. Beispiel: die $MyInvocation. Die Variable "MyCommand.Path" enthält den Pfad und den Dateinamen des Skripts. $MyInvocation. Zeile enthält den Befehl, der das Skript gestartet hat, einschließlich aller Parameter und Werte.

  Ab PowerShell 3.0 gibt es zwei neue Eigenschaften, $MyInvocation die Informationen zum Skript bereitstellen, das das aktuelle Skript aufgerufen oder aufgerufen hat. Die Werte dieser Eigenschaften werden nur aufgefüllt, wenn der Aufrufer oder Aufrufer ein Skript ist.

  • PSCommandPath enthält den vollständigen Pfad und Namen des Skripts, das das aktuelle Skript aufgerufen oder aufgerufen hat.

  • PSScriptRoot enthält das Verzeichnis des Skripts, das das aktuelle Skript aufgerufen oder aufgerufen hat.

  Im Gegensatz zu den $PSCommandPath und $PSScriptRoot automatischen Variablen, die Informationen zum aktuellen Skript enthalten, enthalten die PSCommandPath - und PSScriptRoot-Eigenschaften der $MyInvocation Variablen Informationen über das Skript, das das aktuelle Skript aufgerufen hat.

• Datenabschnitte – Sie können die Data Schlüsselwort (keyword) verwenden, um Daten aus der Logik in Skripts zu trennen. Datenabschnitte können auch die Lokalisierung vereinfachen. Weitere Informationen finden Sie unter about_Data_Sections und about_Script_Internationalization.

• Skriptsignatur – Sie können einem Skript eine digitale Signatur hinzufügen. Abhängig von der Ausführungsrichtlinie können Sie digitale Signaturen verwenden, um die Ausführung von Skripts einzuschränken, die unsichere Befehle enthalten können. Weitere Informationen finden Sie unter about_Execution_Policies und about_Signing.

Weitere Informationen

• 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