PowerShell. User functions for users

Hello! Quite often in my work I have to use independently written functions and drag pieces of code between different scripts. On Habré there is already a pretty good article about the Reuse of code from Mroff , but there was a need to go a little further, document and somehow describe their functions. As it turned out, the search yielded fairly dry information mainly on the general structure of the function and nothing more. Perseverance was rewarded, and I decided to share the information received. Welcome to the cat, where we will learn to add information to our functions for posterity and colleagues.

Let's first analyze the standard structure of the function in PowerShell. It looks like this.

Function TestPath ([String]$Path) { Return(Test-Path $Path) } 

In general, nothing complicated, as in other languages, was given the name TestPath, the $ Path variables were fed in comma separated in parentheses, the necessary actions were performed in the function body and, if necessary, the Return () value was returned. And what about when you need to work with several variables? There are always more outputs than one - to constantly give mnemonic codes or make a description of a variable, let's consider how this is done:

 Function TestPath { PARAM ( [PARAMETER(Mandatory=$True,Position=0,HelpMessage = "   ",ParameterSetName='Path')]$Path ) Return(Test-Path $Path) } 

There is no difficulty, but there are additional parameters that simplify our life:
')

Mandatory - Accepts two True values ​​are required and False is optional;
HelpMessage - variable help;
ParameterSetName - The name of the variable to which these parameters belong;
Position - The position of the variable when the function is called;

It seems that all is well now we have a variable that has a description, but in order to learn it you must execute the following code:

 ((Get-Command TestPath).ParameterSets.Parameters | Where-Object Name -eq Path).HelpMessage 

PowerShell will answer us in one line which will say: Path to the resource being checked.

To some extent it is convenient, but if we are used to working with PowerShell, then we know the command Get-Help, which displays detailed information about the function with examples of its use and variables that need to be passed.

Let's slightly complicate the task and prepare the function, the information about which, upon request, Get-Help will be displayed in full:

 Function WriteToLog { <# .SYNOPSIS        . .DESCRIPTION            PowerShell .EXAMPLE #WriteToLog -Str "           C:\Log\log.txt" -FileName 'C:\Log\log.txt' -Color Red .EXAMPLE #WriteToLog -Str "         (White)    C:\Log\log.txt" -FileName 'C:\Log\log.txt' .PARAMETER Str ,    ( ) .PARAMETER FileName    ( ) .PARAMETER Color      PowerShell (     (White)) #> param ( [PARAMETER(Mandatory=$True,Position=0)][String]$Str, [PARAMETER(Mandatory=$True,Position=1)][String]$FileName, [PARAMETER(Mandatory=$False,Position=2)][String]$Color='White' ) Write-Host $Str -ForegroundColor $Color If ((Test-Path $FileName) -eq $True) { Add-Content -Path $FileName -Value $Str } Else { Set-Content -Path $FileName -Value $Str } } 

After executing this code, the command Get-Help 'WriteToLog' -ShowWindow will display the following window.


Let's look at what we wrote this:

<##> - In this block, the parameters for the PowerShell help are written.
.SYNOPSIS - block for a brief description of the function
.DESCRIPTION - block for full function description
.EXAMPLE - block for an example of using a function, maybe several
.PARAMETR Parameter name - a block for describing a variable, for each variable its own block.

As you can see, a text comment begins on the next line after the key section title and can be multi-line. The end of the comment is considered the closing tag #> or the next block.

param () is a block for describing variables, in which we indicate their order and the need to pass parameters when calling a function. For the $ Color variable, we assigned the default value of 'White'.

Now all user-defined functions can be used centrally and you don’t have to remember which parameter is responsible for what, as well as which data type this or that variable uses.

Thank you for reading to the end.