Udostępnij za pośrednictwem

Moduły — informacje

  • Artykuł

Krótki opis

Wyjaśnia sposób instalowania, importowania i używania modułów programu PowerShell.

Długi opis

Moduł to pakiet zawierający polecenia 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 samo jak polecenia wbudowane.

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

Co to jest moduł?

Moduł jest pakietem poleceń. Wszystkie polecenia cmdlet i dostawcy w sesji są dodawane przez moduł lub przystawkę.

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żesz używać poleceń w module bez żadnej konfiguracji lub konfiguracji profilu, więc nie trzeba zarządzać 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 znajdują się jeszcze w sesji, dzięki czemu można znaleźć polecenie i użyć go bez importowania.

Każdy z poniższych przykładów powoduje zaimportowanie Get-Mailbox modułu do sesji.

  • Uruchamianie polecenia

    Get-Mailbox -Identity Chris

  • Pobieranie polecenia

    Get-Command Get-Mailbox

  • Uzyskiwanie pomocy dotyczącej polecenia

    Get-Help Get-Mailbox

Get-Command polecenia, które zawierają symbol wieloznaczny (*) są uważane za przeznaczone do odnajdywania, nieumyślnie używane i nie importują żadnych modułów.

Importowane są tylko moduły przechowywane w lokalizacji określonej przez zmienną środowiskową PSModulePath. Moduły w innych lokalizacjach muszą być importowane przez uruchomienie Import-Module polecenia cmdlet .

Ponadto polecenia korzystające z dostawców programu PowerShell nie importują automatycznie modułu. Jeśli na przykład używasz polecenia wymagającego dysku WSMan, 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żesz uruchomić Import-Module polecenie , aby zaimportować moduł i użyć zmiennej $PSModuleAutoloadingPreference w celu włączenia, wyłączenia i skonfigurowania automatycznego importowania 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 za 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 o zarządzaniu modułami.

Jak zainstalować moduł

Jeśli otrzymasz moduł jako folder z plikami, 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 "podstawowymi" modułami. 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 na przykład Kreatora dodawania ról i funkcji w Menedżer serwera lub włączania lub wyłączania 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\WindowsPowerShell\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\WindowsPowerShell\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ę Moduły i Lokalizacje zasobów DSC oraz 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 eksportowanych poleceń, 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 dotyczącą 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 (Uzyskiwanie pomocy i aktualizowanie pomocy).

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 Prefix, który dodaje charakterystyczny prefiks do nazw noun wszystkich importowanych poleceń lub parametru NoClobber , co uniemożliwia modułowi dodawanie poleceń, które ukrywają lub zastępują 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łów i DSC oraz PSModulePath

Poniżej przedstawiono domyślne lokalizacje modułów programu PowerShell. Począwszy od programu PowerShell 4.0, wraz z wprowadzeniem rozszerzenia DSC wprowadzono nowy domyślny moduł i folder zasobów DSC. Aby uzyskać więcej informacji na temat rozszerzenia DSC, zobacz about_DesiredStateConfiguration.

  • System: $PSHOME\Modules lub ($env:windir\System32\WindowsPowerShell\v1.0\Modules) Moduły systemowe są dostarczane z systemami Windows i PowerShell.

    Począwszy od programu PowerShell 4.0, gdy wprowadzono Desired State Configuration programu PowerShell (DSC), zasoby DSC dołączone do programu PowerShell są również przechowywane w folderze $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources .$PSHOME\Modules

  • Bieżący użytkownik: $HOME\Documents\WindowsPowerShell\Modules ($env:UserProfile\Documents\WindowsPowerShell\Modules)

    lub

    $HOME\My Documents\WindowsPowerShell\Modules ($env:UserProfile\My Documents\WindowsPowerShell\Modules)

    Jest to lokalizacja modułów dodanych przez użytkownika przed programem PowerShell 4.0.

W programie PowerShell 4.0 i nowszych wersjach programu PowerShell moduły dodane przez użytkownika i zasoby DSC są przechowywane w programie C:\Program Files\WindowsPowerShell\Modules. Moduły i zasoby DSC w tej lokalizacji są dostępne dla wszystkich użytkowników komputera. Ta zmiana była wymagana, ponieważ aparat DSC działa jako system lokalny i nie mógł uzyskać dostępu do ścieżek specyficznych dla użytkownika, takich jak $home\Documents\WindowsPowerShell\Modules.

Począwszy od programu PowerShell 5.0 z dodatkiem modułu PowerShellGet oraz Galeria programu PowerShell zasobów społeczności i zasobów utworzonych przez firmę Microsoft, Install-Module polecenie domyślnie instaluje moduły i zasoby C:\Program Files\WindowsPowerShell\Modules DSC.

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 poprzedzającej ją na liście.

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

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

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

Aby uzyskać więcej informacji na temat przystawek programu PowerShell, zobacz about_PSSnapins.

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.

  • Microsoft.PowerShell.Archive
  • Microsoft.PowerShell.Core
  • Microsoft.PowerShell.Diagnostics
  • Microsoft.PowerShell.Host
  • Microsoft.PowerShell.Management
  • Microsoft.PowerShell.ODataUtils
  • Microsoft.PowerShell.Security
  • Microsoft.PowerShell.Utility
  • Microsoft.WSMan.Management
  • PackageManagement
  • PowerShellGet
  • PSDesiredStateConfiguration
  • Element PSReadline
  • PSScheduledJob
  • PSWorkflow
  • PSWorkflowUtility
  • Środowisko ISE

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 about_EventLogs i about_Group_Policy_Settings.

Zobacz też

about_Command_Precedence

about_DesiredStateConfiguration

about_EventLogs

about_Group_Policy_Settings

about_PSSnapins

Get-Command

Get-Help

Get-Module

Import-Module

Remove-Module