À propos des paramètres avancés functions

Description courte

Explique comment ajouter des paramètres à des fonctions avancées.

Description longue

Vous pouvez ajouter des paramètres aux fonctions avancées que vous écrivez et utiliser des attributs de paramètre et des arguments pour limiter les valeurs de paramètre que les utilisateurs de fonction soumettent avec le paramètre.

Les paramètres que vous ajoutez à votre fonction sont disponibles pour les utilisateurs en plus des paramètres courants que PowerShell ajoute automatiquement à toutes les applets de commande et fonctions avancées. Pour plus d’informations sur les paramètres courants PowerShell, consultez about_CommonParameters.

À compter de PowerShell 3.0, vous pouvez utiliser la mise en forme avec @Args pour représenter les paramètres d’une commande. La mise en plateforme est valide sur des fonctions simples et avancées. Pour plus d’informations, consultez about_Functions et about_Splatting.

Conversion de type de valeurs de paramètre

Lorsque vous fournissez des chaînes en tant qu’arguments aux paramètres qui attendent un autre type, PowerShell convertit implicitement les chaînes en type cible de paramètre. Les fonctions avancées effectuent l’analyse invariante de culture des valeurs de paramètre.

En revanche, une conversion sensible à la culture est effectuée lors de la liaison de paramètres pour les applets de commande compilées.

Dans cet exemple, nous créons une applet de commande et une fonction de script qui prend un [datetime] paramètre. La culture actuelle est modifiée pour utiliser les paramètres allemands. Une date au format allemand est passée au paramètre.

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr

Dienstag, 19. Juni 2018 00:00:00

Comme indiqué ci-dessus, les applets de commande utilisent l’analyse sensible à la culture pour convertir la chaîne.

# Define an equivalent function.
function Get-Date_Func {
  param(
    [DateTime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

Les fonctions avancées utilisent l’analyse invariante de culture, ce qui entraîne l’erreur suivante.

Get-Date_Func : Cannot process argument transformation on parameter 'Date'. Cannot convert
 value "19-06-2018" to type "System.DateTime". Error: "String was not recognized as a valid
 DateTime."
At line:13 char:15
+ Get-Date_Func $dateStr
+               ~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Get-Date_Func], ParameterBindingArgumentTransformationException
    + FullyQualifiedErrorId : ParameterArgumentTransformationError,Get-Date_Func

Paramètres statiques

Les paramètres statiques sont des paramètres qui sont toujours disponibles dans la fonction. La plupart des paramètres dans les applets de commande et les scripts PowerShell sont des paramètres statiques.

L’exemple suivant montre la déclaration d’un paramètre ComputerName qui présente les caractéristiques suivantes :

• Il est obligatoire (obligatoire).
• Il prend une entrée à partir du pipeline.
• Il prend un tableau de chaînes en tant qu’entrée.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

Attributs des paramètres

Cette section décrit les attributs que vous pouvez ajouter aux paramètres de fonction.

Tous les attributs sont facultatifs. Toutefois, si vous omettez l’attribut CmdletBinding , puis pour être reconnu comme une fonction avancée, la fonction doit inclure l’attribut Paramètre .

Vous pouvez ajouter un ou plusieurs attributs dans chaque déclaration de paramètre. Il n’existe aucune limite au nombre d’attributs que vous pouvez ajouter à une déclaration de paramètre.

Attribut de paramètre

L’attribut Paramètre est utilisé pour déclarer les attributs des paramètres de fonction.

L’attribut Paramètre est facultatif et vous pouvez l’omettre si aucun des paramètres de vos fonctions n’a besoin d’attributs. Toutefois, pour être reconnue comme une fonction avancée, plutôt qu’une fonction simple, une fonction doit avoir l’attribut CmdletBinding ou l’attribut Parameter , ou les deux.

L’attribut Paramètre contient des arguments qui définissent les caractéristiques du paramètre, par exemple si le paramètre est obligatoire ou facultatif.

Utilisez la syntaxe suivante pour déclarer l’attribut Paramètre , un argument et une valeur d’argument. Les parenthèses qui entourent l’argument et sa valeur doivent suivre le paramètre sans espace intermédiaire.

Param(
    [Parameter(Argument=value)]
    $ParameterName
)

Utilisez des virgules pour séparer les arguments entre parenthèses. Utilisez la syntaxe suivante pour déclarer deux arguments de l’attribut Paramètre .

Param(
    [Parameter(Argument1=value1,
    Argument2=value2)]
)

Types d’arguments booléens de l’attribut Paramètre par défaut sur False lorsqu’il est omis à partir de l’attribut Paramètre . Définissez la valeur $true de l’argument sur ou répertoriez simplement l’argument par nom. Par exemple, les attributs de paramètre suivants sont équivalents.

Param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

Param(
    [Parameter(Mandatory)]
)

Si vous utilisez l’attribut Parameter sans arguments, comme alternative à l’utilisation de l’attribut CmdletBinding , les parenthèses qui suivent le nom de l’attribut sont toujours requises.

Param(
    [Parameter()]
    $ParameterName
)

Argument obligatoire

L’argument Mandatory indique que le paramètre est requis. Si cet argument n’est pas spécifié, le paramètre est facultatif.

L’exemple suivant déclare le paramètre ComputerName . Il utilise l’argument Mandatory pour rendre le paramètre obligatoire.

Param(
    [Parameter(Mandatory=$true)]
    [String[]]
    $ComputerName
)

Argument position

L’argument Position détermine si le nom du paramètre est requis lorsque le paramètre est utilisé dans une commande. Lorsqu’une déclaration de paramètre inclut l’argument, le nom du Position paramètre peut être omis et PowerShell identifie la valeur de paramètre non nommée par sa position ou son ordre, dans la liste des valeurs de paramètre non nommées dans la commande.

Si l’argument Position n’est pas spécifié, le nom du paramètre, ou un alias ou une abréviation de nom de paramètre, doit précéder la valeur du paramètre chaque fois que le paramètre est utilisé dans une commande.

Par défaut, tous les paramètres de fonction sont positionnels. PowerShell affecte des numéros de position aux paramètres dans l’ordre dans lequel les paramètres sont déclarés dans la fonction. Pour désactiver cette fonctionnalité, définissez la valeur de l’argument de l’attribut PositionalBindingCmdletBinding sur $False. L’argument Position est prioritaire sur la valeur de l’argument de l’attribut PositionalBindingCmdletBinding . Pour plus d’informations, consultez PositionalBindingabout_Functions_CmdletBindingAttribute.

La valeur de l’argument Position est spécifiée sous la forme d’un entier. Une valeur de position de 0 représente la première position de la commande, une valeur de position de 1 représente la deuxième position dans la commande, et ainsi de suite.

Si une fonction n’a aucun paramètre positionnel, PowerShell affecte des positions à chaque paramètre en fonction de l’ordre dans lequel les paramètres sont déclarés. Toutefois, en tant que meilleure pratique, ne vous appuyez pas sur cette affectation. Lorsque vous souhaitez que les paramètres soient positionnels, utilisez l’argument Position .

L’exemple suivant déclare le paramètre ComputerName . Il utilise l’argument Position avec une valeur de 0. Par conséquent, lorsqu’elle -ComputerName est omise de la commande, sa valeur doit être la première ou seule valeur de paramètre non nommée dans la commande.

Param(
    [Parameter(Position=0)]
    [String[]]
    $ComputerName
)

Argument ParameterSetName

L’argument ParameterSetName spécifie le paramètre défini sur lequel appartient un paramètre. Si aucun jeu de paramètres n’est spécifié, le paramètre appartient à tous les ensembles de paramètres définis par la fonction. Par conséquent, pour être unique, chaque jeu de paramètres doit avoir au moins un paramètre qui n’est pas membre d’un autre jeu de paramètres.

Notes

Pour une applet de commande ou une fonction, il existe une limite de 32 jeux de paramètres.

L’exemple suivant déclare un paramètre ComputerName dans le Computer jeu de paramètres, un paramètre UserName dans le User jeu de paramètres et un paramètre Summary dans les deux ensembles de paramètres.

Param(
    [Parameter(Mandatory=$true,
    ParameterSetName="Computer")]
    [String[]]
    $ComputerName,

    [Parameter(Mandatory=$true,
    ParameterSetName="User")]
    [String[]]
    $UserName,

    [Parameter(Mandatory=$false)]
    [Switch]
    $Summary
)

Vous ne pouvez spécifier qu’une ParameterSetName seule valeur dans chaque argument et un seul ParameterSetName argument dans chaque attribut Paramètre . Pour indiquer qu’un paramètre apparaît dans plusieurs ensembles de paramètres, ajoutez des attributs de paramètre supplémentaires.

L’exemple suivant ajoute explicitement le paramètre Summary aux jeux de paramètres et User aux Computer ensembles de paramètres. Le paramètre Summary est facultatif dans le Computer jeu de paramètres et obligatoire dans le jeu de User paramètres.

Param(
    [Parameter(Mandatory=$true,
    ParameterSetName="Computer")]
    [String[]]
    $ComputerName,

    [Parameter(Mandatory=$true,
    ParameterSetName="User")]
    [String[]]
    $UserName,

    [Parameter(Mandatory=$false, ParameterSetName="Computer")]
    [Parameter(Mandatory=$true, ParameterSetName="User")]
    [Switch]
    $Summary
)

Pour plus d’informations sur les ensembles de paramètres, consultez About Parameter Sets.

Argument ValueFromPipeline

L’argument ValueFromPipeline indique que le paramètre accepte l’entrée d’un objet de pipeline. Spécifiez cet argument si la fonction accepte l’objet entier, pas seulement une propriété de l’objet.

L’exemple suivant déclare un paramètre ComputerName obligatoire et accepte un objet transmis à la fonction à partir du pipeline.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipeline=$true)]
    [String[]]
    $ComputerName
)

Argument ValueFromPipelineByPropertyName

L’argument ValueFromPipelineByPropertyName indique que le paramètre accepte l’entrée d’une propriété d’un objet de pipeline. La propriété objet doit avoir le même nom ou alias que le paramètre.

Par exemple, si la fonction a un paramètre ComputerName et que l’objet canalé a une propriété ComputerName , la valeur de la propriété ComputerName est affectée au paramètre ComputerName de la fonction.

L’exemple suivant déclare un paramètre ComputerName obligatoire et accepte l’entrée de la propriété ComputerName de l’objet transmise à la fonction via le pipeline.

Param(
    [Parameter(Mandatory=$true,
    ValueFromPipelineByPropertyName=$true)]
    [String[]]
    $ComputerName
)

Notes

Un paramètre typé qui accepte l’entrée de pipeline () ou (by Valueby PropertyName) permet d’utiliser des blocs de script delay-bind sur le paramètre.

Le bloc de script de liaison différé est exécuté automatiquement pendant ParameterBinding. Le résultat est lié au paramètre. La liaison de retard ne fonctionne pas pour les paramètres définis comme type ScriptBlock ou System.Object. Le bloc de script est passé sans être appelé.

Vous pouvez en savoir plus sur les blocs de script de liaison différé ici about_Script_Blocks.md.

Argument ValueFromRemainingArguments

L’argument ValueFromRemainingArguments indique que le paramètre accepte toutes les valeurs du paramètre dans la commande qui ne sont pas affectées à d’autres paramètres de la fonction.

L’exemple suivant déclare un paramètre Value obligatoire et un paramètre Restant qui accepte toutes les valeurs de paramètre restantes soumises à la fonction.

function Test-Remainder
{
     param(
         [string]
         [Parameter(Mandatory = $true, Position=0)]
         $Value,
         [string[]]
         [Parameter(Position=1, ValueFromRemainingArguments)]
         $Remaining)
     "Found $($Remaining.Count) elements"
     for ($i = 0; $i -lt $Remaining.Count; $i++)
     {
        "${i}: $($Remaining[$i])"
     }
}
Test-Remainder first one,two

Found 2 elements
0: one
1: two

Notes

Avant PowerShell 6.2, la collection ValueFromRemainingArguments a été jointe en tant qu’entité unique sous l’index 0.

Argument HelpMessage

L’argument HelpMessage spécifie une chaîne qui contient une brève description du paramètre ou de sa valeur. PowerShell affiche ce message dans l’invite qui s’affiche lorsqu’une valeur de paramètre obligatoire est manquante dans une commande. Cet argument n’a aucun effet sur les paramètres facultatifs.

L’exemple suivant déclare un paramètre ComputerName obligatoire et un message d’aide qui explique la valeur de paramètre attendue.

S’il n’existe aucune autre syntaxe d’aide basée sur des commentaires pour la fonction (par exemple, .SYNOPSIS), ce message s’affiche également dans la Get-Help sortie.

Param(
    [Parameter(Mandatory=$true,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [String[]]
    $ComputerName
)

Alias (attribut)

L’attribut Alias établit un autre nom pour le paramètre. Il n’existe aucune limite au nombre d’alias que vous pouvez affecter à un paramètre.

L’exemple suivant montre une déclaration de paramètre qui ajoute les alias CN et MachineName au paramètre ComputerName obligatoire.

Param(
    [Parameter(Mandatory=$true)]
    [Alias("CN","MachineName")]
    [String[]]
    $ComputerName
)

Attribut SupportsWildcards

L’attribut SupportsWildcards est utilisé pour indiquer que le paramètre accepte des valeurs génériques. L’exemple suivant montre une déclaration de paramètre pour un paramètre Path obligatoire qui prend en charge les valeurs génériques.

Param(
    [Parameter(Mandatory=$true)]
    [SupportsWildcards()]
    [String[]]
    $Path
)

L’utilisation de cet attribut n’active pas automatiquement la prise en charge des caractères génériques. Le développeur d’applets de commande doit implémenter le code pour gérer l’entrée générique. Les caractères génériques pris en charge peuvent varier en fonction de l’API sous-jacente ou du fournisseur PowerShell. Pour plus d’informations, consultez about_Wildcards.

Attributs de validation des paramètres et des variables

Les attributs de validation dirigent PowerShell pour tester les valeurs de paramètres que les utilisateurs envoient lorsqu’ils appellent la fonction avancée. Si les valeurs de paramètre échouent au test, une erreur est générée et la fonction n’est pas appelée. La validation des paramètres est appliquée uniquement à l’entrée fournie et toutes les autres valeurs telles que les valeurs par défaut ne sont pas validées.

Vous pouvez également utiliser les attributs de validation pour restreindre les valeurs que les utilisateurs peuvent spécifier pour les variables. Lorsque vous utilisez un convertisseur de type avec un attribut de validation, le convertisseur de type doit être défini avant l’attribut.

[int32][AllowNull()] $number = 7

Attribut de validation AllowNull

L’attribut AllowNull autorise la valeur d’un paramètre $nullobligatoire . L’exemple suivant déclare un paramètre ComputerInfo de table de hachage qui peut avoir une valeur Null .

Param(
    [Parameter(Mandatory=$true)]
    [AllowNull()]
    [hashtable]
    $ComputerInfo
)

Notes

L’attribut AllowNull ne fonctionne pas si le convertisseur de type est défini sur chaîne, car le type de chaîne n’accepte pas de valeur Null. Vous pouvez utiliser l’attribut AllowEmptyString pour ce scénario.

Attribut de validation AllowEmptyString

L’attribut AllowEmptyString permet à la valeur d’un paramètre obligatoire d’être une chaîne vide (""). L’exemple suivant déclare un paramètre ComputerName qui peut avoir une valeur de chaîne vide.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyString()]
    [String]
    $ComputerName
)

Attribut de validation AllowEmptyCollection

L’attribut AllowEmptyCollection permet à la valeur d’un paramètre obligatoire d’être une collection @()vide. L’exemple suivant déclare un paramètre ComputerName qui peut avoir une valeur de collection vide.

Param(
    [Parameter(Mandatory=$true)]
    [AllowEmptyCollection()]
    [String[]]
    $ComputerName
)

Attribut de validation ValidateCount

L’attribut ValidateCount spécifie le nombre minimal et maximal de valeurs de paramètre qu’un paramètre accepte. PowerShell génère une erreur si le nombre de valeurs de paramètre dans la commande qui appelle la fonction se trouve en dehors de cette plage.

La déclaration de paramètre suivante crée un paramètre ComputerName qui prend une à cinq valeurs de paramètre.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateCount(1,5)]
    [String[]]
    $ComputerName
)

Attribut de validation ValidateLength

L’attribut ValidateLength spécifie le nombre minimal et maximal de caractères dans un paramètre ou une valeur de variable. PowerShell génère une erreur si la longueur d’une valeur spécifiée pour un paramètre ou une variable est en dehors de la plage.

Dans l’exemple suivant, chaque nom d’ordinateur doit comporter un à dix caractères.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateLength(1,10)]
    [String[]]
    $ComputerName
)

Dans l’exemple suivant, la valeur de la variable $number doit être d’une longueur minimale d’un caractère et d’un maximum de dix caractères.

[Int32][ValidateLength(1,10)]$number = '01'

Notes

Dans cet exemple, la valeur est 01 encapsulée entre guillemets simples. L’attribut ValidateLength n’accepte pas de nombre sans être encapsulé entre guillemets.

Attribut de validation ValidatePattern

L’attribut ValidatePattern spécifie une expression régulière comparée à la valeur du paramètre ou de la variable. PowerShell génère une erreur si la valeur ne correspond pas au modèle d’expression régulière.

Dans l’exemple suivant, la valeur du paramètre doit contenir un nombre à quatre chiffres, et chaque chiffre doit être un nombre zéro à neuf.

Param(
    [Parameter(Mandatory=$true)]
    [ValidatePattern("[0-9][0-9][0-9][0-9]")]
    [String[]]
    $ComputerName
)

Dans l’exemple suivant, la valeur de la variable $number doit être exactement un nombre à quatre chiffres, et chaque chiffre doit être un nombre zéro à neuf.

[Int32][ValidatePattern("^[0-9][0-9][0-9][0-9]$")]$number = 1111

Attribut de validation ValidateRange

L’attribut ValidateRange spécifie une plage numérique ou une valeur d’énumération ValidateRangeKind pour chaque paramètre ou valeur de variable. PowerShell génère une erreur si une valeur est en dehors de cette plage.

L’énumération ValidateRangeKind autorise les valeurs suivantes :

• Positif : nombre supérieur à zéro.
• Négatif : nombre inférieur à zéro.
• Nonpositive : nombre inférieur ou égal à zéro.
• NonNegative : nombre supérieur ou égal à zéro.

Dans l’exemple suivant, la valeur du paramètre Attempts doit être comprise entre zéro et dix.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateRange(0,10)]
    [Int]
    $Attempts
)

Dans l’exemple suivant, la valeur de la variable $number doit être comprise entre zéro et dix.

[Int32][ValidateRange(0,10)]$number = 5

Dans l’exemple suivant, la valeur de la variable $number doit être supérieure à zéro.

[Int32][ValidateRange("Positive")]$number = 1

Attribut de validation ValidateScript

L’attribut ValidateScript spécifie un script utilisé pour valider un paramètre ou une valeur de variable. PowerShell envoie la valeur au script et génère une erreur si le script retourne $false ou si le script lève une exception.

Lorsque vous utilisez l’attribut ValidateScript , la valeur en cours de validation est mappée à la $_ variable. Vous pouvez utiliser la $_ variable pour faire référence à la valeur dans le script.

Dans l’exemple suivant, la valeur du paramètre EventDate doit être supérieure ou égale à la date actuelle.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [DateTime]
    $EventDate
)

Dans l’exemple suivant, la valeur de la variable $date doit être supérieure ou égale à la date et à l’heure actuelles.

[DateTime][ValidateScript({$_ -ge (Get-Date)})]$date = (Get-Date)

Notes

Si vous utilisez ValidateScript, vous ne pouvez pas passer une $null valeur au paramètre. Lorsque vous transmettez une valeur Null ValidateScript ne peut pas valider l’argument.

Attribut ValidateSet

L’attribut ValidateSet spécifie un ensemble de valeurs valides pour un paramètre ou une variable et active la saisie semi-automatique des tabulations. PowerShell génère une erreur si un paramètre ou une valeur de variable ne correspond pas à une valeur dans l’ensemble. Dans l’exemple suivant, la valeur du paramètre Detail peut uniquement être Faible, Moyenne ou Élevée.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet("Low", "Average", "High")]
    [String[]]
    $Detail
)

Dans l’exemple suivant, la valeur de la variable $flavor doit être chocolate, fraise ou vanille.

[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[String]$flavor = "Strawberry"

La validation se produit chaque fois que cette variable est affectée même dans le script. Par exemple, les résultats suivants entraînent une erreur lors de l’exécution :

Param(
    [ValidateSet("hello", "world")]
    [String]$Message
)

$Message = "bye"

Valeurs validateSet dynamiques

Vous pouvez utiliser une classe pour générer dynamiquement les valeurs de ValidateSet au moment de l’exécution. Dans l’exemple suivant, les valeurs valides de la variable $Sound sont générées via une classe nommée SoundNames qui vérifie trois chemins de système de fichiers pour les fichiers audio disponibles :

Class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [String[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = ForEach ($SoundPath in $SoundPaths) {
            If (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [String[]] $SoundNames
    }
}

La [SoundNames] classe est ensuite implémentée en tant que valeur ValidateSet dynamique comme suit :

Param(
    [ValidateSet([SoundNames])]
    [String]$Sound
)

Attribut de validation ValidateNotNull

L’attribut ValidateNotNull spécifie que la valeur du paramètre ne peut pas être $null. PowerShell génère une erreur si la valeur du paramètre est $null.

L’attribut ValidateNotNull est conçu pour être utilisé lorsque le paramètre est facultatif et que le type n’est pas défini ou a un convertisseur de type qui ne peut pas convertir implicitement une valeur null comme un objet. Si vous spécifiez un type qui convertit implicitement une valeur Null telle qu’une chaîne, la valeur null est convertie en chaîne vide même lors de l’utilisation de l’attribut ValidateNotNull . Pour ce scénario, utilisez ValidateNotNullOrEmpty

Dans l’exemple suivant, la valeur du paramètre ID ne peut pas être $null.

Param(
    [Parameter(Mandatory=$false)]
    [ValidateNotNull()]
    $ID
)

Attribut de validation ValidateNotNullOrEmpty

L’attribut ValidateNotNullOrEmpty spécifie que la valeur du paramètre ne peut pas être $null et ne peut pas être une chaîne vide (""). PowerShell génère une erreur si le paramètre est utilisé dans un appel de fonction, mais sa valeur est $null, une chaîne vide ("") ou un tableau @()vide.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateNotNullOrEmpty()]
    [String[]]
    $UserName
)

Attribut de validation ValidateDrive

L’attribut ValidateDrive spécifie que la valeur du paramètre doit représenter le chemin d’accès, qui fait référence uniquement aux lecteurs autorisés. PowerShell génère une erreur si la valeur du paramètre fait référence à des lecteurs autres que ceux autorisés. L’existence du chemin, à l’exception du lecteur lui-même, n’est pas vérifiée.

Si vous utilisez le chemin relatif, le lecteur actuel doit se trouver dans la liste des lecteurs autorisés.

Param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [String]$Path
)

Attribut de validation ValidateUserDrive

L’attribut ValidateUserDrive spécifie que la valeur du paramètre doit représenter le chemin d’accès, qui fait référence au User lecteur. PowerShell génère une erreur si le chemin fait référence à un autre lecteur. L’attribut de validation teste uniquement l’existence de la partie lecteur du chemin d’accès.

Si vous utilisez le chemin relatif, le lecteur actuel doit être User.

function Test-UserDrivePath{
    [OutputType([bool])]
    Param(
      [Parameter(Mandatory=, Position=0)][ValidateUserDrive()][String]$Path
      )
    $True
}

Test-UserDrivePath -Path C:\

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument 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'. Cannot
find drive. A drive with the name 'User' does not exist.

Vous pouvez définir User un lecteur dans les configurations de session Just Enough Administration (JEA). Pour cet exemple, nous créons le lecteur User: .

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

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser

```powershell
Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

True

Attribut de validation ValidateTrustedData

Cet attribut a été ajouté dans PowerShell 6.1.1.

À ce stade, l’attribut est utilisé en interne par PowerShell lui-même et n’est pas destiné à une utilisation externe.

Paramètres dynamiques

Les paramètres dynamiques sont des paramètres d’une applet de commande, d’une fonction ou d’un script qui sont disponibles uniquement dans certaines conditions.

Par exemple, plusieurs applets de commande de fournisseur ont des paramètres qui sont disponibles uniquement lorsque l’applet de commande est utilisée dans le lecteur de fournisseur ou dans un chemin particulier du lecteur de fournisseur. Par exemple, le paramètre d’encodage est disponible sur les Add-Contentapplets de commande , Get-Contentet Set-Content uniquement lorsqu’il est utilisé dans un lecteur de système de fichiers.

Vous pouvez également créer un paramètre qui s’affiche uniquement quand un autre paramètre est utilisé dans la commande de fonction ou lorsqu’un autre paramètre a une certaine valeur.

Les paramètres dynamiques peuvent être utiles, mais les utiliser uniquement si nécessaire, car ils peuvent être difficiles à découvrir pour les utilisateurs. Pour rechercher un paramètre dynamique, l’utilisateur doit se trouver dans le chemin du fournisseur, utiliser le paramètre ArgumentList de l’applet Get-Command de commande ou utiliser le paramètre Path de Get-Help.

Pour créer un paramètre dynamique pour une fonction ou un script, utilisez le DynamicParam mot clé.

La syntaxe est la suivante :

DynamicParam {<statement-list>}

Dans la liste des instructions, utilisez une If instruction pour spécifier les conditions dans lesquelles le paramètre est disponible dans la fonction.

Utilisez l’applet New-Object de commande pour créer un objet System.Management.Automation.RuntimeDefinedParameter pour représenter le paramètre et spécifier son nom.

Vous pouvez utiliser une commande pour créer un New-Object objet System.Management.Automation.ParameterAttribute pour représenter des attributs du paramètre, tels que Obligatoire, Position ou ValueFromPipeline ou son jeu de paramètres.

L’exemple suivant montre un exemple de fonction avec des paramètres standard nommés Nom et Chemin d’accès, ainsi qu’un paramètre dynamique facultatif nommé DP1. Le paramètre DP1 se trouve dans le PSet1 jeu de paramètres et a un type de Int32. Le paramètre DP1 est disponible dans la Get-Sample fonction uniquement lorsque la valeur du paramètre Path commence HKLM:par , indiquant qu’il est utilisé dans le lecteur de HKEY_LOCAL_MACHINE Registre.

function Get-Sample {
  [CmdletBinding()]
  Param([String]$Name, [String]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $attributes = New-Object -Type `
        System.Management.Automation.ParameterAttribute
      $attributes.ParameterSetName = "PSet1"
      $attributes.Mandatory = $false
      $attributeCollection = New-Object `
        -Type System.Collections.ObjectModel.Collection[System.Attribute]
      $attributeCollection.Add($attributes)

      $dynParam1 = New-Object -Type `
        System.Management.Automation.RuntimeDefinedParameter("DP1", [Int32],
          $attributeCollection)

      $paramDictionary = New-Object `
        -Type System.Management.Automation.RuntimeDefinedParameterDictionary
      $paramDictionary.Add("DP1", $dynParam1)
      return $paramDictionary
    }
  }
}

Pour plus d’informations, consultez RuntimeDefinedParameter.

Paramètres de commutateur

Les paramètres de commutateur sont des paramètres sans valeur de paramètre. Ils sont efficaces uniquement lorsqu’ils sont utilisés et n’ont qu’un seul effet.

Par exemple, le paramètre NoProfile de powershell.exe est un paramètre de commutateur.

Pour créer un paramètre de commutateur dans une fonction, spécifiez le Switch type dans la définition de paramètre.

Par exemple :

Param([Switch]<ParameterName>)

Vous pouvez également utiliser une autre méthode :

Param(
    [Parameter(Mandatory=$false)]
    [Switch]
    $<ParameterName>
)

Les paramètres de commutateur sont faciles à utiliser et sont préférés aux paramètres booléens, qui ont une syntaxe plus difficile.

Par exemple, pour utiliser un paramètre de commutateur, l’utilisateur entre le paramètre dans la commande.

-IncludeAll

Pour utiliser un paramètre booléen, l’utilisateur entre le paramètre et une valeur booléenne.

-IncludeAll:$true

Lorsque vous créez des paramètres de commutateur, choisissez attentivement le nom du paramètre. Assurez-vous que le nom du paramètre communique l’effet du paramètre à l’utilisateur. Évitez les termes ambigus, tels que Filtre ou Maximum , ce qui peut impliquer qu’une valeur soit requise.

Attribut ArgumentCompleter

L’attribut ArgumentCompleter vous permet d’ajouter des valeurs d’achèvement de tabulation à un paramètre spécifique. Un attribut ArgumentCompleter doit être défini pour chaque paramètre qui a besoin de la saisie semi-automatique de tabulation. Comme dynamicParameters, les valeurs disponibles sont calculées au moment de l’exécution lorsque l’utilisateur appuie sur Tab après le nom du paramètre.

Pour ajouter un attribut ArgumentCompleter , vous devez définir un bloc de script qui détermine les valeurs. Le bloc de script doit prendre les paramètres suivants dans l’ordre spécifié ci-dessous. Les noms du paramètre n’ont pas d’importance, car les valeurs sont fournies en position.

La syntaxe est la suivante :

Param(
    [Parameter(Mandatory)]
    [ArgumentCompleter({
        param ( $commandName,
                $parameterName,
                $wordToComplete,
                $commandAst,
                $fakeBoundParameters )
        # Perform calculation of tab completed values here.
    })]
)

Bloc de script ArgumentCompleter

Les paramètres de bloc de script sont définis sur les valeurs suivantes :

• $commandName (Position 0) : ce paramètre est défini sur le nom de la commande pour laquelle le bloc de script fournit la saisie semi-automatique de tabulation.
• $parameterName (Position 1) : ce paramètre est défini sur le paramètre dont la valeur nécessite la saisie semi-automatique de tabulation.
• $wordToComplete (Position 2) : ce paramètre est défini sur la valeur fournie par l’utilisateur avant d’appuyer sur Tab. Votre bloc de script doit utiliser cette valeur pour déterminer les valeurs d’achèvement des onglets.
• $commandAst (Position 3) : ce paramètre est défini sur l’arborescence de syntaxe abstraite (AST) pour la ligne d’entrée actuelle. Pour plus d’informations, consultez Classe Ast.
• $fakeBoundParameters (Position 4) : ce paramètre est défini sur un tableau de hachage contenant l’applet $PSBoundParameters de commande, avant que l’utilisateur ait appuyé sur Tab. Pour plus d’informations, consultez about_Automatic_Variables.

Le bloc de script ArgumentCompleter doit désinscrire les valeurs à l’aide du pipeline, par ForEach-Objectexemple, Where-Objectou une autre méthode appropriée. Le renvoi d’un tableau de valeurs entraîne le traitement de PowerShell dans l’ensemble du tableau comme valeur d’achèvement d’un onglet.

L’exemple suivant ajoute la saisie semi-automatique de tabulation au paramètre Value . Si seul le paramètre Value est spécifié, toutes les valeurs possibles ou arguments sont affichés pour La valeur . Lorsque le paramètre Type est spécifié, le paramètre Value affiche uniquement les valeurs possibles pour ce type.

En outre, l’opérateur garantit que si l’utilisateur -like entre la commande suivante et utilise la saisie semi-automatique tabulation , seule Apple est retournée.

Test-ArgumentCompleter -Type Fruits -Value A

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,
        [Parameter(Mandatory=$true)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )

            $possibleValues = @{
                Fruits = @('Apple', 'Orange', 'Banana')
                Vegetables = @('Tomato', 'Squash', 'Corn')
            }
            if ($fakeBoundParameters.ContainsKey('Type'))
            {
                $possibleValues[$fakeBoundParameters.Type] | Where-Object {
                    $_ -like "$wordToComplete*"
                }
            }
            else
            {
                $possibleValues.Values | ForEach-Object {$_}
            }
        } )]
        $Value
      )
}

Voir aussi

about_Automatic_Variables

about_Functions

about_Functions_Advanced

about_Functions_Advanced_Methods

about_Functions_CmdletBindingAttribute

about_Functions_OutputTypeAttribute