PowerShell
Funkcje PowerShell

Wprowadzenie

Prosta funkcja bez parametrów

To jest przykład funkcji, która zwraca ciąg znaków. W tym przykładzie funkcja jest wywoływana w instrukcji przypisującej wartość zmiennej. Wartość w tym przypadku jest wartością zwracaną przez funkcję.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function deklaruje następujący kod jako funkcję.

Get-Greeting to nazwa funkcji. Za każdym razem, gdy funkcja ta musi zostać użyta w skrypcie, można ją wywołać, wywołując ją po nazwie.

{ ... } to blok skryptu wykonywany przez funkcję.

Jeśli powyższy kod zostanie wykonany w ISE, wyniki wyglądałyby mniej więcej tak:

Hello World
Hello World

Podstawowe parametry

Funkcję można zdefiniować za pomocą parametrów za pomocą bloku parametrów:

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

Lub używając prostej składni funkcji:

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

Uwaga: Parametry rzutowania nie są wymagane w żadnej z definicji parametrów.

Prosta składnia funkcji (SFS) ma bardzo ograniczone możliwości w porównaniu do bloku parametrów.
Chociaż można zdefiniować parametry, które mają być ujawnione w ramach funkcji, nie można określić atrybutów parametrów , użyć sprawdzania poprawności parametrów , włączyć [CmdletBinding()] z SFS (i jest to niewyczerpująca lista).

Funkcje można wywoływać z parametrami uporządkowanymi lub nazwanymi.

Kolejność parametrów w wywołaniu jest dopasowana do kolejności deklaracji w nagłówku funkcji (domyślnie) lub można ją określić za pomocą atrybutu parametru Position (jak pokazano w powyższym przykładzie funkcji zaawansowanych).

$greeting = Write-Greeting "Jim" 82

Alternatywnie, tę funkcję można wywołać z nazwanymi parametrami

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

Parametry obowiązkowe

Parametry funkcji można oznaczyć jako obowiązkowe

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

Jeśli funkcja zostanie wywołana bez wartości, wiersz polecenia wyświetli monit o podanie wartości:

$greeting = Get-Greeting 

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

Funkcja zaawansowana

To jest kopia fragmentu funkcji zaawansowanej z Powershell ISE. Zasadniczo jest to szablon wielu rzeczy, których można używać z zaawansowanymi funkcjami programu PowerShell. Najważniejsze kwestie do zapamiętania:

• integracja get-help - początek funkcji zawiera blok komentarza, który jest skonfigurowany do odczytu przez cmdlet get-help. W razie potrzeby blok funkcyjny może znajdować się na końcu.
• cmdletbinding - funkcja będzie zachowywać się jak cmdlet
• parametry
• zestawy parametrów

<#
.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
    {
    }
}

Sprawdzanie poprawności parametrów

Istnieje wiele sposobów sprawdzania poprawności wprowadzania parametrów w PowerShell.

Zamiast pisać kod w funkcjach lub skryptach w celu sprawdzania poprawności wartości parametrów, te parametry ParameterAttributes zostaną wygenerowane, jeśli zostaną przekazane nieprawidłowe wartości.

ValidateSet

Czasami musimy ograniczyć możliwe wartości, które parametr może zaakceptować. Powiedzmy, że chcemy dopuścić tylko czerwony, zielony i niebieski dla parametru $Color w skrypcie lub funkcji.

Możemy użyć atrybutu parametru ValidateSet , aby to ograniczyć. Dodatkową zaletą jest możliwość uzupełniania tabulacji podczas ustawiania tego argumentu (w niektórych środowiskach).

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

Możesz także określić IgnoreCase aby wyłączyć rozróżnianie wielkości liter.

ValidateRange

Ta metoda sprawdzania poprawności parametrów przyjmuje minimalną i maksymalną wartość Int32 i wymaga, aby parametr znajdował się w tym zakresie.

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

ValidatePattern

Ta metoda sprawdzania poprawności parametrów przyjmuje parametry pasujące do określonego wzorca wyrażeń regularnych.

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

ValidateLength

Ta metoda sprawdzania poprawności parametrów sprawdza długość przekazanego ciągu.

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

ValidateCount

Ta metoda sprawdzania poprawności parametrów sprawdza liczbę argumentów przekazanych, na przykład w tablicy ciągów.

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

ValidateScript

Wreszcie metoda ValidateScript jest niezwykle elastyczna, biorąc blok skryptu i oceniając go za pomocą $ _ do reprezentacji przekazanego argumentu. Następnie przekazuje argument, jeśli wynikiem jest $ true (w tym wszelkie dane wyjściowe jako poprawne).

Można to wykorzystać do sprawdzenia, czy plik istnieje:

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

Aby sprawdzić, czy użytkownik istnieje w AD:

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

I prawie wszystko, co możesz napisać (ponieważ nie jest ograniczone do onelinerów):

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
)