Megosztás a következőn keresztül:

Súgó írása PowerShell-modulokhoz

A PowerShell-modulok tartalmazhatnak súgótémaköröket a modulról és a modultagokról, például parancsmagokról, szolgáltatókról, függvényekről és szkriptekről. A Get-Help parancsmag a modul súgótémaköröket ugyanúgy jeleníti meg, mint a többi PowerShell-elem súgóját, a felhasználók pedig szabványos Get-Help parancsokkal kapják meg a súgótémaköröket.

Ez a dokumentum ismerteti a modul súgótémaköreinek formátumát és helyes elhelyezését, és útmutatást nyújt a modul súgójának tartalmához.

A modultípusok súgója

A modulok a következő típusú súgót tartalmazhatják.

  • XML-alapú súgó

    • Parancsmag súgója. A modul parancsmagjait leíró súgótémakörök olyan XML-fájlok, amelyek a parancs súgósémát használják
    • Szolgáltatói súgó. A modulban szereplő szolgáltatókat leíró súgótémakörök olyan XML-fájlok, amelyek a szolgáltató súgósémát használják.
    • Függvény súgója. A modulban található függvényeket leíró súgótémakörök lehetnek olyan XML-fájlok, amelyek a parancssémát vagy a megjegyzésalapú súgótémaköröket használják a függvényen belül, illetve a szkript- vagy szkriptmodult
    • Szkript súgója. A modul szkripteit leíró súgótémakörök lehetnek XML-fájlok, amelyek a parancssémát vagy a megjegyzésalapú súgótémaköröket használják a szkriptben vagy a szkriptmodulban.
    • A $PSHOME\Schemas\PSMaml mappa tartalmazza az XML-formátumot meghatározó sémafájlokat.

  • Fogalmi ("Névjegy") súgószövegfájlok

    Egy fogalmi ("about") súgótémakörrel ismertetheti a modult és annak tagjait, és elmagyarázhatja, hogyan használhatók együtt a tagok a feladatok elvégzéséhez. A PowerShell alapértelmezés szerint több mint 100 fogalmi súgótémakört tartalmaz. A fájlnévnek a formátumot about_<name>.help.txt kell használnia, például about_MyModule.help.txt.

    Megjegyzés:

    A TOPIC szakaszfejlécnek a fájl első sorának első oszlopában kell kezdődnie. A második sorban lévő szakasz tartalmának meg kell egyeznie a fájlnével, az .help.txt utótag nélkül. A tartalmat pontosan 4 szóközzel kell behúzni. A harmadik sornak üresnek kell lennie. A SYNOPSIS szakaszfejlécnek a negyedik sor első oszlopában kell kezdődnie. Az ötödik sor tartalmát pontosan 4 szóközzel kell behúzni. Ezek a követelmények szükségesek ahhoz, hogy a Get-Help parancsmag megfelelően felismerje a tartalmat.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

    A következő mintasablon kiindulópontként használható a fogalmi súgótémakörök írásához. Az első két szakasz kivételével a fogalmi súgótémakörök felépítése tetszőleges. A fennmaradó szakaszcímek a tartalomnak megfelelőek lehetnek.

    TOPIC
    about_<subject or module name>

SYNOPSIS
    A short, one-line description of the topic contents.

LONG DESCRIPTION

A detailed, full description of the subject or purpose of the module.

EXAMPLES

Examples of how to use the module or how the subject feature works in
practice.

TROUBLESHOOTING

Instructions for resolving common problems.

SEE ALSO

Text-only references for further reading. Hyperlinks can't work in the
PowerShell console.

    Bármilyen stílust és korrektúrát használhat, de a PowerShell egyszerű szövegként látja, és a PowerShell-konzolon nincs speciális szövegmegjelenítés. Az alábbi javaslatok biztosítják a legjobb megjelenítési eredményeket és olvashatóságot.

    • Az UTF-8 és a BOM kódolással biztosíthatja, hogy a speciális (több bájtos) karakterek megfelelően jelenjenek meg.
    • Aláhúzhatja a szakaszfejléceket, vagy az összes nagybetűvel kiemelheti őket. Így a tartalom könnyebben beolvasható.
    • Az egyes sorok hosszát 80 karakterre korlátozhatja.
    • Kódblokkok és példakimenet behúzásával elválaszthatja őket a környező prózától.

A modul súgójának elhelyezése

A Get-Help parancsmag a modulkönyvtár nyelvspecifikus alkönyvtáraiban keresi a modul súgótémakör-fájljait.

Az alábbi könyvtárszerkezeti diagram például a Mintamodule modul súgótémakörökének helyét mutatja be.

<ModulePath>
    \SampleModule
        \<en-US>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml
        \<fr-FR>
            \about_SampleModule.help.txt
            \SampleModule.dll-help.xml
            \SampleNestedModule.dll-help.xml

Megjegyzés:

A példában a <ModulePath> helyőrző a környezeti változó egyik elérési útját jelöli, például PSModulePatha , $HOME\Documents\Modulesvagy a felhasználó által megadott egyéni elérési $PSHOME\Modules utat.

Modul súgójának lekérése

Amikor egy felhasználó importál egy modult egy munkamenetbe, a modul súgótémaköröket a modullal együtt importálja a munkamenetbe. A súgótémakör-fájlokat a moduljegyzék FileList kulcsának értékében listázhatja, de a Export-ModuleMember súgótémakörökre a parancsmag nem vonatkozik.

A modul súgótémaköröket különböző nyelveken is megadhatja. A Get-Help parancsmag automatikusan megjeleníti a modul súgótémaköreit a Vezérlőpult Területi és nyelvi beállítások elemében az aktuális felhasználó számára megadott nyelven. A Windows Vista és a Windows Get-Help újabb verzióiban a modulkönyvtár nyelvspecifikus alkönyvtáraiban található súgótémakörökre keres a Windowsra vonatkozó nyelvi tartalék szabványoknak megfelelően.

A PowerShell 3.0-tól kezdve egy Get-Help parancsmag vagy függvény parancsának futtatása aktiválja a modul automatikus importálását. A Get-Help parancsmag azonnal megjeleníti a modul súgótémaköreinek tartalmát.

Ha a modul nem tartalmaz súgótémaköröket, és nincsenek súgótémakörök a modul parancsaihoz a felhasználó számítógépén, Get-Help automatikusan létrehozott súgó jelenik meg. Az automatikusan létrehozott súgó tartalmazza a parancs szintaxisát, paramétereit, valamint a bemeneti és kimeneti típusokat, de nem tartalmaz leírásokat. Az automatikusan létrehozott súgó olyan szöveget tartalmaz, amely arra utasítja a felhasználót, hogy a parancsmag használatával Update-Help próbálja letölteni a parancs súgóját az internetről vagy egy fájlmegosztásból. Azt is javasolja, hogy használja a parancsmag Get-Help paraméterét a súgótémakör online verziójának lekéréséhez.

Frissíthető súgó támogatása

A PowerShell 3.0-s és újabb verzióinak felhasználói letölthetik és telepíthetik a modul frissített súgófájljait az internetről vagy egy helyi fájlmegosztásból. A Update-Help parancsmagok elrejtik Save-Help a felügyeleti adatokat a felhasználó elől. A felhasználók futtatják a Update-Help parancsmagot, majd a Get-Help parancsmaggal felolvassák a modul legújabb súgófájljait a PowerShell parancssorában. A felhasználóknak nem kell újraindítania a Windowst vagy a PowerShellt.

A tűzfalak mögött és az interneteléréssel nem rendelkező felhasználók is használhatnak frissíthető súgót. Az internet-hozzáféréssel rendelkező rendszergazdák a Save-Help parancsmag használatával tölthetik le és telepíthetik a legújabb súgófájlokat egy fájlmegosztásba. Ezután a felhasználók a parancsmag Elérési út paraméterével Update-Help szerezik be a legújabb súgófájlokat a fájlmegosztásból.

A modul szerzői súgófájlokat is tartalmazhatnak a modulban, és az Frissíthető súgó segítségével frissíthetik a súgófájlokat, vagy kihagyhatják a súgófájlokat a modulból, és az Frissíthető súgó segítségével telepítheti és frissítheti őket.

Az frissíthető súgóról további információt az Frissíthető súgó támogatásacímű témakörben talál.

Online súgó támogatása

Azok a felhasználók, akik nem tudnak vagy nem tudnak frissített súgófájlokat telepíteni a számítógépükre, gyakran a modul súgótémaköreinek online verziójára támaszkodnak. A parancsmag Online paramétere Get-Help megnyitja egy parancsmag vagy speciális függvény súgótémakörének online verzióját a felhasználó számára az alapértelmezett internetböngészőben.

A Get-Help parancsmag a parancsmag vagy függvény HelpUri tulajdonságának értékét használja a súgótémakör online verziójának megkereséséhez.

A PowerShell 3.0-tól kezdve segíthet a felhasználóknak megtalálni a parancsmag és a függvény súgótémaköreinek online verzióját a parancsmagosztály SúgóUri attribútumának vagy a CmdletBinding attribútum HelpUri tulajdonságának megadásával. Az attribútum értéke a parancsmag vagy függvény HelpUri tulajdonságának értéke.

További információt az Online támogatás súgójában talál.

Lásd még:

  • Last updated on