PowerShell
Fonctions PowerShell

Introduction

Fonction simple sans paramètre

Ceci est un exemple de fonction qui renvoie une chaîne. Dans l'exemple, la fonction est appelée dans une instruction affectant une valeur à une variable. La valeur dans ce cas est la valeur de retour de la fonction.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function déclare que le code suivant est une fonction.

Get-Greeting est le nom de la fonction. Chaque fois que cette fonction doit être utilisée dans le script, la fonction peut être appelée en l'appelant par son nom.

{ ... } est le bloc de script exécuté par la fonction.

Si le code ci-dessus est exécuté dans l'ISE, les résultats seraient les suivants:

Hello World
Hello World

Paramètres de base

Une fonction peut être définie avec des paramètres en utilisant le bloc param:

function Write-Greeting {
    param(
        [Parameter(Mandatory,Position=0)]
        [String]$name,
        [Parameter(Mandatory,Position=1)]
        [Int]$age
    )
    "Hello $name, you are $age years old."
}

Ou en utilisant la syntaxe de fonction simple:

function Write-Greeting ($name, $age) {
    "Hello $name, you are $age years old."
}

Remarque: les paramètres de moulage ne sont requis dans aucun type de définition de paramètre.

La syntaxe de fonction simple (SFS) a des capacités très limitées par rapport au bloc param.
Bien que vous puissiez définir des paramètres à exposer dans la fonction, vous ne pouvez pas spécifier d' attributs de paramètre , utiliser la validation de paramètre , inclure [CmdletBinding()] , avec SFS (et cette liste n'est pas exhaustive).

Les fonctions peuvent être appelées avec des paramètres ordonnés ou nommés.

L'ordre des paramètres sur l'invocation correspond à l'ordre de la déclaration dans l'en-tête de fonction (par défaut) ou peut être spécifié à l'aide de l'attribut de paramètre de Position (comme illustré dans l'exemple de fonction avancée ci-dessus).

$greeting = Write-Greeting "Jim" 82

Alternativement, cette fonction peut être appelée avec des paramètres nommés

$greeting = Write-Greeting -name "Bob" -age 82

Paramètres obligatoires

Les paramètres d'une fonction peuvent être marqués comme obligatoires

function Get-Greeting{
    param
    (
        [Parameter(Mandatory=$true)]$name
    )
    "Hello World $name"
}

Si la fonction est appelée sans valeur, la ligne de commande demandera la valeur:

$greeting = Get-Greeting 

cmdlet Get-Greeting at command pipeline position 1
Supply values for the following parameters:
name: 

Fonction avancée

Ceci est une copie de l'extrait de fonctions avancées de Powershell ISE. Fondamentalement, il s’agit d’un modèle pour un grand nombre de choses que vous pouvez utiliser avec les fonctions avancées de Powershell. Points clés à noter:

• Intégration de get-help - le début de la fonction contient un bloc de commentaires configuré pour être lu par l'applet de commande get-help. Le bloc fonction peut être situé à la fin, si vous le souhaitez.
• cmdletbinding - la fonction se comportera comme une applet de commande
• paramètres
• jeux de paramètres

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
.INPUTS
   Inputs to this cmdlet (if any)
.OUTPUTS
   Output from this cmdlet (if any)
.NOTES
   General notes
.COMPONENT
   The component this cmdlet belongs to
.ROLE
   The role this cmdlet belongs to
.FUNCTIONALITY
   The functionality that best describes this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                  SupportsShouldProcess=$true, 
                  PositionalBinding=$false,
                  HelpUri = 'http://www.microsoft.com/',
                  ConfirmImpact='Medium')]
    [Alias()]
    [OutputType([String])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true, 
                   ValueFromPipeline=$true,
                   ValueFromPipelineByPropertyName=$true, 
                   ValueFromRemainingArguments=$false, 
                   Position=0,
                   ParameterSetName='Parameter Set 1')]
        [ValidateNotNull()]
        [ValidateNotNullOrEmpty()]
        [ValidateCount(0,5)]
        [ValidateSet("sun", "moon", "earth")]
        [Alias("p1")] 
        $Param1,

        # Param2 help description
        [Parameter(ParameterSetName='Parameter Set 1')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateScript({$true})]
        [ValidateRange(0,5)]
        [int]
        $Param2,

        # Param3 help description
        [Parameter(ParameterSetName='Another Parameter Set')]
        [ValidatePattern("[a-z]*")]
        [ValidateLength(0,15)]
        [String]
        $Param3
    )

    Begin
    {
    }
    Process
    {
        if ($pscmdlet.ShouldProcess("Target", "Operation"))
        {
        }
    }
    End
    {
    }
}

Validation des paramètres

Il existe plusieurs façons de valider la saisie de paramètres dans PowerShell.

Au lieu d'écrire du code dans les fonctions ou les scripts pour valider les valeurs des paramètres, ces paramètres lanceront si des valeurs non valides sont transmises.

ValidateSet

Parfois, nous devons limiter les valeurs possibles qu'un paramètre peut accepter. Disons que nous voulons autoriser uniquement le rouge, le vert et le bleu pour le paramètre $Color dans un script ou une fonction.

Nous pouvons utiliser l'attribut de paramètre ValidateSet pour limiter cela. Il présente l'avantage supplémentaire de permettre la complétion de tabulation lors de la définition de cet argument (dans certains environnements).

param(
    [ValidateSet('red','green','blue',IgnoreCase)]
    [string]$Color
)

Vous pouvez également spécifier IgnoreCase pour désactiver la sensibilité à la casse.

ValiderRange

Cette méthode de validation des paramètres prend une valeur min et max Int32 et nécessite que le paramètre soit compris dans cette plage.

param(
    [ValidateRange(0,120)]
    [Int]$Age
)

ValidatePattern

Cette méthode de validation des paramètres accepte les paramètres correspondant au modèle de regex spécifié.

param(
    [ValidatePattern("\w{4-6}\d{2}")]
    [string]$UserName
)

ValidateLength

Cette méthode de validation des paramètres teste la longueur de la chaîne transmise.

param(
    [ValidateLength(0,15)]
    [String]$PhoneNumber
)

ValidateCount

Cette méthode de validation des paramètres teste la quantité d'arguments transmis, par exemple, un tableau de chaînes.

param(
    [ValidateCount(1,5)]
    [String[]]$ComputerName
)

ValidateScript

Enfin, la méthode ValidateScript est extraordinairement flexible, prenant un scriptblock et l’évaluant en utilisant $ _ pour représenter l’argument passé. Il passe ensuite l'argument si le résultat est $ true (y compris toute sortie valide).

Cela peut être utilisé pour tester qu'un fichier existe:

param(
    [ValidateScript({Test-Path $_})]
    [IO.FileInfo]$Path 
)

Pour vérifier qu'un utilisateur existe dans AD:

param(
    [ValidateScript({Get-ADUser $_})]
    [String]$UserName
)

Et à peu près tout ce que vous pouvez écrire (car cela ne se limite pas aux oneliners):

param(
    [ValidateScript({
        $AnHourAgo = (Get-Date).AddHours(-1)
        if ($_ -lt $AnHourAgo.AddMinutes(5) -and $_ -gt $AnHourAgo.AddMinutes(-5)) {
            $true
        } else {
            throw "That's not within five minutes. Try again."
        }
    })]
    [String]$TimeAboutAnHourAgo
)