Sdílet prostřednictvím

New-Variable

Modul:
Microsoft.PowerShell.Utility Module

Vytvoří novou proměnnou.

Syntax

Default (Výchozí) 

New-Variable
    [-Name] <String>
    [[-Value] <Object>]
    [-Description <String>]
    [-Option <ScopedItemOptions>]
    [-Visibility <SessionStateEntryVisibility>]
    [-Force]
    [-PassThru]
    [-Scope <String>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

Rutina New-Variable vytvoří novou proměnnou v PowerShellu. Hodnotu proměnné můžete přiřadit při vytváření nebo přiřazování nebo změně hodnoty po jejím vytvoření.

Pomocí parametrů New-Variable můžete nastavit vlastnosti proměnné, nastavit obor proměnné a určit, jestli jsou proměnné veřejné nebo soukromé.

Obvykle vytvoříte novou proměnnou zadáním názvu proměnné a její hodnoty, například $Var = 3, ale můžete použít rutinu New-Variable k použití jeho parametrů.

Příklady

Příklad 1: Vytvoření proměnné

New-Variable days

Tento příkaz vytvoří novou proměnnou s názvem days. Není nutné zadávat parametr Name.

Příklad 2: Vytvoření proměnné a přiřazení hodnoty

New-Variable -Name "zipcode" -Value 98033

Tento příkaz vytvoří proměnnou s názvem PSČ a přiřadí jí hodnotu 98033.

Příklad 3: Vytvoření proměnné s možností ReadOnly

PS C:\> New-Variable -Name Max -Value 256 -Option ReadOnly
PS C:\> New-Variable -Name max -Value 1024

New-Variable : A variable with name 'max' already exists.
At line:1 char:1
+ New-Variable -Name max -Value 1024
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ResourceExists: (max:String) [New-Variable], SessionStateException
    + FullyQualifiedErrorId : VariableAlreadyExists,Microsoft.PowerShell.Commands.NewVariableCommand

PS C:\> New-Variable -Name max -Value 1024 -Force

Tento příklad ukazuje, jak pomocí možnosti ReadOnlyNew-Variable chránit proměnnou před přepsáním.

První příkaz vytvoří novou proměnnou s názvem Max a nastaví její hodnotu na 256. Používá parametr Option s hodnotou ReadOnly.

Druhý příkaz se pokusí vytvořit druhou proměnnou se stejným názvem. Tento příkaz vrátí chybu, protože u proměnné je nastavená možnost jen pro čtení.

Třetí příkaz používá parametr Force k přepsání ochrany jen pro čtení u proměnné. V tomto případě příkaz k vytvoření nové proměnné se stejným názvem proběhne úspěšně.

Příklad 4: Přiřazení více možností proměnné

New-Variable -Name 'TestVariable' -Value 'Test Value' -Option AllScope,Constant

Tento příklad vytvoří proměnnou a přiřadí AllScope a Constant možnosti, aby byla proměnná k dispozici v aktuálním oboru a všechny nově vytvořené obory a nelze je změnit ani odstranit.

Příklad 5: Vytvoření privátní proměnné

Tento příkaz ukazuje chování privátní proměnné v modulu. Modul obsahuje rutinu Get-Counter, která má privátní proměnnou s názvem Counter. Příkaz používá parametr Visibility s hodnotou Private k vytvoření proměnné.

PS C:\> New-Variable -Name counter -Visibility Private

#Effect of private variable in a module.

PS C:\> Get-Variable c*

Name                           Value
----                           -----
Culture                        en-US
ConsoleFileName
ConfirmPreference              High
CommandLineParameters          {}

PS C:\> $counter
"Cannot access the variable '$counter' because it is a private variable"
At line:1 char:1
+ $counter
+ ~~~~~~~~
    + CategoryInfo          : PermissionDenied: (counter:String) [], SessionStateException
    + FullyQualifiedErrorId : VariableIsPrivate

PS C:\> Get-Counter
Name         Value
----         -----
Counter1     3.1415
...

Ukázkový výstup ukazuje chování privátní proměnné. Uživatel, který modul načetl, nemůže zobrazit nebo změnit hodnotu proměnné čítače, ale proměnnou čítače lze číst a měnit příkazy v modulu.

Příklad 6: Vytvoření proměnné s mezerou

Tento příklad ukazuje, že proměnné s mezerami je možné vytvořit. K proměnným lze přistupovat pomocí rutiny Get-Variable nebo přímo tak, že proměnnou oddělíte složenými závorkami.

PS C:\> New-Variable -Name 'with space' -Value 'abc123xyz'

PS C:\> Get-Variable -Name 'with space'

Name                           Value
----                           -----
with space                     abc123xyz

PS C:\> ${with space}
abc123xyz

Parametry

-Confirm

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

Vlastnosti parametru

Typ:SwitchParameter
Default value:False
Podporuje zástupné znaky:False
DontShow:False
Aliasy:viz

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Description

Určuje popis proměnné.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Force

Označuje, že rutina vytvoří proměnnou se stejným názvem jako existující proměnná jen pro čtení.

Ve výchozím nastavení můžete proměnnou přepsat, pokud proměnná nemá hodnotu možnosti ReadOnly nebo Constant. Další informace najdete v parametru Option.

Vlastnosti parametru

Typ:SwitchParameter
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Name

Určuje název nové proměnné.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:0
Povinné:True
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:True
Hodnota ze zbývajících argumentů:False

-Option

Určuje hodnotu vlastnosti Options proměnné. Přijatelné hodnoty pro tento parametr jsou:

  • None – Nastaví žádné možnosti. None je výchozí.
  • ReadOnly – lze odstranit. Nelze změnit, s výjimkou použití parametru Force.
  • Private – Proměnná je k dispozici pouze v aktuálním oboru.
  • AllScope – Proměnná se zkopíruje do všech nově vytvořených oborů.
  • Constant – Nelze odstranit ani změnit. Constant je platný pouze při vytváření proměnné. Nelze změnit možnosti existující proměnné na Constant.

Tyto hodnoty jsou definovány jako výčtové hodnoty na bázi příznaků. Pomocí tohoto parametru můžete zkombinovat více hodnot a nastavit více příznaků. Hodnoty lze předat parametru Option jako pole hodnot nebo jako řetězec oddělený čárkami těchto hodnot. Rutina zkombinuje hodnoty pomocí binární operace OR. Předání hodnot jako pole je nejjednodušší možností a také umožňuje využít automatické doplňování pomocí klávesy Tab pro hodnoty.

Chcete-li zobrazit vlastnost Možnosti všech proměnných v relaci, zadejte Get-Variable | Format-Table -Property name, options -AutoSize.

Vlastnosti parametru

Typ:ScopedItemOptions
Default value:None
Přípustné hodnoty:None, ReadOnly, Constant, Private, AllScope, Unspecified
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-PassThru

Vrátí objekt představující položku, se kterou pracujete. Ve výchozím nastavení tato rutina negeneruje žádný výstup.

Vlastnosti parametru

Typ:SwitchParameter
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Scope

Určuje rozsah nové proměnné. Přijatelné hodnoty pro tento parametr jsou:

  • Global – Proměnné vytvořené v globálním oboru jsou přístupné všude v procesu PowerShellu.
  • Local – místní obor odkazuje na aktuální obor, může to být jakýkoli obor v závislosti na kontextu. Local je výchozí obor, pokud není zadán parametr oboru.
  • Script – Proměnné vytvořené v oboru skriptu jsou přístupné pouze v souboru skriptu nebo modulu, ve které jsou vytvořeny.
  • Číslo relativní k aktuálnímu oboru (0 až počet oborů, kde 0 je aktuální obor, 1 je jeho nadřazený obor, 2 nadřazený obor a tak dále). Záporná čísla nelze použít.

Poznámka:

Parametr také přijímá hodnotu Private. Private ve skutečnosti není oborem, ale volitelným nastavením proměnné. Použití hodnoty Private s touto rutinou ale nezmění viditelnost proměnné. Další informace najdete v části about_Scopes.

Vlastnosti parametru

Typ:String
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-Value

Určuje počáteční hodnotu proměnné.

Vlastnosti parametru

Typ:Object
Default value:None
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:1
Povinné:False
Hodnota z kanálu:True
Hodnota z kanálu podle názvu vlastnosti:True
Hodnota ze zbývajících argumentů:False

-Visibility

Určuje, zda je proměnná viditelná mimo relaci, ve které byla vytvořena. Tento parametr je určený pro použití ve skriptech a příkazech, které se doručí jiným uživatelům. Přijatelné hodnoty pro tento parametr jsou:

  • Public – proměnná je viditelná. Public je výchozí.
  • Private – Proměnná není viditelná.

Pokud je proměnná soukromá, nezobrazí se v seznamech proměnných, jako jsou proměnné vrácené Get-Variablenebo v zobrazení jednotky Variable:. Příkazy pro čtení nebo změnu hodnoty privátní proměnné vrátí chybu. Uživatel ale může spouštět příkazy, které používají privátní proměnnou, pokud byly příkazy napsané v relaci, ve které byla proměnná definována.

Vlastnosti parametru

Typ:SessionStateEntryVisibility
Default value:None
Přípustné hodnoty:Public, Private
Podporuje zástupné znaky:False
DontShow:False

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

-WhatIf

Ukazuje, co se stane, když se příkaz spustí. Příkazový modul nebyl spuštěn.

Vlastnosti parametru

Typ:SwitchParameter
Default value:False
Podporuje zástupné znaky:False
DontShow:False
Aliasy:Wi

Sady parametrů

(All)
Position:Named
Povinné:False
Hodnota z kanálu:False
Hodnota z kanálu podle názvu vlastnosti:False
Hodnota ze zbývajících argumentů:False

CommonParameters

Tato rutina podporuje běžné parametry: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction a -WarningVariable. Další informace najdete v about_CommonParameters.

Vstupy

Object

Do New-Variablemůžete převést libovolný objekt .

Výstupy

None

Ve výchozím nastavení tato rutina nevrací žádný výstup.

PSVariable

Pokud použijete parametr PassThru, vrátí tato rutina PSVariable objekt představující novou proměnnou.

Poznámky

PowerShell obsahuje následující aliasy pro New-Variable:

  • Všechny platformy:
    • nv