Kötelező fejlesztői útmutató
A parancsmagok írásakor az alábbi irányelveket kell követni. Ezek a parancsmagok tervezésének irányelvei és a parancsmagkód megírásának irányelvei szerint vannak elválasztva. Ha nem követi ezeket az irányelveket, a parancsmagok sikertelenek lehetnek, és a felhasználók rossz élményben lehetnek a parancsmagok használata során.
Ebben a témakörben
Tervezési irányelvek
Kódra vonatkozó irányelvek
Származtatás a parancsmag- vagy PSCmdlet-osztályokból (RC01)
Parancsmagok Windows PowerShell üzembe helyezése egy új modullal (RC07)
Tervezési irányelvek
A parancsmagok tervezésekor az alábbi irányelveket kell követni, hogy egységes felhasználói élményt biztosítsunk a parancsmagok és más parancsmagok használata között. Ha az adott helyzetre vonatkozó tervezési útmutatót talál, mindenképpen nézze meg a hasonló irányelvekre vonatkozó kód-irányelveket.
Csak jóváhagyott műveletek használata (RD01)
A Parancsmag attribútumban megadott parancsnak a parancsmag által megadott felismert parancskészletből kell Windows PowerShell. Nem lehet a tiltott szinonimák egyike. A parancsmag-műveletek megadásához használja a következő enumerálások által meghatározott konstans sztringeket:
A jóváhagyott műveletek nevével kapcsolatos további információkért lásd: Parancsmag-műveletek.
A felhasználóknak felderíthető és várt parancsmagnevek készletére van szükségük. Használja a megfelelő igét, hogy a felhasználó gyorsan fel tudja használni a parancsmagok működését, és könnyen felfedezze a rendszer képességeit. Az alábbi parancssori parancs például lekért egy listát a rendszeren található összes olyan parancsról, amelynek a neve "start" kezdetű: get-command start-* . A parancsmagok főnevek használatával különbözteti meg a parancsmagokat a többi parancsmagtól. A főnév azt az erőforrást jelöli, amelyen a művelet végre lesz hajtva. Magát a műveletet a művelet képviseli.
Parancsmagok nevei: Nem használható karakterek (RD02)
A parancsmagok elnevezésekor ne használja az alábbi speciális karakterek egyikét.
| Karakter | Name |
|---|---|
| # | számjel |
| , | Vesszővel |
| () | Zárójel |
| {} | Fogszabályozó |
| [] | Zárójelben |
| & | Jel |
| - | kötőjel Megjegyzés: A kötőjellel elkülöníthető a főnévtől, de nem használható a főnéven belül vagy az igében. |
| / | perjel |
| \ | -perjel |
| $ | dollárjel |
| ^ | kalap jel |
| ; | Pontosvessző |
| : | Colon |
| " | dupla idézőjel |
| ' | egyszeres idézőjel |
| <> | szögletes zárójelek |
| | | függőleges sáv |
| ? | kérdőjel |
| @ | at sign (előjel) |
| ` | back tick (ékezet) |
| * | csillag |
| % | százalékjel |
| + | Pluszjel |
| = | egyenlőségjel |
| ~ | Tilde |
Nem használható paraméternevek (RD03)
Windows PowerShell egy közös paraméterkészletet biztosít az összes parancsmaghoz, valamint további paramétereket, amelyek adott helyzetekben vannak hozzáadva. Saját parancsmagok tervezésekor nem használhatja a következő neveket: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction és Verbose. További információ ezekről a paraméterekről: Általános paraméternevek.
Megerősítő kérések támogatása (RD04)
A rendszert módosító műveletet végző parancsmagok esetén meg kell hívniuk a System.Management.Automation.Cmdlet.ShouldProcess* metódust a megerősítés kéréséhez, és különleges esetekben a System.Management.Automation.Cmdlet.ShouldContinue* metódust. (A System.Management.Automation.Cmdlet.ShouldContinue* metódust csak a System.Management.Automation.Cmdlet.ShouldProcess* metódus neve után szabad meghívni.)
Ahhoz, hogy ezeket a hívásokat a parancsmag hívja meg, a Parancsmag attribútum kulcsszavának beállításával meg kell adnia, hogy támogatja-e a SupportsShouldProcess megerősítési kéréseket. Az attribútum beállításával kapcsolatos további információkért lásd: Parancsmag-attribútumdeklaráció.
Megjegyzés
Ha a parancsmagosztály Cmdlet attribútuma azt jelzi, hogy a parancsmag támogatja a System.Management.Automation.Cmdlet.ShouldProcess* metódus hívásait, és a parancsmag nem tudja a System.Management.Automation.Cmdlet.ShouldProcess* metódust hívni, a felhasználó váratlanul módosíthatja a rendszert.
A rendszer bármilyen módosításához használja a System.Management.Automation.Cmdlet.ShouldProcess* metódust. Egy felhasználói beállítás és WhatIf a paraméter a System.Management.Automation.Cmdlet.ShouldProcess* metódust ellenőrzi. Ezzel szemben a System.Management.Automation.Cmdlet.ShouldContinue* hívás egy további ellenőrzést végez a potenciálisan veszélyes módosítások után. Ezt a módszert nem vezérli semmilyen felhasználói beállítás vagy WhatIf paraméter. Ha a parancsmag a System.Management.Automation.Cmdlet.ShouldContinue* metódust hívja meg, akkor olyan paraméterrel kell, hogy legyen, amely megkerüli a két metódus hívásait, és folytatja a Force műveletet. Ez azért fontos, mert lehetővé teszi, hogy a parancsmag nem interaktív szkriptek és gazdagépek esetén is használható legyen.
Ha a parancsmagok támogatják ezeket a hívásokat, a felhasználó meghatározhatja, hogy a műveletet ténylegesen végre kell-e hajtanunk. A Stop-Process parancsmag például a System.Management.Automation.Cmdlet.ShouldContinue* metódust hívja meg, mielőtt leállít néhány kritikus folyamatot, köztük a System, a Winlogon és a Spoolsv folyamatokat.
A módszerek támogatásával kapcsolatos további információkért lásd: Megerősítés kérése.
Force paraméter támogatása interaktív munkamenetekhez (RD05)
Ha a parancsmagot interaktív módon használja, mindig adjon meg egy Force paramétert az interaktív műveletek felülbírálása érdekében, például a parancssorok vagy a bemeneti sorok olvasása). Ez azért fontos, mert lehetővé teszi, hogy a parancsmag nem interaktív szkriptek és gazdagépek esetén is használható legyen. Az interaktív gazdagépek a következő módszereket valósítják meg.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.Pshostuserinterface.PromptForChoice
System.Management.Automation.Host.Ihostuisupportsmultiplechoiceselection.PromptForChoice
System.Management.Automation.Host.Pshostuserinterface.PromptForCredential*
System.Management.Automation.Host.Pshostuserinterface.ReadLine*
System.Management.Automation.Host.Pshostuserinterface.ReadLineAsSecureString*
Dokumentum kimeneti objektumai (RD06)
Windows PowerShell a folyamatba írt objektumokat használja. Ahhoz, hogy a felhasználók kihasználják az egyes parancsmagok által visszaadott objektumokat, dokumentálni kell a visszaadott objektumokat, és dokumentálni kell, hogy mire használják a visszaadott objektumok tagjait.
Kódra vonatkozó irányelvek
Parancsmagkód írásakor az alábbi irányelveket kell követni. Ha az Ön helyzetére vonatkozó kód-útmutatót talál, mindenképpen nézze meg a hasonló irányelvek tervezési irányelveit.
Származtatás a parancsmag- vagy PSCmdlet-osztályokból (RC01)
A parancsmagnak a System.Management.Automation.Cmdlet vagy a System.Management.Automation.PSCmdlet alaposztályból kell származtatva lennie. A System.Management.Automation.Cmdlet osztályból származtatott parancsmagok nem függnek a Windows PowerShell futásidejűtől. Ezek közvetlenül hívhatóak bármely Microsoft .NET-keretrendszer nyelven. A System.Management.Automation.PSCmdlet osztályból származtatott parancsmagok a Windows PowerShell függnek. Ezért egy runspace-en belül futnak.
Minden implementált parancsmagosztálynak nyilvános osztályoknak kell lennie. A parancsmagosztályokkal kapcsolatos további információkért lásd: Parancsmagok áttekintése.
Adja meg a Parancsmag-attribútumot (RC02)
Ahhoz, hogy egy parancsmagot a Windows PowerShell felismerje, a .NET-keretrendszer osztályát a Cmdlet attribútummal kell együtt tartalmazni. Ez az attribútum a parancsmag következő funkcióit határozza meg.
A parancsmagot azonosító ige-főnév pár.
Az alapértelmezett paraméterkészlet, amely több paraméterkészlet megadásakor használatos. Az alapértelmezett paraméterkészlet akkor használatos, Windows PowerShell nem rendelkezik elegendő információval annak meghatározásához, hogy melyik paraméterkészletet szeretné használni.
Jelzi, hogy a parancsmag támogatja-e a System.Management.Automation.Cmdlet.ShouldProcess* metódus hívásait. Ez a metódus egy megerősítő üzenetet jelenít meg a felhasználónak, mielőtt a parancsmag módosítja a rendszert. A megerősítési kérések lekérésének mikéntről a Megerősítés kérése oldalon található további információ.
A megerősítő üzenethez társított művelet hatásszintje (vagy súlyossága). A legtöbb esetben a Közepes alapértelmezett értéket kell használni. További információ arról, hogy a hatásszint hogyan befolyásolja a felhasználó számára megjelenő megerősítési kéréseket: Megerősítés kérése.
A parancsmagattribútum deklarál lásd: CmdletAttribute Deklaráció.
Bemeneti feldolgozási módszer felülbírálása (RC03)
Ahhoz, hogy a parancsmag részt vegyen a Windows PowerShell környezetben, felül kell bírálni a következő bemeneti feldolgozási módszerek legalább egyikét.
System.Management.Automation.Cmdlet.BeginProcessing Ezt a metódust egyszer hívják meg, és előfeldolgozási funkciókat biztosít.
System.Management.Automation.Cmdlet.ProcessRecord Ez a metódus többször is meg van hívva, és rekordról rekordra vonatkozó funkciókat biztosít.
System.Management.Automation.Cmdlet.EndProcessing Ezt a metódust egyszer hívják meg, és utófeldolgozási funkciókat biztosít.
Adja meg az OutputType attribútumot (RC04)
Az OutputType attribútum (Windows PowerShell 2.0-ban bevezetett) .NET-keretrendszer a parancsmag által a folyamatnak visszaadott típust. A parancsmagok kimeneti típusának megadásával a parancsmag által visszaadott objektumokat jobban felderíthetővé teszi más parancsmagok számára. A parancsmagosztály ezzel az attribútummal való dekorálásával kapcsolatos további információkért lásd: OutputType attribútumdeklaráció.
Ne őrizze meg a kimeneti objektumok leíróit (RC05)
A parancsmag nem őrizze meg a System.Management.Automation.Cmdlet.WriteObject* metódusnak átadott objektumok leíróit. Ezeket az objektumokat a rendszer a folyamat következő parancsmagjának továbbkzi, vagy egy szkript használja őket. Ha megtartja az objektumok fogópontját, akkor minden objektumhoz két entitás lesz a tulajdonában, ami hibákat okoz.
A hibák robusztus kezelés (RC06)
A felügyeleti környezet eredendően észleli és fontos módosításokat tesz a felügyelendő rendszeren. Ezért létfontosságú, hogy a parancsmagok megfelelően kezelik a hibákat. További információ a hibarekordokkal kapcsolatban: Windows PowerShell hibajelentés.
Ha egy hiba megakadályozza, hogy egy parancsmag további rekordokat is feldolgozhat, az egy lezáró hiba. A parancsmagnak meg kell hívnia a System.Management.Automation.Cmdlet.ThrowTerminatingError* metódust, amely egy System.Management.Automation.ErrorRecord objektumra hivatkozik. Ha a parancsmag nem kap kivételt, maga a Windows PowerShell futásidejű futtatás olyan lezáró hibát jelez, amely kevesebb információt tartalmaz.
Ha a folyamatból következő rekordon (például egy másik folyamat által előállított rekordon) nem áll le művelet, a parancsmagnak meg kell hívnia a System.Management.Automation.Cmdlet.WriteError* metódust, amely egy System.Management.Automation.ErrorRecord objektumra hivatkozik. Megszakítást nem akadályozó hiba lehet például az a hiba, amely akkor fordul elő, ha egy adott folyamat nem áll le. A System.Management.Automation.Cmdlet.WriteError* metódus hívásával a felhasználó konzisztensen végrehajthatja a kért műveleteket, és megőrizze a sikertelen műveletek adatait. A parancsmagnak minden rekordot a lehető független módon kell kezelnie.
A System.Management.Automation.ErrorRecord objektumra, amelyre a System.Management.Automation.Cmdlet.ThrowTerminatingError* és a System.Management.Automation.Cmdlet.WriteError* metódusok hivatkoznak, kivételt igényel. Kövesse a .NET-keretrendszer irányelveit, amikor meghatározza a kivételt. Ha a hiba szemantikailag megegyezik egy meglévő kivétellel, használja ezt a kivételt, vagy származtasa ebből a kivételből. Ellenkező esetben közvetlenül a System.Exception típusból származtathat egy új kivételt vagy kivételhierarchiát.
A System.Management.Automation.ErrorRecord objektumhoz is szükség van egy hibakategóriára, amely a felhasználó hibáit sorolja fel. A felhasználó a kategória alapján megtekintheti a hibákat, ha a rendszerhéjváltozót CategoryView értékre $ErrorView beértékeli. A lehetséges kategóriákat a System.Management.Automation.ErrorCategory enumerálás határozza meg.
Ha egy parancsmag új szálat hoz létre, és a szálon futó kód nem kezelt kivételt ad vissza, a Windows PowerShell nem fogja kapni a hibát, és megszakítja a folyamatot.
Ha egy objektum a destruktorában olyan kódot tartalmaz, amely nem kezelt kivételt okoz, a Windows PowerShell nem fogja kapni a hibát, és megszakítja a folyamatot. Ez akkor is előfordul, ha egy objektum a Dispose metódusokat hívja meg, amelyek nem kezelt kivételt okoznak.
Parancsmagok Windows PowerShell üzembe helyezése egy új modullal (RC07)
Hozzon létre Windows PowerShell modult a parancsmagok becsomagolására és üzembe helyezésére. A modulok támogatása a 2.0 Windows PowerShell ban van bevezetve. A parancsmagosztályokat tartalmazó szerelvényeket használhatja közvetlenül bináris modulfájlokként (ez nagyon hasznos a parancsmagok tesztelésekor), vagy létrehozhat egy moduljegyzéket, amely a parancsmag-szerelvényekre hivatkozik. (A modulok használata esetén meglévő beépülő modul szerelvényeket is hozzáadhat.) A modulokkal kapcsolatos további információkért lásd: Writing a Windows PowerShell Module (Modul Windows PowerShell írása).
Lásd még:
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: