about_Scripts

Krótki opis

Opisuje sposób uruchamiania i pisania skryptów w programie PowerShell.

Długi opis

Skrypt jest plikiem w postaci zwykłego tekstu, który zawiera co najmniej jedno polecenie programu PowerShell. Skrypty programu PowerShell mają rozszerzenie pliku .ps1.

Uruchamianie skryptu jest bardzo podobne do uruchamiania polecenia cmdlet. Należy wpisać ścieżkę i nazwę pliku skryptu oraz użyć parametrów do przesyłania danych i ustawiania opcji. Skrypty można uruchamiać na komputerze lub w sesji zdalnej na innym komputerze.

Pisanie skryptu zapisuje polecenie do późniejszego użycia i ułatwia udostępnianie innym osobom. Co najważniejsze, umożliwia uruchamianie poleceń po prostu przez wpisanie ścieżki skryptu i nazwy pliku. Skrypty mogą być tak proste, jak pojedyncze polecenie w pliku lub tak obszerne, jak złożony program.

Skrypty mają dodatkowe funkcje, takie jak #Requires specjalny komentarz, użycie parametrów, obsługa sekcji danych i podpisywanie cyfrowe na potrzeby zabezpieczeń. Możesz również napisać tematy pomocy dotyczące skryptów oraz funkcji w dowolnym skrypcie.

Jak uruchomić skrypt

Przed uruchomieniem skryptu w systemie Windows należy zmienić domyślne zasady wykonywania programu PowerShell. Zasady wykonywania nie dotyczą programu PowerShell uruchomionego na platformach innych niż Windows.

Domyślne zasady wykonywania, Restricted, zapobiega uruchamianiu wszystkich skryptów, w tym skryptów zapisywanych na komputerze lokalnym. Aby uzyskać więcej informacji, przejdź do about_Execution_Policies.

Zasady wykonywania są zapisywane w rejestrze, dlatego należy zmienić je tylko raz na każdym komputerze.

Aby zmienić zasady wykonywania, użyj poniższej procedury.

W wierszu polecenia wpisz:

Set-ExecutionPolicy AllSigned

lub

Set-ExecutionPolicy RemoteSigned

Zmiana jest skuteczna natychmiast.

Aby uruchomić skrypt, wpisz pełną nazwę i pełną ścieżkę do pliku skryptu.

Aby na przykład uruchomić skrypt Get-ServiceLog.ps1 w katalogu C:\Scripts, wpisz:

C:\Scripts\Get-ServiceLog.ps1

Aby uruchomić skrypt w bieżącym katalogu, wpisz ścieżkę do bieżącego katalogu lub użyj kropki do reprezentowania bieżącego katalogu, a następnie ukośnika odwrotnego ścieżki (.\).

Aby na przykład uruchomić skrypt ServicesLog.ps1 w katalogu lokalnym, wpisz:

.\Get-ServiceLog.ps1

Jeśli skrypt ma parametry, wpisz parametry i wartości parametrów po nazwie pliku skryptu.

Na przykład następujące polecenie używa parametru ServiceName skryptu Get-ServiceLog, aby zażądać dziennika aktywności usługi WinRM.

.\Get-ServiceLog.ps1 -ServiceName WinRM

Jako funkcja zabezpieczeń program PowerShell nie uruchamia skryptów po dwukrotnym kliknięciu ikony skryptu w Eksploratorze plików lub wpisie nazwy skryptu bez pełnej ścieżki, nawet jeśli skrypt znajduje się w bieżącym katalogu. Aby uzyskać więcej informacji na temat uruchamiania poleceń i skryptów w programie PowerShell, zobacz about_Command_Precedence.

Uruchamianie przy użyciu programu PowerShell

Począwszy od programu PowerShell 3.0, można uruchamiać skrypty w Eksploratorze plików.

Aby użyć funkcji "Uruchom z programem PowerShell":

Uruchom Eksploratora plików, kliknij prawym przyciskiem myszy nazwę pliku skryptu, a następnie wybierz polecenie "Uruchom przy użyciu programu PowerShell".

Funkcja "Uruchom za pomocą programu PowerShell" jest przeznaczona do uruchamiania skryptów, które nie mają wymaganych parametrów i nie zwracają danych wyjściowych do wiersza polecenia.

Aby uzyskać więcej informacji, zobacz about_Run_With_PowerShell.

Uruchamianie skryptów na innych komputerach

Aby uruchomić skrypt na co najmniej jednym komputerze zdalnym, użyj parametru FilePath polecenia cmdlet Invoke-Command.

Wprowadź ścieżkę i nazwę pliku skryptu jako wartość parametru FilePath. Skrypt musi znajdować się na komputerze lokalnym lub w katalogu, do którego komputer lokalny może uzyskać dostęp.

Następujące polecenie uruchamia skrypt Get-ServiceLog.ps1 na komputerach zdalnych o nazwach Server01 i Server02.

$invokeCommandSplat = @{
    ComputerName = 'Server01', 'Server02'
    FilePath = 'C:\Scripts\Get-ServiceLog.ps1'
}
Invoke-Command @invokeCommandSplat

Uzyskiwanie pomocy dotyczącej skryptów

Polecenie cmdlet Get-Help pobiera tematy pomocy dotyczące skryptów oraz innych typów poleceń. Aby uzyskać temat pomocy dla skryptu, wpisz Get-Help, a następnie ścieżkę i nazwę pliku skryptu. Jeśli ścieżka skryptu znajduje się w zmiennej środowiskowej PATH, możesz pominąć ścieżkę.

Aby na przykład uzyskać pomoc dotyczącą skryptu ServicesLog.ps1, wpisz:

Get-Help C:\admin\scripts\ServicesLog.ps1

Jak napisać skrypt

Skrypt może zawierać dowolne prawidłowe polecenia programu PowerShell, w tym pojedyncze polecenia, polecenia korzystające z potoku, funkcji i struktur sterujących, takich jak instrukcje if i pętle for.

Aby napisać skrypt, otwórz nowy plik w edytorze tekstów, wpisz polecenia i zapisz je w pliku z prawidłową nazwą pliku z rozszerzeniem .ps1 pliku.

Poniższy przykład to prosty skrypt, który pobiera usługi uruchomione w bieżącym systemie i zapisuje je w pliku dziennika. Nazwa pliku dziennika jest tworzona na podstawie bieżącej daty.

$date = (Get-Date).DayOfYear
Get-Service | Out-File "$date.log"

Aby utworzyć ten skrypt, otwórz edytor tekstów lub edytor skryptów, wpisz te polecenia, a następnie zapisz je w pliku o nazwie ServiceLog.ps1.

Parametry w skryptach

Aby zdefiniować parametry w skryfcie, użyj instrukcji param. Instrukcja param musi być pierwszą instrukcją w skrypcie, z wyjątkiem komentarzy i instrukcji #Requires.

Parametry skryptu działają jak parametry funkcji. Wartości parametrów są dostępne dla wszystkich poleceń skryptu. Wszystkie funkcje parametrów funkcji, w tym atrybut Parametr i jego nazwane argumenty, są również prawidłowe w skryptach.

Podczas uruchamiania skryptu użytkownicy skryptu wpiszą parametry po nazwie skryptu.

W poniższym przykładzie przedstawiono skrypt Test-Remote.ps1 z parametrem ComputerName. Obie funkcje skryptu mogą uzyskać dostęp do wartości parametru 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}

Aby uruchomić ten skrypt, wpisz nazwę parametru po nazwie skryptu. Na przykład:

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

Ping succeeded: Server01
Remote test failed: Server01

Aby uzyskać więcej informacji na temat instrukcji param i parametrów funkcji, zobacz about_Functions i about_Functions_Advanced_Parameters.

Pomoc w pisaniu skryptów

Temat pomocy dla skryptu można napisać przy użyciu jednej z dwóch następujących metod:

• Comment-Based Pomoc dotycząca skryptów

  Utwórz temat Pomocy, używając specjalnych słów kluczowych w komentarzach. Aby utworzyć pomoc opartą na komentarzach dla skryptu, komentarze muszą zostać umieszczone na początku lub na końcu pliku skryptu. Aby uzyskać więcej informacji na temat pomocy opartej na komentarzach, zobacz about_Comment_Based_Help.

• XML-Based Pomoc dotycząca skryptów

  Utwórz temat Pomocy opartej na formacie XML, taki jak typ, który jest zwykle tworzony dla poleceń cmdlet. Pomoc oparta na języku XML jest wymagana, jeśli tłumaczysz tematy Pomocy na wiele języków.

Aby skojarzyć skrypt z tematem Pomocy opartej na języku XML, użyj słowa kluczowego .EXTERNALHELP Komentarz pomocy. Aby uzyskać więcej informacji, zobacz:

• about_Comment_Based_Help
• Jak napisać pomoc dotyczącą poleceń cmdlet

Zwracanie wartości wyjścia

Domyślnie skrypty nie zwracają stanu zakończenia po zakończeniu skryptu. Aby zwrócić kod zakończenia ze skryptu, należy użyć instrukcji exit. Domyślnie instrukcja exit zwraca 0. Możesz podać wartość liczbową, aby zwrócić inny kod zakończenia. Kod zakończenia niezerowy zwykle sygnalizuje awarię.

W systemie Windows dozwolona jest dowolna liczba między [int]::MinValue a [int]::MaxValue.

W systemie Unix dozwolone są tylko liczby dodatnie z zakresu od [byte]::MinValue (0) do [byte]::MaxValue (255). Liczba ujemna w zakresie -1 przez -255 jest automatycznie tłumaczona na liczbę dodatnią przez dodanie wartości 256. Na przykład -2 jest przekształcana w 254.

W programie PowerShell instrukcja exit ustawia wartość zmiennej $LASTEXITCODE. W powłoce poleceń systemu Windows (cmd.exe) instrukcja exit ustawia wartość zmiennej środowiskowej %ERRORLEVEL%.

Każdy argument, który nie jest numeryczny lub poza zakresem specyficznym dla platformy, jest tłumaczony na wartość 0.

Zakres skryptu i określanie źródła kropki

Każdy skrypt jest uruchamiany we własnym zakresie. Funkcje, zmienne, aliasy i dyski utworzone w skrycie istnieją tylko w zakresie skryptu. Nie można uzyskać dostępu do tych elementów ani ich wartości w zakresie, w którym jest uruchamiany skrypt.

Aby uruchomić skrypt w innym zakresie, możesz określić zakres, taki jak globalny lub lokalny, lub możesz kropkować źródło skryptu.

Funkcja dot sourcing umożliwia uruchomienie skryptu w bieżącym zakresie zamiast w zakresie skryptu. Po uruchomieniu skryptu, który jest dot sourced, polecenia w skrypcie działają tak, jakby były wpisywane w wierszu polecenia. Funkcje, zmienne, aliasy i dyski tworzone przez skrypt są tworzone w zakresie, w którym pracujesz. Po uruchomieniu skryptu możesz użyć utworzonych elementów i uzyskać dostęp do ich wartości w sesji.

Aby kropkować źródło skryptu, wpisz kropkę (.) i spację przed ścieżką skryptu.

Na przykład:

. C:\scripts\UtilityFunctions.ps1

lub

. .\UtilityFunctions.ps1

Po uruchomieniu skryptu UtilityFunctions.ps1 funkcje i zmienne tworzone przez skrypt zostaną dodane do bieżącego zakresu.

Na przykład skrypt UtilityFunctions.ps1 tworzy funkcję New-Profile i zmienną $ProfileName.

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

Jeśli uruchomisz skrypt UtilityFunctions.ps1 we własnym zakresie skryptu, funkcja New-Profile i zmienna $ProfileName istnieją tylko podczas działania skryptu. Po zakończeniu działania skryptu funkcja i zmienna zostaną usunięte, jak pokazano w poniższym przykładzie.

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>

Kiedy wykonujesz kropkowanie źródła skryptu i uruchomisz go, skrypt tworzy funkcję New-Profile i zmienną $ProfileName w twojej sesji w twoim zakresie. Po uruchomieniu skryptu można użyć funkcji New-Profile w sesji, jak pokazano w poniższym przykładzie.

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

Aby uzyskać więcej informacji na temat zakresów, zobacz about_Scopes.

Skrypty w modułach

Moduł to zestaw powiązanych zasobów programu PowerShell, które można dystrybuować jako jednostkę. Moduły umożliwiają organizowanie skryptów, funkcji i innych zasobów. Możesz również użyć modułów do dystrybuowania kodu do innych osób i pobierania kodu z zaufanych źródeł.

Możesz uwzględnić skrypty w modułach lub utworzyć moduł skryptu, który jest modułem składającym się wyłącznie lub głównie ze skryptu i zasobów pomocniczych. Moduł skryptu to tylko skrypt z rozszerzeniem .psm1 pliku.

Aby uzyskać więcej informacji na temat modułów, zobacz about_Modules.

Inne funkcje skryptu

Program PowerShell ma wiele przydatnych funkcji, których można używać w skryptach.

• #Requires — można użyć instrukcji #Requires, aby zapobiec uruchamianiu skryptu bez określonych modułów lub przystawek oraz określonej wersji programu PowerShell. Aby uzyskać więcej informacji, zobacz sekcję about_Requires.

• $PSCommandPath — zawiera pełną ścieżkę i nazwę uruchamianego skryptu. Ten parametr jest prawidłowy we wszystkich skryptach. Ta zmienna automatyczna jest wprowadzana w programie PowerShell 3.0.

• $PSScriptRoot — zawiera katalog, z którego jest uruchamiany skrypt. W programie PowerShell 2.0 ta zmienna jest prawidłowa tylko w modułach skryptów (.psm1). Począwszy od programu PowerShell 3.0, jest on prawidłowy we wszystkich skryptach.

• $MyInvocation — zmienna automatyczna $MyInvocation zawiera informacje na temat bieżącego skryptu, w tym informacje o sposobie jej uruchomienia lub wywołaniu. Możesz użyć tej zmiennej i jej właściwości, aby uzyskać informacje na temat skryptu podczas jego działania. Na przykład $MyInvocation. Zmienna MyCommand.Path zawiera ścieżkę i nazwę pliku skryptu. $MyInvocation. Wiersz zawiera polecenie, które uruchomiło skrypt, w tym wszystkie parametry i wartości.

  Począwszy od programu PowerShell 3.0, $MyInvocation ma dwie nowe właściwości, które zawierają informacje o skrypcie, który zainicjował lub wywołał bieżący skrypt. Wartości tych właściwości są wypełniane wyłącznie, gdy wywołujący jest skryptem.

  • PSCommandPath zawiera pełną ścieżkę i nazwę skryptu, który uruchomił lub wywołał bieżący skrypt.

  • PSScriptRoot zawiera katalog skryptu, który uruchomił lub zainicjował bieżący skrypt.

  W przeciwieństwie do zmiennych automatycznych $PSCommandPath i $PSScriptRoot, które zawierają informacje o bieżącym skrypcie, właściwości PSCommandPath i PSScriptRoot zmiennej $MyInvocation zawierają informacje o skrypcie, który wywołał bieżący skrypt.

• Sekcje danych — słowo kluczowe Data umożliwia oddzielenie danych od logiki w skryptach. Sekcje danych mogą również ułatwić lokalizację. Aby uzyskać więcej informacji, zobacz about_Data_Sections i about_Script_Internationalization.

• Podpisywanie skryptów — możesz dodać podpis cyfrowy do skryptu. W zależności od zasad wykonywania można użyć podpisów cyfrowych, aby ograniczyć uruchamianie skryptów, które mogą zawierać niebezpieczne polecenia. Aby uzyskać więcej informacji, zobacz about_Execution_Policies i about_Signing.

Zobacz także

• about_Command_Precedence
• about_Comment_Based_Help
• opis_polityk_wykonywania
• about_Functions
• o_modułach
• about_Profiles
• o_Wymaganiach
• o_uruchamianiu_z_PowerShell
• about_Scopes
• about_Script_Blocks
• o_podpisywaniu
• Invoke-Command