PowerShell po polsku

W pierwszej części opisałem pracę z typami wyliczeniowymi, które w PowerShellu istnieją out-of-the-box. Drugą część będzie poświęcona temu jak i po co moglibyśmy je tworzyć. Zacznę naturalnie od celu.

Po co mi to?

Czasem w PowerShellu chcielibyśmy zagwarantować, że pewne parametry będą przyjmować ściśle określone wartości. Np. typ komputera w naszej firmie to zawsze albo laptop, albo desktop, albo serwer. Narzędzia powinny korzystać tylko z tych wartości, a gdy ktoś spróbuje użyć innej (notebook, stacja robocza…) generować błąd. Można to osiągnąć na dwa sposoby: walidacja parametrów lub właśnie użycie typu wyliczeniowego. Prosta funkcja, która pozwala skorzystać z obu opcji:

function New-Asset {            
[CmdletBinding(DefaultParameterSetName = 'Enum')]            
param (            
    [Parameter(Mandatory = $true,            
        ParameterSetName = 'NoEnum',            
        HelpMessage = 'Typ komputera.')]            
    [ValidateSet('Laptop','Desktop','Server')]            
    [string]$Typ,            
    [Parameter(Mandatory = $true,            
        ParameterSetName = 'Enum',            
        HelpMessage = 'Rodzaj komputera.')]            
    [rodzaj]$Rodzaj,            
    [Parameter(Mandatory = $true,            
        HelpMessage = 'Nazwa komputera.')]            
    [string]$Nazwa            
)            
            
    switch ($psCmdlet.ParameterSetName) {            
        NoEnum {            
            $Script = {            
                [string]$Nazwa = $args[0]            
                [string]$Typ = $args[1]            
                Export-ModuleMember -Variable *            
            }            
            $Arguments = $Nazwa, $Typ            
        }            
        Enum {            
            $Script = {            
                [string]$Nazwa = $args[0]            
                [rodzaj]$Rodzaj = $args[1]            
                Export-ModuleMember -Variable *            
            }            
            $Arguments = $Nazwa, $Rodzaj            
        }            
    }            
            
    $Options = @{            
        ScriptBlock = $Script            
        AsCustomObject = $true            
        ArgumentList = $Arguments            
    }            
            
    New-Module @Options            
}            

Zarówno parametr ‘Typ’ jak i parametr ‘Rodzaj’ mogą mieć tylko założone przez nas wartości. Niestety, ValidateSet nie dba o wielkość liter… Skutek?

Dużo większą kontrolę uzyskamy więc dzięki typom wyliczeniowym. Co jeszcze? ValidateSet byłby w tym wypadku zastosowany jedynie przy tworzeniu obiektu, jeśli skorzystamy z New-Module do tworzenia obiektu mamy możliwość utrwalania typów właściwości. W przypadku typu [string] daje nam to niewiele, ale skorzystanie z typu wyliczeniowego gwarantuje nam, że nawet modyfikując obiekt będziemy zmuszeni użyć właściwych wartości:

I ostatnia rzecz: tworząc cały moduł w oparciu o założenie, że nie pojawi nam się inny typ komputera, prościej jest zrealizować to przy pomocy typów wyliczeniowych. Zmiana “zestawu” też będzie banalna (modyfikujemy definicję klasy, zamiast modyfikować ValidateSet we wszystkich funkcjach). Wydaje mi się, że tych zalet warto czasem sięgnąć po typ wyliczeniowe. Przejdźmy więc do odpowiedzi na pytanie: jak.

Zaprogramujmy sobie typ.

W wersji pierwszej PowerShella nie było prostej metody na przeprowadzenie takiej operacji. W wersji drugiej mamy dostęp do polecenia Add-Type, które pozwala na kompilowanie kodu ‘w locie’. Dodanie klasy [rodzaj], którą użyłem w funkcji wymagało ode mnie wpisanie jednej, niezbyt skomplikowanej linii kodu:

Przy okazji: widać to, o czym pisałem w części pierwszej. Nowostworzona klasa pozwala używać tych samych metod, co jej ‘matka’ System.Enum. Oczywiście nic nie stoi na przeszkodzie, by klasę tą umieścić w jakiejś przestrzeni nazw, lub stworzyć własną przestrzeń, gdzie przechowywalibyśmy wszystkie stworzone przez nas typy wyliczeniowe. Tyle wersja druga PowerShella. W wersji trzeciej możemy oczekiwać jeszcze lepszego wsparcia dla tego typu zabiegów. Cytując Bruce’a Payette’a, członka zespołu tworzącego PowerShell i autora najlepszej, moim zdaniem, książki PowerShellowi poświęconej:

A common question is why the PowerShell team didn’t add some sort of native mechanism to create .NET types in v2. It’s because a) we were incredibly busy and b) we didn’t want to screw up. With the Dynamic Language Runtime (DLR) on the verge of becoming part of .NET (and it is as of .NET 4.0) the way to create types was in flux. Because we had to ship well before .NET 4 was out, we decided to wait one more release and let the dust settle. We’re keeping our fingers crossed that we’ll finally get native type definition capabilities into v3 (actually fingers, toes, eyes, and any other anatomical protuberances that come to mind).

Pozostaje trzymać również trzymać kciuki…? Na szczęście możemy zrobić nieco więcej: w PowerShellu możemy dość łatwo dodać słowo kluczowe ‘enum’, dzięki któremu sami będziemy mogli tworzyć typy wyliczeniowe w sposób analogiczny do tego, w jaki tworzy się je w C#:

function New-Enum {            
param (            
    [Parameter(Mandatory = $true,             
        HelpMessage = 'Name of your enumerator.')]            
    [string]$EnumName,            
    [Parameter(Mandatory = $true,             
        HelpMessage = 'Definition of this type.')]            
    [scriptblock]$Definition,            
    [Parameter()]            
    [ValidateNotNullOrEmpty()]            
    [string]$Namespace            
)            
            
    Set-StrictMode -Version Latest            
            
    $TypeDefinition =  @"
using System;

$(if ($namespace) { "namespace $Namespace {" } )
    public enum $EnumName 
    {
        $($Definition.ToString())
    }
$(if ($namespace) { "}" } )
"@            
            
    Write-Verbose "Type will be defined using: `n$TypeDefinition"            
    try {            
        Add-Type -TypeDefinition $TypeDefinition -ErrorAction Stop            
    } catch {            
        Write-Error "Error creating type. Use -Verbose for more"            
        Write-Verbose $_            
    }                
}            
            
$MyAlias = @{            
    Name = 'enum'             
    Value = 'New-Enum'            
    Description = 'Keyword to create new System.Enum types'            
}            
New-Alias  @MyAlias            

Od tej pory korzystając z aliasu ‘enum’ i parameterów na odpowiednich pozycjach możemy napisać wprost w konsoli:

Myślę, że mając typy wyliczeniowe na wyciągnięcie ręki trudno się będzie powstrzymać przed ich użyciem. Korzyści może nie są wielkie, ale z pewnością w wielu sytuacjach oszczędzą nam bólu głowy. Choćby dlatego, że pomagają wyeliminować w zasadzie najgorsze w debugowaniu błędy: literóweczki… 😉

Napisane w PowerShell
Tagi: enum, Typy wyliczeniowe

Początkowo planowałem wszystko opisać w jednym artykule, ale niestety rozrosło się to znacznie. Więc w pierwszej części skupię się na wykorzystywaniu typów wyliczeniowych w PowerShellu, a tworzenie ich opiszę następnym razem.

Z czym to się je?

Nie jestem programistą, jednak praca z PowerShellem siłą rzeczy wymusza rozumienie choć podstaw platformy .NET. Typy wyliczeniowe są jej częścią i zdecydowanie ułatwiają pracę w PowerShellu. Prosty przykład: czy łatwiej (zwłaszcza na początku) zapamiętać, że aby wyłączyć raportowanie błędów należy użyć wartości dla ErrorAction ‘SilentlyContinue’, czy wolelibyście zawsze używać wartości numerycznej 0? Dziś chcę poświęcić im nieco czasu: gdzie można je znaleźć, jak sprawdzić jaką mają wartość w części pierwszej. W drugiej napiszę jak zdefiniować własne typy wyliczeniowe i czemu moglibyśmy chcieć to zrobić.

Gdzie je znajdziemy?

Typy wyliczeniowe wykorzystujemy w (niemal?) wszystkich komendach (choćby z tego powodu, że parametry *Action wykorzystują typ wyliczeniowy System.Management.Automation.ActionPreference). Aby uzyskać pełną listę najlepiej skorzystać z samego PowerShella. Wykorzystamy do tego Get-Command i kolekcję Parameters, która jest jedną z właściwości obiektów przez tą komendą generowanych. Widać tam typ parametru, a każdy typ posiada właściwość logiczną IsEnum. Kod poniżej:

Get-Command -CommandType cmdlet -Name * |             
    ForEach-Object { $_.Parameters.GetEnumerator() } |             
    Sort-Object -Unique Key |             
    Select-Object -ExpandProperty Value |             
    Where-Object { $_.ParameterType.IsEnum } |             
    Select-Object Name, ParameterType, @{            
        Name = 'CommandName'            
        Expression = {              
            @(Get-Help -Name * -Parameter $_.Name)[0].Name             
        }            
    }            

Na moim komputerze znalazłem 31 takich parametrów. Większość korzysta z unikalnej klasy, więc by z nich skorzystać należałoby poznać możliwe wartości.

A imię jego…

Sposobów na znalezienie wartości ‘opisowych’ jest kilka. Zacznijmy od najprostszej. Wykorzystamy do tego fakt, że informacja o błędzie dotyczącym parametru będącego typem wyliczeniowym jest jednocześnie doskonałym źródłem informacji o tym, jakie wartości są prawidłowe:Oczywiście bez try/catch to też zadziała, użyłem go tylko po to, by ładnie ‘złamać’ wyświetlaną informację w konsoli. 😉 Istotne części dodatkowo podkolorowałem. A istotne są wartości prawidłowe (których, dzięki takim trikom, nie musimy się uczyć na pamięć), oraz typ używany (który przyda nam się za chwilkę).

Druga opcja to sprawdzić typ wykorzystywany (np. zagłębiając się w rezultat Get-Command) i skorzystać ze statycznych metod typu wyliczeniowego: Wykorzystałem klasę „matkę” (System.Enum), ale równie dobrze mogłem użyć każdej innej, wszystkie dziedziczą metody statyczne Get*. Metody te pozwalają też uzyskać informację, jaką nazwę przypisano danej wartości numerycznePrzeglądając metody statyczne klasy [enum] trudno nie zauważyć metody GetValues. Na logikę spodziewać by się można, że dzięki temu zobaczymy wartości liczbowe. I tak też będzie, mimo że na pierwszy rzut oka wynik metod GetNames i GetValues będzie identyczny.

Tam sięgaj gdzie wzrok nie sięga.

Przyczyną tego, że rezultat GetValues może być na pierwszy rzut oka mało ciekawy jest fakt, że PowerShell domyślnie wykorzystuje metodę ToString() typów wyliczeniowych, a ta zwraca ich nazwę. Skoro nie widać różnicy… to trzeba skorzystać z czegoś, co różnicę uwypukli. Na pierwszy ogień – Get-Member:Metody, jak widać, nie są zbyt ciekawe. A jedyna właściwość to value__. Nie trudno odgadnąć, że to tam właśnie jest zapisana wartość numeryczna typu wyliczeniowego. Wiedząc jaka ta wartość jest, możemy użyć jej zamiast nazwy. Pracując z PowerShellem interaktywnie oszczędzimy sobie sporo czasu:

# Uzyjemy:            
ls nonexistent -EA 0            
# Zamiast:            
ls nonexistent -ErrorAction SilentlyContinue                

Przy pomocy prostej funkcji możemy uzyskać pełnię informacji o wartościach parametru komendy, gdy jest on typu wyliczeniowego: nazwę i odpowiadającą jej wartością numeryczną:

function Get-ParameterValues {            
param (            
    [ValidateScript( { Get-Command $_ })]            
    [string]$Command,            
    [string]$Parameter            
)            
            
$CommandInfo = Get-Command $Command            
if ($type = $CommandInfo.Parameters.$Parameter.ParameterType) {            
    if ($type.IsEnum) {            
        [enum]::GetValues($type) | ForEach-Object {            
            New-Object PSObject -Property @{            
                Name = $_.ToString()            
                Value = $_.value__            
            }            
        }            
    }            
}            
}

W skryptach, dla przejrzystości, najlepiej oczywiście używać znaczących i zrozumiałych nazw. W czasie pracy interaktywnej – można skorzystać z wartości numerycznych. Ewentualnie, korzystając z modułu PowerTab, dopełniać wartości takich parameterów przy pomocy [TAB].

Napisane w PowerShell
Tagi: enum, Typy wyliczeniowe