Module

Die Seite Module bietet Informationen über die im System installierten Module.

Module anzeigen

Sie können die für PowerShell Universal zugänglichen Module anzeigen und durchsuchen, indem Sie die Seite Platform \ Modules aufrufen. Die Suche liefert ein Wildcard-Ergebnis der Module, die in jeder der innerhalb von PowerShell Universal definierten Umgebungen gefunden wurden.

Module aus der Gallery installieren

Module können aus der PowerShell Gallery installiert werden. Um nach einem Modul zu suchen, können Sie das Dropdown-Menü neben dem Suchfeld von Local auf PowerShell Gallery umstellen. Durchgeführte Suchen werden dann gegen die Gallery und nicht lokal ausgeführt.

Sobald ein Modul gefunden wurde, können Sie auf die Schaltfläche Install klicken, um es lokal zu speichern. Auf diese Weise installierte Module werden im Repository-Verzeichnis unter Modules installiert.

Paketquellen

PowerShell Universal ist mit dem Modul PackageManagement v3 integriert und erkennt registrierte Paketquellen automatisch. Beispielsweise können Sie eine Paketquelle mit dem folgenden Befehl registrieren.

Register-PSResourceRepository -Name MyNuGet -Uri https://www.nuget.org/api/v2

Sobald die Quelle registriert wurde, wird sie im Dropdown-Menü auf der Modules-Seite angezeigt.

Module erstellen

Sie können Module auch direkt in PowerShell Universal erstellen. Diese Module werden im Repository-Verzeichnis unter Modules erstellt.

Diese Module sind in allen Umgebungen verfügbar.

Um ein neues Modul zu erstellen, navigieren Sie zu Platform \ Modules und klicken Sie auf Create New Module. Legen Sie den Modulnamen und die Version fest.

Nach der Erstellung wird das Modul unter Universal Modules aufgeführt, mit der Möglichkeit, Eigenschaften und Inhalt zu bearbeiten sowie das Modul zu löschen.

Beim Bearbeiten des Moduls wird ein Code-Editor geöffnet, in dem Sie Funktionen, Variablen und Aliase zum Exportieren definieren können.

Module mit Universal-Ressourcen

Ein Beispielmodul finden Sie hier.

Installieren

Module können PowerShell Universal-Ressourcen wie Skripte, APIs und Apps enthalten. Wenn Sie diese Module Ihrer Umgebung hinzufügen, werden diese Ressourcen automatisch Ihrer PowerShell Universal-Instanz hinzugefügt. Diese Ressourcen sind innerhalb der Umgebung schreibgeschützt. Um sie zu entfernen, müssen Sie das Modul entfernen.

Klicken Sie in der Admin-Konsole auf Platform \ Modules und wählen Sie dann PowerShell Universal Modules.

PowerShell Universal-Module

Klicken Sie auf die Download-Schaltfläche auf der linken Seite des Moduls, um es zu installieren. Nach der Installation werden schreibgeschützte Ressourcen zu Ihrer Umgebung hinzugefügt.

Windows-Systeminformations-App

Sie können Module auch direkt im Repository-Ordner von PowerShell Universal speichern.

Save-Module Universal.Apps.WindowsSystemInformation -Path $Env:ProgramData\UniversalAutomation\Repository\Modules

Erstellen

Nachfolgend ein Beispiel für den Aufbau eines Universal-Moduls. Wenn das Modul den Ordner .universal enthält, werden Ressourcen automatisch daraus geladen.

.universal 
    scripts.ps1
PSUModule.psd1
PSUModule.psm1

Ressourcen können keine Pfade verwenden und müssen den Modul- und Befehlsnamen verwenden, um Ressourcen mit ihren jeweiligen Skripten zu verknüpfen.

Beispielsweise müsste die obige Datei scripts.ps1 wie folgt geschrieben werden.

New-PSUScript -Module 'PSUModule' -Command 'Start-MyScript'

Innerhalb von PSUModule.psm1 müssten Sie die Funktion Start-MyScript definieren. Dies ist die Funktion, die beim Ausführen des Skripts aufgerufen wird.

function Start-MyScript {

}

Veröffentlichen

Wenn Sie Module erstellen, die PowerShell Universal erweitern, können Sie das Tag PowerShellUniversal in Ihr Modulmanifest aufnehmen, damit sie auf der PowerShell Universal Modules-Seite und in der PSU-Admin-Konsole aufgeführt werden.

Veröffentlichen Sie Module in der PowerShell Gallery, um sie mit anderen zu teilen.

Root-Modul

Sie können ein Root-Modul als PowerShell Universal-Konfiguration definieren. Dies ermöglicht reproduzierbare Konfigurationen auf Basis veröffentlichter Module. Ein Root-Modul wird in den Anwendungseinstellungen für den PowerShell Universal-Server definiert. Beim Start von PowerShell Universal wird dieses Modul samt Abhängigkeiten automatisch geladen. Das Root-Modul muss im PSModulePath oder im Modules-Ordner des Repository gefunden werden.

Beispiel

Nachfolgend ein Beispiel für die Verwendung eines Root-Moduls und von Abhängigkeiten zur Definition einer PowerShell Universal-Konfiguration. Von Modulen bereitgestellte Ressourcen sind innerhalb der Plattform schreibgeschützt. Durch die Verwendung von Modulen können Sie sicherstellen, dass bestimmte Versionen von Ressourcen paketiert und auf Ihren PowerShell Universal-Instanzen bereitgestellt werden.

Das Root-Modul kann sich an beliebiger Stelle innerhalb des registrierten PSModulePath für Ihren Server oder Ihr Dienstkonto befinden. Es kann sich auch im Modul-Ordner Ihres Repository befinden. Das folgende Beispiel verwendet relative Pfade.

ARD.Core

Das Modul ARD.Core definiert einige Funktionen und eine Umgebung, die von anderen Modulen verwendet wird. Hier ist ein Beispiel für eine grundlegende Umgebungsdefinition.

Modules\ARD.Core\1.0.0\.universal\environments.ps1

New-PSUEnvironment -Name 'ARD.Core' -Path pwsh.exe -Type PowerShell7

Die Funktionen werden in der PSM1-Datei des Moduls definiert.

Modules\ARD.Core\1.0.0\ARD.Core.psm1

function Get-ARDCore {
    @{
        Name = "ARD.Core"
        Description = "This is a test function result"
    }
}

Das Modulmanifest exportiert die Funktion und stellt einige grundlegende Metadaten bereit.

Modules\ARD.Core\1.0.0\ARD.Core.psd1

@{
    RootModule = "ARD.Core.psm1"
    Description = "ARD.Core is the base module for other modules"
    Version = "1.0.0"
    FunctionsToExport = @("Get-ARDCore")
}

ARD.Endpoints

Das Modul ARD.Endpoints ist ähnlich aufgebaut wie das Modul ARD.Core, stellt jedoch einen Endpunkt anstelle einer Umgebung bereit. Dieser Beispielendpunkt ruft die Funktion Get-ARDResponse auf, wenn die URL ard.endpoint aufgerufen wird. Beachten Sie, dass der Endpunkt den vom obigen Modul bereitgestellten ARD.Core-Endpunkt verwendet.

Modules\ARD.Endpoints\1.0.0\.universal\endpoints.ps1

New-PSUEndpoint -Url /ard.endpoint -Module 'ARD.Endpoints' -Command "Get-ARDResponse" -Environment 'ARD.Core'

Die Datei ARD.Endpoints.psm1 definiert die zu exportierende Funktion, die wir auch für den Endpunkt verwenden können. Der Endpunkt verwendet die Funktion aus ARD.Core, um eine Antwort zurückzugeben. Dies funktioniert, weil es sich dabei alles um gewöhnliche PowerShell-Module handelt.

Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psm1

function Get-ARDResponse {
    Get-ARDCore
}

Die Datei ARD.Endpoints.psd1 exportiert die Funktion und nimmt außerdem eine Abhängigkeit von ARD.Core auf, um sicherzustellen, dass dieses Modul zuerst geladen wird, da der Endpunkt darauf angewiesen ist, dass sowohl die Funktion als auch die Umgebung vorhanden sind.

Modules\ARD.Endpoints\1.0.0\ARD.Endpoints.psd1

@{
    RootModule = "ARD.Endpoints.psm1"
    Description = "Sample endpoints"
    Version = "1.0.0"
    RequiredModules = @("ARD.Core")
    FunctionsToExport = @("Get-ARDResponse")
}

ARD.Root

Das Root-Modul wird von PowerShell Universal zuerst geladen. Es nimmt eine Abhängigkeit sowohl vom Core- als auch vom Endpoints-Modul auf, definiert selbst jedoch keine Funktionalität. PowerShell Universal bestimmt die richtige Ladereihenfolge und lädt die Ressourcen dann beim Start.

@{
    Description = "A PowerShell Universal configuration"
    Version = "1.0.0"
    RequiredModules = @("ARD.Core", "ARD.Endpoints")
}

In den Anwendungseinstellungen können Sie das Root-Modul und die Version auswählen.

appsettings.json

{
    "Data": {
        "Module": "ARD.Root",
        "ModuleVersion": "1.0.0"
    }
}

Sie können dies auch über Umgebungsvariablen konfigurieren. Eine Änderung entweder der Datei oder der Umgebungsvariablen erfordert einen Neustart von PowerShell Universal.

$ENV:Data__Module = "ARD.Root"
$ENV:Data__ModuleVersion = "1.0.0"

Module manuell installieren

PowerShell Universal fügt das Verzeichnis Modules des Repository für alle Umgebungen zum $ENV:PSModulePath hinzu. Wenn Sie Module zu diesem Verzeichnis hinzufügen, stellen Sie sicher, dass das Modul für jeden mit PowerShell Universal laufenden PowerShell-Prozess verfügbar ist.

Modulinformationen

Dieser Abschnitt enthält Informationen über bestimmte Module und deren Verwendung innerhalb von PowerShell Universal.

ActiveDirectory

Das Modul ActiveDirectory unterstützt bei Verwendung der Version 1.0.1.0 natives PowerShell 7. Bei Verwendung der Version 1.0.0.0 wird die Windows-Kompatibilitätsschicht verwendet, wenn die Befehle in PowerShell 7 und der Integrated-Umgebung ausgeführt werden. Dies kann innerhalb von PowerShell Universal zu Problemen führen. Unsere Empfehlung für dieses Modul lautet wie folgt.

Windows Server 2019 und höher

Aktualisieren Sie das Modul ActiveDirectory auf Version 1.0.1.0, die PowerShell Core-Unterstützung bietet

Windows Server 2016 und niedriger

Wählen Sie eine von 2 verfügbaren Problemumgehungen:

• Fügen Sie beim Importieren des ActiveDirectory-Moduls den Parameter -SkipEditionCheck zu Import-Module hinzu
• Verwenden Sie die Windows PowerShell 5.1-Umgebung anstelle von Integrated/PowerShell Core

Weiterführende Literatur

Increased Windows Modules coverage with PowerShell Core 6.1 - PowerShell TeamPowerShell Team

Exchange

Lokales Microsoft Exchange kann mithilfe von Remote-Sitzungen in PowerShell verwaltet werden. Wenn Sie Sitzungen in Apps verwenden, sollten Sie die Sitzung so verwalten, dass nicht für jede Anfrage eine neue Sitzung geöffnet werden muss. Dies verbessert die Leistung erheblich. Das folgende Beispiel verwendet den Bereich $Cache:, um die Sitzung über Anfragen hinweg beizubehalten.

Dieses Beispiel verwendet zwar PSSessions und Exchange, Sie könnten dasselbe Muster jedoch auch für andere Arten persistenter Verbindungen verwenden.

$Cache:ExchangeServer = ''
$Cache:ExchangeCredential = ''
$Cache:ExchangeSessionInfo = @{

    Authentication    = 'Kerberos'
    ConfigurationName = 'Microsoft.Exchange'
    ConnectionUri     = 'https://{0}/PowerShell/' -f $Cache:ExchangeServer
    Credential        = $Cache:ExchangeCredential
    WarningAction     = 'SilentlyContinue'
}

#region PRIVATE FUNCTIONS

Function Script:Connect-ExchServer {
    $exchSession = New-PSSession @Cache:ExchangeSessionInfo
    Import-PSSession $exchSession -WarningAction 'SilentlyContinue'
}


Function Script:Test-ExchConnected {
    $Current = Get-PSSession | Where-Object { $_.ConfigurationName -eq 'Microsoft.Exchange' }
    if ($Current.State -eq 'Opened' -and $Current.Availability -eq 'Available') {
        $true
    }
    else {
        $false
    }
}

#endregion

#region PUBLIC FUNCTIONS 

Function Clear-ExchConnection {
    # called publicly in "End{}" blocks.
    Get-PSSession | Where-Object { $_.ConfigurationName -eq 'Microsoft.Exchange' } | Remove-PSSession -ErrorAction $Cache:ErrorAction
    Get-Module | Where-Object { $_.Description -match $Cache:ExchangeServer } | Remove-Module -Force -ErrorAction $Cache:ErrorAction
}


Function Confirm-ExchConnected {
     # called publicly in "Begin{}" blocks, or just before Exhange actions in functions or scripts.
    if (!( Test-ExchConnected )) {
        Clear-ExchConnection
        Connect-ExchServer
    }
}

#endregion

function Invoke-ExampleExchFunction {
    Param (
        $something
    )

    Begin {
        $null = Confirm-ExchConnected
    }
    
    Process {
        return $something
    }
    
    End {
        Clear-ExchConnection
    }
}

Validierte Modulversionen

Die folgenden Modulversionen wurden gegen PowerShell Universal validiert. Die Modulvalidierung stellt sicher, dass diese Module geladen werden und mit ihren jeweiligen Diensten interagieren.

Modul	Modulversion	PSU-Version	PSU-Umgebungen
Microsoft.Graph.Authentication	2.26.1	5.5.2	PowerShell 7
ExchangeOnlineManagement	3.7.2	5.5.2	PowerShell 7
MicrosoftTeams	6.9.0	5.5.2	PowerShell 7
Az.Accounts	4.1.0	5.5.2	PowerShell 7, Integrated