O aktualizovatelné nápovědě

Krátký popis

Popisuje aktualizovatelný systém nápovědy v PowerShellu.

Dlouhý popis

PowerShell nabízí několik různých způsobů přístupu k nejvíce up-totémat nápovědy k powershellovým rutinám a konceptům.

Systém aktualizovatelné nápovědy představený v PowerShellu 3.0 je navržený tak, aby vám zajistil, že budete mít vždy nejnovější témata nápovědy na místním počítači, abyste je mohli číst na příkazovém řádku. Usnadňuje stahování a instalaci souborů nápovědy a jejich aktualizaci vždy, když budou k dispozici novější soubory nápovědy.

Chcete-li poskytnout aktualizovanou nápovědu pro více počítačů v podniku a pro počítače, které nemají přístup k internetu, umožňuje aktualizovatelná nápověda stáhnout soubory nápovědy do adresáře systému souborů nebo sdílené složky a potom nainstalovat soubory nápovědy ze sdílené složky.

V PowerShellu 4.0 je vlastnost HelpInfoUri zachována přes Windows PowerShell remoting, což umožňuje Save-Help pracovat pro moduly nainstalované ve vzdáleném počítači, ale nemusí být nutně nainstalované na lokálním počítači. Můžete uložit PSModuleInfo objekt na disk nebo vyměnitelné médium (například jednotku USB) spuštěním Export-Clixml na počítači, který nemá přístup k internetu, importováním PSModuleInfo objektu do počítače, který má přístup k internetu, a spuštěním Save-Help na PSModuleInfo objektu. Uloženou nápovědu lze zkopírovat do vzdáleného, odpojeného počítače pomocí vyměnitelného média a nainstalovat spuštěním Update-Help. Tato vylepšení funkcí Save-Help umožňují nainstalovat nápovědu na počítače, které nemají přístup k síti. Příklad použití nové funkce Save-Help najdete v části Jak aktualizovat nápovědu ze sdílené složky v tomto tématu.

Aktualizovatelná nápověda také podporuje online přístup k nejnovějším tématům nápovědy a základní nápovědě pro rutiny, i když v počítači nejsou žádné soubory nápovědy.

PowerShell neobsahuje soubory nápovědy. Pomocí funkce Aktualizovatelná nápověda můžete nainstalovat soubory nápovědy pro všechny příkazy, které jsou ve výchozím nastavení součástí PowerShellu a pro všechny moduly Windows.

Aktualizovatelné rutiny nápovědy

• Update-Help: Stáhne nejnovější soubory nápovědy z internetu nebo sdílené složky a nainstaluje je do místního počítače.

• Save-Help: Stáhne nejnovější soubory nápovědy z internetu a uloží je do adresáře systému souborů nebo sdílené složky. Chcete-li nainstalovat soubory nápovědy do počítačů, použijte Update-Help.

• Get-Help: Zobrazí témata nápovědy na příkazovém řádku. Získá nápovědu ze souborů nápovědy v počítači. Zobrazí automaticky vygenerovanou nápovědu pro rutiny a funkce, které nemají soubory nápovědy. Otevře online témata nápovědy pro rutiny, funkce, skripty a pracovní postupy ve výchozím webovém prohlížeči.

Automaticky generovaná nápověda: Nápověda bez souborů nápovědy

Pokud v počítači nemáte soubor nápovědy pro rutinu, funkci nebo pracovní postup, zobrazí rutina Get-Help automaticky vygenerovanou nápovědu a vyzve vás, abyste si stáhli soubory nápovědy nebo je přečetli online.

Automaticky generovaná nápověda zahrnuje syntaxi a aliasy a poznámky, které vysvětlují, jak používat rutiny aktualizovatelné nápovědy a jak získat přístup k online tématům nápovědy.

Například následující příkaz získá základní nápovědu pro rutinu Get-Culture. Výstup zobrazí Get-Help, když v počítači nejsou žádné soubory nápovědy.

Get-Help Get-Culture

NAME
    Get-Culture

SYNTAX
    Get-Culture [<CommonParameters>]

ALIASES
    None

REMARKS
    To get the latest Help content including descriptions and examples
    type: Update-Help.

Soubory nápovědy pro moduly

Nejmenší jednotka aktualizovatelné nápovědy je pomoc pro modul. Nápověda k modulu obsahuje nápovědu ke všem rutinám, funkcím, pracovním postupům, poskytovatelům, skriptům a konceptům v modulu. Můžete aktualizovat nápovědu pro všechny moduly nainstalované v počítači, i když nejsou importovány do aktuální relace.

Můžete aktualizovat nápovědu pro celý modul, ale nemůžete aktualizovat nápovědu pro jednotlivé rutiny.

Pokud chcete najít modul obsahující konkrétní rutinu, použijte následující formát příkazu:

(Get-Command <cmdlet-name>).ModuleName

Pokud chcete například najít modul, který obsahuje rutinu Set-ExecutionPolicy, zadejte:

(Get-Command Set-ExecutionPolicy).ModuleName

Pokud chcete aktualizovat nápovědu pro konkrétní modul, zadejte:

Update-Help -Module <ModuleName>

Pokud chcete například aktualizovat nápovědu pro modul, který obsahuje rutinu Set-ExecutionPolicy, zadejte:

Update-Help -Module Microsoft.PowerShell.Security

Oprávnění pro aktualizovatelnou nápovědu

Chcete-li aktualizovat nápovědu pro moduly v adresáři $PSHOME/Modules, musíte být členem skupiny Administrators v počítači.

Pokud nejste členem skupiny Administrators, nemůžete aktualizovat nápovědu pro tyto moduly; ale pokud máte přístup k internetu, můžete zobrazit nápovědu online.

Aktualizace nápovědy k modulům v adresáři $HOME/Documents/PowerShell/Modules nebo modulech v jiných podadresářích adresáře $HOME nevyžaduje zvláštní oprávnění.

Rutiny Update-Help a Save-Help mají parametr UseDefaultCredentials, který poskytuje explicitní přihlašovací údaje aktuálního uživatele. Tento parametr je určený pro přístup k zabezpečeným internetovým umístěním.

Rutiny Update-Help a Save-Help mají také parametr přihlašovacích údajů, který umožňuje spustit příkaz na vzdáleném počítači a přistupovat ke sdílené složce na třetím počítači. Parametr přihlašovacích údajů je platný pouze v případě, že použijete parametr SourcePath nebo LiteralPath parametrů Update-Help a DestinationPath nebo LiteralPath parametry Save-Help.

Postup instalace a aktualizace souborů nápovědy

Pokud chcete soubory nápovědy stáhnout a nainstalovat poprvé nebo aktualizovat soubory nápovědy v počítači, použijte rutinu Update-Help.

Cmdlet Update-Help za vás provede veškerou náročnou práci, včetně následujících úloh.

• Určuje, které moduly podporují aktualizovatelnou nápovědu.
• Najde umístění na internetu, kde každý modul ukládá soubory aktualizovatelné nápovědy.
• Porovná soubory nápovědy pro každý modul v počítači s nejnovějšími soubory nápovědy, které jsou k dispozici pro každý modul.
• Stáhne nové soubory z internetu.
• Rozbalí balíček souboru nápovědy.
• Ověřuje, že soubory jsou platné soubory nápovědy.
• Nainstaluje soubory nápovědy do podadresáře adresáře modulu specifického pro jazyk.

K získání přístupu k novým tématům nápovědy použijte rutinu Get-Help. Nemusíte restartovat PowerShell.

Pokud chcete nainstalovat nebo aktualizovat nápovědu pro všechny moduly v počítači, který podporuje aktualizovatelnou nápovědu, zadejte:

Update-Help

Pokud chcete aktualizovat nápovědu pro konkrétní moduly, přidejte parametr moduluUpdate-Help. V názvu modulu jsou povoleny zástupné znaky.

Pokud například chcete aktualizovat nápovědu pro modul ServerManager, zadejte:

Update-Help -Module ServerManager

Bez parametrů Update-Help aktualizuje nápovědu pro všechny moduly v relaci a pro všechny nainstalované moduly, které podporují Aktualizovatelnou Nápovědu. Aby bylo možné moduly zahrnout, musí být nainstalovány v adresářích, které jsou uvedeny v hodnotě proměnné prostředí PSModulePath. Jedná se také o moduly vrácené příkazem Get-Module -ListAvailable.

Pokud je hodnota parametru modulu* (vše), Update-Help se pokusí aktualizovat nápovědu pro všechny nainstalované moduly, včetně modulů, které nepodporují aktualizovatelnou nápovědu. Tento příkaz obvykle generuje mnoho chyb, protože rutina narazí na moduly, které nepodporují aktualizovatelnou nápovědu.

Aktualizace nápovědy ze sdílené složky

Pokud chcete podporovat počítače, které nejsou připojené k internetu, nebo řídit nebo zjednodušit aktualizaci v podniku, použijte rutinu Save-Help. Rutina Save-Help stáhne soubory nápovědy z internetu a uloží je do zadaného adresáře systému souborů.

Save-Help porovná soubory nápovědy v zadaném adresáři s nejnovějšími soubory nápovědy, které jsou k dispozici pro každý modul. Pokud adresář nemá žádné soubory nápovědy nebo jsou k dispozici novější soubory nápovědy pro modul, rutina Save-Help stáhne nové soubory z internetu. Soubory nápovědy se ale neodbalí ani nenainstalují.

Chcete-li nainstalovat nebo aktualizovat soubory nápovědy v počítači ze souborů nápovědy, které byly uloženy do adresáře systému souborů, použijte parametr SourcePath rutiny Update-Help. Rutina Update-Help identifikuje nejnovější soubory nápovědy, rozbalí je a ověří a nainstaluje je do podadresářů modulů specifických pro jazyk.

Pokud chcete například uložit nápovědu pro všechny nainstalované moduly do adresáře \\Server\Share, zadejte:

Save-Help -DestinationPath \\Server\Share

Pokud chcete aktualizovat nápovědu z adresáře \\Server\Share, zadejte:

Update-Help -SourcePath \\Server\Share

Následující příklady ukazují použití Save-Help k uložení nápovědy pro moduly, které nejsou nainstalované v místním počítači. V tomto příkladu správce spustí Save-Help, aby uložil nápovědu pro modul DhcpServer z klientského počítače připojeného k internetu bez instalace modulu DhcpServer nebo role serveru DHCP na místním počítači.

Možnost 1: Spuštěním Invoke-Command získejte objekt PSModuleInfo pro vzdálený modul, uložte ho do proměnné, $ma potom spusťte Save-Help na objektu PSModuleInfo zadáním proměnné $m jako název modulu.

$invokeCommandSplat = @{
    ComputerName = 'RemoteServer'
    ScriptBlock = { Get-Module -Name DhcpServer -ListAvailable }
}
$m = Invoke-Command @invokeCommandSplat
Save-Help -Module $m -DestinationPath C:\SavedHelp

Možnost 2: Otevřete modul PSSession cílený na počítač, na kterém běží modul DHCP Server, a získejte objekt PSModuleInfo modulu, uložte ho do proměnné $ma spusťte Save-Help na objektu, který je uložený v proměnné $m.

$s = New-PSSession -ComputerName RemoteServer
$m = Get-Module -PSSession $s -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

Možnost 3: Otevřete relaci CIM zaměřenou na počítač, na kterém běží modul DHCP Serveru, a získejte PSModuleInfo objekt modulu, uložte ji do proměnné $ma spusťte Save-Help na objektu, který je uložený v proměnné $m.

$c = New-CimSession -ComputerName RemoteServer
$m = Get-Module -CimSession $c -Name DhcpServer -ListAvailable
Save-Help -Module $m -DestinationPath C:\SavedHelp

V následujícím příkladu správce nainstaluje nápovědu pro modul SERVERU DHCP do počítače, který nemá přístup k síti.

Nejprve spuštěním Export-Clixml exportujte objekt PSModuleInfo do sdílené složky nebo do vyměnitelného média.

$m = Get-Module -Name DhcpServer -ListAvailable
Export-Clixml -Path E:\UsbDrive\DhcpModule.xml -InputObject $m

Dále přetáhněte vyměnitelné médium do počítače, který má přístup k internetu, a potom importujte objekt PSModuleInfo s Import-Clixml. Spuštěním Save-Help uložte nápovědu pro importovaný modul DhcpServer OBJEKT PSModuleInfo.

$deserialized_m = Import-Clixml E:\UsbDrive\DhcpModule.xml
Save-Help -Module $deserialized_m -DestinationPath E:\UsbDrive\SavedHelp

Nakonec přetáhněte vyměnitelné médium zpět do počítače, který nemá přístup k síti, a potom nainstalujte nápovědu spuštěním Update-Help.

Update-Help -Module DhcpServer -SourcePath E:\UsbDrive\SavedHelp

Bez parametrů Save-Help stáhne nápovědu pro všechny moduly v relaci a pro všechny nainstalované moduly, které podporují aktualizovatelnou nápovědu. Aby byly zahrnuty, musí být moduly nainstalovány v adresářích, které jsou uvedeny v hodnotě proměnné prostředí $Env:PSModulePath, buď v místním počítači, nebo na vzdáleném počítači, pro který chcete uložit nápovědu. Jedná se také o moduly vrácené spuštěním příkazu Get-Help -ListAvailable.

Aktualizace souborů nápovědy v různých jazycích

Ve výchozím nastavení rutiny Update-Help a Save-Help stahují pomoc v uživatelské kultuře a jazyce, který je nastaven ve Windows na místním počítači. Pokud soubory nápovědy pro zadané moduly nejsou k dispozici v místní jazykové verzi uživatelského rozhraní, Update-Help a Save-Help používají pravidla pro přechod na jinou jazykovou verzi v systému Windows k vyhledání nejlepšího podporovaného jazyka.

Můžete však použít parametry UICulture cmdletů Update-Help a Save-Help ke stažení a instalaci souborů nápovědy v libovolné jazykové verzi uživatelského rozhraní, ve kterých jsou k dispozici.

Pokud chcete například uložit nejnovější soubory nápovědy pro všechny moduly v relaci v japonštině (ja-JP) a francouzštině (fr-FR), zadejte:

Save-Help -Path \Server\Share -UICulture ja-JP, fr-FR

Pokud soubory nápovědy pro moduly nejsou dostupné v zadaných jazycích, vrátí rutiny Update-Help a Save-Help chybovou zprávu se seznamem jazyků, ve kterých je k dispozici nápověda pro jednotlivé moduly, abyste mohli zvolit alternativu, která nejlépe vyhovuje vašim potřebám.

Poznámka

Obsah aktualizovatelné nápovědy je v současné době publikován pouze v angličtině (en-US).

Jak používat online nápovědu

Pokud nemůžete nebo se rozhodnout, že soubory nápovědy na místním počítači neaktualizujete, můžete získat nejnovější soubory nápovědy online.

Pokud chcete otevřít online téma nápovědy pro libovolnou rutinu nebo funkci, použijte parametr Online rutiny Get-Help.

Například následující příkaz otevře online téma nápovědy pro cmdlet Get-Job ve vašem výchozím internetovém prohlížeči:

Get-Help Get-Job -Online

Pokud chcete získat online nápovědu ke skriptu, použijte parametr Online a úplnou cestu ke skriptu.

Parametr Online nefunguje s tématy o aplikaci. Informace o tématech powershellu, včetně témat nápovědy k jazyku PowerShell, najdete v tématu o tématech PowerShellu.

Jak minimalizovat nebo zabránit stahování z internetu

Pokud chcete minimalizovat stahování z internetu a poskytnout aktualizovatelnou nápovědu pro uživatele, kteří nejsou připojení k internetu, použijte rutinu Save-Help. Stáhněte si nápovědu z internetu a uložte ji do sdílené síťové složky. Pak vytvořte nastavení zásad skupiny nebo naplánovanou úlohu, která spouští příkaz Update-Help na všech počítačích. Nastavte hodnotu parametru SourcePath cmdletu Update-Help na síťové sdílení.

Pokud chcete zabránit uživatelům, kteří mají přístup k internetu, stahovat aktualizovatelnou nápovědu z internetu, použijte nastavení zásad skupiny Nastavit výchozí zdrojovou cestu pro Update-Help.

Toto nastavení zásad skupiny implicitně přidá parametr SourcePath s umístěním systému souborů, které zadáte, do každého Update-Help příkazu na každém ovlivněném počítači. Uživatelé mohou použít parametr SourcePath explicitně k určení jiného umístění systému souborů, ale nemůžou vyloučit parametr SourcePath a stáhnout nápovědu z internetu.

Poznámka

Nastavení zásad skupiny Nastavit výchozí zdrojovou cestu pro Update-Help se objevuje v části Konfigurace počítače a Konfigurace uživatele. Platí však pouze nastavení zásad v části Konfigurace počítače. Nastavení zásad v části Konfigurace uživatele se ignoruje.

Další informace naleznete v části about_Group_Policy_Settings.

Aktualizace nápovědy pro nestandardní moduly

Pokud chcete aktualizovat nebo uložit nápovědu pro modul, který nevrací parametr ListAvailable rutiny Get-Module, importujte modul do aktuální relace před spuštěním příkazu Update-Help nebo Save-Help. Před spuštěním Save-Help příkazu na vzdáleném počítači naimportujte modul do aktuální relace nebo Invoke-Command skriptublock, který je připojený ke vzdálenému počítači.

Pokud je modul v aktuální relaci, spusťte rutiny Update-Help nebo Save-Help bez parametrů nebo pomocí parametru Module zadejte název modulu.

Parametry modulu rutin Update-Help a Save-Help přijímají pouze název modulu. Nepovolují zadání cesty k souboru modulu.

Tuto techniku použijte k aktualizaci nebo uložení nápovědy pro jakýkoli modul, který nevrátí parametr ListAvailable rutiny Get-Module, například modul nainstalovaný v umístění, které není uvedené v proměnné prostředí $Env:PSModulePath, nebo modul, který není správně vytvořený (adresář modulu neobsahuje alespoň jeden soubor, jehož základní název je stejný jako název adresáře).

Podpora aktualizovatelné nápovědy

Pokud vytvoříte modul, můžete pro své moduly podporovat online nápovědu a aktualizovatelnou nápovědu. Další informace naleznete v tématu Podpora aktualizovatelné nápovědy a Podpora online nápovědy.

Aktualizovatelná nápověda není k dispozici pro moduly snap-in PowerShellu nebo nápovědu založenou na komentářích.

Poznámky

Rutiny příkazů Update-Help a Save-Help nejsou podporovány v prostředí Windows Preinstallation Environment (Windows PE).

Viz také

• nápovědy
• nápověda pro ukládání
• Update-Help