Schreiben eines PowerShell-Skriptmoduls

Artikel
06/13/2022

Ein Skriptmodul ist ein beliebiges gültiges PowerShell-Skript, das in einer .psm1 Erweiterung gespeichert ist. Mit dieser Erweiterung kann das PowerShell-Modul Regeln und Modul-Cmdlets in Ihrer Datei verwenden. Die meisten dieser Funktionen helfen Ihnen bei der Installation ihres Codes auf anderen Systemen sowie beim Verwalten von Scoping. Sie können auch eine Modulmanifestdatei verwenden, die komplexere Installationen und Lösungen beschreibt.

Schreiben eines PowerShell-Skriptmoduls

Um ein Skriptmodul zu erstellen, speichern Sie ein gültiges PowerShell-Skript in einer .psm1 Datei. Das Skript und das Verzeichnis, in dem er gespeichert ist, müssen denselben Namen verwenden. Ein Skript mit dem Namen MyPsScript.psm1 wird z. B. in einem Verzeichnis mit dem Namen " MyPsScript.

Das Verzeichnis des Moduls muss sich in einem pfad befinden, der in $env:PSModulePath. Das Verzeichnis des Moduls kann alle Ressourcen enthalten, die zum Ausführen des Skripts erforderlich sind, und eine Modulmanifestdatei, die powerShell beschreibt, wie Ihr Modul funktioniert.

Erstellen eines einfachen PowerShell-Moduls

In den folgenden Schritten wird beschrieben, wie Sie ein PowerShell-Modul erstellen.

Speichern Sie ein PowerShell-Skript mit einer .psm1 Erweiterung. Verwenden Sie denselben Namen für das Skript und das Verzeichnis, in dem das Skript gespeichert wird.

Das Speichern eines Skripts mit der .psm1 Erweiterung bedeutet, dass Sie die Modul-Cmdlets verwenden können, z. B. Import-Module. Die Modul-Cmdlets sind hauptsächlich vorhanden, damit Sie Ihren Code in die Systeme anderer Benutzer importieren und exportieren können. Die alternative Lösung wäre, Ihren Code auf anderen Systemen zu laden und dann dot-source it in den aktiven Speicher zu laden, was keine skalierbare Lösung ist. Weitere Informationen finden Sie unter Grundlegendes zu einem Windows PowerShell Modul. Wenn Benutzer Ihre .psm1 Datei importieren, sind alle Funktionen in Ihrem Skript standardmäßig zugänglich, aber Variablen sind nicht möglich.

Ein Beispiel für Ein PowerShell-Skript mit dem Titel " Show-Calendar, ist am Ende dieses Artikels verfügbar.
```
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
}
```
Um den Benutzerzugriff auf bestimmte Funktionen oder Variablen zu steuern, rufen Sie "Export-ModuleMember " am Ende Des Skripts auf.

Der Beispielcode am unteren Rand des Artikels weist nur eine Funktion auf, die standardmäßig verfügbar gemacht wird. Es wird jedoch empfohlen, explizit aufzurufen, welche Funktionen Sie verfügbar machen möchten, wie im folgenden Code beschrieben:
```
function Show-Calendar {
      }
Export-ModuleMember -Function Show-Calendar
```
Sie können das importierte Element mithilfe eines Modulmanifests einschränken. Weitere Informationen finden Sie im Importieren eines PowerShell-Moduls und zum Schreiben eines PowerShell-Modulmanifests.
Wenn Sie Module haben, die ihr eigenes Modul laden muss, können Sie oben in Ihrem Modul verwenden Import-Module.

Das Import-Module Cmdlet importiert ein gezieltes Modul in ein System und kann zu einem späteren Zeitpunkt in der Prozedur verwendet werden, um Ihr eigenes Modul zu installieren. Der Beispielcode unten in diesem Artikel verwendet keine Importmodule. Aber wenn dies der Vorgang getan hat, werden sie oben in der Datei aufgeführt, wie im folgenden Code dargestellt:
```
Import-Module GenericModule
```
Um Ihr Modul im PowerShell-Hilfesystem zu beschreiben, können Sie entweder Standardhilfekommentare innerhalb der Datei verwenden oder eine zusätzliche Hilfedatei erstellen.

Das Codebeispiel am Ende dieses Artikels enthält die Hilfeinformationen in den Kommentaren. Sie können auch erweiterte XML-Dateien schreiben, die zusätzliche Hilfeinhalte enthalten. Weitere Informationen finden Sie in der Hilfe zum Schreiben von Windows PowerShell Modulen.
Wenn Sie über zusätzliche Module, XML-Dateien oder andere Inhalte verfügen, die Sie mit Ihrem Modul verpacken möchten, können Sie ein Modulmanifest verwenden.

Ein Modulmanifest ist eine Datei, die die Namen anderer Module, Verzeichnislayouts, Versionsnummern, Autordaten und andere Informationen enthält. PowerShell verwendet die Modulmanifestdatei, um Ihre Lösung zu organisieren und bereitzustellen. Weitere Informationen finden Sie unter Schreiben eines PowerShell-Modulmanifests.
Um Ihr Modul zu installieren und auszuführen, speichern Sie das Modul in einem der entsprechenden PowerShell-Pfade, und verwenden Sie Import-Modulees.

Die Pfade, in denen Sie Ihr Modul installieren können, befinden sich in der $env:PSModulePath globalen Variablen. Ein allgemeiner Pfad zum Speichern eines Moduls auf einem System wäre %SystemRoot%/users/<user>/Documents/PowerShell/Modules/<moduleName>beispielsweise . Stellen Sie sicher, dass Sie ein Verzeichnis für Ihr Modul erstellen, das denselben Namen wie das Skriptmodul verwendet, auch wenn es sich nur um eine einzelne .psm1 Datei handelt. Wenn Sie Ihr Modul nicht in einem dieser Pfade gespeichert haben, müssen Sie den Speicherort des Import-Module Moduls im Befehl angeben. Andernfalls konnte PowerShell das Modul nicht finden.

Hinweis

Ab PowerShell 3.0 müssen Sie es nicht explizit importieren, wenn Sie Ihr Modul in einem der PowerShell-Modulpfade platziert haben. Ihr Modul wird automatisch geladen, wenn ein Benutzer Ihre Funktion aufruft. Weitere Informationen zum Modulpfad finden Sie unter Importieren eines PowerShell-Moduls und about_PSModulePath.
Verwenden Sie Remove-Module, um ein Modul aus dem aktiven Dienst in der aktuellen PowerShell-Sitzung zu entfernen.

Hinweis

Remove-Module entfernt ein Modul aus der aktuellen PowerShell-Sitzung, deinstalliert jedoch nicht das Modul oder löscht die Dateien des Moduls.

Show-Calendar Codebeispiel

Im folgenden Beispiel handelt es sich um ein Skriptmodul, das eine einzelne Funktion mit dem Namen " Show-Calendar. Diese Funktion zeigt eine visuelle Darstellung eines Kalenders an. Das Beispiel enthält die PowerShell-Hilfezeichenfolgen für die Synopsis, Beschreibung, Parameterwerte und Code. Wenn das Modul importiert wird, stellt der Export-ModuleMember Befehl sicher, dass die Show-Calendar Funktion als Modulelement exportiert wird.

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

Schreiben eines PowerShell-Skriptmoduls