O modułach

Krótki opis

Objaśnienie sposobu 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óre piszą polecenia, mogą używać modułów do organizowania swoich poleceń i udostępniania ich innym. Osoby, które otrzymują moduły, mogą dodawać polecenia w modułach do swoich sesji programu PowerShell i używać ich tak samo jak wbudowanych poleceń.

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ł to pakiet poleceń. Wszystkie polecenia cmdlet i dostawcy w sesji są dodawani przez moduł lub przystawkę.

Automatyczne wczytywanie modułów

Począwszy od programu PowerShell 3.0, program PowerShell automatycznie importuje moduły przy pierwszym uruchomieniu dowolnego polecenia w zainstalowanym module. Teraz możesz używać poleceń w module bez żadnej konfiguracji ani konfiguracji profilu, więc nie ma potrzeby zarządzania modułami po ich zainstalowaniu 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ą one 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, że zawierający Get-Mailbox go moduł musi zostać zaimportowany do sesji.

Uruchamianie polecenia
```
Get-Mailbox -Identity Chris
```
Pobierz polecenie
```
Get-Command Get-Mailbox
```
Uzyskaj pomoc dotyczącą polecenia
```
Get-Help Get-Mailbox
```

Get-Command Polecenia, które zawierają symbol wieloznaczny (*), są traktowane jako przeznaczone do odnajdywania, a nie do użytku i nie importują żadnych modułów.

Automatycznie importowane są tylko moduły przechowywane w lokalizacji określonej przez zmienną środowiskową PSModulePath. Moduły w innych lokalizacjach należy zaimportować 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, które wymaga 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żna uruchomić Import-Module polecenie, aby zaimportować moduł i użyć zmiennej $PSModuleAutoloadingPreference do włączania, wyłączania i konfigurowania automatycznego importowania modułów. Aby uzyskać więcej informacji, zobacz about_Preference_Variables.

Jak korzystać z modułu

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

Zainstaluj moduł. (Często jest to robione za Ciebie).
Znajdź polecenia dodane przez moduł.
Użyj poleceń dodanych przez moduł.

W tym temacie wyjaśniono, jak wykonać te zadania. Zawiera również inne przydatne informacje na temat zarządzania modułami.

Jak zainstalować moduł

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

Większość modułów jest instalowana za Ciebie. Program PowerShell jest dostarczany z kilkoma wstępnie zainstalowanymi modułami, czasami nazywanymi 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ą preinstalowane. Podczas instalowania funkcji systemu Windows za pomocą na przykład Kreatora dodawania ról i funkcji w Menedżerze serwera lub okna dialogowego Włączanie lub wyłączanie funkcji systemu Windows w Panelu sterowania instalowane są wszystkie moduły programu PowerShell, które są częścią tej funkcji. Wiele innych modułów jest dostarczanych w instalatorze lub programie instalacyjnym, który instaluje moduł.

Użyj następującego polecenia, aby utworzyć katalog modułów dla bieżącego użytkownika:

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

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

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ę Lokalizacje zasobów modułu i DSC oraz PSModulePath .

Jak znaleźć zainstalowane moduły

Aby znaleźć moduły, które są zainstalowane w domyślnej lokalizacji modułu, ale nie zostały jeszcze zaimportowane do sesji, należy wpisać:

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

Użyj polecenia cmdlet Get-Command, aby znaleźć wszystkie dostępne polecenia. Możesz użyć parametrów polecenia cmdlet Get-Command do filtrowania poleceń na przykład według modułu, nazwy i rzeczownika.

Aby znaleźć wszystkie polecenia w module, wpisz:

Get-Command -Module <module-name>

Na przykład, aby znaleźć polecenia w module BitsTransfer, należy wpisać:

Get-Command -Module BitsTransfer

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

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

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

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

Aby uzyskać pomoc dotyczącą poleceń w module, należy wpisać:

Get-Help <command-name>

Aby uzyskać pomoc online dotyczącą poleceń w module, należy wpisać:

Get-Help <command-name> -Online

Aby pobrać i zainstalować pliki pomocy dla poleceń w module, należy wpisać:

Update-Help -Module <module-name>

Aby uzyskać więcej informacji, zobacz Get-Help i 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ą $env:PSModulePath lub moduł składa się z pliku, takiego jak plik .dll lub .psm1, a nie typowego modułu dostarczanego jako folder.

Można 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 rzeczowników wszystkich zaimportowanych poleceń, lub parametr NoClobber , który uniemożliwia modułowi dodawanie poleceń, które ukryłyby lub zastąpił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.

Na przykład, aby dodać moduł TestCmdlets w C:\ps-test katalogu do sesji, należy wpisać:

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 katalogu C:\ps-test 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 polecenie Import-Module 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.

Lokalizacje zasobów modułu i DSC oraz PSModulePath

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

System: $PSHOME\Modules lub ($env:windir\System32\WindowsPowerShell\v1.0\Modules) Moduły systemowe to te, które są dostarczane z systemem Windows i programem PowerShell.

Począwszy od programu PowerShell 4.0, po wprowadzeniu konfiguracji żądanego stanu programu PowerShell (DSC), zasoby DSC dołączone do programu PowerShell są również przechowywane w $PSHOME\Modulesfolderze $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources .
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 może uzyskać dostępu do ścieżek specyficznych dla użytkownika, takich jak $home\Documents\WindowsPowerShell\Modules.

Począwszy od programu PowerShell 5.0, z dodaniem modułu PowerShellGet i Galeria programu PowerShell zasobów społeczności i 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 katalogu $env:Windir\System32 , uruchom 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 wzorowana na zmiennej środowiskowej Path i ma ten sam format.

Aby wyświetlić domyślne lokalizacje modułów, należy wpisać:

$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 ją poprzedza na liście.

Na przykład, aby dodać katalog, C:\ps-test\Modules należy wpisać:

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

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

Ustawiona wartość ma wpływ tylko na bieżącą sesję. Aby zmiana była trwała, dodaj polecenie do profilu programu PowerShell lub użyj przystawki System w Panelu sterowania, aby zmienić wartość zmiennej środowiskowej PSModulePath w rejestrze.

Ponadto, aby zmiana była trwała, można również użyć metody SetEnvironmentVariable klasy System.Environment w celu dodania ścieżki do zmiennej środowiskowej PSModulePath .

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

Konflikty modułów i 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 poleceniem uruchamianym po wpisaniu nazwy polecenia, ale można je uruchomić przy użyciu innej metody, na przykład przez zakwalifikowanie nazwy polecenia 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 poleceniem o tej samej nazwie. Nawet po usunięciu modułu, który spowodował konflikt, nie można uruchomić zastąpionego polecenia, chyba że sesja zostanie ponownie uruchomiona.

Import-Module 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 All cmdletu Get-Command. Począwszy od programu PowerShell 3.0, pobiera tylko te polecenia, Get-Command które są uruchamiane po wpisaniu nazwy polecenia. Parametr All pobiera wszystkie polecenia o określonej nazwie w sesji.

Aby zapobiec konfliktom nazw, użyj parametrów NoClobber lub Prefix polecenia cmdlet Import-Module. Parametr Prefix dodaje prefiks do nazw importowanych poleceń, dzięki czemu są one unikatowe w sesji. Parametr NoClobber nie importuje żadnych poleceń, które mogłyby ukryć lub zastąpić istniejące polecenia w sesji.

Możesz również użyć aliasu , cmdletu , funkcji oraz parametrów zmiennej Import-Module, aby wybrać tylko polecenia, które chcesz zaimportować, oraz wykluczyć polecenia powodujące 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 prefiksu ma pierwszeństwo przed wartością DefaultCommandPrefix.

Nawet jeśli polecenie jest ukryte, można je uruchomić, kwalifikując nazwę polecenia do nazwy 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.

Na przykład gdy 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 za pomocą modułów i przystawek. Moduły mogą dodawać wszystkie typy poleceń, w tym polecenia cmdlet, dostawców i funkcje oraz elementy, takie jak zmienne, aliasy i dyski programu PowerShell. Przystawki mogą dodawać tylko cmdlety i dostawców.

Przed usunięciem modułu lub przystawki z sesji należy użyć 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 polecenia cmdlet Get-Date, 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 importowany moduł eksportuje polecenia cmdlet lub funkcje, które mają w nazwie niezatwierdzone czasowniki, Import-Module polecenie cmdlet wyświetla 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 użytkownikom modułu, problem z nazewnictwem powinien zostać rozwiązany przez autora modułu.

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

Wbudowane moduły i przystawki

W programie PowerShell 2.0 i w programach hosta starszego stylu w programie PowerShell 3.0 i nowszych podstawowe polecenia instalowane z programem PowerShell są pakowane w przystawki, które są dodawane automatycznie do każdej sesji programu PowerShell.

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

Uwaga / Notatka

Sesje zdalne, w tym sesje uruchamiane przy użyciu New-PSSession polecenia cmdlet, to sesje starszego stylu, w których wbudowane polecenia są spakowane w przystawki.

Następujące moduły (lub przystawki) są instalowane z programem 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
Zarządzanie pakietami
PowerShellGet
PSDesiredStateConfiguration
PSReadline
PSScheduledJob (Zadanie PSScheduled)
PSWorkflow (Przepływ informacji)
PSWorkflowUtility
ISE

Rejestrowanie zdarzeń modułu

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