Instalowanie modułu programu PowerShell

Artykuł
03/25/2025

Po utworzeniu modułu programu PowerShell prawdopodobnie zechcesz zainstalować moduł w systemie, dzięki czemu użytkownik lub inne osoby mogą z niego korzystać. Ogólnie rzecz biorąc, składa się to z kopiowania plików modułu (tj. .psm1lub zestawu binarnego, manifestu modułu i innych skojarzonych plików) do katalogu na tym komputerze. W przypadku bardzo małego projektu może to być tak proste, jak kopiowanie i wklejanie plików za pomocą Eksploratora Windows na jednym komputerze zdalnym; jednak w przypadku większych rozwiązań można użyć bardziej zaawansowanego procesu instalacji. Niezależnie od sposobu uzyskiwania modułu do systemu program PowerShell może użyć wielu technik, które umożliwią użytkownikom znajdowanie modułów i korzystanie z nich. W związku z tym głównym problemem podczas instalacji jest zapewnienie, że program PowerShell będzie mógł znaleźć moduł. Aby uzyskać więcej informacji, zobacz Importowanie modułu programu PowerShell.

Reguły instalowania modułów

Poniższe informacje dotyczą wszystkich modułów, w tym modułów tworzonych do własnego użytku, modułów pobieranych z innych stron i modułów dystrybuowanych do innych osób.

Instalowanie modułów w programie PSModulePath

Jeśli to możliwe, zainstaluj wszystkie moduły w ścieżce wymienionej w psModulePath zmiennej środowiskowej lub dodaj ścieżkę modułu do PSModulePath wartości zmiennej środowiskowej.

Zmienna środowiskowa PSModulePath ($Env:PSModulePath) zawiera lokalizacje modułów programu Windows PowerShell. Polecenia cmdlet opierają się na wartości tej zmiennej środowiskowej w celu znalezienia modułów.

Domyślnie wartość zmiennej środowiskowej PSModulePath zawiera następujące katalogi systemów i modułów użytkownika, ale można dodać i edytować wartość.

$PSHOME\Modules (%windir%\System32\WindowsPowerShell\v1.0\Modules)

Ostrzeżenie

Ta lokalizacja jest zarezerwowana dla modułów, które są dostarczane z systemem Windows. Nie instaluj modułów w tej lokalizacji.
$HOME\Documents\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules)
$Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

Aby uzyskać wartość zmiennej środowiskowej PSModulePath, użyj jednego z następujących poleceń.
```
$Env:PSModulePath
[Environment]::GetEnvironmentVariable("PSModulePath")
```
Aby dodać ścieżkę modułu do wartości psModulePath wartości zmiennej środowiskowej, użyj następującego formatu polecenia. Ten format używa metody SetEnvironmentVariable klasy System.Environment w celu dokonania niezależnej od sesji zmiany zmiennej środowiskowej PSModulePath.
```
#Save the current value in the $p variable.
$p = [Environment]::GetEnvironmentVariable("PSModulePath")

#Add the new path to the $p variable. Begin with a semi-colon separator.
$p += ";C:\Program Files (x86)\MyCompany\Modules\"

#Add the paths in $p to the PSModulePath value.
[Environment]::SetEnvironmentVariable("PSModulePath",$p)
```
Ważne

Po dodaniu ścieżki do psModulePathnależy wysłać komunikat środowiska o zmianie. Rozgłaszanie zmiany umożliwia innym aplikacjom, takim jak powłoka, pobieranie zmian. Aby rozgłasić zmianę, kod instalacji produktu wysyła komunikat WM_SETTINGCHANGE z lParam ustawionym na ciąg "Środowisko". Pamiętaj, aby wysłać komunikat po zaktualizowaniu kodu instalacji modułu PSModulePath.

Użyj poprawnej nazwy katalogu modułu

Dobrze sformułowany moduł jest modułem przechowywanym w katalogu o takiej samej nazwie jak nazwa podstawowa co najmniej jednego pliku w katalogu modułu. Jeśli moduł nie jest dobrze sformułowany, program Windows PowerShell nie rozpoznaje go jako modułu.

Nazwa "podstawowa" pliku jest nazwą bez rozszerzenia nazwy pliku. W dobrze sformułowanym module nazwa katalogu zawierającego pliki modułu musi być zgodna z nazwą podstawową co najmniej jednego pliku w module.

Na przykład w przykładowym module Fabrikam katalog zawierający pliki modułu nosi nazwę "Fabrikam", a co najmniej jeden plik ma nazwę bazową "Fabrikam". W takim przypadku zarówno Fabrikam.psd1, jak i Fabrikam.dll mają podstawową nazwę "Fabrikam".

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Wpływ nieprawidłowej instalacji

Jeśli moduł nie jest prawidłowo sformułowany i jego lokalizacja nie jest uwzględniona w wartości PSModulePath zmiennej środowiskowej, podstawowe funkcje odnajdywania środowiska Windows PowerShell, takie jak poniższe, nie działają.

Funkcja automatycznego ładowania modułu nie może automatycznie zaimportować modułu.
Nie można odnaleźć modułu ListAvailable parametru polecenia cmdlet Get-Module.
Polecenie cmdlet Import-Module nie może odnaleźć modułu. Aby zaimportować moduł, należy podać pełną ścieżkę do głównego pliku modułu lub pliku manifestu modułu.

Dodatkowe funkcje, takie jak poniższe, nie działają, chyba że moduł zostanie zaimportowany do sesji. W dobrze sformułowanych modułach w zmiennej środowiskowej PSModulePath te funkcje działają nawet wtedy, gdy moduł nie zostanie zaimportowany do sesji.
Polecenie cmdlet get-command nie może znaleźć poleceń w module.
Polecenia cmdlet Update-Help i Save-Help nie mogą aktualizować ani zapisywać pomocy dla modułu.
Polecenie cmdlet Show-Command nie może odnaleźć i wyświetlić poleceń w module.

Brak poleceń w module w oknie Show-Command w zintegrowanym środowisku skryptów środowiska Windows PowerShell (ISE).

Gdzie zainstalować moduły

W tej sekcji wyjaśniono, gdzie w systemie plików do zainstalowania modułów programu Windows PowerShell. Lokalizacja zależy od sposobu użycia modułu.

Instalowanie modułów dla określonego użytkownika

Jeśli utworzysz własny moduł lub pobierzesz moduł z innej firmy, na przykład witryny sieci Web społeczności programu Windows PowerShell i chcesz, aby moduł był dostępny tylko dla twojego konta użytkownika, zainstaluj moduł w katalogu modułów specyficznych dla użytkownika.

$HOME\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Katalog Modules specyficzny dla użytkownika jest domyślnie dodawany do wartości zmiennej środowiskowej PSModulePath.

Instalowanie modułów dla wszystkich użytkowników w plikach programu

Jeśli chcesz, aby moduł był dostępny dla wszystkich kont użytkowników na komputerze, zainstaluj moduł w lokalizacji Program Files.

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

Uwaga

Lokalizacja Program Files jest domyślnie dodawana do wartości zmiennej środowiskowej PSModulePath w programie Windows PowerShell 4.0 lub nowszym. W przypadku wcześniejszych wersji programu Windows PowerShell można ręcznie utworzyć lokalizację plików programu (%ProgramFiles%\WindowsPowerShell\Modules) i dodać tę ścieżkę do zmiennej środowiskowej PSModulePath zgodnie z powyższym opisem.

Instalowanie modułów w katalogu produktów

Jeśli dystrybuujesz moduł do innych firm, użyj domyślnej lokalizacji Program Files opisanej powyżej lub utwórz własny podkatalog specyficzny dla firmy lub specyficzny dla produktu katalogu %ProgramFiles%.

Na przykład firma Fabrikam Technologies, fikcyjna firma, wysyła moduł programu Windows PowerShell dla swojego produktu Fabrikam Manager. Instalator modułu tworzy podkatalog Modules w podkatalogu produktu Fabrikam Manager.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

Aby włączyć funkcje odnajdywania modułów programu Windows PowerShell w celu znalezienia modułu Fabrikam, instalator modułu Fabrikam dodaje lokalizację modułu do wartości zmiennej środowiskowej PSModulePath.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Instalowanie modułów w katalogu Common Files

Jeśli moduł jest używany przez wiele składników produktu lub przez wiele wersji produktu, zainstaluj moduł w podkatalogu specyficznym dla modułu podkatalogu %ProgramFiles%\Common Files\Modules.

W poniższym przykładzie moduł Fabrikam jest instalowany w podkatalogu Fabrikam podkatalogu %ProgramFiles%\Common Files\Modules. Należy pamiętać, że każdy moduł znajduje się we własnym podkatalogu w podkatalogu Modules.

C:\Program Files
  Common Files
    Modules
      Fabrikam
        Fabrikam.psd1 (module manifest)
        Fabrikam.dll (module assembly)

Następnie instalator zapewnia wartość PSModulePath zmiennej środowiskowej zawiera ścieżkę podkatalogu Common Files\Modules.

$m = $Env:ProgramFiles + '\Common Files\Modules'
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$q = $p -split ';'
if ($q -notcontains $m) {
    $q += ";$m"
}
$p = $q -join ';'
[Environment]::SetEnvironmentVariable("PSModulePath", $p)

Instalowanie wielu wersji modułu

Aby zainstalować wiele wersji tego samego modułu, wykonaj poniższą procedurę.

Utwórz katalog dla każdej wersji modułu. Uwzględnij numer wersji w nazwie katalogu.
Utwórz manifest modułu dla każdej wersji modułu. W wartości klucza ModuleVersion w manifeście wprowadź numer wersji modułu. Zapisz plik manifestu (.psd1) w katalogu specyficznym dla wersji dla modułu.
Dodaj ścieżkę folderu głównego modułu do wartości zmiennej środowiskowej PSModulePath, jak pokazano w poniższych przykładach.

Aby zaimportować określoną wersję modułu, użytkownik końcowy może użyć parametrów MinimumVersion lub RequiredVersion polecenia cmdlet Import-Module.

Jeśli na przykład moduł Fabrikam jest dostępny w wersjach 8.0 i 9.0, struktura katalogów modułów Fabrikam może wyglądać podobnie do poniższego.

C:\Program Files
Fabrikam Manager
 Fabrikam8
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "8.0")
     Fabrikam.dll (module assembly)
 Fabrikam9
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "9.0")
     Fabrikam.dll (module assembly)

Instalator dodaje obie ścieżki modułu do wartości zmiennej środowiskowej PSModulePath.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

Po wykonaniu tych kroków parametr ListAvailable polecenia cmdlet Get-Module pobiera oba moduły Fabrikam. Aby zaimportować określony moduł, użyj parametrów MinimumVersion lub RequiredVersion polecenia cmdlet Import-Module.

Jeśli oba moduły są importowane do tej samej sesji, a moduły zawierają polecenia cmdlet o tych samych nazwach, polecenia cmdlet, które są importowane ostatnio, są skuteczne w sesji.

Obsługa konfliktów nazw poleceń

Konflikty nazw poleceń mogą wystąpić, gdy polecenia eksportowane przez moduł mają taką samą nazwę jak polecenia w sesji użytkownika.

Gdy sesja zawiera dwa polecenia o tej samej nazwie, program Windows PowerShell uruchamia typ polecenia, który ma pierwszeństwo. Gdy sesja zawiera dwa polecenia o tej samej nazwie i tym samym typie, program Windows PowerShell uruchamia polecenie, które zostało ostatnio dodane do sesji. Aby uruchomić polecenie, które nie jest uruchamiane domyślnie, użytkownicy mogą kwalifikować nazwę polecenia przy użyciu nazwy modułu.

Jeśli na przykład sesja zawiera funkcję Get-Date i polecenie cmdlet Get-Date, program Windows PowerShell domyślnie uruchamia funkcję. Aby uruchomić polecenie cmdlet, należy wstępnie poprzeć polecenie nazwą modułu, na przykład:

Microsoft.PowerShell.Utility\Get-Date

Aby zapobiec konfliktom nazw, autorzy modułów mogą użyć DefaultCommandPrefix klucza w manifeście modułu, aby określić prefiks rzeczownika dla wszystkich poleceń wyeksportowanych z modułu.

Użytkownicy mogą użyć prefiksu parametru polecenia cmdlet Import-Module, aby użyć alternatywnego prefiksu. Wartość parametru prefiksu ma pierwszeństwo przed wartością klucza DefaultCommandPrefix.

Ścieżki pomocnicze w systemach innych niż Windows

Platformy inne niż Windows używają znaku dwukropka (:) jako separatora ścieżki i ukośnika (/) jako separatora katalogu. Klasa [System.IO.Path] zawiera statyczne składowe, których można użyć do działania kodu na dowolnej platformie:

[System.IO.Path]::PathSeparator — zwraca znak używany do oddzielania ścieżek w zmiennej środowiskowej PATH dla platformy hosta
[System.IO.Path]::DirectorySeparatorChar — zwraca znak używany do oddzielania nazw katalogów ścieżką dla platformy hosta

Użyj tych właściwości statycznych, aby zamiast ; i \ znaków podczas tworzenia ciągów ścieżek.

Zobacz też

about_Command_Precedence

pisanie modułu programu Windows PowerShell

Udostępnij za pośrednictwem