Om CommonParameters

Artikel
06/21/2023

KORT BESKRIVNING

Beskriver de parametrar som kan användas med valfri cmdlet.

LÅNG BESKRIVNING

De vanliga parametrarna är en uppsättning cmdlet-parametrar som du kan använda med valfri cmdlet. De implementeras av PowerShell, inte av cmdlet-utvecklaren, och de är automatiskt tillgängliga för alla cmdletar.

Du kan använda vanliga parametrar med valfri cmdlet, men de kanske inte påverkar alla cmdletar. Om en cmdlet till exempel inte genererar utförliga utdata har användningen av den utförliga gemensamma parametern ingen effekt.

De gemensamma parametrarna är också tillgängliga för avancerade funktioner som använder attributet CmdletBinding eller parameterattributet och i alla arbetsflöden.

Flera vanliga parametrar åsidosätter systemstandarder eller inställningar som du anger med hjälp av PowerShell-inställningsvariablerna. Till skillnad från inställningsvariablerna påverkar de vanliga parametrarna bara de kommandon som de används i.

Förutom de vanliga parametrarna erbjuder många cmdletar parametrarna WhatIf och Confirm risk mitigation. Cmdletar som innebär risk för systemet eller användardata erbjuder vanligtvis dessa parametrar.

I följande lista visas de vanliga parametrarna. Deras alias visas inom parentes.

Felsöka (db)
ErrorAction (ea)
ErrorVariable (ev)
InformationAction (infa)
InformationVariable (iv)
OutVariable (ov)
OutBuffer (ob)
PipelineVariable (pv)
Utförlig ( vb)
WarningAction (wa)
WarningVariable (wv)

Riskreduceringsparametrarna är:

WhatIf (wi)
Bekräfta (cf)

Mer information finns i about_Preference_Variables.

VANLIGA PARAMETERBESKRIVNINGAR

Felsöka

Aliaset för Felsökning är db.

Visar information på programmeringsnivå om den åtgärd som utförs av kommandot. Den här parametern fungerar bara när kommandot genererar ett felsökningsmeddelande. Den här parametern fungerar till exempel när ett kommando innehåller cmdleten Write-Debug .

Parametern Debug åsidosätter värdet för variabeln $DebugPreference för det aktuella kommandot och anger värdet $DebugPreference för till Fortsätt. Eftersom standardvärdet för variabeln $DebugPreference är SilentlyContinue visas inte felsökningsmeddelanden som standard.

-Debug:$true har samma effekt som -Debug. Använd -Debug:$false för att förhindra visning av felsökningsmeddelanden när $DebugPreference inte är TystFortsätt, vilket är standardinställningen.

ErrorAction

Aliaset för ErrorAction är ea.

Avgör hur cmdleten svarar på ett icke-avslutande fel från kommandot. Den här parametern fungerar bara när kommandot genererar ett icke-avslutande fel, till exempel de från cmdleten Write-Error .

Parametern ErrorAction åsidosätter värdet för variabeln $ErrorActionPreference för det aktuella kommandot. Eftersom standardvärdet för variabeln $ErrorActionPreference är Fortsätt visas felmeddelanden och körningen fortsätter om du inte använder parametern ErrorAction .

Parametern ErrorAction har ingen effekt på avslutande fel (till exempel saknade data, parametrar som inte är giltiga eller otillräckliga behörigheter) som hindrar ett kommando från att slutföras.

-ErrorAction:Continue visar felmeddelandet och fortsätter att köra kommandot. Continue används som standard.

-ErrorAction:Ignore undertrycker felmeddelandet och fortsätter att köra kommandot. Till skillnad från SilentlyContinue lägger Ignore inte till felmeddelandet i den $Error automatiska variabeln. Värdet Ignore introduceras i PowerShell 3.0.

-ErrorAction:Inquire visar felmeddelandet och uppmanar dig att bekräfta innan du fortsätter körningen. Det här värdet används sällan.

-ErrorAction:SilentlyContinue undertrycker felmeddelandet och fortsätter att köra kommandot.

-ErrorAction:Stop visar felmeddelandet och slutar köra kommandot.

-ErrorAction:Suspend stöds inte i PowerShell Core eftersom det endast är tillgängligt för arbetsflöden.

Anteckning

Parametern ErrorAction åsidosätter, men ersätter inte värdet för inställningsvariabeln $ErrorAction när parametern används i ett kommando för att köra ett skript eller en funktion.

ErrorVariable

Aliaset för ErrorVariable är ev.

ErrorVariable lagrar felmeddelanden om kommandot i den angivna variabeln och i den $Error automatiska variabeln. Om du vill ha mer information skriver du följande kommando:

Get-Help about_Automatic_Variables

Som standard skriver nya felmeddelanden över felmeddelanden som redan lagras i variabeln. Om du vill lägga till felmeddelandet i variabelinnehållet skriver du ett plustecken (+) före variabelnamnet.

Följande kommando skapar till exempel variabeln och lagrar sedan eventuella fel i den $a :

Get-Process -Id 6 -ErrorVariable a

Följande kommando lägger till eventuella felmeddelanden i variabeln $a :

Get-Process -Id 2 -ErrorVariable +a

Följande kommando visar innehållet i $a:

$a

Du kan använda den här parametern för att skapa en variabel som endast innehåller felmeddelanden från specifika kommandon. Den $Error automatiska variabeln innehåller felmeddelanden från alla kommandon i sessionen. Du kan använda matrisnotation, till exempel eller $error[1,2] för att referera till specifika fel som $a[0] lagras i variablerna.

InformationAction

Aliaset för InformationAction är ia.

Introducerades i PowerShell 5.0. I kommandot eller skriptet där den används åsidosätter den vanliga Parametern InformationAction värdet $InformationPreference för inställningsvariabeln, som som standard är inställt på SilentlyContinue. När du använder Write-Information i ett skript med InformationActionWrite-Information visas värden beroende på värdet för parametern InformationAction. Mer information om $InformationPreferencefinns i about_Preference_Variables.

-InformationAction:Stop stoppar ett kommando eller skript vid en förekomst av Write-Information kommandot.

-InformationAction:Ignore undertrycker informationsmeddelandet och fortsätter att köra kommandot. Till skillnad från SilentlyContinue, Ignorera helt glömmer det informationsmeddelande; Det lägger inte till informationsmeddelandet i informationsströmmen.

-InformationAction:Inquire visar det informationsmeddelande som du anger i ett Write-Information kommando och frågar sedan om du vill fortsätta.

-InformationAction:Continue visar informationsmeddelandet och fortsätter att köras.

-InformationAction:Suspend stöds inte i PowerShell Core eftersom det endast är tillgängligt för arbetsflöden.

-InformationAction:SilentlyContinue ingen effekt eftersom informationsmeddelandet inte visas (standard) och skriptet fortsätter utan avbrott.

Anteckning

Parametern InformationAction åsidosätter, men ersätter inte värdet för inställningsvariabeln $InformationAction när parametern används i ett kommando för att köra ett skript eller en funktion.

InformationVariable

Aliaset för InformationVariable är iv.

Introducerades i PowerShell 5.0. I kommandot eller skriptet där den används lagrar den gemensamma Parametern InformationVariable i en variabel en sträng som du anger genom att lägga till Write-Information kommandot . Write-Informationvärden visas beroende på värdet för den gemensamma InformationAction-parametern; Om du inte lägger till den gemensamma Parametern Write-InformationInformationAction visas strängar beroende på värdet för $InformationPreference inställningsvariabeln. Mer information om $InformationPreferencefinns i about_Preference_Variables.

OutBuffer

Aliaset för OutBuffer är ob och tar ett System.Int32-värde .

Avgör hur många objekt som ska ackumuleras i en buffert innan några objekt skickas via pipelinen. Om du utelämnar den här parametern skickas objekt när de genereras.

Den här resurshanteringsparametern är utformad för avancerade användare. När du använder den här parametern skickar PowerShell data till nästa cmdlet i batchar av OutBuffer + 1.

I följande exempel visas alternativ mellan för att ForEach-Object bearbeta block som använder cmdleten Write-Host . Visningen växlar i batchar med 2 eller 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

Aliaset för OutVariable är ov.

Lagrar utdataobjekt från kommandot i den angivna variabeln förutom att skicka utdata längs pipelinen.

Om du vill lägga till utdata i variabeln skriver du ett plustecken (+) före variabelnamnet i stället för att ersätta utdata som redan kan lagras där.

Följande kommando skapar till exempel variabeln $out och lagrar processobjektet i den:

Get-Process PowerShell -OutVariable out

Följande kommando lägger till processobjektet i variabeln $out :

Get-Process iexplore -OutVariable +out

Följande kommando visar innehållet i variabeln $out :

$out

Anteckning

Variabeln som skapas av parametern OutVariable är en [System.Collections.ArrayList].

PipelineVariable

Aliaset för PipelineVariable är pv och tar ett strängvärde .

PipelineVariable lagrar värdet för det aktuella pipelineelementet som en variabel för alla namngivna kommandon när det flödar genom pipelinen.

Giltiga värden är strängar, samma som för alla variabelnamn.

Följande är ett exempel på hur PipelineVariable fungerar. I det här exemplet läggs parametern PipelineVariable till i ett Foreach-Object kommando för att lagra resultatet av kommandot i variabler. Ett intervall med tal, 1 till 10, skickas till det första Foreach-Object kommandot, vars resultat lagras i en variabel med namnet Left.

Resultatet av det första Foreach-Object kommandot skickas till ett andra Foreach-Object kommando, som filtrerar de objekt som returneras av det första Foreach-Object kommandot. Resultatet av det andra kommandot lagras i en variabel med namnet Right.

I det tredje Foreach-Object kommandot bearbetas resultatet av de två Foreach-Object första kommandona, som representeras av variablerna Vänster och Höger, med hjälp av en multiplikationsoperator. Kommandot instruerar objekt som lagras i variablerna Vänster och Höger att multipliceras och anger att resultatet ska visas som "Left range member * Right range member = product".

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

Aliaset för Verbose är vb.

Visar detaljerad information om åtgärden som utförs av kommandot. Den här informationen liknar informationen i en spårning eller i en transaktionslogg. Den här parametern fungerar bara när kommandot genererar ett utförligt meddelande. Den här parametern fungerar till exempel när ett kommando innehåller cmdleten Write-Verbose .

Den utförliga parametern åsidosätter värdet för variabeln $VerbosePreference för det aktuella kommandot. Eftersom standardvärdet för variabeln $VerbosePreference är SilentlyContinue visas inte utförliga meddelanden som standard.

-Verbose:$true har samma effekt som -Verbose

-Verbose:$false undertrycker visning av utförliga meddelanden. Använd den här parametern när värdet $VerbosePreference för inte är SilentlyContinue (standard).

WarningAction

Aliaset för WarningAction är wa.

Avgör hur cmdleten svarar på en varning från kommandot. Fortsätt är standardvärdet. Den här parametern fungerar bara när kommandot genererar ett varningsmeddelande. Den här parametern fungerar till exempel när ett kommando innehåller cmdleten Write-Warning .

Parametern WarningAction åsidosätter värdet för variabeln $WarningPreference för det aktuella kommandot. Eftersom standardvärdet för variabeln $WarningPreference är Fortsätt visas varningar och körningen fortsätter om du inte använder parametern WarningAction .

-WarningAction:Continue visar varningsmeddelandena och fortsätter att köra kommandot. Continue används som standard.

-WarningAction:Inquire visar varningsmeddelandet och uppmanar dig att bekräfta innan du fortsätter körningen. Det här värdet används sällan.

-WarningAction:SilentlyContinue undertrycker varningsmeddelandet och fortsätter att köra kommandot.

-WarningAction:Stop visar varningsmeddelandet och slutar köra kommandot.

Anteckning

Parametern WarningAction åsidosätter, men ersätter inte värdet för inställningsvariabeln $WarningAction när parametern används i ett kommando för att köra ett skript eller en funktion.

WarningVariable

Aliaset för WarningVariable är wv.

Lagrar varningar om kommandot i den angivna variabeln.

Alla genererade varningar sparas i variabeln även om varningarna inte visas för användaren.

Om du vill lägga till varningarna i variabelinnehållet skriver du ett plustecken (+) före variabelnamnet i stället för att ersätta eventuella varningar som redan kan lagras där.

Följande kommando skapar till exempel variabeln $a och lagrar sedan eventuella varningar i den:

Get-Process -Id 6 -WarningVariable a

Följande kommando lägger till varningar i variabeln $a :

Get-Process -Id 2 -WarningVariable +a

Följande kommando visar innehållet i $a:

$a

Du kan använda den här parametern för att skapa en variabel som endast innehåller varningar från specifika kommandon. Du kan använda matrisnotation, till exempel $a[0] eller $warning[1,2] för att referera till specifika varningar som lagras i variabeln.

Anteckning

Parametern WarningVariable samlar inte in varningar från kapslade anrop i funktioner eller skript.

Beskrivningar av parametern Risk Management

WhatIf

Aliaset för WhatIf är wi.

Visar ett meddelande som beskriver effekten av kommandot i stället för att köra kommandot.

Parametern WhatIf åsidosätter värdet för variabeln $WhatIfPreference för det aktuella kommandot. Eftersom standardvärdet för variabeln $WhatIfPreference är 0 (inaktiverat) görs inte WhatIf-beteendet utan parametern WhatIf . Om du vill ha mer information skriver du följande kommando:

Get-Help about_Preference_Variables

-WhatIf:$true har samma effekt som -WhatIf.

-WhatIf:$false undertrycker det automatiska WhatIf-beteendet som resulterar när värdet för variabeln $WhatIfPreference är 1.

Följande kommando använder till exempel parametern -WhatIf i ett Remove-Item kommando:

Remove-Item Date.csv -WhatIf

I stället för att ta bort objektet listar PowerShell de åtgärder som det skulle utföra och de objekt som skulle påverkas. Det här kommandot genererar följande utdata:

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

Bekräfta

Aliaset för Confirm är cf.

Uppmanar dig att bekräfta innan du kör kommandot.

Parametern Confirm åsidosätter värdet för variabeln $ConfirmPreference för det aktuella kommandot. Standardvärdet är True. Om du vill ha mer information skriver du följande kommando:

Get-Help about_Preference_Variables

-Confirm:$true har samma effekt som -Confirm.

-Confirm:$false undertrycker automatisk bekräftelse, vilket inträffar när värdet för $ConfirmPreference är mindre än eller lika med den uppskattade risken för cmdleten.

Följande kommando använder till exempel parametern Bekräfta med ett Remove-Item kommando. Innan du tar bort objektet listar PowerShell de åtgärder som det skulle utföra och de objekt som skulle påverkas och ber om godkännande.

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"):

Alternativen för att bekräfta svar är följande:

Svarsåtgärder	Resultat
Ja (Y)	Utför åtgärden.
Ja till alla (A)	Utför alla åtgärder och ignorera efterföljande Bekräfta frågor
	för det här kommandot.
Nej (N):	Utför inte åtgärden.
Nej till alla (L):	Utför inga åtgärder och ignorera efterföljande bekräfta
	frågor för det här kommandot.
Pausa (S):	Pausa kommandot och skapa en tillfällig session.
Hjälp (?)	Visa hjälp för dessa alternativ.

Alternativet Pausa placerar kommandot i vänteläge och skapar en tillfällig kapslad session där du kan arbeta tills du är redo att välja alternativet Bekräfta . Kommandotolken för den kapslade sessionen har två extra bekymmer (>>) som anger att det är en underordnad åtgärd för det ursprungliga överordnade kommandot. Du kan köra kommandon och skript i den kapslade sessionen. Om du vill avsluta den kapslade sessionen och återgå till alternativen Bekräfta för det ursprungliga kommandot skriver du "avsluta".

I följande exempel används alternativet Pausa (S) för att tillfälligt stoppa ett kommando medan användaren kontrollerar hjälpen efter en kommandoparameter. När du har hämtat nödvändig information skriver användaren "avsluta" för att avsluta den kapslade prompten och väljer sedan svaret Ja (y) på Bekräfta frågan.

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