Informace o CommonParameters

STRUČNÝ POPIS

Popisuje parametry, které lze použít s libovolnou rutinou.

DLOUHÝ POPIS

Společné parametry jsou sada parametrů rutiny, které můžete použít s libovolnou rutinou. Implementuje je PowerShell, ne vývojář rutin, a jsou automaticky dostupné pro všechny rutiny.

Společné parametry můžete použít s libovolnou rutinou, ale nemusí mít vliv na všechny rutiny. Pokud například rutina negeneruje žádný podrobný výstup, nemá použití společného parametru Verbose žádný vliv.

Společné parametry jsou k dispozici také u pokročilých funkcí, které používají atribut CmdletBinding nebo atribut Parameter , a ve všech pracovních postupech.

Několik běžných parametrů přepisuje výchozí nastavení systému nebo předvolby, které jste nastavili pomocí proměnných předvoleb PowerShellu. Na rozdíl od proměnných předvoleb mají společné parametry vliv jenom na příkazy, ve kterých se používají.

Kromě běžných parametrů mnoho rutin nabízí parametry WhatIf a Confirm zmírnění rizika. Rutiny, které představují riziko pro systém nebo uživatelská data, obvykle nabízejí tyto parametry.

V následujícím seznamu jsou uvedené společné parametry. Jejich aliasy jsou uvedené v závorkách.

• Ladění (db)
• ErrorAction (ea)
• ErrorVariable (ev)
• InformationAction (infa)
• InformaceVariable (iv)
• OutVariable (ov)
• OutBuffer (ob)
• PipelineVariable (pv)
• Podrobné (vb)
• WarningAction (wa)
• WarningVariable (wv)

Parametry zmírnění rizika jsou:

• WhatIf (wi)
• Potvrdit (cf)

Další informace najdete v tématu about_Preference_Variables.

BĚŽNÉ POPISY PARAMETRŮ

Ladění

Alias pro ladění je db.

Zobrazí podrobnosti o operaci provedené příkazem na úrovni programátora. Tento parametr funguje pouze v případě, že příkaz vygeneruje zprávu ladění. Tento parametr například funguje, když příkaz obsahuje rutinu Write-Debug .

Parametr Debug přepíše hodnotu $DebugPreference proměnné pro aktuální příkaz a nastaví hodnotu $DebugPreference na Pokračovat. Vzhledem k tomu, že výchozí hodnota $DebugPreference proměnné je SilentlyContinue, zprávy ladění se ve výchozím nastavení nezobrazují.

-Debug:$true má stejný účinek jako -Debug. Slouží -Debug:$false k potlačení zobrazení zpráv ladění, když $DebugPreference není SilentlyContinue, což je výchozí nastavení.

Erroraction

Alias pro ErrorAction je ea.

Určuje, jak rutina reaguje na neukončující chybu z příkazu. Tento parametr funguje pouze v případě, že příkaz vygeneruje neukončující chybu, například chybu z rutiny Write-Error .

Parametr ErrorAction přepíše hodnotu $ErrorActionPreference proměnné pro aktuální příkaz. Vzhledem k tomu, že výchozí hodnota $ErrorActionPreference proměnné je Continue, zobrazí se chybové zprávy a provádění pokračuje, pokud nepoužijete parametr ErrorAction .

Parametr ErrorAction nemá žádný vliv na ukončování chyb (například chybějící data, parametry, které nejsou platné nebo nedostatečná oprávnění), které brání úspěšnému dokončení příkazu.

-ErrorAction:Continue zobrazí chybovou zprávu a pokračuje v provádění příkazu. Continue je výchozí možnost.

-ErrorAction:Ignore potlačí chybovou zprávu a pokračuje v provádění příkazu. Na rozdíl od SilentlyContinue nepřidá funkce Ignorovat chybovou zprávu do $Error automatické proměnné. Hodnota Ignore (Ignorovat ) se zavádí v PowerShellu 3.0.

-ErrorAction:Inquire zobrazí chybovou zprávu a před pokračováním v provádění vás vyzve k potvrzení. Tato hodnota se používá zřídka.

-ErrorAction:SilentlyContinue potlačí chybovou zprávu a pokračuje v provádění příkazu.

-ErrorAction:Stop zobrazí chybovou zprávu a příkaz se ukončí.

-ErrorAction:Suspend Se nepodporuje v PowerShellu Core, protože je k dispozici pouze pro pracovní postupy.

Poznámka

Parametr ErrorAction přepíše, ale nenahrazuje hodnotu $ErrorAction proměnné předvolby, pokud je parametr použit v příkazu ke spuštění skriptu nebo funkce.

ErrorVariable

Alias pro ErrorVariable je ev.

ErrorVariable ukládá chybové zprávy o příkazu do zadané proměnné a do $Error automatické proměnné. Další informace potřebujete zadáním následujícího příkazu:

Get-Help about_Automatic_Variables

Ve výchozím nastavení nové chybové zprávy přepíšou chybové zprávy, které jsou již uloženy v proměnné . Pokud chcete připojit chybovou zprávu k obsahu proměnné, zadejte před název proměnné znaménko plus (+).

Například následující příkaz vytvoří proměnnou $a a uloží do ní všechny chyby:

Get-Process -Id 6 -ErrorVariable a

Následující příkaz přidá do $a proměnné všechny chybové zprávy:

Get-Process -Id 2 -ErrorVariable +a

Následující příkaz zobrazí obsah souboru $a:

$a

Tento parametr můžete použít k vytvoření proměnné, která obsahuje pouze chybové zprávy z konkrétních příkazů. Automatická $Error proměnná obsahuje chybové zprávy ze všech příkazů v relaci. K odkazování na konkrétní chyby uložené v proměnných můžete použít maticový zápis, například $a[0] nebo $error[1,2] .

Akce informací

Alias pro InformationAction je ia.

Zavedeno v PowerShellu 5.0. V rámci příkazu nebo skriptu, ve kterém se používá, přepíše společný parametr InformationAction hodnotu $InformationPreference proměnné předvolby, která je ve výchozím nastavení nastavená na SilentlyContinue. Při použití Write-Information ve skriptu s InformationAction, Write-Information hodnoty jsou zobrazeny v závislosti na hodnotě InformationAction parametru. Další informace o $InformationPreferencenajdete v tématu about_Preference_Variables.

-InformationAction:Stop zastaví příkaz nebo skript v výskytu Write-Information příkazu.

-InformationAction:Ignore potlačí informační zprávu a pokračuje ve spuštění příkazu . Na rozdíl od SilentlyContinue, Ignore zcela zapomene informační zprávu; nepřidá informační zprávu do informačního streamu.

-InformationAction:Inquire zobrazí informační zprávu, kterou zadáte v Write-Information příkazu, a pak se zeptá, zda chcete pokračovat.

-InformationAction:Continue zobrazí informační zprávu a poběží dál.

-InformationAction:Suspend Se nepodporuje v PowerShellu Core, protože je k dispozici pouze pro pracovní postupy.

-InformationAction:SilentlyContinue bez efektu, protože informační zpráva se nezobrazuje (výchozí) a skript pokračuje bez přerušení.

Poznámka

Parametr InformationAction přepíše, ale nenahrazuje hodnotu $InformationAction proměnné předvolby, pokud se parametr použije v příkazu ke spuštění skriptu nebo funkce.

InformaceVariable

Alias pro InformationVariable je iv.

Zavedeno v PowerShellu 5.0. V rámci příkazu nebo skriptu, ve kterém se používá, ukládá společný parametr InformationVariable do proměnné řetězec, který zadáte přidáním Write-Information příkazu . Write-Information Hodnoty jsou zobrazeny v závislosti na hodnotě InformationAction společného parametru; Pokud nepřidáte společný parametr InformationAction , Write-Information zobrazí se řetězce v závislosti na hodnotě $InformationPreference proměnné předvolby. Další informace o $InformationPreferencenajdete v tématu about_Preference_Variables.

OutBuffer

Alias pro OutBuffer je ob a přebírá hodnotu System.Int32 .

Určuje počet objektů, které se mají nahromadit ve vyrovnávací paměti před odesláním libovolných objektů kanálem. Pokud tento parametr vynecháte, objekty se odesílají tak, jak se vygenerují.

Tento parametr správy prostředků je určený pro pokročilé uživatele. Když použijete tento parametr, PowerShell odesílá data do další rutiny v dávkách .OutBuffer + 1

Následující příklad střídá zobrazení mezi a ForEach-Object zpracovává bloky, které používají rutinu Write-Host . Zobrazení se střídá v dávkách po 2 nebo OutBuffer + 1.

1..4 | ForEach-Object {
        Write-Host "$($_): First"; $_
      } -OutBuffer 1 | ForEach-Object {
                        Write-Host "$($_): Second" }

1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second

OutVariable

Alias outvariable je ov.

Ukládá výstupní objekty z příkazu do zadané proměnné kromě odesílání výstupu v kanálu.

Pokud chcete do proměnné přidat výstup, místo abyste nahradili výstup, který by tam už mohl být uložený, zadejte před název proměnné znaménko plus (+).

Například následující příkaz vytvoří proměnnou $out a uloží do ní objekt procesu:

Get-Process PowerShell -OutVariable out

Následující příkaz přidá objekt procesu do $out proměnné :

Get-Process iexplore -OutVariable +out

Následující příkaz zobrazí obsah $out proměnné:

$out

Poznámka

Proměnná vytvořená parametrem OutVariable je [System.Collections.ArrayList].

PipelineVariable

Alias pro PipelineVariable je pv a přebírá řetězcovou hodnotu.

PipelineVariable ukládá hodnotu aktuálního prvku kanálu jako proměnnou pro libovolný pojmenovaný příkaz, který prochází kanálem.

Platné hodnoty jsou řetězce, stejné jako pro názvy proměnných.

Následuje příklad toho, jak PipelineVariable funguje. V tomto příkladu se do Foreach-Object příkazu přidá parametr PipelineVariable, který uloží výsledky příkazu do proměnných. Rozsah čísel od 1 do 10 se předá do prvního Foreach-Object příkazu, jehož výsledky jsou uloženy v proměnné Left.

Výsledky prvního Foreach-Object příkazu se předávají do druhého Foreach-Object příkazu, který filtruje objekty vrácené prvním Foreach-Object příkazem. Výsledky druhého příkazu jsou uloženy v proměnné s názvem Right.

Ve třetím Foreach-Object příkazu jsou výsledky prvních dvou Foreach-Object příkazů s kanálem reprezentované proměnnými Vlevo a Vpravo zpracovány pomocí operátoru násobení. Příkaz dá objektům uloženým v proměnných Vlevo a Vpravo pokyn, aby se vynásobily, a určuje, že výsledky by se měly zobrazit jako "Levý člen oblasti * Pravý člen oblasti = součin".

1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
  Foreach-Object -PV Right -Process { 1..10 } |
  Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) }

1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
...

Verbose

Alias pro podrobné je vb.

Zobrazí podrobné informace o operaci provedené příkazem . Tyto informace se podobají informacím v trasování nebo v transakčním protokolu. Tento parametr funguje pouze v případě, že příkaz vygeneruje podrobnou zprávu. Tento parametr například funguje, když příkaz obsahuje rutinu Write-Verbose .

Podrobný parametr přepíše hodnotu $VerbosePreference proměnné pro aktuální příkaz. Vzhledem k tomu, že výchozí hodnota $VerbosePreference proměnné je SilentlyContinue, podrobné zprávy se ve výchozím nastavení nezobrazují.

-Verbose:$true má stejný účinek jako -Verbose

-Verbose:$false potlačí zobrazení podrobných zpráv. Tento parametr použijte, pokud hodnota parametru $VerbosePreference není SilentlyContinue (výchozí).

Akce upozornění

Alias pro WarningAction je wa.

Určuje, jak rutina reaguje na upozornění z příkazu . Výchozí hodnotou je Continue (Pokračovat). Tento parametr funguje pouze v případě, že příkaz vygeneruje zprávu upozornění. Tento parametr například funguje, když příkaz obsahuje rutinu Write-Warning .

Parametr WarningAction přepíše hodnotu $WarningPreference proměnné pro aktuální příkaz. Vzhledem k tomu, že výchozí hodnota $WarningPreference proměnné je Continue, upozornění se zobrazí a provádění pokračuje, pokud nepoužijete parametr WarningAction .

-WarningAction:Continue zobrazí varovné zprávy a pokračuje v provádění příkazu. Continue je výchozí možnost.

-WarningAction:Inquire zobrazí upozornění a před pokračováním v provádění vás vyzve k potvrzení. Tato hodnota se používá zřídka.

-WarningAction:SilentlyContinue potlačí zprávu upozornění a pokračuje v provádění příkazu.

-WarningAction:Stop zobrazí varovnou zprávu a zastaví provádění příkazu .

Poznámka

Parametr WarningAction přepíše, ale nenahrazuje hodnotu $WarningAction proměnné předvolby, pokud je parametr použit v příkazu ke spuštění skriptu nebo funkce.

WarningVariable

Alias pro WarningVariable je wv.

Ukládá upozornění týkající se příkazu do zadané proměnné.

Všechna vygenerovaná upozornění se uloží do proměnné i v případě, že se upozornění uživateli nezobrazí.

Pokud chcete tato upozornění připojit k obsahu proměnné, místo abyste nahradili všechna upozornění, která by tam už mohla být uložená, zadejte před název proměnné znaménko plus (+).

Například následující příkaz vytvoří proměnnou $a a uloží do ní všechna upozornění:

Get-Process -Id 6 -WarningVariable a

Následující příkaz přidá do $a proměnné všechna upozornění:

Get-Process -Id 2 -WarningVariable +a

Následující příkaz zobrazí obsah souboru $a:

$a

Tento parametr můžete použít k vytvoření proměnné, která obsahuje pouze upozornění z konkrétních příkazů. K odkazování na konkrétní upozornění uložená v proměnné můžete použít zápis pole, například $a[0] nebo $warning[1,2] .

Poznámka

Parametr WarningVariable nezachycuje upozornění z vnořených volání ve funkcích nebo skriptech.

Popisy parametrů řízení rizik

WhatIf

Alias pro WhatIf je wi.

Místo spuštění příkazu zobrazí zprávu, která popisuje účinek příkazu.

WhatIf Parametr přepíše hodnotu $WhatIfPreference proměnné pro aktuální příkaz. Vzhledem k tomu, že výchozí hodnota $WhatIfPreference proměnné je 0 (zakázáno), chování WhatIf se bez parametru WhatIf neprochází. Další informace potřebujete zadáním následujícího příkazu:

Get-Help about_Preference_Variables

-WhatIf:$true má stejný účinek jako -WhatIf.

-WhatIf:$false potlačí automatické chování WhatIf, které je výsledkem, když je hodnota $WhatIfPreference proměnné 1.

Například následující příkaz používá -WhatIf parametr v Remove-Item příkazu :

Remove-Item Date.csv -WhatIf

Místo odebrání položky PowerShell vypíše operace, které provede, a položky, které by to ovlivnilo. Tento příkaz vytvoří následující výstup:

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

Confirm

Alias pro potvrzení je cf.

Před spuštěním příkazu vás vyzve k potvrzení.

Parametr Confirm přepíše hodnotu $ConfirmPreference proměnné pro aktuální příkaz. Výchozí hodnotou je hodnota true. Další informace potřebujete zadáním následujícího příkazu:

Get-Help about_Preference_Variables

-Confirm:$true má stejný účinek jako -Confirm.

-Confirm:$false potlačí automatické potvrzení, ke kterému dochází, když je hodnota $ConfirmPreference menší než nebo rovna odhadovanému riziku rutiny.

Například následující příkaz používá parametr Confirm s příkazem Remove-Item . Před odebráním položky PowerShell vypíše operace, které provede, a položky, které by to ovlivnilo, a požádá o schválení.

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

Confirm
Are you sure you want to perform this action?
Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend
[?] Help (default is "Y"):

Možnosti Potvrdit odpověď jsou následující:

Odpověď	Výsledek
Ano (Y)	Proveďte akci.
Ano všem (A)	Provedení všech akcí a potlačení následných potvrdit dotazy
	pro tento příkaz.
Ne (N):	Neprovádějte akci.
Ne všem (L):	Neprovádějte žádné akce a potlačit následné potvrzení
	dotazuje se na tento příkaz.
Pozastavení (S):	Pozastavte příkaz a vytvořte dočasnou relaci.
Nápověda (?)	Zobrazí nápovědu k těmto možnostem.

Možnost Pozastavit tento příkaz pozastaví a vytvoří dočasnou vnořenou relaci, ve které můžete pracovat, dokud nebudete připraveni zvolit možnost Potvrdit . Příkazový řádek pro vnořenou relaci obsahuje dva další karety (>>), které označují, že se jedná o podřízenou operaci původního nadřazeného příkazu. Ve vnořené relaci můžete spouštět příkazy a skripty. Pokud chcete ukončit vnořenou relaci a vrátit se k možnostem Potvrdit původní příkaz, zadejte "exit".

V následujícím příkladu se k dočasnému zastavení příkazu používá možnost Pozastavit (S), zatímco uživatel zkontroluje v nápovědě parametr příkazu. Po získání potřebných informací uživatel zadáním příkazu exit ukončí vnořenou výzvu a pak vybere odpověď Ano (y) na dotaz Confirm.

PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

Confirm
Are you sure you want to perform this action?

Performing operation "Create File" on Target "Destination:
C:\ps-test\test.txt".
[Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default
is "Y"): s

PS C:\ps-test> Get-Help New-Item -Parameter ItemType

-ItemType <string>
Specifies the provider-specified type of the new item.

Required?                    false
Position?                    named
Default value
Accept pipeline input?       true (ByPropertyName)
Accept wildcard characters?  false

PS C:\ps-test> exit

Confirm
Are you sure you want to perform this action?
Performing operation "Create File" on Target "Destination: C:\ps-test\test
.txt".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (defau
lt is "Y"): y

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---         8/27/2010   2:41 PM          0 test.txt

KLÍČOVÁ SLOVA

about_Common_Parameters

VIZ TAKÉ

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose