PowerShell. Custom features for users

Hello! Quite often in your work you have to use self-written functions and carry pieces of code between different scripts. On habré already there are quite good article about code reuse from Mroff, but it was necessary to go a little further, to document and to describe their functions. As it turned out, the search gave a rather dry information mainly on the General structure of functions and nothing more. Perseverance was rewarded, and I decided to share the obtained information. Welcome to under the cat, where we learn to make in their function information for the descendants and colleagues.

To begin with, let us examine the standard structure functions in PowerShell. It looks like this

the

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

In General, there is nothing complicated as in other languages, asked the name TestPath, in round brackets, comma separated feed variables $Path, performed in the function body the necessary action and, if necessary, returned to the Return() value. And what about when you need to work with multiple variables? Outputs always more than one constant to give mnemonic codes or to describe a variable, let's look at how this is done:

the

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

There is no difficulty, but there are additional options that we make life easier:

Mandatory – Accepts two values: True mandatory and optional False;
HelpMessage – the help for the variable.
ParameterSetName – the variable Name which includes the data parameters;
Position – the Position of the variable in the function call;

Everything seems to be fine now we have a variable that has a description, but in order for that to know him, you must perform the following code:

the

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

PowerShell will answer us in one line in that says: the Path to check the resource.

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

A little complicate the task and prepare the feature which, on request, Get-Help will be displayed in full:

the

Function WriteToLog {
<#
.SYNOPSIS
Output messages to console and log file.
.DESCRIPTION
This function prints the passed string to the log file and the PowerShell console
.EXAMPLE
#WriteToLog -Str "This message will be displayed in the console in red and a file C:\Log\log.txt" -FileName 'C:\Log\log.txt' -Color Red
.EXAMPLE
#WriteToLog -Str "This message will be displayed in the console with the default color (White) to the file C:\Log\log.txt" -FileName 'C:\Log\log.txt'
.PARAMETER Str
The string that you want to display (required)
.PARAMETER FileName
The log file name (mandatory parameter).
.PARAMETER Color
The color of the message text in the PowerShell console (the default text color white (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 Get-Help command 'WriteToLog' -ShowWindow displays the following window.

Let's look at what we wrote this:

<##> – this block is written the parameters for the PowerShell reference.
.SYNOPSIS is a brief description of the function
.DESCRIPTION – block for a complete description of the function
.EXAMPLE – for example, use the function, there may be several
As you can see the text comment applies to the next line after the section title and can be multiline. The end of the review considered the closing tag #> or the next block.

param () block to describe the variables in which we specified the order and the need to pass parameters when calling the function. For the variable $Color we assigned a value for umolchaniu White'.

Now all user functions can be used centrally and you don't have to remember which parameter is responsible for what, and what type of data uses one or the other variable.

Thanks for reading to the end.

Article based on information from habrahabr.ru