about_Scripts

Kurze Beschreibung

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

Lange Beschreibung

Ein Skript ist eine einfache Textdatei, 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 den Dateinamen des Skripts ein und verwenden Parameter zum Übermitteln 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. Am wichtigsten ist es, dass 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, unterstützung für Datenabschnitte und 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 Standard-PowerShell-Ausführungsrichtlinie ändern. Die Ausführungsrichtlinie gilt nicht für PowerShell, die auf Nicht-Windows-Plattformen ausgeführt wird.

Die Standardausführungsrichtlinie verhindert Restricted, dass 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.

Um die Ausführungsrichtlinie zu ändern, verwenden Sie die folgende Prozedur.

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 Get-ServiceLog.ps1-Skript im Verzeichnis "C:\Skripts" ausführen möchten, geben Sie folgendes ein:

C:\Scripts\Get-ServiceLog.ps1

Geben Sie zum Ausführen eines Skripts im aktuellen Verzeichnis den Pfad zum aktuellen Verzeichnis ein, oder verwenden Sie einen Punkt, um das aktuelle Verzeichnis darzustellen, gefolgt von einem Pfad backslash (.\).

Geben Sie beispielsweise zum Ausführen des ServicesLog.ps1-Skripts im lokalen Verzeichnis 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.

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 Skriptdateinamen, und wählen Sie dann "Mit PowerShell ausführen" aus.

Das Feature "Ausführen mit PowerShell" ist so konzipiert, dass Skripts ausgeführt werden, die keine erforderlichen Parameter aufweisen und keine Ausgabe an die Eingabeaufforderung zurückgeben.

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

Ausführen von Skripts auf anderen Computern

Verwenden Sie zum Ausführen eines Skripts auf einem oder mehreren Remotecomputern den FilePath-Parameter des Invoke-Command Cmdlets.

Geben Sie den Pfad und den 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 Get-ServiceLog.ps1 Skript auf den Remotecomputern mit dem Namen Server01 und Server02 aus.

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

Hilfe für Skripts erhalten

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 den Pfad und den Dateinamen des Skripts ein. Wenn sich der Skriptpfad in Ihrer Path Umgebungsvariable befindet, können Sie den Pfad auslassen.

Geben Sie beispielsweise Hilfe für das ServicesLog.ps1-Skript ein:

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

So schreiben Sie ein Skript

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.

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

Im folgenden Beispiel handelt es sich um ein einfaches Skript, das die Dienste ruft, 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

Um Parameter in einem Skript zu definieren, verwenden Sie eine Param-Anweisung. Die Param Anweisung muss die erste Anweisung in einem Skript sein, außer für Kommentare und alle #Require Anweisungen.

Skriptparameter funktionieren wie Funktionsparameter. Die Parameterwerte sind für alle Befehle im Skript verfügbar. Alle Funktionen 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.

Im folgenden Beispiel wird ein Test-Remote.ps1 Skript mit einem ComputerName-Parameter angezeigt. 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:

  • hilfe für Skripts Comment-Based

    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.

  • hilfe für Skripts XML-Based

    Erstellen Sie ein XML-basiertes Hilfethema, z. B. den Typ, der in der Regel 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-Hilfekommentarwort. Weitere Informationen zum ExternalHelp-Schlüsselwort 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 gibt Skripts keinen Exitstatus zurück, wenn das Skript beendet wird. Sie müssen die exit Anweisung verwenden, um einen Exitcode aus einem Skript zurückzugeben. Standardmäßig gibt 0die exit Anweisung zurück. Sie können einen numerischen Wert bereitstellen, um einen anderen Exitstatus zurückzugeben. Ein Nichtzero-Exitcode signalisiert normalerweise einen Fehler.

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

Bei Unix sind nur positive Zahlen zwischen [byte]::MinValue (0) und [byte]::MaxValue (255) zulässig. Eine negative Zahl im Bereich des -1 Durchlaufs -255 wird automatisch in eine positive Zahl übersetzt, indem Sie 256 hinzufügen. So wird z. B -2 . in 254".

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

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

Skriptbereich und Dot-Beschaffung

Jedes Skript wird im 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 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 dot ist, führen die Befehle im Skript aus, wie sie bei der Eingabeaufforderung eingegeben wurden. Die Funktionen, Variablen, Aliase und Laufwerke, die das Skript erstellt, werden im Bereich erstellt, in dem Sie arbeiten. Nachdem das Skript ausgeführt wurde, können Sie die erstellten Elemente verwenden und auf ihre Werte in Ihrer Sitzung zugreifen.

Um ein Skript zu dotieren, geben Sie einen Punkt (.) und einen 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.

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 Skript in einem eigenen Skriptbereich ausführen, ist die Funktion und die New-Profile$ProfileName Variable nur vorhanden, während das UtilityFunctions.ps1 Skript ausgeführt wird. Wenn das Skript beendet wird, werden die Funktion und Variable entfernt, wie im folgenden Beispiel dargestellt.

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

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 ein Skriptmodul erstellen, das ein Modul ist, das vollständig oder primär aus einem Skript und unterstützenden Ressourcen besteht. Ein Skriptmodul ist nur ein Skript mit einer PSM1-Dateierweiterung.

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 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 den 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 gültig (.psm1). Ab PowerShell 3.0 ist es in allen Skripts gültig.

  • $MyInvocation - Die $MyInvocation automatische Variable enthält Informationen zu dem aktuellen Skript, einschließlich Informationen zum Starten oder "Aufrufen". Sie können diese Variable und ihre Eigenschaften verwenden, um Informationen über das Skript abzurufen, während sie ausgeführt wird. Beispiel: Das $MyInvocation. MyCommand.Path-Variable 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, die Informationen über das Skript bereitstellen, $MyInvocation das das aktuelle Skript aufgerufen oder aufgerufen hat. Die Werte dieser Eigenschaften werden nur ausgefü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.

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

  • Datenabschnitte – Sie können das Data Schlüsselwort verwenden, um Daten aus 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 einer 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önnten. Weitere Informationen finden Sie unter about_Execution_Policies und about_Signing.

Siehe auch