about_Functions_Advanced_Parameters

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ètres que les utilisateurs envoient avec le paramètre.

Les paramètres que vous ajoutez à votre fonction sont disponibles pour les utilisateurs en plus des paramètres communs 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 forme 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 pendant 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 acceptent 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 '19-06-2018' was not recognized as a valid DateTime."

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 l’entrée du pipeline.
• Il prend un tableau de chaînes comme entrée.

param(
    [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
    [string[]]$ComputerName
)

Paramètres de commutateur

Les paramètres de commutateur sont des paramètres qui ne prennent aucune valeur de paramètre. Au lieu de cela, ils transmettent une valeur booléenne true-or-false par le biais de leur présence ou de leur absence, de sorte que lorsqu’un paramètre switch est présent, il a une valeur true et lorsqu’il n’a pas de valeur false .

Par exemple, le paramètre Recurse d’est Get-ChildItem un paramètre switch.

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

Par exemple, votre fonction peut avoir la possibilité de générer des données en tant que tableau d’octets :

param([switch]$AsByteArray)

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

Par exemple, pour utiliser un paramètre switch, l’utilisateur tape le paramètre dans la commande.

-IncludeAll

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

-IncludeAll $true

Lorsque vous créez des paramètres de commutateur, choisissez soigneusement 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.

Considérations relatives à la conception des paramètres de commutateur

• Les paramètres de commutateur ne doivent pas recevoir de valeurs par défaut. Ils doivent toujours avoir la valeur false par défaut.

• Les paramètres de commutateur sont exclus des paramètres positionnels par défaut. Même si d’autres paramètres sont implicitement positionnels, les paramètres de commutateur ne le sont pas. Vous pouvez remplacer cela dans l’attribut Paramètre, mais cela confond les utilisateurs.

• Les paramètres de commutateur doivent être conçus afin que leur définition déplace une commande de son comportement par défaut vers un mode moins courant ou plus compliqué. Le comportement le plus simple d’une commande doit être le comportement par défaut qui ne nécessite pas l’utilisation des paramètres de commutateur.

• Les paramètres de commutateur ne doivent pas être obligatoires. Le seul cas où il est nécessaire de rendre obligatoire un paramètre de commutateur est quand il est nécessaire de différencier un jeu de paramètres.

• La définition explicite d’un commutateur à partir d’un booléen peut être effectuée avec -MySwitch:$boolValue et en platissement avec $params = @{ MySwitch = $boolValue }.

• Les paramètres de commutateur sont de type SwitchParameter, qui se convertissent implicitement en booléen. La variable de paramètre peut être utilisée directement dans une expression conditionnelle. Par exemple :

  if ($MySwitch) { ... }

  Il n’est pas nécessaire d’écrire if ($MySwitch.IsPresent) { ... }

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 disponibles uniquement lorsque l’applet de commande est utilisée dans le lecteur du 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 la 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.

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

function Get-Sample {
  [CmdletBinding()]
  param([string]$Name, [string]$Path)

  DynamicParam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
          ParameterSetName = "ByRegistryPath"
          Mandatory = $false
      }

      $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
      $attributeCollection.Add($parameterAttribute)

      $dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
        'KeyCount', [Int32], $attributeCollection
      )

      $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
      $paramDictionary.Add('KeyCount', $dynParam1)
      return $paramDictionary
    }
  }
}

Pour plus d’informations, consultez la documentation du type RuntimeDefinedParameter .

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 , pour être reconnu comme une fonction avancée, la fonction doit inclure l’attribut Parameter .

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 a 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 Parameter , 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)]
    $ParameterName
)

Les types d’arguments booléens de l’attribut Paramètre par défaut ont la valeur False lorsqu’ils sont omis à partir de l’attribut Paramètre . Définissez la valeur de $true l’argument sur ou listez 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)]
    [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 Position , le nom du 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 PositionalBinding de l’attribut $FalseCmdletBinding sur . L’argument Position est prioritaire sur la valeur de l’argument de l’attribut PositionalBindingCmdletBinding . Pour plus d’informations, consultez PositionalBinding about_Functions_CmdletBindingAttribute.

La valeur de l’argument Position est spécifiée sous forme d’entier. Une valeur de position de 0 représente la première position dans 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, comme bonne pratique, ne vous fiez pas à 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 la valeur 0. Par conséquent, lorsqu’elle -ComputerName est omise à partir 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 jeu de paramètres auquel appartient un paramètre. Si aucun jeu de paramètres n’est spécifié, le paramètre appartient à tous les jeux de paramètres définis par la fonction. 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.

Remarque

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 jeux de paramètres.

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

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

    [Parameter()]
    [switch]$Summary
)

Vous ne pouvez spécifier qu’une ParameterSetName seule valeur dans chaque argument et un ParameterSetName seul argument dans chaque attribut Parameter . Pour inclure un paramètre 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 jeux 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, ParameterSetName="Computer")]
    [string[]]$ComputerName,

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

    [Parameter(ParameterSetName="Computer")]
    [Parameter(Mandatory, ParameterSetName="User")]
    [switch]$Summary
)

Pour plus d’informations sur les jeux de paramètres, consultez À propos des jeux de paramètres.

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 passé à la fonction à partir du pipeline.

param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [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é d’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 redirigé 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 passée à la fonction via le pipeline.

param(
    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
    [string[]]$ComputerName
)

Considérez une implémentation d’une fonction à l’aide de cet argument :

function Test-ValueFromPipelineByPropertyName{
  param(
      [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
      [string[]]$ComputerName
  )
  Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}

Ensuite, une démonstration de piping d’un objet avec la propriété ComputerName serait :

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName

Saw that ComputerName was 'HelloWorld'

Remarque

Un paramètre typé qui accepte l’entrée de pipeline (by Value) ou (by PropertyName) permet d’utiliser des blocs de script de liaison différée sur le paramètre.

Le bloc de script de liaison différée 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 en tant que type ScriptBlock ou System.Object. Le bloc de script est transmis sans être appelé. Pour plus d’informations sur les blocs de script de liaison différée, consultez about_Script_Blocks.

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(
        [Parameter(Mandatory, Position=0)]
        [string]$Value,

        [Parameter(Position=1, ValueFromRemainingArguments)]
        [string[]]$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

Argument HelpMessage

L’argument HelpMessage spécifie une chaîne qui contient une brève description du paramètre ou de sa valeur. Si vous exécutez la commande sans le paramètre obligatoire, PowerShell vous invite à entrer. Pour afficher le message d’aide, tapez !? à l’invite et appuyez sur Entrée.

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

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

Exemple de sortie :

cmdlet  at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:

S’il n’existe aucune aide basée sur des commentaires pour la fonction, ce message s’affiche dans la Get-Help -Full sortie.

Cet argument n’a aucun effet sur les paramètres facultatifs.

Attribut d’alias

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)]
    [Alias("CN","MachineName")]
    [string[]]$ComputerName
)

Attribut d’informations d’identification

L’attribut Credential est utilisé pour indiquer que le paramètre accepte les informations d’identification. L’exemple suivant montre une déclaration de paramètre qui utilise l’attribut Credential .

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

Attribut expérimental

Utilisez l’attribut Expérimental pour déclarer du code comme expérimental. Pour obtenir une description complète de l’attribut, consultez about_Experimental_Features.

Attribut PSDefaultValue

PSDefaultValue spécifie la valeur par défaut d’un paramètre de commande dans un script. Ces informations sont affichées par l’applet Get-Help de commande. Pour afficher les informations de valeur par défaut, la fonction doit inclure de l’aide basée sur les commentaires. Par exemple :

<#
    .SYNOPSIS
     This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
    param(
        [PSDefaultValue(Help='Current directory')]
        [string]$Name = $PWD.Path
    )

    $Name
}

Permet Get-Help d’afficher les informations de valeur par défaut.

Get-Help TestDefaultValue -Parameter name

-Name <String>

    Required?                    false
    Position?                    1
    Default value                Current directory
    Accept pipeline input?       false
    Accept wildcard characters?  false

Arguments d’attribut PSDefaultValue

L’attribut PSDefaultValue a deux arguments :

• Aide : chaîne qui décrit la valeur par défaut. Ces informations sont affichées par l’applet Get-Help de commande.
• Valeur : valeur par défaut du paramètre.

Les deux arguments sont facultatifs. Si vous ne spécifiez aucun argument, Get-Help la valeur affectée au paramètre s’affiche.

Attribut PSTypeName

Vous ne pouvez pas utiliser de noms de types étendus dans une déclaration de type. L’attribut PSTypeName* vous permet de restreindre le type du paramètre au type étendu.

Dans cet exemple, l’applet Test-Connection de commande retourne un type étendu. Vous pouvez utiliser l’attribut PSTypeName pour restreindre le type du paramètre au type étendu.

function TestType {
    param(
        [PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
        [psobject]$MtuStatus
    )

    $MtuStatus
}

$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu

Attribut System.Obsolete

Utilisez l’attribut System.Obsolete pour marquer les paramètres qui ne sont plus pris en charge. Cela peut être utile lorsque vous souhaitez supprimer un paramètre d’une fonction, mais que vous ne souhaitez pas interrompre les scripts existants qui utilisent la fonction.

Par exemple, considérez une fonction qui a un paramètre de commutateur NoTypeInformation qui contrôle si les informations de type sont incluses dans la sortie. Vous souhaitez rendre ce comportement par défaut et supprimer le paramètre de la fonction. Toutefois, vous ne souhaitez pas interrompre les scripts existants qui utilisent la fonction. Vous pouvez marquer le paramètre comme obsolète et ajouter un message qui explique la modification.

param(
    [System.Obsolete("The NoTypeInformation parameter is obsolete.")]
    [SwitchParameter]$NoTypeInformation
)

Attribut SupportsWild carte s

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

param(
    [Parameter(Mandatory)]
    [SupportsWildcards()]
    [string[]]$Path
)

L’utilisation de cet attribut n’active pas automatiquement la prise en charge des caractères génériques carte. Le développeur d’applets de commande doit implémenter le code pour gérer l’entrée sauvage carte. Les carte 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_Wild carte s.

Attributs d’achèvement des arguments

Attribut ArgumentCompletions

L’attribut ArgumentCompletions vous permet d’ajouter des valeurs d’achèvement de tabulation à un paramètre spécifique. Un attribut ArgumentCompletions doit être défini pour chaque paramètre qui a besoin de la saisie semi-automatique de tabulation. L’attribut ArgumentCompletions est similaire à ValidateSet. Les deux attributs prennent une liste de valeurs à présenter lorsque l’utilisateur appuie sur Tab après le nom du paramètre. Toutefois, contrairement à ValidateSet, les valeurs ne sont pas validées.

Cet attribut a été introduit dans PowerShell 6.0.

Pour plus d’informations, consultez about_Functions_Argument_Completion.

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 plus d’informations, consultez about_Functions_Argument_Completion.

Attributs de validation des paramètres et des variables

Les attributs de validation dirigent PowerShell pour tester les valeurs des 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 comme 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.

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

Les attributs de validation peuvent être appliqués à n’importe quelle variable, pas seulement aux paramètres. Vous pouvez définir la validation pour n’importe quelle variable au sein d’un script.

Remarque

Lorsque vous utilisez des attributs avec une variable typée, il est recommandé de déclarer l’attribut avant le type.

Si vous déclarez un type avec un saut de ligne avant l’attribut et le nom de la variable, le type est traité comme sa propre instruction.

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

Si vous déclarez un attribut de validation après un type, la valeur affectée est validée avant la conversion de type, ce qui peut entraîner des échecs de validation inattendus.

[string] [ValidateLength(1,5)]$TicketIDFromInt        = 43
[string] [ValidateLength(1,5)]$TicketIDFromString     = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43

MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.

Attribut de validation AllowNull

L’attribut AllowNull permet à la valeur d’un paramètre obligatoire d’être $null. L’exemple suivant déclare un paramètre ComputerInfo de table de hachage qui peut avoir une valeur Null.

param(
    [Parameter(Mandatory)]
    [AllowNull()]
    [hashtable]$ComputerInfo
)

Remarque

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)]
    [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)]
    [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 est 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)]
    [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 avoir un à dix caractères.

param(
    [Parameter(Mandatory)]
    [ValidateLength(1,10)]
    [string[]]$ComputerName
)

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

[ValidateLength(1,10)] [string] $text = 'valid'

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)]
    [ValidatePattern("[0-9]{4}")]
    [string[]]$ComputerName
)

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

[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 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 permet 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)]
    [ValidateRange(0,10)]
    [Int]$Attempts
)

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

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

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

[ValidateRange("Positive")] [int]$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)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [DateTime]$EventDate
)

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

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

Remarque

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

Substitution du message d’erreur par défaut

À compter de PowerShell 6, vous pouvez remplacer le message d’erreur par défaut généré lorsqu’une valeur spécifiée n’est pas valide avec l’argument ErrorMessage . Spécifiez une chaîne de format composite. Le 0 composant d’index utilise la valeur d’entrée. Le 1 composant d’index utilise ScriptBlock utilisé pour valider la valeur d’entrée.

Dans l’exemple suivant, la valeur du paramètre EventDate doit être supérieure ou égale à la date et à l’heure actuelles. Si la valeur n’est pas valide, le message d’erreur indique que la date et l’heure spécifiées sont trop anciennes.

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date)},
        ErrorMessage = "{0} isn't a future date. Specify a later date."
    )]
    [DateTime]$EventDate
)

Lorsque la valeur spécifiée est une date passée, le message d’erreur personnalisé est retourné.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.

Vous pouvez appliquer une mise en forme supplémentaire dans la chaîne avec des composants de chaîne de format facultatifs.

Dans l’exemple suivant, la valeur du paramètre EventDate doit être supérieure ou égale à la date et à l’heure actuelles. Si la valeur n’est pas valide, le message d’erreur signale que la date spécifiée est trop ancienne.

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date).Date},
        ErrorMessage = "{0:d} isn't a future date. Specify a later date."
    )]
    [DateTime]$EventDate
)

Lorsque la valeur spécifiée est une date passée, le message d’erreur personnalisé est retourné.

Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.

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 de tabulation. 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 ne peut être basse, moyenne ou élevée que.

param(
    [Parameter(Mandatory)]
    [ValidateSet("Low", "Average", "High")]
    [string[]]$Detail
)

Dans l’exemple suivant, la valeur de la variable $flavor doit être chocolat, 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 au moment de l’exécution :

param(
    [ValidateSet("hello", "world")]
    [string]$Message
)

$Message = "bye"

Cet exemple retourne l’erreur suivante au moment de l’exécution :

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

L’utilisation permet ValidateSet également l’extension de tabulation des valeurs pour ce paramètre. Pour plus d’informations, consultez about_Tab_Expansion.

Valeurs ValidateSet dynamiques à l’aide de classes

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 pour la variable $Sound sont générées via une classe nommée SoundNames qui case activée 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
)

Remarque

La IValidateSetValuesGenerator classe a été introduite dans PowerShell 6.0

Attribut de validation ValidateNotNull

L’attribut ValidateNotNull spécifie que la valeur du paramètre ne peut pas être $null. Lorsque la valeur est $null, PowerShell déclenche une exception.

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 l’attribut ValidateNotNullOrEmpty .

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

param(
    [Parameter()]
    [ValidateNotNull()]
    $ID
)

Attribut de validation ValidateNotNullOrEmpty

L’attribut ValidateNotNullOrEmpty spécifie que la valeur affectée ne peut pas être l’une des valeurs suivantes :

• $null
• une chaîne vide ("")
• un tableau vide (@())

Lorsque la valeur n’est pas valide, PowerShell déclenche une exception.

param(
    [Parameter(Mandatory)]
    [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 aux lecteurs autorisés uniquement. 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 d’accès relatif, le lecteur actuel doit figurer 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 dans le 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 du préfixe de 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 le User lecteur dans les configurations de session Just Enough Administration istration (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

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.

Voir aussi

• about_Automatic_Variables
• about_Functions
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute