Über_Skripte

Kurzbeschreibung

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 verfügen über 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 zur 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 standardmäßige Ausführungsrichtlinie Restrictedverhindert, dass 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 ist 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 umgekehrten 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 Parameter ServiceName 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 im Datei-Explorer auf das Skriptsymbol doppelklicken oder 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.

Ausführen mit PowerShell

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

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

Führen Sie den Datei-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

Um ein Skript auf einem oder mehreren Remotecomputern auszuführen, verwenden Sie den FilePath Parameter des cmdlets Invoke-Command.

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.

Der folgende Befehl führt das skript Get-ServiceLog.ps1 auf den Remotecomputern Server01 und Server02 aus.

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

Wie man ein Skript schreibt

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 dateierweiterung .ps1.

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 #Require Anweisungen.

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. 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.

Hilfe beim Schreiben von Skripten

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

• Comment-Based Hilfe für Skripts

  Erstellen Sie ein Hilfethema, indem Sie spezielle Schlüsselwörter in den Kommentaren verwenden. 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-Based 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 das Schlüsselwort ".ExternalHelp-Hilfekommentar". Weitere Informationen zum Schlüsselwort „ExternalHelp“ finden Sie unter about_Comment_Based_Help. Weitere Informationen zur XML-basierten Hilfe finden Sie unter Wie man Cmdlet-Hilfe schreibt.

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 0zurück. Sie können einen numerischen Wert angeben, um einen anderen Beendigungsstatus zurückzugeben. Ein Exitcode ungleich Null signalisiert in der Regel einen Fehler.

Unter Windows ist eine beliebige Zahl zwischen [int]::MinValue und [int]::MaxValue 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 bis -255 wird automatisch in eine positive Zahl übersetzt, indem 256 hinzugefügt wird. Beispielsweise wird -2 in 254transformiert.

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

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

Skriptbereich und DOT-Quellentnahme

Jedes Skript wird in seinem 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 dot-sourcen.

Mit dem Feature „DOT-Quellentnahme“ können Sie ein Skript im aktuellen Bereich statt im Skriptbereich ausführen. Wenn Sie ein Skript ausführen, das dot-sourced ist, werden die Befehle im Skript so ausgeführt, als hätten Sie sie direkt in die 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 für ein Skript Dot-Sourcing durchzuführen, setzen Sie vor dem Skriptpfad einen Punkt (.) und ein Leerzeichen.

Beispiel:

. C:\scripts\UtilityFunctions.ps1

oder

. .\UtilityFunctions.ps1

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

Beispielsweise erstellt das skript UtilityFunctions.ps1 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 ein punktiertes Skript ausführen, erstellt es in Ihrer Sitzung in Ihrem Geltungsbereich die Funktion New-Profile und die Variable $ProfileName. 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 Geltungsbereich 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 Skriptfunktionen

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.

  Seit PowerShell 3.0 hat $MyInvocation zwei neue Eigenschaften, die Informationen über das Skript bereitstellen, das das aktuelle Skript aufgerufen oder eingeleitet hat. Die Werte dieser Eigenschaften werden nur aufgefüllt, wenn der Aufrufer oder Auslöser ein Skript ist.

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

  • PSScriptRoot enthält das Verzeichnis des Skripts, das das aktuelle Skript aufrief 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 zum Skript, das das aktuelle Skript aufgerufen hat.

• Datenabschnitte – Sie können das schlüsselwort Data verwenden, um Daten von 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 über_Ausführungsrichtlinien und über_Signieren.

Siehe auch

• about_Command_Precedence
• Über kommentarbasierte Hilfe
• about_Execution_Policies
• about_Functions
• about_Modules
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Befehl