Udostępnij za pośrednictwem

O_modułach

  • Artykuł

Krótki opis

Objaśnienie sposobu instalowania, importowania i używania modułów programu PowerShell.

Długi opis

Moduł to pakiet zawierający elementy członkowskie programu PowerShell, takie jak polecenia cmdlet, dostawcy, funkcje, przepływy pracy, zmienne i aliasy.

Osoby, którzy piszą polecenia, mogą używać modułów do organizowania poleceń i udostępniania ich innym osobom. Osoby, którzy odbierają moduły, mogą dodawać polecenia w modułach do sesji programu PowerShell i używać ich tak jak w przypadku wbudowanych poleceń.

W tym temacie wyjaśniono, jak używać modułów programu PowerShell. Aby uzyskać informacje o sposobie pisania modułów programu PowerShell, zobacz Pisanie modułu programu PowerShell.

Co to jest moduł?

Moduł to pakiet zawierający elementy członkowskie programu PowerShell, takie jak polecenia cmdlet, dostawcy, funkcje, przepływy pracy, zmienne i aliasy. Elementy członkowskie tego pakietu można zaimplementować w skryscie programu PowerShell, skompilowanej biblioteki DLL lub kombinacji obu tych elementów. Te pliki są zwykle grupowane razem w jednym katalogu. Aby uzyskać więcej informacji, zobacz Omówienie modułu Windows PowerShell w dokumentacji zestawu SDK.

Automatyczne ładowanie modułu

Począwszy od programu PowerShell 3.0, program PowerShell importuje moduły automatycznie przy pierwszym uruchomieniu dowolnego polecenia w zainstalowanym module. Teraz można używać poleceń w module bez żadnej konfiguracji konfiguracji lub konfiguracji profilu, więc nie ma potrzeby zarządzania modułami po zainstalowaniu ich na komputerze.

Polecenia w module są również łatwiejsze do znalezienia. Polecenie Get-Command cmdlet pobiera teraz wszystkie polecenia we wszystkich zainstalowanych modułach, nawet jeśli nie są jeszcze w sesji. Możesz znaleźć polecenie i użyć go bez konieczności importowania, aby najpierw zaimportować moduł.

Każdy z poniższych przykładów powoduje zaimportowanie modułu CimCmdlets zawierającego element , który zawiera Get-CimInstanceelement , który ma zostać zaimportowany do sesji.

  • Uruchamianie polecenia

    Get-CimInstance Win32_OperatingSystem

  • Pobieranie polecenia

    Get-Command Get-CimInstance

  • Uzyskiwanie pomocy dotyczącej polecenia

    Get-Help Get-CimInstance

Get-Command polecenia zawierające symbol wieloznaczny (*) są uważane za odnajdywanie, nieumyślnie używane i nie importuje żadnych modułów.

Importowane są automatycznie tylko moduły przechowywane w lokalizacji określonej przez zmienną środowiskową PSModulePath. Moduły w innych lokalizacjach należy zaimportować, uruchamiając Import-Module polecenie cmdlet .

Ponadto polecenia korzystające z dostawców programu PowerShell nie importują modułu automatycznie. Jeśli na przykład używasz polecenia wymagającego dysku WSMan: dysku, takiego jak Get-PSSessionConfiguration polecenie cmdlet, może być konieczne uruchomienie Import-Module polecenia cmdlet w celu zaimportowania modułu Microsoft.WSMan.Management zawierającego WSMan: dysk.

Nadal można uruchomić Import-Module polecenie , aby zaimportować moduł i użyć zmiennej $PSModuleAutoloadingPreference , aby włączyć, wyłączyć i skonfigurować automatyczne importowanie modułów. Aby uzyskać więcej informacji, zobacz about_Preference_Variables.

Jak używać modułu

Aby użyć modułu, wykonaj następujące zadania:

  1. Zainstaluj moduł. (Jest to często wykonywane dla Ciebie).
  2. Znajdź polecenia dodane przez moduł.
  3. Użyj poleceń dodanych przez moduł.

W tym temacie opisano sposób wykonywania tych zadań. Zawiera również inne przydatne informacje na temat zarządzania modułami.

Jak zainstalować moduł

Jeśli otrzymasz moduł jako folder z plikami w nim, musisz zainstalować go na komputerze, zanim będzie można go użyć w programie PowerShell.

Większość modułów jest instalowana. Program PowerShell zawiera kilka wstępnie zainstalowanych modułów, czasami nazywanych modułami podstawowymi . Na komputerach z systemem Windows, jeśli funkcje dołączone do systemu operacyjnego mają polecenia cmdlet do zarządzania nimi, te moduły są wstępnie zainstalowane. Podczas instalowania funkcji systemu Windows przy użyciu kreatora dodawania ról i funkcji w Menedżer serwera lub w oknie dialogowym Włączanie lub wyłączanie funkcji systemu Windows w Panel sterowania są instalowane wszystkie moduły programu PowerShell, które są częścią funkcji. Wiele innych modułów jest dostępnych w instalatorze lub programie instalacyjnym, który instaluje moduł.

Użyj następującego polecenia, aby utworzyć katalog Modules dla bieżącego użytkownika:

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

Skopiuj cały folder modułu do katalogu Modules. Możesz użyć dowolnej metody do skopiowania folderu, w tym Eksploratora Windows i Cmd.exe, a także programu PowerShell. W programie PowerShell użyj Copy-Item polecenia cmdlet . Aby na przykład skopiować folder MyModule z C:\ps-test\MyModule do katalogu Modules, wpisz:

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

Moduł można zainstalować w dowolnej lokalizacji, ale instalowanie modułów w domyślnej lokalizacji modułu ułatwia zarządzanie nimi. Aby uzyskać więcej informacji na temat domyślnych lokalizacji modułów, zobacz sekcję Lokalizacje zasobów modułu i DSC oraz modułu PSModulePath .

Jak znaleźć zainstalowane moduły

Aby znaleźć moduły zainstalowane w domyślnej lokalizacji modułu, ale nie zostały jeszcze zaimportowane do sesji, wpisz:

Get-Module -ListAvailable

Aby znaleźć moduły, które zostały już zaimportowane do sesji, w wierszu polecenia programu PowerShell wpisz:

Get-Module

Aby uzyskać więcej informacji na temat Get-Module polecenia cmdlet, zobacz Get-Module.

Jak znaleźć polecenia w module

Get-Command Użyj polecenia cmdlet , aby znaleźć wszystkie dostępne polecenia. Możesz użyć parametrów Get-Command polecenia cmdlet, aby filtrować polecenia, takie jak moduł, nazwa i noun.

Aby znaleźć wszystkie polecenia w module, wpisz:

Get-Command -Module <module-name>

Aby na przykład znaleźć polecenia w module BitsTransfer, wpisz:

Get-Command -Module BitsTransfer

Aby uzyskać więcej informacji na temat Get-Command polecenia cmdlet, zobacz Get-Command.

Jak uzyskać pomoc dotyczącą poleceń w module

Jeśli moduł zawiera pliki Pomocy dla poleceń, które eksportuje, Get-Help polecenie cmdlet wyświetli tematy Pomocy. Użyj tego samego Get-Help formatu polecenia, którego można użyć, aby uzyskać pomoc dotyczącą dowolnego polecenia w programie PowerShell.

Począwszy od programu PowerShell 3.0, możesz pobrać pliki Pomocy dla modułu i pobrać aktualizacje do plików Pomocy, aby nigdy nie były przestarzałe.

Aby uzyskać pomoc dotyczącą poleceń w module, wpisz:

Get-Help <command-name>

Aby uzyskać pomoc online dla polecenia w module, wpisz:

Get-Help <command-name> -Online

Aby pobrać i zainstalować pliki pomocy dla poleceń w module, wpisz:

Update-Help -Module <module-name>

Aby uzyskać więcej informacji, zobacz Get-Help and Update-Help (Get-Help and Update-Help).

Jak zaimportować moduł

Może być konieczne zaimportowanie modułu lub zaimportowanie pliku modułu. Importowanie jest wymagane, gdy moduł nie jest zainstalowany w lokalizacjach określonych przez zmienną środowiskową PSModulePath , $env:PSModulePathlub moduł składa się z pliku, takiego jak plik .dll lub psm1, zamiast typowego modułu dostarczanego jako folder.

Możesz również zaimportować moduł, aby można było użyć parametrów Import-Module polecenia, takich jak parametr prefiksu, który dodaje charakterystyczny prefiks do nazw un wszystkich zaimportowanych poleceń lub parametru NoClobber , co uniemożliwia modułowi dodawanie poleceń, które ukrywałyby lub zastępowały istniejące polecenia w sesji.

Aby zaimportować moduły, użyj Import-Module polecenia cmdlet .

Aby zaimportować moduły w lokalizacji PSModulePath do bieżącej sesji, użyj następującego formatu polecenia.

Import-Module <module-name>

Na przykład następujące polecenie importuje moduł BitsTransfer do bieżącej sesji.

Import-Module BitsTransfer

Aby zaimportować moduł, który nie znajduje się w domyślnej lokalizacji modułu, użyj w pełni kwalifikowanej ścieżki do folderu modułu w poleceniu .

Aby na przykład dodać moduł TestCmdlets w C:\ps-test katalogu do sesji, wpisz:

Import-Module C:\ps-test\TestCmdlets

Aby zaimportować plik modułu, który nie znajduje się w folderze modułu, użyj w pełni kwalifikowanej ścieżki do pliku modułu w poleceniu .

Aby na przykład dodać moduł TestCmdlets.dll w C:\ps-test katalogu do sesji, wpisz:

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

Aby uzyskać więcej informacji na temat dodawania modułów do sesji, zobacz Import-Module.

Jak zaimportować moduł do każdej sesji

Polecenie Import-Module importuje moduły do bieżącej sesji programu PowerShell. Aby zaimportować moduł do każdej uruchomionej sesji programu PowerShell, dodaj Import-Module polecenie do profilu programu PowerShell.

Aby uzyskać więcej informacji na temat profilów, zobacz about_Profiles.

Jak usunąć moduł

Po usunięciu modułu polecenia dodane przez moduł zostaną usunięte z sesji.

Aby usunąć moduł z sesji, użyj następującego formatu polecenia.

Remove-Module <module-name>

Na przykład następujące polecenie usuwa moduł BitsTransfer z bieżącej sesji.

Remove-Module BitsTransfer

Usunięcie modułu odwraca operację importowania modułu. Usunięcie modułu nie powoduje odinstalowania modułu. Aby uzyskać więcej informacji, zobacz Remove-Module (Usuwanie modułu).

Lokalizacje zasobów modułu i DSC oraz modułu PSModulePath

Zmienna $env:PSModulePath środowiskowa zawiera listę lokalizacji folderów, które są wyszukiwane w celu znalezienia modułów i zasobów.

Domyślnie obowiązują lokalizacje przypisane do $env:PSModulePath :

  • Lokalizacje dla całego systemu: $PSHOME\Modules

    Te foldery zawierają moduły dostarczane z systemem Windows i programem PowerShell.

    Zasoby DSC dołączone do programu PowerShell są przechowywane w folderze $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources .

  • Moduły specyficzne dla użytkownika: są to moduły instalowane przez użytkownika w zakresie użytkownika. Install-Module Ma parametr Zakres , który umożliwia określenie, czy moduł jest zainstalowany dla bieżącego użytkownika, czy dla wszystkich użytkowników. Aby uzyskać więcej informacji, zobacz Install-Module (Instalowanie modułu).

    Lokalizacja CurrentUser specyficzna dla użytkownika w systemie Windows to PowerShell\Modules folder znajdujący się w lokalizacji Dokumenty w profilu użytkownika. Określona ścieżka tej lokalizacji różni się w zależności od wersji systemu Windows i tego, czy używasz przekierowania folderów. Usługa Microsoft OneDrive może również zmienić lokalizację folderu Dokumenty .

    Domyślnie w Windows 10 i nowszych lokalizacja to $HOME\Documents\PowerShell\Modules. W systemie Linux lub Mac lokalizacja CurrentUser to $HOME/.local/share/powershell/Modules.

    Uwaga

    Lokalizację folderu Documents można sprawdzić za pomocą następującego polecenia: [Environment]::GetFolderPath('MyDocuments').

  • Lokalizacja AllUsers znajduje się $env:PROGRAMFILES\PowerShell\Modules w systemie Windows. W systemie Linux lub Mac moduły są przechowywane pod adresem /usr/local/share/powershell/Modules.

Uwaga

Aby dodać lub zmienić pliki w $env:Windir\System32 katalogu, uruchom program PowerShell z opcją Uruchom jako administrator .

Domyślne lokalizacje modułów w systemie można zmienić, zmieniając wartość zmiennej środowiskowej PSModulePath. $Env:PSModulePath Zmienna środowiskowa PSModulePath jest modelowana w zmiennej środowiskowej Path i ma ten sam format.

Aby wyświetlić domyślne lokalizacje modułów, wpisz:

$Env:PSModulePath

Aby dodać domyślną lokalizację modułu, użyj następującego formatu polecenia.

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

Średnik (;) w poleceniu oddziela nową ścieżkę od ścieżki, która poprzedza ją na liście.

Aby na przykład dodać C:\ps-test\Modules katalog, wpisz:

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

Aby dodać domyślną lokalizację modułu w systemie Linux lub MacOS, użyj następującego formatu polecenia:

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

Aby na przykład dodać /usr/local/Fabrikam/Modules katalog do wartości zmiennej środowiskowej PSModulePath , wpisz:

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

W systemie Linux lub MacOS dwukropek (:) w poleceniu oddziela nową ścieżkę od ścieżki poprzedzającej ją na liście.

Po dodaniu ścieżki do ścieżki PSModulePathGet-Module i Import-Module polecenia zawierają moduły w tej ścieżce.

Ustawiona wartość wpływa tylko na bieżącą sesję. Aby wprowadzić zmianę trwałą, dodaj polecenie do profilu programu PowerShell lub użyj polecenia System w Panel sterowania, aby zmienić wartość zmiennej środowiskowej PSModulePath w rejestrze.

Ponadto, aby wprowadzić zmianę jako trwałą, można również użyć metody SetEnvironmentVariable klasy System.Environment , aby dodać ścieżkę do zmiennej środowiskowej PSModulePath .

Aby uzyskać więcej informacji na temat zmiennej PSModulePath , zobacz about_Environment_Variables.

Moduły i konflikty nazw

Konflikty nazw występują, gdy więcej niż jedno polecenie w sesji ma taką samą nazwę. Importowanie modułu powoduje konflikt nazw, gdy polecenia w module mają takie same nazwy jak polecenia lub elementy w sesji.

Konflikty nazw mogą spowodować ukrycie lub zastąpienie poleceń.

Ukryty

Polecenie jest ukryte, gdy nie jest to polecenie uruchamiane podczas wpisywania nazwy polecenia, ale można go uruchomić przy użyciu innej metody, takiej jak kwalifikowanie nazwy polecenia z nazwą modułu lub przystawki, z której pochodzi.

Zastąpione

Polecenie jest zastępowane, gdy nie można go uruchomić, ponieważ zostało zastąpione przez polecenie o tej samej nazwie. Nawet po usunięciu modułu, który spowodował konflikt, nie można uruchomić zastąpionego polecenia, chyba że ponownie uruchomisz sesję.

Import-Module polecenie może dodawać polecenia, które ukrywają i zastępują polecenia w bieżącej sesji. Ponadto polecenia w sesji mogą ukrywać polecenia dodane przez moduł.

Aby wykryć konflikty nazw, użyj parametru Get-CommandAll polecenia cmdlet. Począwszy od programu PowerShell 3.0, Get-Command pobiera tylko te polecenia uruchamiane podczas wpisywania nazwy polecenia. Parametr All pobiera wszystkie polecenia o określonej nazwie w sesji.

Aby zapobiec konfliktom nazw, użyj parametrów NoClobber lub Prefiks polecenia Import-Module cmdlet. Parametr Prefiks dodaje prefiks do nazw importowanych poleceń, aby były unikatowe w sesji. Parametr NoClobber nie importuje żadnych poleceń, które mogłyby ukryć lub zastąpić istniejące polecenia w sesji.

Można również użyć aliasu, polecenia cmdlet, funkcji i zmiennej parametrów Import-Module , aby wybrać tylko polecenia, które chcesz zaimportować, i można wykluczyć polecenia, które powodują konflikty nazw w sesji.

Autorzy modułów mogą zapobiegać konfliktom nazw przy użyciu właściwości DefaultCommandPrefix manifestu modułu w celu dodania domyślnego prefiksu do wszystkich nazw poleceń. Wartość parametru Prefix ma pierwszeństwo przed wartością DefaultCommandPrefix.

Nawet jeśli polecenie jest ukryte, można go uruchomić, kwalifikując nazwę polecenia z nazwą modułu lub przystawki, z której pochodzi.

Reguły pierwszeństwa poleceń programu PowerShell określają, które polecenie jest uruchamiane, gdy sesja zawiera polecenia o tej samej nazwie.

Jeśli na przykład sesja zawiera funkcję i polecenie cmdlet o tej samej nazwie, program PowerShell domyślnie uruchamia funkcję. Gdy sesja zawiera polecenia tego samego typu o tej samej nazwie, takie jak dwa polecenia cmdlet o tej samej nazwie, domyślnie uruchamia ostatnio dodane polecenie.

Aby uzyskać więcej informacji, w tym wyjaśnienie reguł pierwszeństwa i instrukcje dotyczące uruchamiania ukrytych poleceń, zobacz about_Command_Precedence.

Moduły i przystawki

Polecenia można dodawać do sesji z modułów i przystawek. Moduły mogą dodawać wszystkie typy poleceń, w tym poleceń cmdlet, dostawców i funkcji oraz elementów, takich jak zmienne, aliasy i dyski programu PowerShell. Przystawki mogą dodawać tylko polecenia cmdlet i dostawców.

Przed usunięciem modułu lub przystawki z sesji użyj następujących poleceń, aby określić, które polecenia zostaną usunięte.

Aby znaleźć źródło polecenia cmdlet w sesji, użyj następującego formatu polecenia:

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

Aby na przykład znaleźć źródło Get-Date polecenia cmdlet, wpisz:

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

Polecenia eksportowane przez moduł powinny być zgodne z regułami nazewnictwa poleceń programu PowerShell. Jeśli moduł importowany eksportuje polecenia cmdlet lub funkcje, które mają niezatwierdzone czasowniki w nazwach, polecenie Import-Module cmdlet wyświetli następujący komunikat ostrzegawczy.

OSTRZEŻENIE: Niektóre zaimportowane nazwy poleceń obejmują niezatwierdzone czasowniki, które mogą sprawić, że będą one mniej wykrywalne. Użyj parametru Verbose, aby uzyskać więcej szczegółów lub wpisz Get-Verb, aby wyświetlić listę zatwierdzonych czasowników.

Ten komunikat jest tylko ostrzeżeniem. Cały moduł jest nadal importowany, w tym polecenia niezgodne. Mimo że komunikat jest wyświetlany dla użytkowników modułu, autor modułu powinien rozwiązać problem z nazewnictwem.

Aby pominąć komunikat ostrzegawczy, użyj parametru Import-ModuleDisableNameChecking polecenia cmdlet.

Wbudowane moduły i przystawki

W programie PowerShell 2.0 i starszych programach hosta w programie PowerShell 3.0 lub nowszym podstawowe polecenia instalowane przy użyciu programu PowerShell są pakowane w przystawkach dodawanych automatycznie do każdej sesji programu PowerShell.

Począwszy od programu PowerShell 3.0, w przypadku programów hosta, które implementują interfejs API stanu sesji początkowej InitialSessionState.CreateDefault2 , przystawka Microsoft.PowerShell.Core jest domyślnie dodawana do każdej sesji. Moduły są ładowane automatycznie podczas pierwszego użycia.

Uwaga

Sesje zdalne, w tym sesje, które są uruchamiane przy użyciu New-PSSession polecenia cmdlet, są sesjami w starszym stylu, w których wbudowane polecenia są pakowane w przystawki.

Następujące moduły (lub przystawki) są instalowane przy użyciu programu PowerShell.

  • Moduł 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
  • Element PSReadline

Rejestrowanie zdarzeń modułu

Począwszy od programu PowerShell 3.0, można rejestrować zdarzenia wykonywania dla poleceń cmdlet i funkcji w modułach programu PowerShell i przystawkach, ustawiając właściwość LogPipelineExecutionDetails modułów i przystawek na $Truewartość . Możesz również użyć ustawienia zasady grupy Włącz rejestrowanie modułu, aby włączyć rejestrowanie modułów we wszystkich sesjach programu PowerShell. Aby uzyskać więcej informacji, zobacz artykuły dotyczące rejestrowania i zasad grupy.

Zobacz też