Instalace modulu PowerShellu

Článek
2025-03-25

Po vytvoření modulu PowerShellu budete pravděpodobně chtít modul nainstalovat do systému, abyste ho mohli používat vy nebo jiní uživatelé. Obecně řečeno, to se skládá z kopírování souborů modulu (tj. .psm1, nebo binárního sestavení, manifestu modulu a všech dalších přidružených souborů) do adresáře v tomto počítači. Pro velmi malý projekt to může být stejně jednoduché jako kopírování a vkládání souborů pomocí Průzkumníka Windows do jednoho vzdáleného počítače; u větších řešení však možná budete chtít použít sofistikovanější proces instalace. Bez ohledu na to, jak modul dostanete do systému, může PowerShell používat řadu technik, které uživatelům umožní najít a používat vaše moduly. Hlavním problémem instalace je proto to, že PowerShell bude moct váš modul najít. Další informace najdete v tématu Import modulu PowerShellu.

Pravidla pro instalaci modulů

Následující informace se týkají všech modulů, včetně modulů, které vytvoříte pro vlastní použití, modulů, které získáte od jiných stran, a modulů, které distribuujete ostatním.

Instalace modulů v PSModulePath

Kdykoli je to možné, nainstalujte všechny moduly do cesty uvedené v proměnné prostředí PSModulePath nebo přidejte cestu modulu do hodnoty proměnné prostředí PSModulePath proměnné prostředí.

Proměnná prostředí PSModulePath ($Env:PSModulePath) obsahuje umístění modulů Windows PowerShellu. Rutiny spoléhají na hodnotu této proměnné prostředí k vyhledání modulů.

Ve výchozím nastavení obsahuje PSModulePath hodnotu proměnné prostředí následující adresáře systémového a uživatelského modulu, ale můžete ji přidat a upravit.

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

Varování

Toto umístění je vyhrazené pro moduly, které se dodávají s Windows. Neinstalujte do tohoto umístění moduly.
$HOME\Documents\WindowsPowerShell\Modules (%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules)
$Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

Pokud chcete získat hodnotu proměnné prostředí PSModulePath, použijte některý z následujících příkazů.
```
$Env:PSModulePath
[Environment]::GetEnvironmentVariable("PSModulePath")
```
Chcete-li přidat cestu modulu k hodnotě PSModulePath hodnotu proměnné prostředí, použijte následující formát příkazu. Tento formát používá metodu SetEnvironmentVariable třídy System.Environment k vytvoření nezávislé relace na proměnné prostředí PSModulePath prostředí.
```
#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)
```
Důležité

Po přidání cesty k PSModulePathbyste měli vysílat zprávu prostředí o této změně. Vysílání změny umožňuje ostatním aplikacím, jako je prostředí, změnu vyzvednout. Pokud chcete změnu vysílat, požádejte kód instalace produktu, aby odeslal zprávu WM_SETTINGCHANGE s lParam nastavenou na řetězec Environment. Po aktualizaci kódu instalace modulu PSModulePathnezapomeňte zprávu odeslat .

Použití správného názvu adresáře modulu

Dobře vytvořený modul je modul uložený v adresáři, který má stejný název jako základní název alespoň jednoho souboru v adresáři modulu. Pokud modul není správně vytvořený, Windows PowerShell ho nerozpozná jako modul.

Základní název souboru je název bez přípony názvu souboru. V dobře vytvořeném modulu musí název adresáře, který obsahuje soubory modulů, odpovídat základnímu názvu alespoň jednoho souboru v modulu.

Například v ukázkovém modulu Fabrikam má adresář obsahující soubory modulů název "Fabrikam" a alespoň jeden soubor má základní název Fabrikam. V tomto případě mají Fabrikam.psd1 i Fabrikam.dll základní název "Fabrikam".

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

Účinek nesprávné instalace

Pokud modul není správně vytvořený a jeho umístění není zahrnuto v hodnotě PSModulePath proměnné prostředí, základní funkce zjišťování prostředí Windows PowerShell, například následující, nefungují.

Funkce automatického načítání modulu nemůže modul importovat automaticky.
Parametr ListAvailable rutiny Get-Module nemůže modul najít.
Rutina Import-Module nemůže modul najít. Pokud chcete modul importovat, musíte zadat úplnou cestu k souboru kořenového modulu nebo souboru manifestu modulu.

Další funkce, například následující, nefungují, pokud se modul nenaimportuje do relace. V dobře formátovaných modulech v proměnné prostředí PSModulePath tyto funkce fungují i v případě, že modul není importován do relace.
Rutina Get-Command nemůže v modulu najít příkazy.
Rutiny Update- Help a Save-Help nemůžou aktualizovat ani uložit nápovědu pro modul.
Rutina Show-Command nemůže najít a zobrazit příkazy v modulu.

Příkazy v modulu chybí v okně Show-Command v integrovaném skriptovacím prostředí Windows PowerShellu (ISE).

Kde instalovat moduly

Tato část vysvětluje, kde se v systému souborů instalují moduly Windows PowerShellu. Umístění závisí na tom, jak se modul používá.

Instalace modulů pro konkrétního uživatele

Pokud vytvoříte vlastní modul nebo ho získáte od jiné strany, například z webu komunity Windows PowerShellu, a chcete, aby byl modul dostupný jenom pro váš uživatelský účet, nainstalujte modul do adresáře modulů specifických pro uživatele.

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

Adresář modulů specifický pro uživatele se ve výchozím nastavení přidá do hodnoty proměnné prostředí PSModulePath.

Instalace modulů pro všechny uživatele v programových souborech

Pokud chcete, aby byl modul dostupný pro všechny uživatelské účty v počítači, nainstalujte modul do umístění Program Files.

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

Poznámka:

Umístění Program Files se ve výchozím nastavení přidá do hodnoty proměnné prostředí PSModulePath ve Windows PowerShellu 4.0 a novějším. Pro starší verze Windows PowerShellu můžete ručně vytvořit umístění Program Files (%ProgramFiles%\WindowsPowerShell\Modules) a přidat tuto cestu k proměnné prostředí PSModulePath, jak je popsáno výše.

Instalace modulů v adresáři produktů

Pokud modul distribuujete jiným stranám, použijte výchozí umístění Program Files popsané výše nebo vytvořte vlastní podadresář konkrétní společnosti nebo produktový podadresář adresáře %ProgramFiles%.

Například Fabrikam Technologies, fiktivní společnost, dodává modul Windows PowerShellu pro produkt Fabrikam Manager. Instalační program modulu vytvoří podadresář Modulů v podadresáři produktu Fabrikam Manager.

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

Aby instalační program modulu Fabrikam mohl vyhledat funkce zjišťování modulu Prostředí Windows PowerShell, přidá instalační program modulu Fabrikam umístění modulu k hodnotě PSModulePath proměnné prostředí.

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

Instalace modulů v adresáři Common Files

Pokud modul používá více komponent produktu nebo více verzí produktu, nainstalujte modul do podadresáře konkrétního modulu podadresáře %ProgramFiles%\Common Files\Modules.

V následujícím příkladu se modul Fabrikam nainstaluje do podadresáře Fabrikam podadresáře %ProgramFiles%\Common Files\Modules. Všimněte si, že každý modul se nachází ve svém vlastním podadresáři v podadresáři Modulů.

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

Instalační program pak zajistí hodnotu proměnné prostředí PSModulePath zahrnuje cestu podadresáře 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)

Instalace více verzí modulu

Pokud chcete nainstalovat více verzí stejného modulu, použijte následující postup.

Vytvořte adresář pro každou verzi modulu. Do názvu adresáře zadejte číslo verze.
Vytvořte manifest modulu pro každou verzi modulu. Do hodnoty klíče ModuleVersion v manifestu zadejte číslo verze modulu. Uložte soubor manifestu (.psd1) do adresáře specifického pro verzi modulu.
Přidejte cestu ke kořenové složce modulu k hodnotě proměnné prostředí PSModulePath, jak je znázorněno v následujících příkladech.

K importu konkrétní verze modulu může koncový uživatel použít parametry MinimumVersion nebo RequiredVersion rutiny Import-Module.

Pokud je například modul Fabrikam dostupný ve verzích 8.0 a 9.0, může adresářová struktura modulu Fabrikam vypadat přibližně takto.

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)

Instalační program přidá obě cesty modulu do PSModulePath hodnotu proměnné prostředí.

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

Po dokončení těchto kroků získá parametr ListAvailable rutiny Get-Module oba moduly Fabrikam. K importu konkrétního modulu použijte parametry MinimumVersion nebo RequiredVersion rutiny Import-Module.

Pokud se oba moduly naimportují do stejné relace a moduly obsahují rutiny se stejnými názvy, jsou rutiny importované jako poslední v relaci efektivní.

Zpracování konfliktů názvů příkazů

Ke konfliktům názvů příkazů může dojít, když příkazy, které modul exportuje, mají stejný název jako příkazy v relaci uživatele.

Pokud relace obsahuje dva příkazy se stejným názvem, windows PowerShell spustí typ příkazu, který má přednost. Pokud relace obsahuje dva příkazy se stejným názvem a stejným typem, spustí Windows PowerShell příkaz, který byl přidán do relace naposledy. Pokud chcete spustit příkaz, který není ve výchozím nastavení spuštěný, mohou uživatelé kvalifikovat název příkazu s názvem modulu.

Pokud například relace obsahuje funkci Get-Date a rutinu Get-Date, spustí windows PowerShell funkci ve výchozím nastavení. Pokud chcete spustit rutinu, před příkazem zadejte název modulu, například:

Microsoft.PowerShell.Utility\Get-Date

Aby se zabránilo konfliktům názvů, můžou autoři modulů použít DefaultCommandPrefix klíč v manifestu modulu k zadání předpony podstatných jmen pro všechny příkazy exportované z modulu.

Uživatelé mohou k použití alternativní předpony použít parametr Prefix rutiny Import-Module. Hodnota parametru Prefix má přednost před hodnotou klíče DefaultCommandPrefix.

Podpůrné cesty na jiných systémech než Windows

Jiné platformy než Windows používají znak dvojtečky (:) jako oddělovač cest a znak lomítka (/) jako oddělovač adresářů. Třída [System.IO.Path] má statické členy, které lze použít k tomu, aby váš kód fungoval na libovolné platformě:

[System.IO.Path]::PathSeparator – vrátí znak použitý k oddělení cest v proměnné prostředí PATH pro hostitelskou platformu.
[System.IO.Path]::DirectorySeparatorChar – vrátí znak použitý k oddělení názvů adresářů s cestou pro platformu hostitele.

Tyto statické vlastnosti použijte místo ; a \ znaků při vytváření řetězců cest.

Viz také

o_Přednost_Příkazů

psaní modulu Windows PowerShellu

Sdílet prostřednictvím