Freigeben über

Installieren eines PowerShell-Moduls

Nachdem Sie Ihr PowerShell-Modul erstellt haben, möchten Sie das Modul wahrscheinlich auf einem System installieren, damit Sie oder andere es verwenden können. Im Allgemeinen besteht dies aus dem Kopieren der Moduldateien (d. h. der .psm1oder der Binärassembly, des Modulmanifests und aller anderen zugehörigen Dateien) in ein Verzeichnis auf diesem Computer. Für ein sehr kleines Projekt kann dies so einfach wie das Kopieren und Einfügen der Dateien mit Windows Explorer auf einem einzigen Remotecomputer sein. Für größere Lösungen können Sie jedoch einen komplexeren Installationsprozess verwenden. Unabhängig davon, wie Sie Ihr Modul auf das System übertragen, kann PowerShell eine Reihe von Techniken verwenden, mit denen Benutzer Ihre Module finden und verwenden können. Daher stellt das Hauptproblem bei der Installation sicher, dass PowerShell Ihr Modul finden kann. Weitere Informationen finden Sie unter Importieren eines PowerShell-Moduls.

Regeln für die Installation von Modulen

Die folgenden Informationen beziehen sich auf alle Module, einschließlich Module, die Sie für Ihre eigene Verwendung erstellen, Module, die Sie von anderen Parteien erhalten, und Module, die Sie an andere Personen verteilen.

Installieren von Modulen in PSModulePath

Installieren Sie nach Möglichkeit alle Module in einem Pfad, der in der PSModulePath Umgebungsvariablen aufgeführt ist, oder fügen Sie den Modulpfad zum wert der PSModulePath Umgebungsvariablen hinzu.

Die PSModulePath Umgebungsvariable ($Env:PSModulePath) enthält die Speicherorte von Windows PowerShell-Modulen. Cmdlets basieren auf dem Wert dieser Umgebungsvariable, um Module zu finden.

Standardmäßig enthält der wert der PSModulePath Umgebungsvariablen die folgenden System- und Benutzermodulverzeichnisse, Sie können den Wert jedoch hinzufügen und bearbeiten.

  • $PSHOME\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules)

    Warnung

    Dieser Standort ist für Module reserviert, die mit Windows ausgeliefert werden. Installieren Sie Keine Module an diesem Speicherort.

  • $HOME\Documents\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules)

  • $Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

    Um den Wert der PSModulePath Umgebungsvariable abzurufen, verwenden Sie einen der folgenden Befehle.

    $Env:PSModulePath
[Environment]::GetEnvironmentVariable("PSModulePath")

    Verwenden Sie das folgende Befehlsformat, um einen Modulpfad zum Wert des PSModulePath Umgebungsvariablenwerts hinzuzufügen. Dieses Format verwendet die SetEnvironmentVariable-Methode der System.Environment Klasse, um eine sitzungsunabhängige Änderung an der PSModulePath Umgebungsvariablen vorzunehmen.

    #Save the current value in the $p variable.
$p = [Environment]::GetEnvironmentVariable("PSModulePath")

#Add the new path to the $p variable. Begin with a semi-colon separator.
$p += ";C:\Program Files (x86)\MyCompany\Modules\"

#Add the paths in $p to the PSModulePath value.
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

    Wichtig

    Nachdem Sie den Pfad zu PSModulePathhinzugefügt haben, sollten Sie eine Umgebungsnachricht über die Änderung übertragen. Durch das Übertragen der Änderung können andere Anwendungen, z. B. die Shell, die Änderung aufnehmen. Wenn Sie die Änderung übertragen möchten, senden Sie mit ihrem Produktinstallationscode eine WM_SETTINGCHANGE Nachricht, wobei lParam auf die Zeichenfolge "Environment" festgelegt ist. Achten Sie darauf, die Nachricht zu senden, nachdem der Modulinstallationscode PSModulePathaktualisiert wurde.

Verwenden des richtigen Modulverzeichnisnamens

Ein wohlgeformtes Modul ist ein Modul, das in einem Verzeichnis gespeichert ist, das denselben Namen wie der Basisname von mindestens einer Datei im Modulverzeichnis hat. Wenn ein Modul nicht wohlgeformt ist, erkennt Windows PowerShell es nicht als Modul.

Der "Basisname" einer Datei ist der Name ohne dateinamenerweiterung. In einem wohlgeformten Modul muss der Name des Verzeichnisses, das die Moduldateien enthält, mit dem Basisnamen mindestens einer Datei im Modul übereinstimmen.

Im Beispielmodul "Fabrikam" heißt beispielsweise das Verzeichnis, das die Moduldateien enthält, den Namen "Fabrikam", und mindestens eine Datei hat den Basisnamen "Fabrikam". In diesem Fall weisen sowohl Fabrikam.psd1 als auch Fabrikam.dll den Basisnamen "Fabrikam" auf.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Auswirkung einer falschen Installation

Wenn das Modul nicht wohlgeformt ist und seine Position nicht im Wert der PSModulePath Umgebungsvariable enthalten ist, funktionieren grundlegende Ermittlungsfeatures von Windows PowerShell, z. B. die folgende, nicht.

  • Die AutoLadefunktion des Moduls kann das Modul nicht automatisch importieren.

  • Der ListAvailable Parameter des cmdlets Get-Module das Modul nicht finden kann.

  • Das Cmdlet Importmodul- kann das Modul nicht finden. Um das Modul zu importieren, müssen Sie den vollständigen Pfad zur Stammmoduldatei oder Modulmanifestdatei angeben.

    Weitere Features, z. B. die folgenden, funktionieren nicht, es sei denn, das Modul wird in die Sitzung importiert. In wohlgeformten Modulen in der PSModulePath Umgebungsvariable funktionieren diese Features auch dann, wenn das Modul nicht in die Sitzung importiert wird.

  • Das cmdlet Get-Command cmdlet kann keine Befehle im Modul finden.

  • Die Update-Help- und Save-Help--Cmdlets können keine Hilfe für das Modul aktualisieren oder speichern.

  • Das Cmdlet "Einbl"-Cmdlet kann die Befehle im Modul nicht finden und anzeigen.

    Die Befehle im Modul fehlen im fenster Show-Command in windows PowerShell Integrated Scripting Environment (ISE).

Speicherort für die Installation von Modulen

In diesem Abschnitt wird erläutert, wo im Dateisystem Windows PowerShell-Module installiert werden sollen. Die Position hängt davon ab, wie das Modul verwendet wird.

Installieren von Modulen für einen bestimmten Benutzer

Wenn Sie Ein eigenes Modul erstellen oder ein Modul von einer anderen Partei abrufen, z. B. eine Windows PowerShell-Communitywebsite, und sie möchten, dass das Modul nur für Ihr Benutzerkonto verfügbar sein soll, installieren Sie das Modul in Ihrem benutzerspezifischen Modulverzeichnis.

$HOME\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Das benutzerspezifische Modulverzeichnis wird standardmäßig dem Wert der PSModulePath Umgebungsvariablen hinzugefügt.

Installieren von Modulen für alle Benutzer in Programmdateien

Wenn ein Modul für alle Benutzerkonten auf dem Computer verfügbar sein soll, installieren Sie das Modul am Speicherort "Programme".

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Hinweis

Der Speicherort "Programme" wird dem Wert der PSModulePath-Umgebungsvariablen standardmäßig in Windows PowerShell 4.0 und höher hinzugefügt. Für frühere Versionen von Windows PowerShell können Sie den Speicherort der Programme (%ProgramFiles%\WindowsPowerShell\Modules) manuell erstellen und diesen Pfad ihrer PSModulePath-Umgebungsvariablen hinzufügen, wie oben beschrieben.

Installieren von Modulen in einem Produktverzeichnis

Wenn Sie das Modul an andere Parteien verteilen, verwenden Sie den oben beschriebenen Standardspeicherort für Programmdateien, oder erstellen Sie ihr eigenes unternehmensspezifisches oder produktspezifisches Unterverzeichnis des %ProgramFiles% Verzeichnisses.

Beispielsweise wird fabrikam Technologies, ein fiktives Unternehmen, ein Windows PowerShell-Modul für sein Fabrikam Manager-Produkt versenden. Das Modulinstallationsprogramm erstellt ein Unterverzeichnis "Modules" im Produktunterverzeichnis Fabrikam Manager.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Damit die Windows PowerShell-Modulermittlungsfeatures das Fabrikam-Modul finden können, fügt das Fabrikam-Modulinstallationsprogramm den Modulspeicherort dem Wert der PSModulePath Umgebungsvariablen hinzu.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Installieren von Modulen im Verzeichnis "Gemeinsame Dateien"

Wenn ein Modul von mehreren Komponenten eines Produkts oder von mehreren Versionen eines Produkts verwendet wird, installieren Sie das Modul in einem modulspezifischen Unterverzeichnis des Unterverzeichnisses %ProgramFiles%\Common Files\Modules.

Im folgenden Beispiel wird das Fabrikam-Modul in einem Fabrikam-Unterverzeichnis des Unterverzeichnisses %ProgramFiles%\Common Files\Modules installiert. Beachten Sie, dass sich jedes Modul in einem eigenen Unterverzeichnis im Unterverzeichnis "Modules" befindet.

C:\Program Files
  Common Files
    Modules
      Fabrikam
        Fabrikam.psd1 (module manifest)
        Fabrikam.dll (module assembly)

Anschließend stellt das Installationsprogramm den Wert der PSModulePath Umgebungsvariablen den Pfad des Unterverzeichnisses Common Files\Modules bereit.

$m = $Env:ProgramFiles + '\Common Files\Modules'
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$q = $p -split ';'
if ($q -notcontains $m) {
    $q += ";$m"
}
$p = $q -join ';'
[Environment]::SetEnvironmentVariable("PSModulePath", $p)

Installieren mehrerer Versionen eines Moduls

Wenn Sie mehrere Versionen desselben Moduls installieren möchten, verwenden Sie das folgende Verfahren.

  1. Erstellen Sie ein Verzeichnis für jede Version des Moduls. Fügen Sie die Versionsnummer in den Verzeichnisnamen ein.
  2. Erstellen Sie ein Modulmanifest für jede Version des Moduls. Geben Sie im Wert des ModuleVersion- Schlüssels im Manifest die Versionsnummer des Moduls ein. Speichern Sie die Manifestdatei (.psd1) im versionsspezifischen Verzeichnis für das Modul.
  3. Fügen Sie den Pfad des Modulstammordners zum Wert der PSModulePath Umgebungsvariable hinzu, wie in den folgenden Beispielen gezeigt.

Um eine bestimmte Version des Moduls zu importieren, kann der Endbenutzer die parameter MinimumVersion oder RequiredVersion des Cmdlets Import-Module verwenden.

Wenn das Fabrikam-Modul beispielsweise in den Versionen 8.0 und 9.0 verfügbar ist, könnte die Fabrikam-Modulverzeichnisstruktur wie folgt aussehen.

C:\Program Files
Fabrikam Manager
 Fabrikam8
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "8.0")
     Fabrikam.dll (module assembly)
 Fabrikam9
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "9.0")
     Fabrikam.dll (module assembly)

Das Installationsprogramm fügt beide Modulpfade zum PSModulePath Umgebungsvariablenwert hinzu.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Nach Abschluss dieser Schritte ruft der parameter ListAvailable des Cmdlets Get-Module beide Fabrikam-Module ab. Verwenden Sie zum Importieren eines bestimmten Moduls die parameter MinimumVersion oder RequiredVersion des Cmdlets Import-Module.

Wenn beide Module in dieselbe Sitzung importiert werden und die Module Cmdlets mit denselben Namen enthalten, sind die zuletzt importierten Cmdlets in der Sitzung wirksam.

Behandeln von Befehlsnamenkonflikten

Befehlsnamenkonflikte können auftreten, wenn die Befehle, die ein Modul exportiert, denselben Namen wie Befehle in der Sitzung des Benutzers haben.

Wenn eine Sitzung zwei Befehle mit demselben Namen enthält, führt Windows PowerShell den Befehlstyp aus, der Vorrang hat. Wenn eine Sitzung zwei Befehle mit demselben Namen und demselben Typ enthält, führt Windows PowerShell den Befehl aus, der der Sitzung zuletzt hinzugefügt wurde. Um einen Befehl auszuführen, der nicht standardmäßig ausgeführt wird, können Benutzer den Befehlsnamen mit dem Modulnamen qualifizieren.

Wenn die Sitzung beispielsweise eine Get-Date-Funktion und das cmdlet Get-Date enthält, führt Windows PowerShell die Funktion standardmäßig aus. Um das Cmdlet auszuführen, stellen Sie dem Befehl den Modulnamen voran, z. B.:

Microsoft.PowerShell.Utility\Get-Date

Um Namenskonflikte zu verhindern, können Modulautoren den DefaultCommandPrefix- Schlüssel im Modulmanifest verwenden, um ein Substantivpräfix für alle befehle anzugeben, die aus dem Modul exportiert wurden.

Benutzer können den Parameter Präfix des Cmdlets Import-Module verwenden, um ein alternatives Präfix zu verwenden. Der Wert des Prefix-Parameters hat Vorrang vor dem Wert des DefaultCommandPrefix--Schlüssels.

Unterstützen von Pfaden auf Nicht-Windows-Systemen

Nicht-Windows-Plattformen verwenden das Doppelpunktzeichen (:) als Pfadtrennzeichen und ein Schrägstrich (/) als Verzeichnistrennzeichen. Die [System.IO.Path]-Klasse verfügt über statische Member, mit denen Ihr Code auf einer beliebigen Plattform funktioniert:

  • [System.IO.Path]::PathSeparator : Gibt das Zeichen zurück, das zum Trennen von Pfaden in einer PATH-Umgebungsvariablen für die Hostplattform verwendet wird.
  • [System.IO.Path]::DirectorySeparatorChar – gibt das Zeichen zurück, das zum Trennen von Verzeichnisnamen mit einem Pfad für die Hostplattform verwendet wird.

Verwenden Sie diese statischen Eigenschaften, um anstelle der ;- und \ Zeichen beim Erstellen von Pfadzeichenfolgen zu arbeiten.

Siehe auch

about_Command_Precedence

Schreiben eines Windows PowerShell-Moduls