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 .ps1 souboru.

Spuštění skriptu je hodně jako spuštění rutiny. 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 #Requires je 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í brání Restrictedspuštění všech skriptů, včetně skriptů, které píšete v místním počítači. Další informace najdete v tématu 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.

Na příkazovém řá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 protokolu 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ík 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.

Spustit s prostředím PowerShell

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

Použití funkce Spustit s PowerShellem:

Spusťte Průzkumník 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 najdete 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í Get-ServiceLog.ps1 skript 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

Rutina Get-Help získá témata nápovědy pro skripty i rutiny a další typy příkazů. Pokud chcete získat téma nápovědy pro skript, zadejte Get-Help cestu a název souboru skriptu. Pokud je cesta skriptu ve vaší Path proměnné prostředí, můžete tuto cestu vynechat.

Pokud například chcete 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 souboru.

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 libovolných #Require příkazů.

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 za název skriptu zadává uživatelé skriptu parametry.

Následující příklad ukazuje Test-Remote.ps1 skript, který má parametr ComputerName . 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. Příklad:

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

Ping succeeded: Server01
Remote test failed: Server01

Další informace o příkazu Param a parametrech funkce najdete 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 založená na komentářích

  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 najdete v tématu about_Comment_Based_Help.

• Nápověda založená na jazyce XML pro skripty

  Vytvořte téma nápovědy založené na jazyce XML, například typ, který se obvykle vytvoří pro rutiny. 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 přidružit skript k tématu nápovědy založené na jazyce XML, použijte tlačítko . Klíčové slovo komentáře k externí nápovědě Další informace o klíčovém slově ExternalHelp najdete v tématu about_Comment_Based_Help. Další informace o nápovědě založené na jazyce XML naleznete v tématu Jak napsat nápovědu k rutině.

Vrácení výstupní hodnoty

Skripty ve výchozím nastavení nevrací stav ukončení, když skript skončí. Příkaz exit je nutné použít k vrácení ukončovacího kódu ze skriptu. Ve výchozím nastavení exit příkaz vrátí 0. 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 povoleným.

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

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

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

Rozsah skriptů a tečky sourcing

Každý skript běží ve vlastním oboru. Funkce, proměnné, aliasy a jednotky vytvořené ve skriptu existují pouze v oboru 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 oboru místo v oboru skriptu. Když spustíte skript, který je zdrojem tečky, příkazy ve skriptu se spustí, jako kdybyste je zadali do příkazového řádku. Funkce, proměnné, aliasy a jednotky, které skript vytvoří, se vytvoří v oboru, ve kterém pracujete. Po spuštění skriptu můžete použít vytvořené položky a přistupovat k jejich hodnotám ve vaší relaci.

Pokud chcete vytvořit tečku skriptu, zadejte tečku (.) a mezeru před cestu ke skriptu.

Příklad:

. C:\scripts\UtilityFunctions.ps1

nebo

. .\UtilityFunctions.ps1

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

Skript například UtilityFunctions.ps1 vytvoří New-Profile funkci 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 spustíte UtilityFunctions.ps1 ve vlastním oboru skriptu, New-Profile funkce a $ProfileName proměnná existují pouze v době, kdy skript běží. 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 tečkujete a spustíte ho, skript vytvoří New-Profile funkci a proměnnou $ProfileName ve vaší relaci ve vašem oboru. Po spuštění skriptu můžete funkci použít New-Profile ve své relaci, 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 oboru najdete 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 tématu about_Modules.

Další funkce skriptů

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

• #Requires – Pomocí příkazu můžete #Requires zabránit spuštění skriptu bez zadaných modulů nebo modulů snap-in a zadané verze PowerShellu. Další informace najdete v tématu 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 v modulech skriptu (.psm1). Počínaje PowerShellem 3.0 je platný ve všech skriptech.

• $MyInvocation - Automatická $MyInvocation proměnná 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 mají dvě nové vlastnosti, které poskytují informace o skriptu, $MyInvocation který volal nebo vyvolal aktuální skript. Hodnoty těchto vlastností jsou naplněny pouze v případech, kdy je invoker 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.

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

• Datové oddíly – Klíčové slovo můžete použít Data k oddělení dat 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. Další informace najdete v tématu about_Execution_Policies a about_Signing.

Viz také

• 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