about_Modules

Kurze Beschreibung

Erläutert das Installieren, Importieren und Verwenden von PowerShell-Modulen.

Lange Beschreibung

Ein Modul ist ein Paket, das PowerShell-Member wie Cmdlets, Anbieter, Funktionen, Workflows, Variablen und Aliase enthält.

Personen, die Befehle schreiben, können Module verwenden, um ihre Befehle zu organisieren und für andere Benutzer freizugeben. Personen, die Module erhalten, können die Befehle in den Modulen ihren PowerShell-Sitzungen hinzufügen und sie wie die integrierten Befehle verwenden.

In diesem Thema wird die Verwendung von PowerShell-Modulen erläutert. Informationen zum Schreiben von PowerShell-Modulen finden Sie unter Schreiben eines PowerShell-Moduls.

Was ist ein Modul?

Ein Modul ist ein Paket, das PowerShell-Member wie Cmdlets, Anbieter, Funktionen, Workflows, Variablen und Aliase enthält. Die Member dieses Pakets können in einem PowerShell-Skript, einer kompilierten DLL oder einer Kombination aus beidem implementiert werden. Diese Dateien werden in der Regel in einem einzigen Verzeichnis gruppiert. Weitere Informationen finden Sie unter Understanding a Windows PowerShell Module in der SDK-Dokumentation.

Automatisches Laden von Modulen

Ab PowerShell 3.0 importiert PowerShell Module automatisch, wenn Sie einen Befehl zum ersten Mal in einem installierten Modul ausführen. Sie können jetzt die Befehle in einem Modul ohne weitere Einrichtung oder Profilkonfiguration verwenden, daher besteht keine Notwendigkeit, Module nach der Installation auf Ihrem Computer zu verwalten.

Die Befehle in einem Modul sind auch leichter zu finden. Das Get-Command Cmdlet ruft jetzt alle Befehle in allen installierten Modulen ab, auch wenn sie sich noch nicht in der Sitzung befinden. Sie finden einen Befehl und verwenden ihn, ohne dass Sie zuerst das Modul importieren müssen.

Jedes der folgenden Beispiele bewirken, dass das CimCmdlets-Modul, Get-CimInstancedas enthält, in Ihre Sitzung importiert wird.

  • Ausführen des Befehls

    Get-CimInstance Win32_OperatingSystem
    
  • Befehl "Get" (Befehl)

    Get-Command Get-CimInstance
    
  • Hilfe für den Befehl

    Get-Help Get-CimInstance
    

Get-Command -Befehle, die ein Platzhalterzeichen (*) enthalten, werden als für die Ermittlung und nicht für die Verwendung betrachtet und importieren keine Module.

Nur Module, die an dem von der PSModulePath-Umgebungsvariablen angegebenen Speicherort gespeichert werden, werden automatisch importiert. Module an anderen Speicherorten müssen durch Ausführen des Cmdlets importiert Import-Module werden.

Außerdem importieren Befehle, die PowerShell-Anbieter verwenden, nicht automatisch ein Modul. Wenn Sie beispielsweise einen Befehl verwenden, der das Laufwerk WSMan: erfordert, Get-PSSessionConfiguration z. B. das Cmdlet, Import-Module müssen Sie möglicherweise das Cmdlet ausführen, um das Modul Microsoft.WSMan.Management WSMan: zu importieren, das das Laufwerk enthält.

Sie können weiterhin den Befehl ausführen Import-Module , um ein Modul zu importieren $PSModuleAutoloadingPreference , und die Variable verwenden, um den automatischen Import von Modulen zu aktivieren, zu deaktivieren und zu konfigurieren. Weitere Informationen finden Sie unter about_Preference_Variables.

Verwenden eines Moduls

Um ein Modul zu verwenden, führen Sie die folgenden Aufgaben aus:

  1. Installieren Sie das Modul. (Dies wird häufig für Sie durchgeführt.)
  2. Suchen Sie die Befehle, die das Modul hinzugefügt hat.
  3. Verwenden Sie die Befehle, die das Modul hinzugefügt hat.

In diesem Thema wird erläutert, wie Sie diese Aufgaben ausführen. Darüber hinaus gibt es weitere wichtige Informationen zur Verwaltung von Modulen.

Installieren eines Moduls

Wenn Sie ein Modul als Ordner mit Dateien erhalten, müssen Sie es auf Ihrem Computer installieren, bevor Sie es in PowerShell verwenden können.

Die meisten Module werden für Sie installiert. PowerShell enthält mehrere vorinstallierte Module, die manchmal als Kernmodule bezeichnet werden. Auf Windows Computern sind diese Module vorinstalliert, wenn features, die im Betriebssystem enthalten sind, über Cmdlets verfügen, um sie zu verwalten. Wenn Sie ein Windows-Feature installieren, z. B. mithilfe des Assistenten zum Hinzufügen von Rollen und Features in Server-Manager oder des Dialogfelds Windows-Features aktivieren oder deaktivieren in Systemsteuerung werden alle PowerShell-Module installiert, die Teil des Features sind. Viele andere Module sind in einem Installationsprogramm oder Setup-Programm, mit dem das Modul installiert wird.

Verwenden Sie den folgenden Befehl, um ein Modulverzeichnis für den aktuellen Benutzer zu erstellen:

New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules

Kopieren Sie den gesamten Modulordner in das Verzeichnis „Modules“. Sie können eine beliebige Methode verwenden, um den Ordner zu kopieren, einschließlich Windows Explorer und Cmd.exe sowie PowerShell. Verwenden Sie in PowerShell das Cmdlet Copy-Item . Geben Sie beispielsweise Folgendes ein, um den Ordner MyModule aus C:\ps-test\MyModule in das Verzeichnis Modules zu kopieren:

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\PowerShell\Modules

Sie können ein Modul an einem beliebigen Speicherort installieren, aber wenn Sie Ihre Module an einem Standardspeicherort installieren, sind sie leichter zu verwalten. Weitere Informationen zu den Standardspeicherorten für Module finden Sie im Abschnitt Module and DSC Resource Locations (Speicherorte von Modulen und DSC-Ressourcen) und PSModulePath (PSModulePath ).

Suchen nach installierten Modulen

Geben Sie Folgendes ein, um Module zu suchen, die an einem Modul-Standardspeicherort installiert sind, jedoch noch nicht in die Sitzung importiert wurden:

Get-Module -ListAvailable

Um die Module zu finden, die bereits in Ihre Sitzung importiert wurden, geben Sie an der PowerShell-Eingabeaufforderung Ein:

Get-Module

Weitere Informationen zum Cmdlet finden Sie Get-Module unter Get-Module.

Suchen der Befehle in einem Modul

Verwenden Sie das Get-Command Cmdlet , um nach allen verfügbaren Befehlen zu suchen. Sie können die Parameter des Cmdlets verwenden Get-Command , um Befehle wie Modul, Name und Nomen zu filtern.

Um alle Befehle in einem Modul zu suchen, geben Sie Folgendes ein:

Get-Command -Module <module-name>

Geben Sie beispielsweise Folgendes ein, um die Befehle im BitsTransfer-Modul zu finden:

Get-Command -Module BitsTransfer

Weitere Informationen zum Cmdlet finden Sie Get-Command unter Get-Command.

How to Hilfe for the Commands in a Module

Wenn das Modul Hilfedateien für die Befehle enthält, die es exportiert, Get-Help zeigt das Cmdlet die Hilfethemen an. Verwenden Sie das gleiche Get-Help Befehlsformat, das Sie verwenden würden, um Hilfe zu jedem Befehl in PowerShell zu erhalten.

Ab PowerShell 3.0 können Sie Hilfedateien für ein Modul herunterladen und Updates für die Hilfedateien herunterladen, damit sie nie veraltet sind.

Um Hilfe für Befehle in einem Modul zu erhalten, geben Sie Folgendes ein:

Get-Help <command-name>

Um Hilfe online für den Befehl in einem Modul zu erhalten, geben Sie Ein:

Get-Help <command-name> -Online

Geben Sie Zum Herunterladen und Installieren der Hilfedateien für die Befehle in einem Modul Ein:

Update-Help -Module <module-name>

Weitere Informationen finden Sie unter Get-Help und Update-Help.

Importieren eines Moduls

Sie müssen möglicherweise ein Modul oder eine Moduldatei importieren. Der Import ist erforderlich, wenn ein Modul nicht an den speicherorten installiert ist, die von der UMGEBUNGsvariablen PSModulePath angegeben werden, $env:PSModulePathoder das Modul aus einer Datei besteht, z. B. einer .dll- oder PSM1-Datei, anstatt aus einem typischen Modul, das als Ordner bereitgestellt wird.

Import-Module Sie können auch ein Modul importieren, damit Sie die Parameter des Befehls verwenden können, z. B. den Prefix-Parameter, der den Nomennamen aller importierten Befehle ein präfix-Präfix hinzufügt, oder den NoClobber-Parameter, der verhindert, dass das Modul Befehle hinzufügt, die vorhandene Befehle in der Sitzung ausblenden oder ersetzen würden.

Verwenden Sie zum Importieren von Modulen das Cmdlet Import-Module .

Verwenden Sie das folgende Befehlsformat, um Module an einen PSModulePath-Speicherort in der aktuellen Sitzung zu importieren.

Import-Module <module-name>

Mit dem folgenden Befehl importieren Sie beispielsweise das Modul "BitsTransfer" in die aktuelle Sitzung.

Import-Module BitsTransfer

Verwenden Sie zum Importieren eines Moduls, das sich nicht am Standard-Modulspeicherort befindet, den vollqualifizierten Pfad zum Modulordner im Befehl.

Geben Sie beispielsweise Folgendes ein, um das TestCmdlets-Modul im C:\ps-test Verzeichnis Ihrer Sitzung hinzuzufügen:

Import-Module C:\ps-test\TestCmdlets

Um eine Moduldatei zu importieren, die nicht in einem Modulordner enthalten ist, verwenden Sie den vollqualifizierten Pfad der Moduldatei im Befehl.

Geben Sie beispielsweise Folgendes ein, um TestCmdlets.dll -Modul im C:\ps-test Verzeichnis ihrer Sitzung hinzuzufügen:

Import-Module C:\ps-test\TestCmdlets.dll

Weitere Informationen zum Hinzufügen von Modulen zu Ihrer Sitzung finden Sie unter Import-Module.

Importieren eines Moduls in jede Sitzung

Der Import-Module Befehl importiert Module in Ihre aktuelle PowerShell-Sitzung. Um ein Modul in jede PowerShell-Sitzung zu importieren, die Sie starten, fügen Sie den Import-Module Befehl Ihrem PowerShell-Profil hinzu.

Weitere Informationen zu Profilen finden Sie unter about_Profiles.

Entfernen eines Moduls

Wenn Sie ein Modul entfernen, werden die vom Modul hinzugefügten Befehle aus der Sitzung gelöscht.

Verwenden Sie das folgende Befehlsformat, um ein Modul aus Ihrer Sitzung zu entfernen.

Remove-Module <module-name>

Beispielsweise entfernt der folgende Befehl das BitsTransfer-Modul aus der aktuellen Sitzung.

Remove-Module BitsTransfer

Entfernen einrd Moduld kehrt den Vorgang des Modulimports um. Beim Entfernen eines Moduls wird das Modul nicht deinstalliert. Weitere Informationen finden Sie unter Remove-Module.

Modul- und DSC-Ressourcenstandorte und PSModulePath

Die $env:PSModulePath Umgebungsvariable enthält eine Liste der Ordnerspeicherorte, die nach Modulen und Ressourcen durchsucht werden.

Standardmäßig sind die folgenden effektiven Speicherorte $env:PSModulePath zugewiesen:

  • Systemweite Speicherorte: $PSHOME\Modules

    Diese Ordner enthalten Module, die mit Windows und PowerShell versendet werden.

    DSC-Ressourcen, die in PowerShell enthalten sind, werden im $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources Ordner gespeichert.

  • Benutzerspezifische Module: Dies sind Module, die vom Benutzer im Bereich des Benutzers installiert werden. Install-Module verfügt über einen Scope-Parameter , mit dem Sie angeben können, ob das Modul für den aktuellen Benutzer oder für alle Benutzer installiert ist. Weitere Informationen finden Sie unter Install-Module.

    Der benutzerspezifische CurrentUser-Speicherort auf Windows ist der PowerShell\Modules Ordner, der sich im Speicherort Dokumente in Ihrem Benutzerprofil befindet. Der spezifische Pfad dieses Speicherorts variiert je nach Version von Windows und davon, ob Sie die Ordnerumleitung verwenden oder nicht. Microsoft OneDrive können auch den Speicherort Ihres Ordners Dokumente ändern.

    Bei Windows 10 und höher ist $HOME\Documents\PowerShell\Modulesdieser Speicherort standardmäßig . Unter Linux oder Mac lautet $HOME/.local/share/powershell/Modulesder CurrentUser-Speicherort .

    Hinweis

    Sie können den Speicherort Ihres Ordners Dokumente mit dem folgenden Befehl überprüfen: [Environment]::GetFolderPath('MyDocuments').

  • Der Standort AllUsers befindet sich $env:PROGRAMFILES\PowerShell\Modules auf Windows. Unter Linux oder Mac werden die Module unter /usr/local/share/powershell/Modulesgespeichert.

Hinweis

Um Dateien im $env:Windir\System32 Verzeichnis hinzuzufügen oder zu ändern, starten Sie PowerShell mit der Option Als Administrator ausführen .

Sie können die Standardmodulspeicherorte auf Ihrem System ändern, indem Sie den Wert der PSModulePath-Umgebungsvariablen $Env:PSModulePathändern. Die Umgebungsvariable PSModulePath basiert auf der Path-Umgebungsvariablen und hat das gleiche Format.

Um die Standardspeicherorte für das Modul anzuzeigen, geben Sie Folgendes ein:

$Env:PSModulePath

Um einen Standardspeicherort für das Modul hinzuzufügen, verwenden Sie das folgende Befehlsformat.

$Env:PSModulePath = $Env:PSModulePath + ";<path>"

Das Semikolon (;) im Befehl trennt den neuen Pfad von dem Pfad, der ihm in der Liste vorangestellt ist.

Geben Sie beispielsweise Folgendes ein, um das C:\ps-test\Modules Verzeichnis hinzuzufügen:

$Env:PSModulePath + ";C:\ps-test\Modules"

Verwenden Sie zum Hinzufügen eines Standardmodulspeicherorts unter Linux oder MacOS das folgende Befehlsformat:

$Env:PSModulePath += ":<path>"

Geben Sie beispielsweise Folgendes ein, um das /usr/local/Fabrikam/Modules Verzeichnis dem Wert der Umgebungsvariablen PSModulePath hinzuzufügen:

$Env:PSModulePath += ":/usr/local/Fabrikam/Modules"

Unter Linux oder MacOS trennt der Doppelpunkt (:) im Befehl den neuen Pfad von dem Pfad, der ihm in der Liste vorangestellt ist.

Wenn Sie PSModulePath einen Pfad hinzufügen, Get-Module Import-Module enthalten befehle Module in diesem Pfad.

Der festgelegte Wert wirkt sich nur auf die aktuelle Sitzung aus. Um die Änderung persistent zu machen, fügen Sie den Befehl Ihrem PowerShell-Profil hinzu, oder verwenden Sie System in Systemsteuerung , um den Wert der Umgebungsvariablen PSModulePath in der Registrierung zu ändern.

Um die Änderung persistent zu machen, können Sie auch die SetEnvironmentVariable-Methode der System.Environment-Klasse verwenden, um der Umgebungsvariablen PSModulePath einen Pfad hinzuzufügen.

Weitere Informationen zur PsModulePath-Variablen finden Sie unter about_Environment_Variables.

Module und Namenskonflikte

Namenskonflikte treten auf, wenn mehrere Befehle in der Sitzung denselben Namen haben. Das Importieren eines Moduls bewirkt einen Namenskonflikt, wenn Befehle im Modul die gleichen Namen wie die Befehle oder Elemente in der Sitzung haben.

Namenskonflikte können dazu führen, dass Befehle ausgeblendet oder ersetzt werden.

Ausgeblendet

Ein Befehl ist ausgeblendet, wenn er nicht ausgeführt wird, wenn Sie den Befehl eingeben, Sie ihn jedoch mithilfe einer anderen Methode ausführen können, wie z. B. den Befehlsnamen mit dem Namen des Moduls oder Snap-Ins zu qualifizieren, aus dem sie stammen.

Ersetzt

Ein Befehl wurde ersetzt, wenn Sie ihn nicht ausführen können, weil er durch einen Befehl mit demselben Namen überschrieben wurde. Selbst wenn Sie das Modul entfernen, das den Konflikt verursacht hat, kann ein ersetzter Befehl nicht ausgeführt werden, sofern Sie die Sitzung nicht neu starten.

Import-Module kann Befehle hinzufügen, die Befehle in der aktuellen Sitzung ausblenden und ersetzen. Darüber hinaus können Befehle in der Sitzung Befehle ausblenden, die das Modul hinzugefügt hat.

Um Namenskonflikte zu erkennen, verwenden Sie den All-Parameter des Get-Command Cmdlets. Ruft ab PowerShell 3.0 nur die Befehle ab, Get-Command die ausgeführt werden, wenn Sie den Befehlsnamen eingeben. Der All-Parameter ruft alle Befehle mit dem spezifischen Namen in der Sitzung ab.

Um Namenskonflikte zu vermeiden, verwenden Sie die Parameter NoClobber oder Prefix des Import-Module Cmdlets. Der Prefix-Parameter fügt den Namen importierter Befehle ein Präfix hinzu, damit sie in der Sitzung eindeutig sind. Der NoClobber-Parameter importiert keine Befehle, die vorhandene Befehle in der Sitzung ausblenden oder ersetzen würden.

Sie können auch die Parameter Alias, Cmdlet, Function und Variable von Import-Module verwenden, um nur die Befehle auszuwählen, die Sie importieren möchten, und Sie können Befehle ausschließen, die Namenskonflikte in Ihrer Sitzung verursachen.

Modulautoren können Namenskonflikte verhindern, indem sie die DefaultCommandPrefix-Eigenschaft des Modulmanifests verwenden, um allen Befehlsnamen ein Standardpräfix hinzuzufügen. Der Wert des Prefix-Parameters hat Vorrang vor dem Wert von DefaultCommandPrefix.

Selbst wenn ein Befehl ausgeblendet ist, können Sie ihn durch die Qualifizierung des Befehlsnamens mit dem Namen des Moduls oder des ursprüunglichen Snap-Ins ausführen.

Die Rangfolgenregeln für PowerShell-Befehle bestimmen, welcher Befehl ausgeführt wird, wenn die Sitzung Befehle mit dem gleichen Namen enthält.

Wenn eine Sitzung beispielsweise eine Funktion und ein Cmdlet mit dem gleichen Namen enthält, führt PowerShell die Funktion standardmäßig aus. Wenn die Sitzung Befehle vom gleichen Typ mit dem gleichen Namen, z. B. zwei Cmdlets mit demselben Namen enthält, wird standardmäßig der zuletzt hinzugefügte Befehl ausgeführt.

Weitere Informationen, einschließlich einer Erläuterung der Rangfolgenregeln und Anweisungen zum Ausführen ausgeblendeter Befehle, finden Sie unter about_Command_Precedence.

Module und Snap-Ins

Sie können Ihrer Sitzung Befehle aus Modulen und Snap-Ins hinzufügen. Module können alle Arten von Befehlen hinzufügen, einschließlich Cmdlets, Anbieter und Funktionen sowie Elemente wie Variablen, Aliase und PowerShell-Laufwerke. Snap-Ins können nur Cmdlets und Anbieter hinzufügen.

Vor dem Entfernen eines Moduls oder Snap-Ins aus der Sitzung verwenden Sie die folgenden Befehle, um zu bestimmen, welche Befehle entfernt werden.

Verwenden Sie das folgende Befehlsformat, um die Quelle eines Cmdlets in Ihrer Sitzung zu ermitteln:

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

Geben Sie beispielsweise Folgendes ein, um die Quelle des Get-Date Cmdlets zu suchen:

Get-Command Get-Date | Format-List -Property verb,noun,module

Die Befehle, die ein Modul exportiert, sollten den Benennungsregeln für PowerShell-Befehle entsprechen. Wenn das modul, das Sie importieren, Cmdlets oder Funktionen exportiert, deren Namen nicht genehmigte Verben enthalten, zeigt das Import-Module Cmdlet die folgende Warnmeldung an.

WARNUNG: Einige importierte Befehlsnamen enthalten nicht genehmigte Verben, die sie möglicherweise weniger auffindbar machen. Verwenden Sie den Verbose-Parameter für weitere Details, oder geben Sie „Get-Verb“ ein, um die Liste der zulässigen Verben anzuzeigen.

Diese Meldung ist nur eine Warnung. Es wird trotzdem das gesamte Modul einschließlich nicht konformer Befehle importiert. Obwohl die Meldung für Modulbenutzer angezeigt wird, sollte das Namensproblem vom Modulautor behoben werden.

Um die Warnmeldung zu unterdrücken, verwenden Sie den DisableNameChecking-Parameter des Import-Module Cmdlets.

Integrierte Module und Snap-Ins

In PowerShell 2.0 und in Hostprogrammen im älteren Stil in PowerShell 3.0 und höher werden die mit PowerShell installierten Kernbefehle in Snap-Ins gepackt, die jeder PowerShell-Sitzung automatisch hinzugefügt werden.

Ab PowerShell 3.0 wird für Hostprogramme, die die API für den InitialSessionState.CreateDefault2 anfänglichen Sitzungszustand implementieren, das Microsoft.PowerShell.Core-Snap-In standardmäßig jeder Sitzung hinzugefügt. Module werden automatisch bei der ersten Verwendung geladen.

Hinweis

Remotesitzungen, einschließlich Sitzungen, die mit dem New-PSSession Cmdlet gestartet werden, sind Sitzungen im älteren Stil, in denen die integrierten Befehle in Snap-Ins gepackt werden.

Die folgenden Module (oder Snap-Ins) werden mit PowerShell installiert.

  • CimCmdlets
  • Microsoft.PowerShell.Archive
  • Microsoft.PowerShell.Core
  • Microsoft.PowerShell.Diagnostics
  • Microsoft.PowerShell.Host
  • Microsoft.PowerShell.Management
  • Microsoft.PowerShell.Security
  • Microsoft.PowerShell.Utility
  • Microsoft.WSMan.Management
  • PackageManagement
  • PowerShellGet
  • PSDesiredStateConfiguration
  • PSDiagnostics
  • PSReadline

Protokollieren von Modulereignissen

Ab PowerShell 3.0 können Sie Ausführungsereignisse für die Cmdlets und Funktionen in PowerShell-Modulen und Snap-Ins aufzeichnen, indem Sie die LogPipelineExecutionDetails-Eigenschaft von Modulen und Snap-Ins auf $Truefestlegen. Sie können auch die Gruppenrichtlinie Einstellung Modulprotokollierung aktivieren verwenden, um die Modulprotokollierung in allen PowerShell-Sitzungen zu aktivieren. Weitere Informationen finden Sie in den Artikeln zur Protokollierung und Gruppenrichtlinie.

Siehe auch