about_Scripts

Krótki opis

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

Długi opis

Skrypt to zwykły plik tekstowy zawierający co najmniej jedno polecenie programu PowerShell. Skrypty programu PowerShell mają .ps1 rozszerzenie pliku.

Uruchamianie skryptu jest bardzo podobne do uruchamiania polecenia cmdlet. Wpisz ścieżkę i nazwę pliku skryptu i użyj 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ć proste jako 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ż pisać tematy pomocy dotyczące skryptów i dowolnych funkcji w skrycie.

Jak uruchomić skrypt

Przed uruchomieniem skryptu w systemie Windows należy zmienić domyślne zasady wykonywania programu PowerShell. Zasady wykonywania nie mają zastosowania do programu PowerShell działającego na platformach innych niż Windows.

Domyślne zasady wykonywania , Restricteduniemożliwiają uruchamianie wszystkich skryptów, w tym skryptów zapisywanych na komputerze lokalnym. Aby uzyskać więcej informacji, zobacz 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 polecenie:

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, aby reprezentować bieżący katalog, a następnie ukośnik odwrotny ś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 skryptu.

Na przykład następujące polecenie używa parametru ServiceName skryptu Get-ServiceLog w celu żądania 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 Eksplorator plików lub po wpiseniu nazwy skryptu bez pełnej ścieżki, nawet gdy 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 za pomocą programu PowerShell

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

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

Uruchom polecenie Eksplorator plików, kliknij prawym przyciskiem myszy nazwę pliku skryptu, a następnie wybierz polecenie "Uruchom za pomocą 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 Invoke-CommandFilePath polecenia cmdlet.

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 Get-ServiceLog.ps1 skrypt na komputerach zdalnych o nazwie Server01 i Server02.

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

Uzyskiwanie pomocy dotyczącej skryptów

Polecenie cmdlet Get-Help pobiera tematy pomocy dla skryptów, a także polecenia cmdlet i inne typy poleceń. Aby uzyskać temat pomocy dla skryptu, wpisz Get-Help ścieżkę i nazwę pliku skryptu. Jeśli ścieżka skryptu znajduje się w Path zmiennej środowiskowej, 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 .ps1 rozszerzeniem 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 skrycie, użyj instrukcji Param. Instrukcja Param musi być pierwszą instrukcją w skrypcie, z wyjątkiem komentarzy i wszystkich #Require instrukcji.

Parametry skryptu działają jak parametry funkcji. Wartości parametrów są dostępne dla wszystkich poleceń w skrycie. 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 Test-Remote.ps1 skrypt, który ma parametr ComputerName . Obie funkcje skryptu mogą uzyskiwać 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.

Pisanie pomocy dotyczącej 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

  Twórca tematu Pomocy przy użyciu 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

  Twórca 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 polecenia . ExternalHelp Pomoc słowo kluczowe komentarza. Aby uzyskać więcej informacji na temat słowa kluczowego ExternalHelp, zobacz about_Comment_Based_Help. Aby uzyskać więcej informacji na temat pomocy opartej na formacie XML, zobacz How to Write Cmdlet Help (Jak napisać pomoc dotyczącą poleceń cmdlet).

Zwracanie wartości zakończenia

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

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

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

W programie PowerShell exit instrukcja 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 liczbowy 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 source umożliwia uruchamianie skryptu w bieżącym zakresie zamiast w zakresie skryptu. Po uruchomieniu skryptu, który jest dot sourced, polecenia w skrypcie są uruchamiane 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żna 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 są dodawane do bieżącego zakresu.

Na przykład UtilityFunctions.ps1 skrypt tworzy New-Profile funkcję 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 skrypt zostanie uruchomiony UtilityFunctions.ps1 we własnym zakresie skryptu, New-Profile funkcja 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>

Po utworzeniu kropki źródłowej skryptu i uruchomieniu go skrypt tworzy New-Profile funkcję i zmienną $ProfileName w sesji w zakresie. Po uruchomieniu skryptu można użyć New-Profile funkcji 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 zakresu, 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 dołączyć skrypty w modułach lub utworzyć moduł skryptu, który jest modułem składającym się całkowicie lub przede wszystkim ze skryptu i zasobów pomocniczych. Moduł skryptu to tylko skrypt z rozszerzeniem pliku psm1.

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ć #Requires instrukcji, aby zapobiec uruchamianiu skryptu bez określonych modułów lub przystawki i określonej wersji programu PowerShell. Aby uzyskać więcej informacji, zobacz 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 tym, jak została uruchomiona lub "wywoływana". 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 skrycie, który wywołał lub wywołał bieżący skrypt. Wartości tych właściwości są wypełniane tylko wtedy, gdy obiekt wywołujący lub wywołujący jest skryptem.

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

  • Plik PSScriptRoot zawiera katalog skryptu o nazwie lub wywołaniu bieżącego skryptu.

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

• Sekcje danych — słowo kluczowe umożliwia Data 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 też

• about_Command_Precedence
• about_Comment_Based_Help
• about_Execution_Policies
• about_Functions
• O_modułach
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Wywołaj polecenie