O_modułach

Krótki opis

Objaśnia sposób 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óre piszą polecenia, mogą używać modułów do organizowania poleceń i udostępniania ich innym osobom. Osoby, które otrzymują moduły, mogą dodawać polecenia w modułach do 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 Writing a PowerShell Module (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 skrypcie programu PowerShell, skompilowanej bibliotece DLL lub kombinacji obu tych elementów. Te pliki są zwykle grupowane razem w jednym katalogu. Aby uzyskać więcej informacji, zobacz Understanding a Windows PowerShell Module (Opis 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żesz używać poleceń w module bez żadnej konfiguracji konfiguracji ani 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 modułu w pierwszej kolejności.

Każdy z poniższych przykładów powoduje zaimportowanie do sesji modułu CimCmdlets, Get-CimInstancektóry zawiera plik .

  • Uruchamianie polecenia

    Get-CimInstance Win32_OperatingSystem
    
  • Pobierz polecenie

    Get-Command Get-CimInstance
    
  • Uzyskaj pomoc polecenia

    Get-Help Get-CimInstance
    

Get-Command Polecenia, które zawierają symbol wieloznaczny (*), są traktowane jako do odnajdywania, używania 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ć, uruchamiając polecenie Import-Module cmdlet .

Ponadto polecenia, które używają dostawców programu PowerShell, nie importowane automatycznie modułu. Jeśli na przykład używasz polecenia wymagającego dysku WSMan:, Get-PSSessionConfiguration takiego jak polecenie cmdlet, Import-Module może być konieczne uruchomienie polecenia cmdlet w celu zaimportowania modułu Microsoft.WSMan.ManagementWSMan:, który zawiera ten dysk.

Nadal możesz uruchomić polecenie Import-Module , aby $PSModuleAutoloadingPreference zaimportować moduł i użyć zmiennej , 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 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 dotyczące zarządzania 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 automatycznie. Program PowerShell zawiera kilka wstępnie zainstalowanych modułów, czasami nazywanych modułami podstawowymi . Na Windows opartych na systemie operacyjnym, 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 Windows przy użyciu na przykład Kreatora dodawania ról i funkcji w programie Menedżer serwera lub okna dialogowego Włączanie lub wyłączanie funkcji programu Windows w programie Panel sterowania są instalowane wszystkie moduły programu PowerShell, które są częścią tej funkcji. Wiele innych modułów jest instalowanych w instalatorze lub programie instalacyjnym.

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, aby skopiować folder, w tym Windows Explorer 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 folderu 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 sekcje Module i DSC Resource Locations oraz PSModulePath .

How to Find Installed Modules

Aby znaleźć moduły, które są zainstalowane w domyślnej lokalizacji modułu, ale jeszcze nie 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.

How to Find the Commands in a Module

Użyj polecenia Get-Command cmdlet , aby znaleźć wszystkie dostępne polecenia. Za pomocą parametrów polecenia cmdlet można Get-Command filtrować polecenia, takie jak moduł, nazwa i rzeczownik.

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 Uzyskaj pomoc 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óry jest używany do uzyskania pomocy dotyczącej 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 dla 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 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ą środowiskową PSModulePath $env:PSModulePathlub moduł składa się z pliku, takiego jak plik .dll lub psm1, zamiast typowego modułu dostarczanego jako folder.

Import-Module Możesz również zaimportować moduł, aby można było użyć parametrów polecenia, takich jak prefiks parametru, który dodaje prefiks prefiksu do nazw rzeczowników wszystkich zaimportowanych poleceń lub parametr NoClobber, który uniemożliwia modułowi dodawanie poleceń, które mogłyby ukryć lub zastąpić 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 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.

How to Import a Module into Every Session

Polecenie Import-Module importuje moduły do bieżącej sesji programu PowerShell. Aby zaimportować moduł do każdej sesji programu PowerShell, która jest uruchamiana, 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 dodane polecenia 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.

Moduły i lokalizacje zasobów DSC oraz ścieżka PSModulePath

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

Domyślnie efektywne lokalizacje przypisane do programu to $env:PSModulePath :

  • Lokalizacje całego systemu: $PSHOME\Modules

    Te foldery zawierają moduły, które są Windows programem PowerShell.

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

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

    Specyficzna dla użytkownika lokalizacja CurrentUser na Windows to PowerShell\Modules folder znajdujący się w lokalizacji Dokumenty w profilu użytkownika. Określonej ścieżki tej lokalizacji zależy od wersji Windows i czy używasz przekierowania folderu. Microsoft OneDrive także zmienić lokalizację folderu Dokumenty.

    Domyślnie w przypadku Windows 10 i wyższych lokalizacja to $HOME\Documents\PowerShell\Modules. W systemie Linux lub Mac bieżąca lokalizacja użytkownika to $HOME/.local/share/powershell/Modules.

    Uwaga

    Możesz sprawdzić lokalizację folderu Dokumenty przy użyciu następującego polecenia: [Environment]::GetFolderPath('MyDocuments').

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

Uwaga

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

Możesz zmienić domyślne lokalizacje modułów w systemie, zmieniając wartość zmiennej środowiskowej PSModulePath . $Env:PSModulePath Zmienna środowiskowa PSModulePath jest modelowana na 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ć katalog C:\ps-test\Modules , 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ć katalog /usr/local/Fabrikam/Modules 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 poprzedzanej na liście.

Po dodaniu ścieżki do ścieżki PSModulePath polecenia Get-Module Import-Module obejmują moduły w tej ścieżce.

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

Ponadto, aby zmiana została trwała, 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.

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 podczas wpisywania nazwy polecenia, ale można je uruchomić przy użyciu innej metody, takiej jak kwalifikowanie nazwy polecenia za pomocą nazwy 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 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 polecenia Get-Command cmdlet . Począwszy od programu PowerShell 3.0, program pobiera tylko te polecenia, Get-Command które są uruchamiane po wpisaniu nazwy polecenia. Wszystkie parametr pobiera wszystkie polecenia o określonej nazwie w sesji.

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

Możesz również użyć parametrów Alias, Cmdlet, Function i Variable Import-Module polecenia , aby wybrać tylko polecenia, które chcesz zaimportować, i wykluczyć polecenia, które powodują konflikty nazw w sesji.

Autorzy modułów mogą zapobiegać konfliktom nazw, używając 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 je uruchomić przez kwalifikowanie nazwy 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 takiej 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 opis reguł pierwszeństwa i instrukcje dotyczące uruchamiania ukrytych poleceń, zobacz about_Command_Precedence.

Moduły i przystawki

Do sesji można dodawać polecenia z modułów i przyciągnijek. 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 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 polecenia Get-Date 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 importowany moduł eksportuje polecenia cmdlet lub funkcje, które mają niezatwierdzone czasowniki w nazwach, Import-Module polecenie cmdlet wyświetli następujący komunikat ostrzegawczy.

OSTRZEŻENIE: Niektóre zaimportowane nazwy poleceń zawierają niezatwierdzone czasowniki, co może sprawić, że będą mniej wykrywalne. Użyj pełne parametru, aby uzyskać więcej szczegółów lub Get-Verb, aby wyświetlić listę zatwierdzonych zleceń.

Ten komunikat jest tylko ostrzeżeniem. Cały moduł jest nadal importowany, łącznie z niezgodnymi poleceniami. Mimo że komunikat jest wyświetlany użytkownikom modułu, autor modułu powinien rozwiązać problem z nazewnictwem.

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

Wbudowane moduły i przystawki

W programie PowerShell 2.0 i starszych wersjach programów hosta w programie PowerShell 3.0 lub nowszym podstawowe polecenia instalowane przy użyciu programu PowerShell są spakowane w przystawki, które są automatycznie dodawane do każdej sesji programu PowerShell.

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

Uwaga

Sesje zdalne, New-PSSession w tym sesje, które zostały uruchomione przy użyciu polecenia cmdlet, to sesje w starszym stylu, w których wbudowane polecenia są spakowane w przystawkach.

Następujące moduły (lub przystawki) są instalowane z programem PowerShell.

  • 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
  • DIAGNOSTYKA PS
  • 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 i przystawkach programu PowerShell, ustawiając właściwość LogPipelineExecutionDetails modułów i przyciągnięć na wartość $True. Możesz również użyć ustawienia zasady grupy, Włącz rejestrowanie modułów, 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ż