Jak napisać moduł skryptu programu PowerShell

  • Artykuł

Moduł skryptu jest dowolnym prawidłowym skryptem programu PowerShell zapisanym .psm1 w rozszerzeniu. To rozszerzenie umożliwia aparatowi programu PowerShell używanie reguł i poleceń cmdlet modułu w pliku. Większość tych funkcji ułatwia instalowanie kodu w innych systemach, a także zarządzanie określaniem zakresu. Można również użyć pliku manifestu modułu, który opisuje bardziej złożone instalacje i rozwiązania.

Pisanie modułu skryptu programu PowerShell

Aby utworzyć moduł skryptu, zapisz prawidłowy skrypt programu PowerShell w .psm1 pliku. Skrypt i katalog, w którym są przechowywane, muszą używać tej samej nazwy. Na przykład skrypt o nazwie MyPsScript.psm1 jest przechowywany w katalogu o nazwie MyPsScript.

Katalog modułu musi znajdować się w ścieżce określonej w $env:PSModulePathpliku . Katalog modułu może zawierać wszystkie zasoby potrzebne do uruchomienia skryptu oraz plik manifestu modułu opisujący działanie modułu w programie PowerShell.

Tworzenie podstawowego modułu programu PowerShell

W poniższych krokach opisano sposób tworzenia modułu programu PowerShell.

  1. Zapisz skrypt programu PowerShell z .psm1 rozszerzeniem. Użyj tej samej nazwy skryptu i katalogu, w którym jest zapisywany skrypt.

    Zapisanie skryptu .psm1 z rozszerzeniem oznacza, że można użyć poleceń cmdlet modułu, takich jak Import-Module. Polecenia cmdlet modułu istnieją przede wszystkim, aby można było importować i eksportować kod do systemów innych użytkowników. Alternatywnym rozwiązaniem byłoby załadowanie kodu w innych systemach, a następnie kropkowanie go do aktywnej pamięci, co nie jest skalowalnym rozwiązaniem. Aby uzyskać więcej informacji, zobacz Understanding a Windows PowerShell Module (Omówienie modułu Windows PowerShell). Domyślnie podczas importowania .psm1 pliku przez użytkowników wszystkie funkcje skryptu są dostępne, ale zmienne nie są.

    Przykładowy skrypt programu PowerShell zatytułowany Show-Calendarjest dostępny na końcu tego artykułu.

    function Show-Calendar {
param(
    [DateTime] $start = [DateTime]::Today,
    [DateTime] $end = $start,
    $firstDayOfWeek,
    [int[]] $highlightDay,
    [string[]] $highlightDate = [DateTime]::Today.ToString('yyyy-MM-dd')
    )

    #actual code for the function goes here see the end of the topic for the complete code sample
}

  2. Aby kontrolować dostęp użytkownika do niektórych funkcji lub zmiennych, wywołaj polecenie Export-ModuleMember na końcu skryptu.

    Przykładowy kod w dolnej części artykułu zawiera tylko jedną funkcję, która domyślnie byłaby uwidoczniona. Zaleca się jednak jawne wywołanie funkcji, które chcesz uwidocznić, zgodnie z opisem w poniższym kodzie:

    function Show-Calendar {
      }
Export-ModuleMember -Function Show-Calendar

    Możesz ograniczyć importowane elementy przy użyciu manifestu modułu. Aby uzyskać więcej informacji, zobacz Importowanie modułu programu PowerShell i Jak napisać manifest modułu programu PowerShell.

  3. Jeśli masz moduły, które wymagają załadowania własnego modułu, możesz użyć polecenia Import-Module, w górnej części modułu.

    Polecenie Import-Module cmdlet importuje docelowy moduł do systemu i można go użyć w późniejszym momencie procedury w celu zainstalowania własnego modułu. Przykładowy kod w dolnej części tego artykułu nie używa żadnych modułów importu. Jeśli tak się stanie, zostaną one wyświetlone w górnej części pliku, jak pokazano w poniższym kodzie:

    Import-Module GenericModule

  4. Aby opisać moduł w systemie Pomocy programu PowerShell, możesz użyć standardowych komentarzy pomocy wewnątrz pliku lub utworzyć dodatkowy plik Pomocy.

    Przykładowy kod w dolnej części tego artykułu zawiera informacje pomocy w komentarzach. Możesz również napisać rozwinięte pliki XML zawierające dodatkową zawartość pomocy. Aby uzyskać więcej informacji, zobacz Pisanie pomocy dotyczącej modułów Windows PowerShell.

  5. Jeśli masz dodatkowe moduły, pliki XML lub inną zawartość, którą chcesz spakować przy użyciu modułu, możesz użyć manifestu modułu.

    Manifest modułu to plik zawierający nazwy innych modułów, układy katalogów, numery wersji, dane autora i inne informacje. Program PowerShell używa pliku manifestu modułu do organizowania i wdrażania rozwiązania. Aby uzyskać więcej informacji, zobacz Jak napisać manifest modułu programu PowerShell.

  6. Aby zainstalować i uruchomić moduł, zapisz moduł w jednej z odpowiednich ścieżek programu PowerShell i użyj polecenia Import-Module.

    Ścieżki, w których można zainstalować moduł, znajdują się w zmiennej globalnej $env:PSModulePath . Na przykład typową ścieżką do zapisania modułu w systemie jest %SystemRoot%/users/<user>/Documents/PowerShell/Modules/<moduleName>. Pamiętaj, aby utworzyć katalog dla modułu, który używa tej samej nazwy co moduł skryptu, nawet jeśli jest to tylko jeden .psm1 plik. Jeśli moduł nie został zapisany w jednej z tych ścieżek, musisz określić lokalizację modułu w poleceniu Import-Module . W przeciwnym razie program PowerShell nie będzie mógł odnaleźć modułu.

    Uwaga

    Począwszy od programu PowerShell 3.0, jeśli moduł został umieszczony w jednej ze ścieżek modułu programu PowerShell, nie musisz jawnie go importować. Moduł jest ładowany automatycznie po wywołaniu funkcji przez użytkownika. Aby uzyskać więcej informacji na temat ścieżki modułu, zobacz Importowanie modułu programu PowerShell i about_PSModulePath.

  7. Aby usunąć moduł z aktywnej usługi w bieżącej sesji programu PowerShell, użyj polecenia Remove-Module.

    Uwaga

    Remove-Module Usuwa moduł z bieżącej sesji programu PowerShell, ale nie odinstalowuje modułu ani nie usuwa plików modułu.

przykład kodu Show-Calendar

Poniższy przykład to moduł skryptu zawierający pojedynczą funkcję o nazwie Show-Calendar. Ta funkcja wyświetla wizualną reprezentację kalendarza. Przykład zawiera ciągi Pomocy programu PowerShell dla składni, opisu, wartości parametrów i kodu. Po zaimportowaniu modułu Export-ModuleMember polecenie gwarantuje, że Show-Calendar funkcja zostanie wyeksportowana jako element członkowski modułu.

<#
 .Synopsis
  Displays a visual representation of a calendar.

 .Description
  Displays a visual representation of a calendar. This function supports multiple months
  and lets you highlight specific date ranges or days.

 .Parameter Start
  The first month to display.

 .Parameter End
  The last month to display.

 .Parameter FirstDayOfWeek
  The day of the month on which the week begins.

 .Parameter HighlightDay
  Specific days (numbered) to highlight. Used for date ranges like (25..31).
  Date ranges are specified by the Windows PowerShell range syntax. These dates are
  enclosed in square brackets.

 .Parameter HighlightDate
  Specific days (named) to highlight. These dates are surrounded by asterisks.

 .Example
   # Show a default display of this month.
   Show-Calendar

 .Example
   # Display a date range.
   Show-Calendar -Start "March, 2010" -End "May, 2010"

 .Example
   # Highlight a range of days.
   Show-Calendar -HighlightDay (1..10 + 22) -HighlightDate "2008-12-25"
#>
function Show-Calendar {
param(
    [DateTime] $start = [DateTime]::Today,
    [DateTime] $end = $start,
    $firstDayOfWeek,
    [int[]] $highlightDay,
    [string[]] $highlightDate = [DateTime]::Today.ToString('yyyy-MM-dd')
    )

## Determine the first day of the start and end months.
$start = New-Object DateTime $start.Year,$start.Month,1
$end = New-Object DateTime $end.Year,$end.Month,1

## Convert the highlighted dates into real dates.
[DateTime[]] $highlightDate = [DateTime[]] $highlightDate

## Retrieve the DateTimeFormat information so that the
## calendar can be manipulated.
$dateTimeFormat  = (Get-Culture).DateTimeFormat
if($firstDayOfWeek)
{
    $dateTimeFormat.FirstDayOfWeek = $firstDayOfWeek
}

$currentDay = $start

## Process the requested months.
while($start -le $end)
{
    ## Return to an earlier point in the function if the first day of the month
    ## is in the middle of the week.
    while($currentDay.DayOfWeek -ne $dateTimeFormat.FirstDayOfWeek)
    {
        $currentDay = $currentDay.AddDays(-1)
    }

    ## Prepare to store information about this date range.
    $currentWeek = New-Object PsObject
    $dayNames = @()
    $weeks = @()

    ## Continue processing dates until the function reaches the end of the month.
    ## The function continues until the week is completed with
    ## days from the next month.
    while(($currentDay -lt $start.AddMonths(1)) -or
        ($currentDay.DayOfWeek -ne $dateTimeFormat.FirstDayOfWeek))
    {
        ## Determine the day names to use to label the columns.
        $dayName = "{0:ddd}" -f $currentDay
        if($dayNames -notcontains $dayName)
        {
            $dayNames += $dayName
        }

        ## Pad the day number for display, highlighting if necessary.
        $displayDay = " {0,2} " -f $currentDay.Day

        ## Determine whether to highlight a specific date.
        if($highlightDate)
        {
            $compareDate = New-Object DateTime $currentDay.Year,
                $currentDay.Month,$currentDay.Day
            if($highlightDate -contains $compareDate)
            {
                $displayDay = "*" + ("{0,2}" -f $currentDay.Day) + "*"
            }
        }

        ## Otherwise, highlight as part of a date range.
        if($highlightDay -and ($highlightDay[0] -eq $currentDay.Day))
        {
            $displayDay = "[" + ("{0,2}" -f $currentDay.Day) + "]"
            $null,$highlightDay = $highlightDay
        }

        ## Add the day of the week and the day of the month as note properties.
        $currentWeek | Add-Member NoteProperty $dayName $displayDay

        ## Move to the next day of the month.
        $currentDay = $currentDay.AddDays(1)

        ## If the function reaches the next week, store the current week
        ## in the week list and continue.
        if($currentDay.DayOfWeek -eq $dateTimeFormat.FirstDayOfWeek)
        {
            $weeks += $currentWeek
            $currentWeek = New-Object PsObject
        }
    }

    ## Format the weeks as a table.
    $calendar = $weeks | Format-Table $dayNames -AutoSize | Out-String

    ## Add a centered header.
    $width = ($calendar.Split("`n") | Measure-Object -Maximum Length).Maximum
    $header = "{0:MMMM yyyy}" -f $start
    $padding = " " * (($width - $header.Length) / 2)
    $displayCalendar = " `n" + $padding + $header + "`n " + $calendar
    $displayCalendar.TrimEnd()

    ## Move to the next month.
    $start = $start.AddMonths(1)

}
}
Export-ModuleMember -Function Show-Calendar