O společnosti CommonParameters

KRÁTKÝ POPIS

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

DLOUHÝ POPIS

Běžné parametry jsou sada parametrů rutiny, které můžete použít s libovolnou rutinou. Implementují se v PowerShellu, ne vývojáři rutin a jsou automaticky dostupné pro libovolnou rutinu.

Běž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í podrobného společného parametru žádný vliv.

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

Výchozí nastavení systému nebo předvolby, které nastavíte pomocí proměnných předvoleb PowerShellu, má přednost několik běžných parametrů. 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ů nabízí mnoho rutin parametry zmírnění rizik WhatIf a Potvrdit . Rutiny, které zahrnují riziko pro systém nebo uživatelská data, obvykle nabízejí tyto parametry.

Následující seznam zobrazuje společné parametry. Jejich aliasy jsou uvedeny v závorkách.

• ladění (db)
• ErrorAction (ea)
• Chybová_proměnná (ev)
• InformationAction (infa)
• Informační_proměnná (iv)
• OutVariable (ov)
• Výstupní vyrovnávací paměť (ob)
• Proměnná potrubí (pv)
• Podrobné (vb)
• WarningAction (wa)
• WarningVariable (wv)

Parametry zmírnění rizik jsou:

• WhatIf (wi)
• Potvrdit (cf)

Další informace najdete v části about_Preference_Variables.

BĚŽNÉ POPISY PARAMETRŮ

Ladění

Alias pro ladění je db.

Zobrazí podrobnosti na úrovni programátora o operaci provedené příkazem. 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 proměnné $DebugPreference pro aktuální příkaz a nastaví hodnotu na $DebugPreferencePokračovat. Vzhledem k tomu, že výchozí hodnota proměnné $DebugPreference 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í, pokud $DebugPreference není Bezobslužná Funkce, což je výchozí nastavení.

ErrorAction (Chybová akce)

Alias pro ErrorAction je ea.

Určuje, jak rutina reaguje na neukončující chybu z příkazu. Tento parametr funguje jenom 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žíváte parametr ErrorAction .

Parametr ErrorAction nemá žádný vliv na ukončení 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 bude pokračovat v provádění příkazu. Continue je výchozí.

-ErrorAction:Ignore potlačuje chybovou zprávu a pokračuje v provádění příkazu. Na rozdíl od silentlyContinue, Ignore nepřidá chybovou $Error zprávu do automatické proměnné. Hodnota Ignore je zavedena 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čuje chybovou zprávu a pokračuje v provádění příkazu.

-ErrorAction:Stop zobrazí chybovou zprávu a zastaví spuštění příkazu.

-ErrorAction:Suspend není podporován v PowerShell Core, protože je k dispozici pouze pro pracovní postupy.

Poznámka:

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

Chybová_proměnná

Alias pro ErrorVariable je ev.

ErrorVariable ukládá chybové zprávy o příkazu v zadané proměnné a v automatické proměnné $Error . Další informace získáte 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íší chybové zprávy, které jsou již uloženy v proměnné. Chcete-li 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 $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. Maticový zápis můžete použít, například $a[0] odkazovat $error[1,2] na konkrétní chyby uložené v proměnných.

Informační akce

Alias pro InformationAction je ia.

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

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

-InformationAction:Ignore potlačuje informační zprávu a pokračuje ve spuštění příkazu. Na rozdíl od SilentlyContinue, Ignorovat 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á, jestli chcete pokračovat.

-InformationAction:Continue zobrazí informační zprávu a pokračuje ve spuštění.

-InformationAction:Suspend není podporován v PowerShell Core, protože je k dispozici pouze pro pracovní postupy.

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

Poznámka:

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

InformačníProměnná

Alias pro InformationVariable je iv.

Představeno v PowerShellu 5.0. V rámci příkazu nebo skriptu, ve kterém je použit, ukládá společný parametr InformationVariable do proměnné řetězec, který určíte přidáním příkazu Write-Information . Write-Informationhodnoty se zobrazují v závislosti na hodnotě společného parametru InformationAction; pokud nepřidáte společný parametr InformationAction, Write-Information zobrazí se řetězce v závislosti na hodnotě proměnné předvoleb.$InformationPreference Další informace o $InformationPreferencenaleznete v tématu about_Preference_Variables.

Vyrovnávací paměť OutBuffer

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

Určuje počet objektů, které se mají nahromadět ve vyrovnávací paměti před odesláním jakýchkoli objektů prostřednictvím kanálu. Pokud tento parametr vynecháte, objekty se posílají při jejich vygenerování.

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

Následující příklad alternativy se zobrazí mezi ForEach-Object procesem bloků, které používají rutinu Write-Host . Alternativy zobrazení v dávkách 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 pro 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 přidat výstup do proměnné, místo nahrazení jakéhokoli výstupu, který by tam mohl být již 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ží objekt procesu do něj:

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]

Proměnná potrubí

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

Proměnná PipelineVariable ukládá hodnotu aktuálního prvku kanálu jako proměnnou pro jakýkoli pojmenovaný příkaz při jeho průchodu kanálem.

Platné hodnoty jsou řetězce, stejné jako u názvů proměnných.

Následuje příklad fungování PipelineVariable . V tomto příkladu , který uloží výsledky příkazu do proměnných. Rozsah čísel od 1 do 10 je vložen do prvního Foreach-Object příkazu, jehož výsledky jsou uloženy v proměnné s názvem Left.

Výsledky prvního Foreach-Object příkazu jsou předány 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ých proměnnými Left a Right, zpracovány pomocí operátoru násobení. Příkaz dává pokyn k vynásobení objektů uložených v proměnných Left a Right a určuje, že výsledky by měly být zobrazeny jako "Levý člen rozsahu * Pravý člen rozsahu = produkt".

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

Zdlouhavý

Alias pro Verbose 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 $VerbosePreference není SilentlyContinue (výchozí).

Výstražná akce

Alias pro WarningAction je wa.

Určuje, jak rutina reaguje na upozornění z příkazu. Pokračovat je výchozí hodnota. Tento parametr funguje pouze v případě, že příkaz vygeneruje zprávu s upozorněním. 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, zobrazí se upozornění a provádění pokračuje, pokud nepoužíváte parametr WarningAction .

-WarningAction:Continue zobrazí zprávy s upozorněním a pokračuje v provádění příkazu. Continue je výchozí.

-WarningAction:Inquire zobrazí zprávu s upozorněním 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čuje zprávu upozornění a pokračuje v provádění příkazu.

-WarningAction:Stop zobrazí zprávu s upozorněním a ukončí provádění příkazu.

Poznámka:

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

VýstražnáProměnná

Alias pro WarningVariable je wv.

Uloží upozornění na příkaz do určené proměnné.

Všechna vygenerovaná upozornění se ukládají do proměnné, i když se upozornění uživateli nezobrazí.

Pokud chcete upozornění připojit k obsahu proměnné, místo nahrazení všech upozornění, která by tam již mohla být uložena, 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 proměnné všechna upozornění $a :

Get-Process -Id 2 -WarningVariable +a

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

$a

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

Poznámka:

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

Popisy parametrů řízení rizik

Co když

Alias pro WhatIf je wi.

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

Parametr WhatIf 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 neprovede bez parametru WhatIf . Další informace získáte zadáním následujícího příkazu:

Get-Help about_Preference_Variables

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

-WhatIf:$false potlačuje automatické chování WhatIf, které má za následek, 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 zobrazí seznam operací, které by udělal, a položek, 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".

Potvrdit

Alias pro Confirm je cf.

Před provedením příkazu vás vyzve k potvrzení.

Parametr Confirm přepíše hodnotu proměnné $ConfirmPreference pro aktuální příkaz. Výchozí hodnota je true. Další informace získáte 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ší 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 zobrazí seznam operací, které by udělal, a položek, které by to ovlivnilo, a požádal 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í:

Odezva	Výsledek
Ano (Y)	Proveďte akci.
Ano všem (A)	Provést všechny akce a potlačit následné potvrzovací dotazy
	pro tento příkaz.
Ne (N):	Akci neprovádějte.
Ne všem (L):	Neprovádět žádné akce a potlačit následné Potvrdit
	dotazy pro tento příkaz.
Pozastavit (S):	Pozastavte příkaz a vytvořte dočasnou relaci.
Nápověda (?)	Zobrazit nápovědu k těmto možnostem

Možnost Pozastavit pozastaví příkaz 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 dvě nadbytečné karety (>>), které indikují, že se jedná o podřízenou operaci původního nadřazeného příkazu. Vnořené relaci můžete spouštět příkazy a skripty. Chcete-li ukončit vnořenou relaci a vrátit se k možnostem Potvrdit pro původní příkaz, zadejte "exit".

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

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É

o_Preferenčních_Proměnných

ladění zápisu

upozornění na zápis

při zápisu

Podrobný zápis