Sdílet prostřednictvím

about_Scripts

Krátký popis

Popisuje, jak spouštět a zapisovat skripty v PowerShellu.

Dlouhý popis

Skript je soubor ve formátu prostého textu, který obsahuje jeden nebo více příkazů PowerShellu. Skripty PowerShellu mají příponu souboru .ps1.

Spuštění skriptu je hodně jako spuštění cmdletu. Zadáte cestu a název souboru skriptu a použijete parametry k odeslání dat a nastavení možností. Skripty můžete spouštět na počítači nebo ve vzdálené relaci na jiném počítači.

Napsání skriptu uloží příkaz pro pozdější použití a usnadňuje sdílení s ostatními. Nejdůležitější je, že vám umožní spouštět příkazy jednoduše zadáním cesty skriptu a názvu souboru. Skripty můžou být stejně jednoduché jako jeden příkaz v souboru nebo stejně rozsáhlé jako složitý program.

Skripty mají další funkce, jako je #Requires speciální komentář, použití parametrů, podpora datových oddílů a digitální podepisování pro zabezpečení. Můžete také napsat témata nápovědy pro skripty a pro všechny funkce ve skriptu.

Spuštění skriptu

Než budete moct spustit skript ve Windows, musíte změnit výchozí zásady spouštění PowerShellu. Zásady spouštění se nevztahují na PowerShell spuštěný na platformách mimo Windows.

Výchozí zásady spouštění Restrictedbrání spuštění všech skriptů, včetně skriptů, které píšete na místním počítači. Další informace naleznete v části about_Execution_Policies.

Zásady spouštění jsou uloženy v registru, takže je nutné je změnit pouze jednou na každém počítači.

Pokud chcete změnit zásady spouštění, použijte následující postup.

Do příkazového řádku zadejte:

Set-ExecutionPolicy AllSigned

nebo

Set-ExecutionPolicy RemoteSigned

Změna je okamžitě efektivní.

Pokud chcete spustit skript, zadejte úplný název a úplnou cestu k souboru skriptu.

Pokud chcete například spustit skript Get-ServiceLog.ps1 v adresáři C:\Scripts, zadejte:

C:\Scripts\Get-ServiceLog.ps1

Pokud chcete spustit skript v aktuálním adresáři, zadejte cestu k aktuálnímu adresáři nebo použijte tečku k reprezentaci aktuálního adresáře a za ní zpětné lomítko (.\).

Pokud chcete například spustit skript ServicesLog.ps1 v místním adresáři, zadejte:

.\Get-ServiceLog.ps1

Pokud má skript parametry, zadejte parametry a hodnoty parametrů za název souboru skriptu.

Například následující příkaz používá parametr ServiceName skriptu Get-ServiceLog k vyžádání protokolu aktivity služby WinRM.

.\Get-ServiceLog.ps1 -ServiceName WinRM

PowerShell jako funkce zabezpečení nespustí skripty, když dvakrát kliknete na ikonu skriptu v Průzkumníku souborů nebo když zadáte název skriptu bez úplné cesty, i když je skript v aktuálním adresáři. Další informace o spouštění příkazů a skriptů v PowerShellu najdete v tématu about_Command_Precedence.

Spuštění pomocí PowerShellu

Počínaje PowerShellem 3.0 můžete spouštět skripty z Průzkumníka souborů.

Použití funkce Spustit s PowerShellem:

Spusťte Průzkumníka souborů, klikněte pravým tlačítkem na název souboru skriptu a pak vyberte Spustit pomocí PowerShellu.

Funkce Spustit s PowerShellem je navržená tak, aby spouštěla skripty, které nemají požadované parametry, a nevracela výstup do příkazového řádku.

Další informace naleznete v tématu about_Run_With_PowerShell.

Spouštění skriptů na jiných počítačích

Pokud chcete spustit skript na jednom nebo více vzdálených počítačích, použijte parametr FilePath rutiny Invoke-Command.

Jako hodnotu parametru FilePath zadejte cestu a název souboru skriptu. Skript musí být umístěn v místním počítači nebo v adresáři, ke kterému má místní počítač přístup.

Následující příkaz spustí skript Get-ServiceLog.ps1 na vzdálených počítačích s názvem Server01 a Server02.

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

Získání nápovědy ke skriptům

Cmdlet Get-Help získá témata nápovědy pro skripty i pro cmdlety a další typy příkazů. Pokud chcete získat téma nápovědy pro skript, zadejte Get-Help následovanou cestou a názvem souboru skriptu. Pokud je cesta ke skriptu v prostředí proměnné Path, můžete ji vynechat.

Pokud chcete například získat nápovědu pro skript ServicesLog.ps1, zadejte:

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

Jak napsat skript

Skript může obsahovat všechny platné příkazy PowerShellu, včetně jednoduchých příkazů, příkazů, které používají kanál, funkce a řídicí struktury, jako jsou příkazy If a smyčky For.

Pokud chcete napsat skript, otevřete nový soubor v textovém editoru, zadejte příkazy a uložte je do souboru s platným názvem souboru s příponou .ps1.

Následující příklad je jednoduchý skript, který získá služby spuštěné v aktuálním systému a uloží je do souboru protokolu. Název souboru protokolu se vytvoří z aktuálního data.

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

Chcete-li vytvořit tento skript, otevřete textový editor nebo editor skriptů, zadejte tyto příkazy a uložte je do souboru s názvem ServiceLog.ps1.

Parametry ve skriptech

K definování parametrů ve skriptu použijte příkaz Param. Příkaz Param musí být prvním příkazem ve skriptu s výjimkou komentářů a všech příkazů #Require.

Parametry skriptu fungují jako parametry funkce. Hodnoty parametrů jsou k dispozici pro všechny příkazy ve skriptu. Všechny funkce parametrů funkce, včetně atributu Parameter a jejích pojmenovaných argumentů, jsou také platné ve skriptech.

Při spuštění skriptu zadávají uživatelé skriptu parametry za název skriptu.

Následující příklad ukazuje Test-Remote.ps1 skript, který má ComputerName parametr. Obě funkce skriptu mají přístup k hodnotě 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}

Chcete-li tento skript spustit, zadejte název parametru za název skriptu. Například:

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

Ping succeeded: Server01
Remote test failed: Server01

Další informace o příkazu Param a parametrech funkce naleznete v tématu about_Functions a about_Functions_Advanced_Parameters.

Psaní nápovědy pro skripty

Téma nápovědy pro skript můžete napsat pomocí některé z těchto dvou metod:

  • Nápověda pro skripty Comment-Based

    Vytvořte téma nápovědy pomocí speciálních klíčových slov v komentářích. Chcete-li vytvořit nápovědu založenou na komentáři pro skript, musí být komentáře umístěny na začátku nebo na konci souboru skriptu. Další informace o nápovědě založené na komentářích naleznete v tématu about_Comment_Based_Help.

  • Nápověda pro skripty XML-Based

    Vytvořte téma nápovědy na bázi XML, jako je typ, který se obvykle vytváří pro cmdlety. Pokud překládáte témata nápovědy do více jazyků, potřebujete nápovědu založenou na jazyce XML.

Chcete-li spojit skript s tématem nápovědy založeným na XML, použijte klíčové slovo komentáře .ExternalHelp. Další informace o klíčovém slově ExternalHelp naleznete v části about_Comment_Based_Help. Další informace o nápovědě založené na jazyce XML naleznete v tématu How to Write Cmdlet Help.

Vrácení výstupní hodnoty

Skripty ve výchozím nastavení nevrací stav ukončení, když skript skončí. K vrácení ukončovacího kódu ze skriptu je nutné použít příkaz exit. Ve výchozím nastavení vrátí příkaz exit0. Můžete zadat číselnou hodnotu, která vrátí jiný stav ukončení. Nenulový ukončovací kód obvykle signalizuje selhání.

Ve Windows je povolené libovolné číslo mezi [int]::MinValue a [int]::MaxValue.

V unixu jsou povolena pouze kladná čísla mezi [byte]::MinValue (0) a [byte]::MaxValue (255). Záporné číslo v rozsahu -1 až -255 se automaticky přeloží na kladné číslo přidáním čísla 256. Například -2 se transformuje na 254.

V PowerShellu nastaví příkaz exit hodnotu proměnné $LASTEXITCODE. V prostředí Windows Command Shell (cmd.exe) nastaví příkaz exit hodnotu proměnné prostředí %ERRORLEVEL%.

Jakýkoli argument, který není číselný nebo mimo rozsah specifický pro platformu, se přeloží na hodnotu 0.

Rozsah skriptů a dat sourcing

Každý skript běží ve vlastním prostředí. Funkce, proměnné, aliasy a jednotky vytvořené ve skriptu existují pouze v rozsahu skriptu. K těmto položkám nebo jejich hodnotám v oboru, ve kterém se skript spouští, nelze získat přístup.

Pokud chcete spustit skript v jiném oboru, můžete zadat obor, například globální nebo místní, nebo můžete skript vytvořit tečkou.

Funkce dot sourcing umožňuje spustit skript v aktuálním prostředí místo v samostatném oboru skriptu. Pokud spustíte skript metodou dot sourcing, příkazy v něm se spustí, jako byste je zadali přímo do příkazového řádku. Funkce, proměnné, aliasy a jednotky, které skript vytvoří, jsou vytvořeny v oboru, ve kterém pracujete. Po spuštění skriptu můžete používat vytvořené položky a přistupovat k jejich hodnotám ve své relaci.

Pokud chcete spustit skript metodou dot sourcing, zadejte tečku (.) a mezeru před cestou ke skriptu.

Například:

. C:\scripts\UtilityFunctions.ps1

nebo

. .\UtilityFunctions.ps1

Po spuštění UtilityFunctions.ps1 skriptu se funkce a proměnné, které skript vytvoří, přidají do aktuálního oboru.

Například skript UtilityFunctions.ps1 vytvoří funkci New-Profile a proměnnou $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 }
}

Pokud skript UtilityFunctions.ps1 spustíte ve vlastním oboru skriptu, funkce New-Profile a proměnná $ProfileName existují pouze při spuštění skriptu. Po ukončení skriptu se funkce a proměnná odeberou, jak je znázorněno v následujícím příkladu.

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>

Když skript zatáhnete do zdroje a spustíte ho, skript vytvoří funkci New-Profile a proměnnou $ProfileName ve vaší relaci ve vašem oboru. Po spuštění skriptu můžete ve své relaci použít funkci New-Profile, jak je znázorněno v následujícím příkladu.

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

Další informace o rozsahu naleznete v tématu about_Scopes.

Skripty v modulech

Modul je sada souvisejících prostředků PowerShellu, které je možné distribuovat jako jednotku. Moduly můžete použít k uspořádání skriptů, funkcí a dalších prostředků. Moduly můžete použít také k distribuci kódu ostatním a získání kódu z důvěryhodných zdrojů.

Do modulů můžete zahrnout skripty nebo můžete vytvořit skriptovací modul, což je modul, který se skládá výhradně nebo primárně ze skriptu a podpůrných prostředků. Skriptový modul je pouze skript s příponou souboru .psm1.

Další informace o modulech najdete v about_Modules.

Další funkce skriptů

PowerShell obsahuje mnoho užitečných funkcí, které můžete použít ve skriptech.

  • #Requires – Pomocí příkazu #Requires můžete zabránit spuštění skriptu bez zadaných modulů nebo modulů snap-in a zadané verze PowerShellu. Další informace najdete v části about_Requires.

  • $PSCommandPath – obsahuje úplnou cestu a název skriptu, který se spouští. Tento parametr je platný ve všech skriptech. Tato automatická proměnná se zavádí v PowerShellu 3.0.

  • $PSScriptRoot – obsahuje adresář, ze kterého se spouští skript. V PowerShellu 2.0 je tato proměnná platná pouze ve skriptových modulech (.psm1). Počínaje PowerShellem 3.0 je platný ve všech skriptech.

  • $MyInvocation – automatická proměnná $MyInvocation obsahuje informace o aktuálním skriptu, včetně informací o tom, jak byla spuštěna nebo "vyvolána". Tuto proměnnou a její vlastnosti můžete použít k získání informací o skriptu během jeho spuštění. Například $MyInvocation. Proměnná MyCommand.Path obsahuje cestu a název souboru skriptu. $MyInvocation. Řádek obsahuje příkaz, který spustil skript, včetně všech parametrů a hodnot.

    Počínaje PowerShellem 3.0 má $MyInvocation dvě nové vlastnosti, které poskytují informace o skriptu, který volal nebo vyvolal aktuální skript. Hodnoty těchto vlastností jsou naplněny pouze tehdy, když je vyvolávač nebo volající skript.

    • psCommandPath obsahuje úplnou cestu a název skriptu, který volal nebo vyvolal aktuální skript.

    • PSScriptRoot obsahuje adresář skriptu, který volal nebo vyvolal aktuální skript.

    Na rozdíl od $PSCommandPath a $PSScriptRoot automatických proměnných, které obsahují informace o aktuálním skriptu, PSCommandPath a PSScriptRoot vlastnosti proměnné $MyInvocation obsahují informace o skriptu, který volal aktuální skript.

  • Datové části – Pomocí klíčového slova Data můžete oddělit data od logiky ve skriptech. Datové oddíly můžou také usnadnit lokalizaci. Další informace najdete v tématu about_Data_Sections a about_Script_Internationalization.

  • Podepisování skriptů – Digitální podpis můžete přidat do skriptu. V závislosti na zásadách spouštění můžete pomocí digitálních podpisů omezit spouštění skriptů, které můžou obsahovat nebezpečné příkazy. Podrobnosti najdete u about_Execution_Policies a about_Signing.

Viz také

  • Last updated on