about_Updatable_Help

  • Článek

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 nejaktuálnějším tématům nápovědy pro rutiny a koncepty PowerShellu.

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 vzdálenou vzdálenou komunikace prostředí Windows PowerShell, která umožňuje Save-Help pracovat pro moduly nainstalované ve vzdáleném počítači, ale nemusí být nutně nainstalovány na místním počítači. Objekt PSModuleInfo můžete uložit na disk nebo vyměnitelné médium (například jednotku USB) spuštěním Export-Clixml v počítači, který nemá přístup k internetu, importem objektu PSModuleInfo do počítače, který má přístup k internetu, a pak spuštěný Save-Help v objektu PSModuleInfo. Uloženou nápovědu lze zkopírovat do vzdáleného, odpojeného počítače pomocí vyměnitelného média a potom nainstalovat spuštěním Update-Helppříkazu . Tato vylepšení funkcí Save-Help umožňují nainstalovat nápovědu na počítače, které nejsou bez jakéhokoli druhu síťového přístupu. Příklad použití nové Save-Help funkce naleznete 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 internetové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, Get-Help zobrazí rutina automaticky vygenerovanou nápovědu a zobrazí výzvu ke stažení souborů nápovědy nebo jejich čtení 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 zobrazení, 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 například chcete 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 Správa istrators v počítači.

Pokud nejste členem skupiny Správa istrators, 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 pro moduly v adresáři $HOME/Documents/PowerShell/Modules nebo modulech v jiných podadresářích $HOME adresáře nevyžaduje zvláštní oprávnění.

Rutiny Update-Help mají parametr UseDefaultCredentials, který poskytuje explicitní přihlašovací údaje Save-Help 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 mají také parametr Credential, který umožňuje spustit příkaz na vzdáleném počítači a získat přístup ke sdílené složce Save-Help na třetím počítači. Parametr Credential je platný pouze v případě, že použijete parametry Update-Help SourcePath nebo LiteralPath parametru DestinationPathnebo LiteralPath parametru Save-Help.

Postup instalace a aktualizace souborů nápovědy

K prvnímu stažení a instalaci souborů nápovědy nebo aktualizaci souborů nápovědy v počítači použijte rutinu Update-Help .

Rutina Update-Help pro vás dělá veškerou tvrdou 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

Chcete-li aktualizovat nápovědu pro konkrétní moduly, přidejte parametr Module parametru Update-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 aktualizují 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, které vrací Get-Module -ListAvailable příkaz.

Pokud je * hodnota parametru Modulu (vše), Update-Help pokusí se 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 tuto 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á pro modul k dispozici žádné soubory nápovědy nebo novější soubory nápovědy, 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 \\Server\Share pro všechny nainstalované moduly do adresáře, zadejte:

Save-Help -DestinationPath \\Server\Share

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

Update-Help -SourcePath \\Server\Share

Následující příklady ukazují použití nápovědy 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 uložení nápovědy 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 rutiny získejte Invoke-Command objekt PSModuleInfo pro vzdálený modul, uložte ho do proměnné $ma pak spusťte Save-Help na objektu PSModuleInfo zadáním proměnné $m jako názvu 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 psSession cílenou na počítač, na kterém běží modul DHCP Server, abyste získali objekt PSModuleInfo modulu, uložte ho do proměnné $ma pak spusťte Save-Help na objektu, který je uložen v $m proměnné.

$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 objekt PSModuleInfo modulu, uložte ji do proměnné $ma pak spusťte Save-Help na objektu, který je uložen v $m proměnné.

$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 spusťte Export-Clixml export 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 pak importujte OBJEKT PSModuleInfo s Import-Clixml. Spuštěním uložte Save-Help nápovědu pro importovaný modul DhcpServer PSModuleInfo objektu.

$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 pak 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 bylo možné zahrnout moduly, musí být nainstalovány v adresářích, které jsou uvedeny v hodnotě $env:PSModulePath proměnné prostředí, na místním počítači nebo ve 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 Get-Help -ListAvailable příkazu.

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

Ve výchozím nastavení Update-Help si rutiny Save-Help stahují nápovědu v jazykové verzi uživatelského rozhraní a jazyku nastaveném pro 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í a Update-HelpSave-Help pomocí pravidel pro použití náhradní verze jazyka Windows vyhledejte nejlepší podporovaný jazyk.

Parametry UICulture těchto Update-Help rutin a Save-Help rutin ale můžete použít 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 Save-Help chybovou zprávu se seznamem jazyků, ve kterých je k dispozici nápověda pro jednotlivé moduly, Update-Help abyste mohli zvolit alternativu, která nejlépe vyhovuje vašim potřebám.

Poznámka:

V současné době je aktualizovatelný obsah nápovědy 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 rutinu Get-Job ve 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. Pokud se chcete podívat na témata týkající se PowerShellu, včetně témat nápovědy o jazyce PowerShellu, přečtěte si téma o tématech o 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 tuto 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 Update-Help úlohu, která spustí příkaz na všech počítačích. Nastavte hodnotu parametru SourcePath rutiny Update-Help na sdílenou síť.

Chcete-li uživatelům, kteří mají přístup k internetu, zabránit stahování aktualizovatelné nápovědy z internetu, použijte nastavení Nastavit výchozí zdrojovou cestu pro zásady skupiny Update-Help .

Toto nastavení zásad skupiny implicitně přidá parametr SourcePath se zadaným umístěním systému souborů ke každému Update-Help příkazu v každém ovlivněném počítači. Uživatelé můžou pomocí parametru SourcePath explicitně zadat jiné umístění systému souborů, ale nemůžou vyloučit parametr SourcePath a stáhnout nápovědu z internetu.

Poznámka:

V části Konfigurace počítače a Konfigurace uživatele se zobrazí výchozí zdrojová cesta pro nastavení zásad skupiny Update-Help. 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 najdete v tématu about_Group_Policy_Settings.

Aktualizace nápovědy pro nestandardní moduly

Chcete-li aktualizovat nebo uložit nápovědu pro modul, který není vrácen parametrem Get-Module ListAvailable rutiny, importujte modul do aktuální relace před spuštěním Update-Help příkazu nebo Save-Help příkazu. Na vzdáleném počítači před spuštěním Save-Help příkazu naimportujte modul do aktuální relace nebo Invoke-Command bloku skriptu, který je připojený ke vzdálenému počítači.

Pokud je modul v aktuální relaci, spusťte Update-Help rutiny Save-Help bez parametrů nebo použijte parametr Module k zadání názvu modulu.

Parametry Update-Help modulu a Save-Help rutiny přijímají pouze název modulu. Nepřijímají cestu k souboru modulu.

Tuto techniku použijte k aktualizaci nebo uložení nápovědy pro jakýkoli modul, který nevrátí parametr Get-Module ListAvailable rutiny, například modul nainstalovaný v umístění, které není uvedené v $env:PSModulePath proměnné prostředí, 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).

Jak podporovat aktualizovatelnou nápovědu

Pokud vytvoříte modul, můžete pro své moduly podporovat online nápovědu a aktualizovatelnou nápovědu. Další informace najdete v tématu Podpora aktualizovatelné nápovědy a podpory 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

Tyto Update-Help rutiny Save-Help nejsou podporovány v prostředí Windows Preinstallation Environment (Windows PE).

Viz také