En programmation, lorsque du code est plusieurs fois r\u00e9utilis\u00e9, il est pr\u00e9f\u00e9rable pour gagner du temps d’\u00e9crire une fonction, qui permet d’effectuer une t\u00e2che pr\u00e9cise avec de potentiels arguments, PowerShell n’\u00e9chappe pas \u00e0 la r\u00e8gle et propose la cr\u00e9ation de ce genre d’objet.<\/p>\n\n\n\n
Globalement une fonction est cr\u00e9\u00e9 avec le mot r\u00e9serv\u00e9 Accessoirement pour demander un param\u00e8tre, une autre syntaxe existe:<\/p>\n\n\n\n Les param\u00e8tres sont appel\u00e9s par un Ces fonctions sont vraiment plus int\u00e9ressantes puisqu\u2019elles imitent le comportement d\u2019une cmdlet, les param\u00e8tres ont des attributs, et la fonction poss\u00e8de les parties Commen\u00e7ons par les attributs de param\u00e8tre, ces derniers sont pr\u00e9sents entre crochet sous forme d\u2019acc\u00e9l\u00e9rateur de type:<\/p>\n\n\n\n La d\u00e9claration d\u2019un param\u00e8tre exigeant des Il en existe quelques autres que vous pouvez retrouver ici<\/a>. PowerShell prend aussi en charge l\u2019utilisation de param\u00e8tre dynamique, ils permettent la cr\u00e9ation ou non de param\u00e8tre lors de l\u2019appel des param\u00e8tres d\u2019une fonction avanc\u00e9e (ou une cmdlet). Plus globalement ces derniers sont cr\u00e9\u00e9s dans une section nomm\u00e9e C\u2019est plut\u00f4t complexe mais extr\u00eamement pratique. La valeur des param\u00e8tres ne sera pas retourn\u00e9e directement, mais sera ajout\u00e9 dans Il est possible, comme en python par exemple, d\u2019ajouter une aide int\u00e9gr\u00e9e \u00e0 nos fonctions. Elle se d\u00e9finit au d\u00e9but de la fonction, entre commentaires multi lignes. Chaque segment permet d\u2019ajouter une entr\u00e9e \u00e0 l\u2019aide, on d\u00e9compte:<\/p>\n\n\n\n Une fois un segment appel\u00e9, sa valeur doit \u00eatre ajout\u00e9e sur la ligne de dessous, et durera jusqu’\u00e0 la fin du commentaire. Exemple d’aide int\u00e9gr\u00e9e:<\/p>\n\n\n\n Un petit projet de fin de dossier est disponible sur le blog, n\u2019h\u00e9sitez pas \u00e0 aller le consulter, il met en pratique les diff\u00e9rentes notions abord\u00e9es durant ces derniers postes.<\/p>\n","protected":false},"excerpt":{"rendered":" En programmation, lorsque du code est plusieurs fois r\u00e9utilis\u00e9, il est pr\u00e9f\u00e9rable pour gagner du temps d’\u00e9crire une fonction, qui permet d’effectuer une t\u00e2che pr\u00e9cise avec de potentiels arguments, PowerShell n’\u00e9chappe pas \u00e0 la r\u00e8gle et propose la cr\u00e9ation de ce genre d’objet. Fonction simple Globalement une fonction est cr\u00e9\u00e9 avec le mot r\u00e9serv\u00e9 function […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[2],"tags":[],"_links":{"self":[{"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/posts\/84"}],"collection":[{"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/comments?post=84"}],"version-history":[{"count":5,"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/posts\/84\/revisions"}],"predecessor-version":[{"id":254,"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/posts\/84\/revisions\/254"}],"wp:attachment":[{"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/media?parent=84"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/categories?post=84"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/theredwindows.net\/index.php\/wp-json\/wp\/v2\/tags?post=84"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}function<\/code><\/code> il en est suivi du nom de la fonction et enfin entre accolade (et oui encore) les instructions \u00e0 ex\u00e9cuter. Une fonction est appel\u00e9e par son nom et ses diff\u00e9rents param\u00e8tres. Ces derniers sont d\u00e9finis gr\u00e2ce \u00e0 param()<\/code><\/code>; pour cr\u00e9er un param\u00e8tre il faut simplement indiquer son nom comme une variable (si un type plus qu\u2019un autre est attendu, comme pour les variables, il faut simplement ajouter entre crochet avant le type), s’ils sont plusieurs les s\u00e9parer par une virgule (si une valeur par d\u00e9faut est exig\u00e9e si le param\u00e8tre n\u2019est pas appel\u00e9, comme pour une variable apr\u00e8s un =<\/code> ajouter la valeur par d\u00e9faut), les param\u00e8tres peuvent poss\u00e9der des attributs (ces derniers seront d\u00e9taill\u00e9s dans la partie Fonction avanc\u00e9e) qui permettent de mieux g\u00e9n\u00e9rer les entr\u00e9es. La variable $PSBoundParameters<\/code><\/code> est instanci\u00e9e \u00e0 chaque fois qu\u2019une fonction est appel\u00e9e. C\u2019est une variable locale de type Dictionnary<\/code>. Les cl\u00e9s sont le nom des param\u00e8tres et la valeur associ\u00e9e la valeur donn\u00e9e au param\u00e8tre. Une fonction peut avoir une valeur de retour, pour cela le mot return<\/code><\/code> suivi ou non d\u2019une variable (ou une valeur directement) peut \u00eatre utilis\u00e9. Par exemple:<\/p>\n\n\n\nfunction Power {\n\n\tparam (\n\n\t\t[Int32]$Number,\n\t\t[Int32]$Exponent = 2\n\t)\n\n\t$result [System.Math]::Pow($Number, $Exponent)\n\treturn $result\n}<\/pre>\n\n\n\nfunction foo ($param) {}<\/pre>\n\n\n\n-<\/code> pr\u00e9c\u00e9dant leur nom (ou leur alias) suivi d\u2019une \u00e9ventuelle valeur, ou alors en pla\u00e7ant la valeur sur l\u2019index de position du param\u00e8tre. Les variables d\u00e9finies \u00e0 l\u2019int\u00e9rieur d\u2019une fonction ne sont pas globales mais locales.<\/p>\n\n\n\nFonction avanc\u00e9e<\/h3>\n\n\n\n
BEGIN<\/code>, PROCESS<\/code> et END<\/code> (non obligatoire) exactement comme en C#. De ce fait, des arguments “par d\u00e9faut” lui sont attribu\u00e9s: -Verbose<\/code>, -Debug<\/code> etc. Ces param\u00e8tres permettent de modifier le comportement d\u2019une fonction avanc\u00e9e tel une cmdlet, pour plus de renseignement vous pouvez regarder cet article de Microsoft<\/a>. Une fonction avanc\u00e9e reprend la syntaxe d\u2019une fonction simple, avec quelques modifications:<\/p>\n\n\n\n[CmdletBinding()]<\/code><\/code> qui peut prendre diff\u00e9rents arguments (la documentation de Microsoft sur ce sujet<\/a>), il en existe d\u2019autre tel [OutputType()]<\/code><\/code> qui prend en param\u00e8tre le type de sortie de la fonction (il est attendu le type litt\u00e9ral, comme celui pr\u00e9c\u00e9dant une variable typ\u00e9; il peut y en avoir plusieurs chaque type \u00e9tant s\u00e9par\u00e9 par une virgule).<\/li>BEGIN<\/code>, PROCESS<\/code> et END<\/code>.<\/li><\/ul>\n\n\n\n[Alias('NAME1', 'NAME2')]<\/code><\/code> un attribut qui permet d\u2019ajouter un alias non pas sur la cmdlet mais sur le nom du param\u00e8tre.<\/li>[ValidateCount(MIN,MAX)]<\/code><\/code> un attribut qui permet de n\u2019accepter que des listes dont la taille est comprise entre MIN<\/code> et MAX<\/code>.<\/li>[ValidateLenght(MIN,MAX)]<\/code><\/code> un attribut qui permet de n\u2019accepter qu\u2019une cha\u00eene de caract\u00e8re dont la longueur est comprise entre MIN<\/code> et MAX<\/code>.<\/li>[ValidatePattern('REGEX')]<\/code><\/code> un attribut qui permet de n\u2019accepter qu\u2019une cha\u00eene de caract\u00e8re qui valide une comparaison “regex” qui est d\u00e9finit par REGEX<\/code>.<\/li>[ValidateRange(MIN, MAX)]<\/code><\/code> un attribut qui permet de n\u2019accepter qu\u2019un entier situer entre MIN<\/code> et MAX<\/code>.<\/li>[ValidateScript(SCRIPT)]<\/code><\/code> un attribut qui permet de n\u2019accepter qu\u2019un param\u00e8tre apr\u00e8s sa v\u00e9rification par un scriptblock SCRIPT<\/code>, la valeur pass\u00e9 dans le param\u00e8tre est plac\u00e9 dans la variable $_<\/code>.<\/li>[ValidateSet('VALUE1', 'VALUE2')]<\/code><\/code> un attribut qui permet de n\u2019accepter que si la valeur du param\u00e8tre est comprise dans le tableau @('VALUE1', 'VALUE2')<\/code><\/code>, chaque valeur est s\u00e9par\u00e9 de la prochaine par une virgule.<\/li>[ValidateNotNull()]<\/code><\/code> un attribut qui permet de ne pas accepter une valeur fourni si elle est \u00e9gal \u00e0 $null<\/code>.<\/li>[ValidateDrive('DRIVE1', 'DRIVE2')]<\/code><\/code> un attribut qui permet de ne pas accepter un chemin fourni si ce dernier n\u2019est pas dans le tableau de PSDrive<\/code> @('DRIVE1', 'DRIVE2')<\/code><\/code>.<\/li>[ValidateNotNullOrEmpty()]<\/code><\/code> un attribut qui permet de ne pas accepter les param\u00e8tres dont la valeur est $null<\/code><\/code> ou si la cha\u00eene de caract\u00e8re est vide.<\/li>[AllowNull()]<\/code><\/code> permet d\u2019accepter un param\u00e8tre dont la valeur est $null<\/code><\/code>.<\/li>[AllowEmptyString()]<\/code><\/code> permet d\u2019accepter une cha\u00eene de caract\u00e8re vide.<\/li>[AllowEmptyCollection()]<\/code><\/code> permet d\u2019accepter des tableaux, liste par exemple dont la longueur est 0.<\/li>[switch]<\/code> dont la valeur est un PSObject<\/code> \u00e0 une seul entr\u00e9e .IsPresent<\/code> qui est un bool\u00e9en indiquant si l\u2019argument a \u00e9t\u00e9 appel\u00e9 ou non.<\/li>[Parameter()]<\/code><\/code> qui peut prendre en arguments plusieurs choses:Mandatory<\/code> un bool\u00e9en qui d\u00e9termine si le param\u00e8tre est n\u00e9cessaire.<\/li>Position<\/code> un entier qui d\u00e9finit la position par d\u00e9faut du param\u00e8tre.<\/li>ValueFromPipeline <\/code>un bool\u00e9en qui d\u00e9finit si la variable peut prendre ses valeurs depuis un “pipeline”.<\/li>ValueFromPipelineByPropertyName <\/code>est un bool\u00e9en qui d\u00e9termine si l\u2019objet pass\u00e9 par la pipeline doit avoir le m\u00eame nom de propri\u00e9t\u00e9 que le nom du param\u00e8tre.<\/li>ParameterSetName <\/code>une cha\u00eene de caract\u00e8res qui d\u00e9termine un groupe de param\u00e8tre auquel ce dernier appartient.<\/li>helpMessage<\/code>, est une cha\u00eene de caract\u00e8res qui appara\u00eet lors de l\u2019usage de Get-Help CMDLET -Parameter ParameterName<\/code>.<\/li><\/ul><\/li><\/ul>\n\n\n\nPSCredential<\/code> est un peu particuli\u00e8re, il est en effet pr\u00e9f\u00e9rable de la faire ainsi (sans compter l\u2019attribut Parameter()<\/code><\/code>):<\/p>\n\n\n\n[Parameter(Mandatory=$false)]\n[System.Management.Automation.CredentialAttribute()]\n[System.Management.Automation.PSCredential]\n$Credential = [System.Management.Automation.PSCredential]::Empty<\/pre>\n\n\n\n
DynamicParameter<\/code><\/code> suivie d\u2019accolades dans lesquelles il y a les instructions. Si un param\u00e8tre est appel\u00e9 il ne sera pas nul, donc la v\u00e9rification de la pr\u00e9sence peut se faire avec if<\/code><\/code>. La cr\u00e9ation d\u2019un param\u00e8tre reprend les \u00e9tapes suivantes:<\/p>\n\n\n\n$paramDictionnary = New-Object System.Management.Automation.RuntimeDefinedParameterDictionary\n$attributeCollection = New-Object System.Collections.ObjectModel.Collection[System.Attribute]\n\n$attribute = New-Object System.Management.Automation.ParameterAttribute\n$attribute.Mandatory = $true\n$attribute.Position = 0\n$attribute.ValueFromPipeline = $true\n$attributeCollection.Add($attribute)\n\n$attribute = New-Object System.Management.Automation.ValidateNotNullOrEmptyAttribute\n$attributeCollection.Add($attribute)\n\n$attribute = New-Object System.Management.Automation.ValidateCountAttribute(1,2)\n$attributeCollection.Add($attribute)\n\n...\n\n$Name = 'DynamicParameter'\n\n$dynParam = New-Object System.Management.Automation.RuntimeDefinedParameter($name, [String[]]; $attributeCollection)\n$paramDictionnary.Add($Name, $dynParam)\n\n$paramDictionnary<\/pre>\n\n\n\n
$PSBoundParameters<\/code><\/code>.<\/p>\n\n\n\nAide int\u00e9gr\u00e9e<\/h3>\n\n\n\n
.SYNOPSIS<\/code>.<\/li>.DESCRIPTION<\/code>.<\/li>.PARAMETER<\/code>.<\/li>.EXAMPLE<\/code>.<\/li>.NOTES<\/code>.<\/li>.LINK<\/code>.<\/li>.OUTPUTS<\/code>.<\/li>.INPUTS<\/code>.<\/li><\/ul>\n\n\n\n.PARAMETER<\/code> prend un argument \u00e0 sa droite le nom du param\u00e8tre. Certains segments sont d\u00e9finis lorsque certaines options sont ajout\u00e9es: helpMessage<\/code> de l\u2019attribut Parameter()<\/code><\/code> permet de d\u00e9finir .PARAMETER<\/code> et l\u2019attribut [OutputType()]<\/code><\/code> ajoute .OUTPUTS<\/code> \u00e0 l\u2019aide. Il existe d\u2019autres mani\u00e8res de d\u00e9finir l\u2019aide d\u2019une fonction, Laurent Dardenne (Microsoft PowerShell MVP, fran\u00e7ais qui plus ai) en propose une ici<\/a>. Pour acc\u00e9der \u00e0 l\u2019aide d\u2019une fonction il faut utiliser la cmdlet Get-Help<\/code><\/code> qui propose nombre de param\u00e8tres:<\/p>\n\n\n\n-Name<\/code> pr\u00e9cise le nom de la cmdlet.<\/li>-Full<\/code> affiche toutes l\u2019aide.<\/li>-Parameter<\/code> suivit d\u2019un param\u00e8tre, affiche l\u2019aide d\u2019un param\u00e8tre particulier.<\/li>-Examples<\/code> affiche les exemples de la fonction.<\/li><\/ul>\n\n\n\n<#\n\t.SYNOPSIS\n\t\tcette partie r\u00e9sume bri\u00e8vement la fonction\n\n\t.DESCRIPTION\n\t\tcette partie explique plus en d\u00e9tail ce que fait la fonction\n\n\t.PARAMETER Parameter\n\t\tcette partie explique le r\u00f4le, les valeurs par d\u00e9faut du param\u00e8tre Parameter\n\t\n\t.EXAMPLE\n\t\tInvoke-MyFunction -Parameter \"hello\"\n\n\t.NOTES\n\t\tcette partie exprime diff\u00e9rentes remarques \u00e0 l\u2019\u00e9gard de la fonction\n\n\t.LINK\n\t\tcette partie nous donne des \u00e9ventuelles liens pour mieux comprendre le fonctionnement, ou les r\u00e9f\u00e9rences \u00e0 cette fonction\n\n\t.OUTPUTS\n\t\tcette partie informe des types de retour de la fonction\n\n\t.INPUTS\n\t\tcette partie informe des types d\u2019entr\u00e9e de la fonction\n#><\/pre>\n\n\n\n