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 verfügen über eine .ps1 Dateierweiterung.

Das Ausführen eines Skripts ähnelt der Ausführung eines Cmdlets. Sie geben den Pfad und dateinamen des Skripts ein und verwenden Parameter, um Daten zu übermitteln und Optionen festzulegen. 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. Am wichtigsten ist, dass Sie die Befehle einfach ausführen können, 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 die Sicherheit. Sie können auch Hilfethemen für Skripts und 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 about_Execution_Policies.

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

Gehen Sie wie folgt vor, um die Ausführungsrichtlinie zu ändern.

Geben Sie an der Eingabeaufforderung Folgendes ein:

Set-ExecutionPolicy AllSigned

oder

Set-ExecutionPolicy RemoteSigned

Die Änderung wird sofort wirksam.

Um ein Skript auszuführen, geben Sie den vollständigen Namen und den vollständigen Pfad zur Skriptdatei ein.

Um beispielsweise das skript Get-ServiceLog.ps1 im Verzeichnis C:\Scripts auszuführen, 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 zur Darstellung des aktuellen Verzeichnisses, gefolgt von einem 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 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 in 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 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 Namen der Skriptdatei, und wählen Sie dann "Mit PowerShell ausführen" aus.

Das Feature "Mit PowerShell ausführen" dient zum Ausführen von Skripts ohne erforderliche Parameter und gibt keine Ausgabe an die Eingabeaufforderung zurück.

Weitere Informationen finden Sie unter Informationen zum Ausführen mit PowerShell.

Ausführen von Skripts auf anderen Computern

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

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 für Skripts

Das Cmdlet Get-Help ruft die Hilfethemen für Skripts sowie für Cmdlets und andere Befehlstypen 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 Umgebungsvariablen befindet, können Sie den Pfad weglassen.

Um beispielsweise Hilfe für das ServicesLog.ps1-Skript 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 verwenden, Funktionen und Steuerungsstrukturen wie If-Anweisungen und For-Schleifen.

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 sie in einer Protokolldatei speichert. Der Protokolldateiname wird ab dem aktuellen Datum erstellt.

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

Öffnen Sie zum Erstellen dieses Skripts einen Text-Editor oder einen Skript-Editor, geben Sie diese Befehle ein, und speichern Sie sie dann in einer Datei namens ServiceLog.ps1.

Parameter in Skripts

Verwenden Sie eine Param-Anweisung, um Parameter in einem Skript zu definieren. 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 seiner 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, das über einen ComputerName-Parameter verfügt. 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}

Um dieses Skript auszuführen, geben Sie 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 zu 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:

• Comment-Based Hilfe für Skripts

  Erstellen Sie ein Hilfethema, indem Sie spezielle Schlüsselwörter in den Kommentaren verwenden. Um 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 . ExternalHelp-Hilfekommentarschlüsselwort. Weitere Informationen zum ExternalHelp-Schlüsselwort finden Sie unter about_Comment_Based_Help. Weitere Informationen zur XML-basierten Hilfe finden Sie unter How to Write Cmdlet Help.For more information about XML-based help, see How to Write Cmdlet Help.

Zurückgeben eines Exitwerts

Standardmäßig geben Skripts keinen Exitstatus zurück, wenn das Skript endet. Sie müssen die exit -Anweisung verwenden, um einen Exitcode aus einem Skript zurückzugeben. Standardmäßig gibt die exit -Anweisung zurück 0. Sie können einen numerischen Wert angeben, um einen anderen Exitstatus zurückzugeben. Ein Exitcode ungleich 0 (null) signalisiert in der Regel einen Fehler.

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

Unter 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. Beispielsweise -2 wird in 254transformiert.

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% Umgebungsvariablen fest.

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

Skriptbereich und Punktsourcing

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 in dem Bereich zugreifen, in dem das Skript ausgeführt wird.

Um ein Skript in einem anderen Bereich auszuführen, können Sie einen Bereich angeben, z. B. Global oder Lokal, oder Sie können die Quelle des Skripts punktieren.

Mit der Dot-Sourcing-Funktion können Sie ein Skript im aktuellen Bereich anstatt im Skriptbereich ausführen. Wenn Sie ein Skript mit Punktquelle ausführen, 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 auf deren Werte in Ihrer Sitzung zugreifen.

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

Beispiel:

. C:\scripts\UtilityFunctions.ps1

oder

. .\UtilityFunctions.ps1

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

Das Skript erstellt beispielsweise 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 die 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 die Quelle des Skripts 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 ein Satz verwandter PowerShell-Ressourcen, die als Einheit verteilt werden können. Sie können Module verwenden, um Ihre 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 Sie können 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.

Andere 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 angegebene 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 es in allen Skripts gültig.

• $MyInvocation – Die $MyInvocation automatische Variable enthält Informationen zum aktuellen Skript, einschließlich Informationen darüber, wie es gestartet oder "aufgerufen" wurde. Sie können diese Variable und ihre Eigenschaften verwenden, um Informationen zum Skript abzurufen, während es ausgeführt wird. Beispiel: $MyInvocation. Die Variable MyCommand.Path enthält den Pfad und dateinamen des Skripts. $MyInvocation. Line enthält den Befehl, der das Skript gestartet hat, einschließlich aller Parameter und Werte.

  Ab PowerShell 3.0 verfügt über zwei neue Eigenschaften, die Informationen zum Skript bereitstellen, $MyInvocation 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 automatischen Variablen und $PSScriptRoot , die Informationen zum aktuellen Skript enthalten, enthalten die EIGENSCHAFTEN PSCommandPath und PSScriptRoot der $MyInvocation Variablen Informationen zu dem Skript, das das aktuelle Skript aufgerufen hat.

• Datenabschnitte: Sie können das Data Schlüsselwort 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 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