Powershell-Modul entwickeln und vertreiben

Trotz der Tatsache, dass es im Internet unzählige verschiedene Anleitungen und Anleitungen zum Erstellen eines eigenen Powershell-Moduls gibt, vermittelt nicht einmal die offizielle Dokumentation ein umfassendes Verständnis dafür, wie ein Modul mit Flexibilität/Skalierbarkeit für eine einfache Ergänzung richtig erstellt wird von Funktionen.

Ich habe mehrere Stunden damit verbracht, einige Artikel zu lernen und zu lesen, und bin wie immer zu meinem eigenen Ansatz gekommen, der mir ausreichend bequem und elastisch erscheint und den ich jetzt mit Ihnen allen teilen möchte.

Überlegen Sie sich den Namen

Es ist wichtig :-). Später werden Sie mit diesem Namen ziemlich lange leben, denken Sie also über den Namen nach, der für Sie jeden Tag angenehm zu sehen sein wird =).

In meinem Fall habe ich mich für den Ansatz entschieden: <customer_code\customer_name>.<project_code>.Powershell.

Für die Zwecke dieses Handbuchs verwenden wir den Modulnamen My.OwnModule.Powershell.

Erstellen Sie ein Präfix für Funktionsnamen

Wenn Sie mehrere Module gleichzeitig entwickeln/unterstützen/verwenden (z. B. für verschiedene Unternehmen oder Teams), verwenden Sie manchmal dieselbe Funktion in allen Modulen (einfach weil das praktisch ist). Und wenn Sie anfangen, diese Module zu verwenden, werden Sie beim Importieren auf einige Namenskonflikte stoßen. Deshalb gibt es einen Grund, warum Sie ein eindeutiges Präfix für Funktionsnamen verwenden sollten.

In unserem Beispiel verwende ich das MyOwn-Präfix. Beispielsweise wird der Standardname des bekannten Cmdlets New-Item in New-MyOwnItem umgewandelt.

Installieren Sie die Voraussetzungen

Außer Powershell selbst benötigen Sie das Befehlszeilentool Nuget. Es ist erforderlich, das Modul in das Nuget-Paket zu packen und es an andere Computer oder Benutzer zu verteilen.

Erstellen Sie eine Ordnerstruktur

Mit Ausnahme des Stammordners, der denselben Namen wie das Modul erhält, benötigen Sie die ursprüngliche Ordnerstruktur.

D:.
└───My.OwnModule.Powershell
    ├───images
    ├───private
    ├───public
    │   └───common
    └───_bin

• images. Für ein Paket wird es eine Symboldatei geben, die theoretisch in einem Repository wie Artifactory zu sehen wäre.
• private. Es handelt sich um einen Ordner für Skripte, der nur für Servicezwecke verwendet werden sollte. Beispielsweise zum Lesen einer Datei von der Festplatte mit Fehlerbehandlung.
• public. Hier speichern Sie Skriptdateien mit Funktionen, auf die Modulbenutzer direkt zugreifen können. Hier können Sie Ihre Skripte der Einfachheit halber in Unterordnern gruppieren.
  • public -> common. Dies ist ein Beispiel für einen Unterordner. Das Verzeichnis dient ausschließlich der Strukturierung und Gruppierung von Dateien. Alles im public Ordner wird rekursiv gelesen.
• _bin. Das Nuget-Tool stellt kompilierte Pakete hier ab.

Erstellen und füllen Sie die erforderlichen Dateien

Sicherlich müssen Sie Dateien erstellen, die genau genommen eine Reihe von Powershell-Skripten in ein Powershell-Modul konvertieren.

D:.
│   LICENSE
│   PSScriptAnalyzerSettings.psd1
│   README.md
│
└───My.OwnModule.Powershell
    │   local-build.ps1
    │   local-install.ps1
    │   My.OwnModule.Powershell.nuspec
    │   My.OwnModule.Powershell.psd1
    │   My.OwnModule.Powershell.psm1
    │
    ├───images
    │       icon.png
    │
    ├───private
    │       _stub.ps1
    │
    ├───public
    │   └───common
    │           Read-MyOwnJsonFile.ps1
    │
    └───_bin

Wir interessieren uns für Dateien, die sich im Modulstammordner befinden, privat und öffentlich. Andere – sind die Servicedateien des Git-Repositorys. Nachfolgend finden Sie den Inhalt jeder Datei mit Kommentaren.

Schreiben von Servicedateien des Powershell-Moduls

My.OwnModule.Powershell.nuspec

Dies ist erforderlich, damit das Nuget-Tool das Paket generieren kann.

<?xml version="1.0" encoding="utf-8"?>
<package >
  <metadata>
    <id>My.OwnModule.Powershell</id>
    <version>0.0.2</version>
    <authors>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein.</authors>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <icon>images\icon.png</icon>
    <description>
      There is no any description available at this time. Sorry for that.
    </description>
    <releaseNotes>Initial release.</releaseNotes>
    <tags>PSEdition_Core PSEdition_Desktop Linux Mac PSModule PSIncludes_Cmdlet</tags>
  </metadata>
</package>

My.OwnModule.Powershell.psd1

Diese Datei ist ein Modulmanifest, eine Beschreibung des Moduls in den Begriffen von Powershell selbst. Es gibt verschiedene Details zum Autor, zu den vom Modul unterstützten Funktionen usw.

Beachten Sie die Zeile 11 und den FunctionsToExport-Parameter. Dabei handelt es sich um Funktionen, die den Nutzern Ihres Moduls zur Verfügung stehen. Denken Sie deshalb beim Hinzufügen neuer Funktionen zum Modul daran, diese hier hinzuzufügen.

@{
    RootModule           = "My.OwnModule.Powershell.psm1"
    ModuleVersion        = "0.0.2"
    CompatiblePSEditions = "Desktop", "Core"
    GUID                 = "8f37ba7b-be77-4b6e-8ceb-d30c0c328674"
    Author               = "Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein."
    PowerShellVersion    = "7.0"

    ScriptsToProcess     = @();
       
    FunctionsToExport    = @(
        "Read-MyOwnJsonFile"
    );
    CmdletsToExport      = "*"
    VariablesToExport    = "*"
    AliasesToExport      = "*"
}

My.OwnModule.Powershell.psm1

Bei dieser Datei handelt es sich um ein Skript, das ausgeführt wird, wenn Sie Import-Module ausführen (oder das System ausführt). Es ist eine Hauptdatei im Modul. Im Allgemeinen stellt diese Datei das Modul selbst dar (das heißt, Sie können das Powershell-Modul ohne die psd1-Datei erstellen, aber das wird natürlich nicht empfohlen).

#Requires -Version 7.0


$public  = @( Get-ChildItem -Path $PSScriptRoot\public\*.ps1 -Recurse; );
$private = @( Get-ChildItem -Path $PSScriptRoot\private\*.ps1 -Recurse; );


# Dot source the files
foreach ($import in @($public + $private))
{
    try
    {
        Write-Verbose "Importing '$($import.FullName)'.";
        . $import.FullName;
    }
    catch
    {
        Write-Error -Message "Failed to import function $($import.fullname): $_";
    }
}


Export-ModuleMember -Function $public.Basename;

_stub.ps1

Ich habe diesen Datei-Stub eingefügt, damit das Skript aus der psm1-Datei den Ordner normal und ohne mögliche Probleme lesen kann. Aber im Allgemeinen ist es völlig leer.

Read-MyOwnJsonFile.ps1

Dies ist eine Datei des Cmdlets, das wir mit unserem Modul bereitstellen. Beachten Sie den Namen – Read-MyOwnJsonFile. Ich meine hier, dass ich Präfixe für die Funktionsnamen verwende.

local-build.ps1

Diese Datei ist nicht direkt Teil des Powershell-Moduls. Es ist ein Skript, mit dem ich das Modul in ein Nuget-Paket kompiliere, damit ich es später irgendwo im Repository ablege. Außerdem erhöht dieses Skript die Modulversion um 1.

# Config
$moduleName = "My.OwnModule.Powershell";


# Clear old packages
# Get-ChildItem .\$moduleName\_bin | Remove-Item -Force -Verbose;


#region Get current package version and increment Patch
$version = Select-String -Path .\$moduleName\$moduleName.nuspec -Pattern "<version>(\d)\.(\d)\.(\d{1,})</version>";
[int]$majorVersion = $version | Select-Object @{name="version"; expression={$_.Matches.Groups[1].Value}} | select-object -ExpandProperty version;
[int]$minorVersion = $version | Select-Object @{name="version"; expression={$_.Matches.Groups[2].Value}} | select-object -ExpandProperty version;
[int]$patchVersion = $version | Select-Object @{name="version"; expression={$_.Matches.Groups[3].Value}} | select-object -ExpandProperty version;
$patchVersion++;
$nuspecVersionString = "<version>$majorVersion.$minorVersion.$patchVersion</version>";
$psd1VersionString = "ModuleVersion        = `"$majorVersion.$minorVersion.$patchVersion`"";
#endregion /Get current package version and increment Patch


#region Update package version
$a = Get-Content -Path ".\$moduleName\$moduleName.nuspec" | %{$_ -replace "<version>(\d)\.(\d)\.(\d{1,})<\/version>", $nuspecVersionString };
$a | Out-File ".\$moduleName\$moduleName.nuspec" -Verbose;

$a = Get-Content -Path ".\$moduleName\$moduleName.psd1" | %{$_ -replace "ModuleVersion        = `"\d\.\d.\d{1,}`"", $psd1VersionString };
$a | Out-File ".\$moduleName\$moduleName.psd1" -Verbose;
#endregion /Update package version


nuget pack ".\$moduleName\$moduleName.nuspec" -OutputDirectory .\$moduleName\_bin -Properties NoWarn=NU5111,NU5110,NU5100
$package = Get-ChildItem .\$moduleName\_bin\*.nupkg | Sort-Object -Property CreationTime | Select-Object -Last 1;

$package

local-install.ps1

Dementsprechend dient dieses benutzerdefinierte Skript der Installation des Moduls.

$moduleName = "My.OwnModule.Powershell";
$repoName = "My.OwnModule.Powershell.Repository";
$repoPath = "D:\Private\My.OwnModule.Powershell\My.OwnModule.Powershell\_bin\";

Register-PSRepository -Name $repoName -SourceLocation $repoPath -InstallationPolicy Trusted -ScriptSourceLocation $repoPath;

Install-Module -Name $moduleName -Repository $repoName -Verbose;

Get-Module $moduleName -ListAvailable;

Verpacken des Powershell-Moduls

Versuchen wir, local-build.ps1 auszuführen und zu sehen, was passiert.

Großartig! Das Nuget-Paket ist fertig und wird in den Ordner My.OwnModule.Powershell\_bin\My.OwnModule.Powershell.0.0.3.nupkg verschoben. Versuchen wir nun, das Modul aus dem Paket zu installieren und zu verwenden.

Installation des Powershell-Moduls aus dem Nuget-Paket

Wunderbar, das Modul ist betriebsbereit!

Verbose sagt, dass Version 0.0.5 bereits installiert wurde und so weiter. Das liegt daran, dass ich versucht habe, die Version manuell zu verringern, anstatt sie zu erhöhen. Achten Sie nicht darauf.

GitHub-Repository

Sie finden alle diese Dateien in meinem GitHub-Repository: https://github.com/vicioussn/My.OwnModule.Powershell.