About Functions Advanced Parameters (Čeština)

• 10/27/2020
• 20 minutes to read
• • S
  • s
  • s
  • c
  • g

Short description

Explains how to add parameters to advanced functions.,

popis

můžete přidat parametry do pokročilých funkcí, které píšete, a useparameter atributy a argumenty pro omezení hodnoty parametrů, které functionusers předložit s parametrem.

parametry, které můžete přidat do své funkce jsou k dispozici uživatelům kromě běžných parametrů, které PowerShell přidává automaticky ke všem rutin andadvanced funkce. Pro více informací o PowerShell commonparameters, viz about_CommonParameters.

začátek v PowerShell 3.,0, můžete použít splatting s @Args reprezentovatparametry v příkazu. Splatting platí pro jednoduché a pokročiléfunkce. Pro více informací viz about_Functions andabout_Splatting.

typ konverze hodnot parametrů

když řetězce dodáváte jako argumenty parametrům, které očekávají jiný typ, PowerShell implicitně převádí řetězce na typ parametru target.Pokročilé funkce provádějí kultivačně invariantní analýzu hodnot parametrů.

naproti tomu při parametrizaci kompilovaných cmdletů se provádí konverze citlivá na kulturu.,

v tomto příkladu vytvoříme cmdlet a funkci skriptu, která vezme parametr. Současná kultura se mění tak, aby používala německá nastavení.Do parametru je předáno Německo-formátované Datum.

Dienstag, 19. Juni 2018 00:00:00

jak je uvedeno výše, cmdlets používají analýzu citlivou na kulturu k převodu řetězce.

pokročilé funkce používají kultivačně invariantní parsování, což má za následek následující chybu.

statické parametry

statické parametry jsou parametry, které jsou vždy k dispozici ve funkci.,Většina parametrů v PowerShell cmdlets a skripty jsou statické parametry.

následující příklad ukazuje deklaraci a ComputerName parameterthat má následující charakteristiky:

• povinné (povinné).
• bere vstup z potrubí.
• to trvá řadu řetězců jako vstup.

Param( ] $ComputerName)

atributy parametrů

tato část popisuje atributy, které můžete přidat do funkčních parametrů.

všechny atributy jsou volitelné., Nicméně, pokud vynecháte CmdletBindingattribute, pak být rozpoznán jako pokročilá funkce, funkce musízahrnují atribut parametru.

do každé deklarace parametrů můžete přidat jeden nebo více atributů. Neexistuje žádný limit na počet atributů, které můžete přidat do parametrudeklarace.

atribut parametru

atribut parametru se používá k deklaraci atributů functionparameters.

atribut parametru je volitelný a můžete jej vynechat, pokud žádný z nichparametry vašich funkcí nepotřebují atributy., Ale, být rozpoznán jako anadvanced funkce, spíše než jednoduchá funkce, funkce musí mít buďto atribut CmdletBinding nebo atribut parametru, nebo obojí.

atribut parametru má argumenty, které definují vlastnosti parametru, například zda je parametr povinný nebo volitelný.

použijte následující syntaxi k deklaraci atributu parametru, argumentu a hodnoty argumentu. Závorky, které uzavírají argument a jeho hodnotumusí následovat parametr bez zasahujícího prostoru.,

Param( $ParameterName)

použijte čárky k oddělení argumentů v závorkách. Pomocí followingsyntax deklarovat dva argumenty atributu parametru.

Param( )

typy argumentů boolean atributu parametru výchozí Falsewhen vynechán z atributu parametru. Nastavte hodnotu argumentu na$true nebo stačí uvést argument podle názvu. Například následujícíparametrové atributy jsou ekvivalentní.,

Pokud použijete atribut parametru bez argumentů, jako alternativu k atributu CmdletBinding jsou stále vyžadovány závorky, které následují Název theattribute.

Param( $ParameterName)

Povinný argument

Mandatory argument indikuje, že parametr je povinný. Pokud tento parametr není zadán, je parametr volitelný.

následující příklad deklaruje parametr ComputerName. Používá argumentMandatory, aby byl parametr povinný.,

Param( ] $ComputerName)

argument Pozice

Position argument určuje, zda je název parametru, je nutné, když je použit parametr v příkazu. Když parametr prohlášení obsahujePosition argument, název parametru, může být vynechán a PowerShellidentifies nejmenovaný parametr hodnotu jeho polohy, nebo pořadí, v seznamu nejmenovaný hodnoty parametrů v příkazu.,

není-li zadán argumentPosition, musí název parametru nebo parametrname alias nebo zkratka předcházet hodnotě parametru, kdykoli je parametr použit v příkazu.

ve výchozím nastavení jsou všechny funkční parametry poziční. PowerShell přiřadí pozicičísla na parametry v pořadí, ve kterém jsou parametry deklarovány vfunkce. Tuto funkci zakázat, nastavte hodnotu na PositionalBindingargument atribut CmdletBinding $False., Argument Positionmá přednost před hodnotouPositionalBinding atributu CmdletBinding. Pro více informací viz PositionalBindingv about_Functions_CmdletBindingAttribute.

hodnota argumentu Position je zadána jako celé číslo. Pozicehodnota 0 představuje první pozici v příkazu, hodnota poziceof 1 představuje druhou pozici v příkazu a tak dále.,

Pokud funkce nemá žádné polohové parametry, PowerShell přiřadí polohykaždý parametr na základě pořadí, ve kterém jsou parametry deklarovány.Nicméně, jako nejlepší praxe, nespoléhejte se na tento úkol. Pokud chcete, aby byly parametry poziční, použijte argument Position.

následující příklad deklaruje parametr ComputerName. Používá argumentPosition s hodnotou 0. Výsledkem je, že když je -ComputerName isomitováno z příkazu, jeho hodnota musí být první nebo pouze nejmenovaný parametrvalue v příkazu.,

Param( ] $ComputerName)

ParameterSetName argument,

ParameterSetName argument určuje parametr nastaven na který aparameter patří. Pokud není zadána žádná sada parametrů, parametr patřívšechny sady parametrů definované funkcí. Proto, aby byl jedinečný, každýparametrová sada musí mít alespoň jeden parametr, který není členem žádné jinéparametrové sady.

následující příklad deklaruje ComputerName parametr v Computerparametr nastavit, uživatelské Jméno parametru v User parametr nastaven, a aSummary parametr v obou sad parametrů.

v každém argumentu můžete zadat pouze jednu hodnotu ParameterSetName a pouze jedenParameterSetName argument v každém atributu parametru. Chcete-li uvést, že aparameter se objeví ve více než jedné sadě parametrů, přidejte další Parametrattributes.,

následující příklad explicitně přidává Shrnutí parametrComputer User parametr nastavuje. Souhrnný parametr je volitelný v souborech parametrů Computer a povinný v parametruUser.

Další informace o sadách parametrů naleznete v části sady parametrů.

ValueFromPipeline argument

ValueFromPipeline argument znamená, že parametr přijímá vstupz objektu potrubí., Zadejte tento argument, pokud funkce akceptujejeho objekt, ne jen vlastnost objektu.

následující příklad deklaruje parametr ComputerName, který je povinný a přijímá objekt, který je předán funkci z potrubí.

Param( ] $ComputerName)

ValueFromPipelineByPropertyName argument,

ValueFromPipelineByPropertyName argument naznačuje, že parameteraccepts vstup z majetku potrubí objektu. Vlastnost objektu musímají stejný název nebo alias jako parametr.,

například pokud má funkce parametr ComputerName a pipedobject má vlastnost ComputerName, je hodnota computernameproperty přiřazena parametru ComputerName.

následující příklad deklaruje parametr ComputerName, který je povinný, a přijímá vstup z Vlastnosti objektu ComputerName, která je předána funkci potrubím.,

Param( ] $ComputerName)

ValueFromRemainingArguments argument,

ValueFromRemainingArguments argument ukazuje, že parametr acceptsall parametr hodnoty v příkazu, které nejsou přiřazeny k otherparameters funkce.

následující příklad deklaruje Hodnotu parametru, který je povinný a aRemaining parametr, který přijímá všechny zbývající hodnoty parametrů, které jsou předloženy funkce.

Found 2 elements0: one1: two

argument HelpMessage

argumentHelpMessage určuje řetězec, který obsahuje stručný popis parametru nebo jeho hodnoty. PowerShell zobrazí tuto zprávu v promptto se objeví, když v příkazu chybí povinná hodnota parametru. To nemá žádný vliv na volitelné parametry.

následující příklad deklaruje povinný parametr ComputerName a zprávu ahelp, která vysvětluje očekávanou hodnotu parametru.,

Pokud neexistuje žádný další komentář-na základě pomoci syntaxfor funkci (např. .SYNOPSIS), pak tato zpráva také se objeví vGet-Help výstup.

Param( ] $ComputerName)

Alias atribut

atribut Alias vytváří alternativní název parametru.Neexistuje žádný limit na počet aliasů, které můžete přiřadit parametru.

následující příklad ukazuje deklaraci parametrů, která přidává aliasy CN andMachineName k povinnému parametru ComputerName.,

Param( ] $ComputerName)

SupportsWildcards atribut

SupportsWildcards atribut se používá k označení, že parameteraccepts zástupné hodnoty. Následující příklad ukazuje deklaraci parametrupro parametr povinné cesty, který podporuje hodnoty zástupných znaků.

Param( ] $Path)

použití tohoto atributu automaticky neumožňuje podporu zástupných znaků. Cmdletdeveloper musí implementovat kód pro zpracování zástupných vstupů. Wildcardssupported se může lišit podle základního API nebo poskytovatele PowerShell. Formore informace, viz about_Wildcards.,

parametry a atributy validace proměnných

validace atributy direct PowerShell testovat hodnoty parametrů, které userssubmit při volání pokročilé funkce. Pokud hodnoty parametru selžoutest, je generována chyba a funkce není volána. Ověření parametru se použije pouze na zadaný vstup a jiné hodnoty, jako jsou výchozí hodnoty, nejsou validovány.

atributy validace můžete také použít k omezení hodnot, které mohou uživatelé zadat pro proměnné., Používáte-li převodník typu spolu s atributem avalidace, převodník typu musí být definován před atributem.

 $number = 7

AllowNull validace atribut

AllowNull atribut umožňuje hodnotu povinný parametr$null. Následující příklad deklaruje hashtable computerinfo parametrkterý může mít nulovou hodnotu.

Param( $ComputerInfo)

AllowEmptyString validace atribut

AllowEmptyString atribut umožňuje hodnotu povinný parametr tobe prázdný řetězec (""). Následující příklad deklaruje ComputerNameparameter, který může mít prázdnou hodnotu řetězce.

Param( $ComputerName)

AllowEmptyCollection validace atribut

AllowEmptyCollection atribut umožňuje hodnotu mandatoryparameter být prázdné kolekce @()., Následující příklad deklaruje parametr aComputerName, který může mít prázdnou hodnotu sběru.

Param( ] $ComputerName)

ValidateCount validace atribut

ValidateCount atribut určuje minimální a maximální počet parametrů hodnoty, které jako parametr přijímá. PowerShell generuje chybu, pokud počet hodnot parametrů v příkazu volání funkce je outsidethat rozsahu.

následující deklarace parametrů vytvoří parametr ComputerName, který provede jednu až pět hodnot parametrů.,

Param( ] $ComputerName)

ValidateLength validace atribut

ValidateLength atribut určuje minimální a maximální počet znaků v parametru nebo proměnné hodnoty. PowerShell generuje chybu, pokuddélka hodnoty zadané pro parametr nebo proměnnou je mimo rozsah.

v následujícím příkladu musí mít každý název počítače jeden až deset znaků.

Param( ] $ComputerName)

V následujícím příkladu hodnota proměnné $number musí být studenti, kteří chtějí jeden znak v délce, a maximálně deset znaků.,

$number = '01'

validatepattern validation attribute

atribut ValidatePattern určuje regulární výraz, který ‚ porovnává s parametrem nebo proměnnou hodnotou. PowerShell generuje chybu, pokudhodnota neodpovídá vzoru regulárního výrazu.,

v následujícím příkladu musí hodnota parametru obsahovat čtyřmístné číslo a každá číslice musí být číslo nula až devět.

Param( ")] ] $ComputerName)

V následujícím příkladu hodnota proměnné $number musí být přesně čtyři-místné číslo, a každá číslice musí být číslo nula až devět.

$")]$number = 1111

ValidateRange validace atribut

ValidateRange atribut určuje číselný rozsah nebo aValidateRangeKind enum hodnotu pro každý parametr nebo hodnotu proměnné.PowerShell generuje chybu, pokud je nějaká hodnota mimo tento rozsah.,

ValidateRangeKind enum umožňuje následující hodnoty:

• Pozitivní – číslo větší než nula.
• negativní-číslo menší než nula.
• Nepozitivní-číslo menší nebo rovno nule.
• NonNegative-číslo větší nebo rovno nule.

v následujícím příkladu musí být hodnota parametru Pokusymezi nulou a deseti.

Param( $Attempts)

V následujícím příkladu hodnota proměnné $number musí být betweenzero a deset.,

$number = 5

V následujícím příkladu hodnota proměnné $number musí být větší než nula.

$number = 1

ValidateScript validace atribut

ValidateScript atribut určuje skript, který se používá k ověření aparameter nebo hodnotu proměnné. PowerShell potrubí hodnoty do skriptu, andgenerates chybu, pokud skript vrátí $false nebo pokud skript hází anexception.,

při použití atributu ValidateScript je hodnota, která je validována, mapována na proměnnou $_. Pomocí proměnné $_ můžete odkazovat na hodnotu ve skriptu.

v následujícím příkladu musí být hodnota parametru EventDate větší než nebo rovna aktuálnímu datu.

Param( $EventDate)

V následujícím příkladu hodnota proměnné $date musí být větší než nebo rovno aktuální datum a čas.,

$date = (Get-Date)

atribut ValidateSet

atribut ValidateSet určuje sadu platných hodnot pro proměnnou parametror a umožňuje dokončení karty. PowerShell generuje chybu, pokud aparametr nebo proměnná hodnota neodpovídá hodnotě v sadě. V následujícímpříklad, hodnota parametru detailu může být pouze nízká, průměrná, nebovysoká.,

Param( ] $Detail)

V následujícím příkladu hodnota proměnné $flavor musí být eitherChocolate, Jahodový, nebo Vanilkový.

$flavor = "Strawberry"

validace nastává vždy, když je tato proměnná přiřazena i v rámci thescriptu. Například, následující za následek chybu v době běhu:

Param( $Message)$Message = "bye"

Dynamické validateSet hodnoty

můžete použít Třídy dynamicky generovat hodnoty pro ValidateSetat runtime., V následujícím příkladu, platné hodnoty pro proměnnou$Sound jsou generovány pomocí Třídy jménem SoundNames, že kontroly threefilesystem cesty k dispozici pro zvukové soubory:

třída je pak realizován jako dynamický ValidateSet valueas takto:

Param( )] $Sound)

ValidateNotNull validace atribut

ValidateNotNull atribut určuje, že hodnota parametru může být$null. PowerShell generuje chybu, pokud je hodnota parametru $null.,

ValidateNotNull atribut je určen pro použití, když je parametr isoptional a typ není definován nebo má typ konvertor, který může’timplicitly převést hodnotu null jako objekt. Pokud zadáte typ, který implicitně převede hodnotu null, jako je řetězec, hodnota nullse převede na prázdný řetězec i při použití ValidateNotNullattribute. Pro tento scénář použijte ValidateNotNullOrEmpty

v následujícím příkladu nemůže být hodnota parametru ID $null.,

Param( $ID)

ValidateNotNullOrEmpty validace atribut

ValidateNotNullOrEmpty atribut určuje, že parametr valuecan být $null a nemůže být prázdný řetězec (""). PowerShell generuje anerror pokud je použit parametr ve volání funkce, ale jeho hodnota je $null, anempty řetězec (""), nebo prázdné pole @().,

Param( ] $UserName)

ValidateDrive validace atribut

ValidateDrive atribut určuje, že hodnota parametru mustrepresent cestu, která odkazuje k povoleny disky pouze. Powershellgeneruje chybu, pokud hodnota parametru odkazuje na jiné jednotky než na povolené. Existence cesty, s výjimkou samotného pohonu, není ověřena.

Pokud používáte relativní cestu, musí být aktuální jednotka v seznamu povolených jednotek.,

Param( $Path)

ValidateUserDrive validace atribut

ValidateUserDrive atribut určuje, že hodnota parametru mustrepresent cestu, která je s odkazem na User autem. PowerShell generuje anerror, pokud cesta odkazuje na jinou jednotku. Pouze atribut validacetesty pro existenci hnací části cesty.

Pokud používáte relativní cestu, musí být aktuální jednotka User.,

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The pathargument drive C does not belong to the set of approved drives: User.Supply a path argument with an approved drive.

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannotfind drive. A drive with the name 'User' does not exist.

můžete definovat User pohon Jen v Dost Správy (JEA) sessionconfigurations. Pro tento příklad vytvoříme User: drive.

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $env:HOMEPATH

True

ValidateTrustedData validace atribut

Tento atribut byl přidán v PowerShell 6.1.1.

v tomto okamžiku je atribut používán interně samotným PowerShellem a není určen pro externí použití.,

Dynamické parametry

Dynamické parametry jsou parametry cmdlet, funkce, nebo skript, který areavailable pouze za určitých podmínek.

například, několik poskytovatele rutin mít parametry, které jsou k dispozici teprve rutiny se používá u poskytovatele disku, nebo v konkrétní cestu theprovider disku. Například, Kódování parametr je k dispozici naAdd-Content Get-Content Set-Content rutin pouze, když je použit ina systému souborů disku.,

můžete také vytvořit parametr, který se objeví pouze tehdy, když je v příkazu funkce použit jiný parametr nebo pokud má jiný parametr určitou hodnotu.

dynamické parametry mohou být užitečné, ale používají je pouze v případě potřeby, protožemohou být pro uživatele obtížné objevit. Najít dynamický parametr, uživatel musí být v provider cestu, použijte Argument parametrGet-Command rutinu nebo použít parametr Path Get-Help.

Chcete-li vytvořit dynamický parametr pro funkci nebo skript, použijte klíčové slovoDynamicParam.,

syntaxe je následující:

DynamicParam {<statement-list>}

V prohlášení seznam, použít If prohlášení pro upřesnění podmínek, underwhich parametru je k dispozici funkce.

použijteNew-Object cmdlet pro vytvoření asystému.Řízení.Automatizace.RuntimeDefinedParameter objekt reprezentovatparametr a zadejte jeho název.

pro vytvoření asystému můžete použít příkazNew-Object.Řízení.Automatizace.,Parametrattribute objekt reprezentovatattributes parametru, jako je povinné, pozice, orValueFromPipeline nebo jeho parametr set.

následující příklad ukazuje funkci se standardními parametry namedName a Cestu, a volitelný dynamický parametr s názvem DP1. Parametr DP1 je v parametruPSet1 a má typ Int32.,Na DP1 parametr je k dispozici v Get-Sample funkce pouze tehdy, když hodnota Path parametr začíná HKLM:, což značí, že je beingused v HKEY_LOCAL_MACHINE registru jízdy.

pro více informací, seeRuntimeDefinedParameter.

parametry přepínače

parametry přepínače jsou parametry bez hodnoty parametru. Jsou účinné pouze tehdy, když jsou používány a mají pouze jeden účinek.

například parametr noprofile powershell.exe je switchparameter.,

Chcete-li vytvořit parametr přepínače ve funkci, zadejte Switch typ v definici parametru.

například:

Param(<ParameterName>)

Nebo můžete použít jinou metodu:

Param( $<ParameterName>)

Přepněte nastavení parametrů jsou snadné na používání a jsou upřednostňovány před Boolean parametry,které mají složitější syntaxi.

například pro použití parametru switch uživatel zadá parametr in thecommand.

-IncludeAll

pro použití booleovského parametru uživatel zadá parametr a hodnotu Boolean.,

-IncludeAll:$true

při vytváření parametrů přepínače pečlivě zvolte název parametru. Ujistěte se, že název parametru sděluje účinek parametru uživateli.Vyhněte se nejednoznačným termínům, jako je filtr nebo Maximum, které by mohlo znamenat, že je vyžadována avalue.

atribut ArgumentCompleter

atribut ArgumentCompleter umožňuje přidat hodnoty dokončení karty na konkrétní parametr. Atribut ArgumentCompleter musí být definován prokaždý parametr, který potřebuje dokončení karty., Podobně jako DynamicParameters, available hodnoty jsou vypočteny za běhu, když uživatel stiskne Tabpo názvu parametru.

Chcete-li přidat atribut ArgumentCompleter, musíte definovat blok skriptukterý určuje hodnoty. Blok skriptu musí být následujícíparametry v níže uvedeném pořadí. Názvy parametrů nezáleží jakozávažky jsou poskytovány polohově.,

syntaxe je následující:

ArgumentCompleter blok skriptu

blok skriptu, parametry jsou nastaveny na následující hodnoty:

• $commandName (Pozice 0) – Tento parametr je nastaven na název příkazovém pro které je blok skriptu je poskytování kartu dokončení.
• $parameterName (Pozice 1) – Tento parametr je nastaven na parametr whosevalue vyžaduje kartu dokončení.
• $wordToComplete (Pozice 2) – Tento parametr je nastaven na hodnotu uživatel hasprovided před stisknutí Tab., Váš blok skriptu by měl používattato hodnota pro určení hodnot dokončení karty.
• $commandAst (Pozice 3) – Tento parametr je nastaven na Abstraktní SyntaxTree (AST) pro aktuální vstupní řádek. Pro více informací viz třída.
• $fakeBoundParameters (Pozice 4) – Tento parametr je nastaven na hashtablecontaining $PSBoundParameters pro rutiny, předtím, než uživatel pressedTab. Pro více informací vizabout_automatic_variables.,

ArgumentCompleter blok skriptu, musí rozvinout hodnoty pomocí thepipeline, jako je ForEach-Object Where-Object, nebo jinou vhodnou metodou.Vrácení pole hodnot způsobí, že PowerShell zachází s celou hodnotou dokončení karty array asone.

následující příklad přidá dokončení karty k parametru hodnota. Pokud je zadán pouze parametr hodnot, zobrazí se všechny možné hodnoty nebo argumenty forValue. Když je zadán parametr typeparametr value zobrazuje pouze možné hodnoty pro tento typ.,

kromě toho, -like provozovatel zaručuje, že pokud uživatel zadá followingcommand a používá Kartu dokončení, jen Apple je vrátil.

Test-ArgumentCompleter -Type Fruits -Value A

Viz také

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute