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ą .ps1 rozszerzenie pliku.

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 i dowolnych funkcji w skry skrycie.

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, 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:

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 Eksplorator plików lub wpisania 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.

Uruchom za pomocą programu PowerShell

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

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

Uruchom Eksplorator 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 Invoke-Command FilePath 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 nazwach 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 dotyczące skryptów, a także poleceń cmdlet i innych typów 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 skry skrycie, użyj instrukcji Param. Instrukcja Param musi być pierwszą instrukcją w skrypcie, z wyjątkiem komentarzy i instrukcji #Require .

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 pokazano Test-Remote.ps1 skrypt 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.

Pisanie pomocy dotyczącej skryptów

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

• Pomoc oparta na komentarzach dla 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.

• Pomoc oparta na języku XML dla 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 polecenia . ExternalHelp , słowo kluczowe komentarza Pomocy. 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 awarię.

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 -1 od jest -255 automatycznie tłumaczona na liczbę dodatnią przez dodanie wartości 256. Na przykład -2 element jest przekształcany na 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 określania źródła kropk 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 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ła 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 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 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 przystawek i określonej wersji programu PowerShell. Aby uzyskać więcej informacji, zobacz about_Requires.

• $PSCommandPath — Zawiera pełną ścieżkę i nazwę skryptu, który jest uruchamiany. 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 skry 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, który wywołał lub wywołał bieżący skrypt.

  $PSCommandPath W przeciwieństwie do zmiennych automatycznych 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 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
• about_Modules
• about_Profiles
• about_Requires
• about_Run_With_PowerShell
• about_Scopes
• about_Script_Blocks
• about_Signing
• Invoke-Command