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

Nagyon ajánlott fejlesztési irányelvek

Ez a szakasz a parancsmagok írásakor követendő irányelveket ismerteti. Ezek a parancsmagok tervezésére és a parancsmagkód írására vonatkozó irányelvekre vannak elválasztva. Előfordulhat, hogy ezek az irányelvek nem alkalmazhatók minden forgatókönyvre. Ha azonban ezek érvényesek, és Ön nem követi ezeket az irányelveket, előfordulhat, hogy a felhasználók rossz felhasználói élményt tapasztalnak a parancsmagok használatakor.

Tervezési irányelvek

A parancsmagok tervezésekor a következő irányelveket kell követni, hogy egységes felhasználói élményt biztosítson a parancsmagok és más parancsmagok használata között. Ha olyan tervezési útmutatót talál, amely az Ön helyzetére vonatkozik, mindenképpen tekintse meg a kódra vonatkozó irányelveket a hasonló irányelvekhez.

Konkrét főnév használata cmdlet névhez (SD01)

A parancsmagok elnevezéséhez használt főneveknek nagyon specifikusnak kell lenniük, hogy a felhasználó felfedezhesse a parancsmagokat. Az általános főneveket, mint például a "kiszolgáló", lássa el a terméknév rövidített verziójával. Ha például egy főnév egy Microsoft SQL Server-példányt futtató kiszolgálóra hivatkozik, használjon egy főnevet, például az "SQLServer"-t. Az egyes főnevek és a jóváhagyott igék rövid listája lehetővé teszi a felhasználó számára, hogy gyorsan felderítse és előrejelezze a funkciókat, miközben elkerülheti a parancsmagok nevei közötti duplikációt.

A felhasználói élmény fokozása érdekében a parancsmag nevének választott főnévnek egyedinek kell lennie. Használja például a nevet Get-Process ahelyett, hogy Get-Processes. Ezt a szabályt érdemes követni az összes parancsmagnév esetében, még akkor is, ha egy parancsmag valószínűleg több elemet is használ.

Pascal-eset használata parancsmagnevekhez (SD02)

Használja a Pascal-esetet a paraméternevekhez. Más szóval, nagybetűvel kezdje az igék első betűjét és a főnévben használt összes kifejezést. Például: „Clear-ItemProperty”.

Paramétertervezési irányelvek (SD03)

A parancsmagoknak olyan paraméterekre van szükségük, amelyek megkapják azokat az adatokat, amelyeken működnie kell, valamint olyan paraméterekre, amelyek a művelet jellemzőinek meghatározásához használt információkat jelzik. Előfordulhat például, hogy egy Name parancsmag olyan paraméterrel rendelkezik, amely adatokat fogad a folyamatból, és a parancsmag rendelkezhet egy Force paraméterrel, amely azt jelzi, hogy a parancsmag kényszeríthető a művelet végrehajtására. A parancsmagok által definiálható paraméterek száma nincs korlátozva.

Standard paraméternevek használata

A parancsmagnak szabványos paraméterneveket kell használnia, hogy a felhasználó gyorsan megállapíthassa, mit jelent egy adott paraméter. Ha pontosabb névre van szükség, használjon egy szabványos paraméternevet, majd adjon meg egy pontosabb nevet aliasként. A parancsmag például egy olyan paraméterrel rendelkezik, Get-Service amely egy általános névvel (Name) és egy konkrétabb aliassal (ServiceName) rendelkezik. Mindkét kifejezés használható a paraméter megadásához.

A paraméterek nevével és adattípusokkal kapcsolatos további információkért lásd a parancsmag paraméternevének és funkcióinak irányelveit.

Szingular paraméternevek használata

Ne használjon többes számú nevet olyan paraméterekhez, amelyek értéke egyetlen elem. Ide tartoznak azok a paraméterek, amelyek tömböket vagy listákat vesznek fel, mert előfordulhat, hogy a felhasználó csak egy elemet tartalmazó tömböt vagy listát ad meg.

A többes számú paraméter neve csak azokban az esetekben használható, amikor a paraméter értéke mindig többelemes érték. Ezekben az esetekben a parancsmagnak ellenőriznie kell, hogy több elem van-e megadva, és a parancsmagnak figyelmeztetést kell megjelenítenie a felhasználónak, ha több elem nincs megadva.

Pascal-eset használata paraméternevekhez

Használja a Pascal-esetet a paraméternevekhez. Más szóval a paraméternévben szereplő egyes szavak első betűjének nagybetűsítése, beleértve a név első betűét is. A paraméter neve ErrorAction például a helyes nagybetűsítést használja. A következő paraméternevek helytelen nagybetűsítést használnak:

  • errorAction
  • erroraction

A beállítások listáját tartalmazó paraméterek

Kétféleképpen hozhat létre olyan paramétert, amelynek értéke kiválasztható egy beállításkészletből.

  • Adjon meg egy enumerálási típust (vagy használjon meglévő számbavételi típust), amely megadja az érvényes értékeket. Ezután az enumerálási típussal hozzon létre egy ilyen típusú paramétert.

  • Adja hozzá a ValidateSet attribútumot a paraméterdeklarációhoz. Az attribútummal kapcsolatos további információkért lásd: ValidateSet Attribute Deklaráció.

Standard típusok használata paraméterekhez

A többi parancsmaggal való konzisztenciának biztosítása érdekében használjon szabványos típusokat a paraméterekhez, ahol csak lehetséges. A különböző paraméterekhez használandó típusokkal kapcsolatos további információkért tekintse meg a Standard parancsmag paraméternevei és típusai című témakört. Ez a témakör több témakörre mutató hivatkozásokat tartalmaz, amelyek leírják a standard paraméterek csoportjainak nevét és .NET-keretrendszertípusait, például a "tevékenységparamétereket".

.NET-keretrendszertípusok használata Strongly-Typed

A paramétereket .NET-keretrendszertípusokként kell definiálni a jobb paraméterérvényesítés érdekében. Például azokat a paramétereket, amelyek egy értékkészlet egyetlen értékére korlátozódnak, enumerálási típusként kell definiálni. Az egységes erőforrás-azonosító (URI) érték támogatásához adja meg a paramétert System.Uri típusként. Kerülje az egyszerű sztringparamétereket, kivéve a szabad szövegű tulajdonságok esetében.

Konzisztens paramétertípusok használata

Ha ugyanazt a paramétert több parancsmag használja, mindig ugyanazt a paramétertípust használja. Ha például a Process paraméter egy parancsmag System.Int16 típusa, ne állítsa egy Process másik parancsmag paraméterét System.Uint16 típussá.

Igaz és hamis értéket tartalmazó paraméterek

Ha a paraméter csak a true és false értékeket veszi fel, definiálja a paramétert System.Management.Automation.SwitchParameter típusúként. A kapcsolóparamétereket a rendszer úgy kezeli, mint true amikor egy parancsban meg van adva. Ha a paraméter nem szerepel egy parancsban, a Windows PowerShell a paraméter falseértékét veszi figyelembe. Ne definiáljon logikai paramétereket.

Ha a paraméternek 3 értéket kell megkülönböztetnie: $true, $false és "meghatározatlan", akkor adjon meg egy Null értékű<bool> típusú paramétert. A harmadik, "meghatározatlan" érték szükséglete általában akkor fordul elő, ha a parancsmag módosíthatja egy objektum logikai tulajdonságát. Ebben az esetben a "meghatározatlan" azt jelenti, hogy nem módosítja a tulajdonság aktuális értékét.

Paramétereket támogató tömbök

A felhasználóknak gyakran ugyanazt a műveletet több argumentumon kell végrehajtaniuk. Ezeknek a felhasználóknak a parancsmagoknak paraméterbemenetként el kell fogadniuk egy tömböt, hogy a felhasználó windowsos PowerShell-változóként átadhassa az argumentumokat a paraméternek. A Get-Process parancsmag például egy tömböt használ a lekérni kívánt folyamatok nevét azonosító sztringekhez.

A PassThru paraméter támogatása

Alapértelmezés szerint számos, a rendszert módosító parancsmag, például a Stop-Process parancsmag "fogadóként" működik az objektumok esetében, és nem ad vissza eredményt. Ezeknek a parancsmagoknak implementálniuk kell a PassThru paramétert, hogy kényszerítsék a parancsmagot egy objektum visszaadására. PassThru A paraméter megadásakor a parancsmag egy objektumot a System.Management.Automation.Cmdlet.WriteObject metódus hívásával ad vissza. A következő parancs például leállítja a Calc (CalculatorApp.exe) alkalmazást, és az eredményül kapott folyamatot átadja a csővezetéknek.

Stop-Process -Name CalculatorApp -PassThru

A legtöbb esetben a Hozzáadás, a Beállítás és az Új parancsmagoknak támogatniuk kell egy paramétert PassThru .

Támogatási paraméterkészletek

A parancsmagok célja egyetlen cél elérése. A művelet vagy a műveleti cél leírásának azonban gyakran több módja is van. Egy folyamat például a neve, az azonosítója vagy egy folyamatobjektum alapján azonosítható. A parancsmagnak támogatnia kell a céljainak minden ésszerű ábrázolását. A parancsmag általában megfelel ennek a követelménynek az együttes működésű paraméterkészletek (más néven paraméterkészletek) megadásával. Egyetlen paraméter tetszőleges számú paraméterkészlethez tartozhat. További információ a paraméterkészletekről: parancsmag paraméterkészletei.

Paraméterkészletek megadásakor a készletben csak egy paramétert állítson be ValueFromPipeline értékre. A paraméterattribútum deklarálásáról további információt a ParameterAttribute Deklarációban talál.

Paraméterkészletek használata esetén az alapértelmezett paraméterkészletet a Parancsmag attribútum határozza meg. Az alapértelmezett paraméterkészletnek tartalmaznia kell az interaktív Windows PowerShell-munkamenetben valószínűleg használt paramétereket. A Parancsmag attribútum deklarálásával kapcsolatos további információkért lásd: CmdletAttribute Deklaráció.

Visszajelzés küldése a felhasználónak (SD04)

Az ebben a szakaszban található irányelvek segítségével visszajelzést küldhet a felhasználónak. Ez a visszajelzés lehetővé teszi a felhasználó számára, hogy tisztában legyen azzal, mi történik a rendszerben, és jobb rendszergazdai döntéseket hozzon.

A Windows PowerShell-futtatókörnyezet lehetővé teszi a felhasználó számára, hogy egy beállítási változó beállításával megadhatja, hogyan kezelheti az egyes hívások kimenetét a Write metódushoz. A felhasználó több beállítási változót is beállíthat, köztük egy változót, amely meghatározza, hogy a rendszernek meg kell-e jelenítenie az információkat, valamint egy változót, amely meghatározza, hogy a rendszernek le kell-e kérdeznie a felhasználót a további műveletek végrehajtása előtt.

A WriteWarning, a WriteVerbose és a WriteDebug metódus támogatása

A parancsmagnak meghívnia kell a System.Management.Automation.Cmdlet.WriteWarning metódust, ha a parancsmag egy olyan műveletet fog végrehajtani, amely esetleg nem kívánt eredményt ad. Egy parancsmagnak például ezt a metódust kell meghívnia, ha a parancsmag írásvédett fájl felülírására készül.

A parancsmagnak meg kell hívnia a System.Management.Automation.Cmdlet.WriteVerbose metódust, ha a felhasználónak részletes információra van szüksége a parancsmag működéséről. Egy parancsmagnak például ezt az információt kell meghívnia, ha a parancsmag szerzője úgy érzi, hogy vannak olyan forgatókönyvek, amelyek további információkat igényelhetnek a parancsmag működéséről.

A parancsmagnak a System.Management.Automation.Cmdlet.WriteDebug metódust kell meghívnia, amikor egy fejlesztő vagy terméktámogatási mérnöknek meg kell értenie, hogy mi sérült a parancsmag műveletében. Nem szükséges, hogy a parancsmag meghívja a System.Management.Automation.Cmdlet.WriteDebug metódust ugyanabban a kódban, amely meghívja a System.Management.Automation.Cmdlet.WriteVerbose metódust , mert a Debug paraméter mindkét információkészletet megjeleníti.

A WriteProgress támogatása hosszú ideig tartó műveletekhez

Azok a parancsmagműveletek, amelyek hosszú időt vesznek igénybe, és amelyek nem futnak a háttérben, támogatniuk kell a folyamatjelentést a System.Management.Automation.Cmdlet.WriteProgress metódushoz intézett rendszeres hívásokon keresztül.

A gazdafelületek használata

Előfordulhat, hogy a parancsmagnak közvetlenül a felhasználóval kell kommunikálnia a System.Management.Automation.Cmdlet osztály által támogatott különböző Írási vagy Should metódusok használata helyett. Ebben az esetben a parancsmagnak a System.Management.Automation.PSCmdlet osztályból kell származnia, és a System.Management.Automation.PSCmdlet.Host* tulajdonságot kell használnia. Ez a tulajdonság különböző kommunikációs szinteket támogat, például a PromptForChoice, a Prompt és a WriteLine/ReadLine típusokat. A legspecifikusabb szinten lehetővé teszi az egyes kulcsok olvasását és írását, valamint a pufferek kezelését is.

Hacsak egy parancsmagot kifejezetten grafikus felhasználói felület (GUI) létrehozására terveztek, a System.Management.Automation.PSCmdlet.Host* tulajdonsággal nem kerülheti el a gazdagépet. A grafikus felhasználói felület létrehozására tervezett parancsmagra példa a Out-GridView parancsmag.

Megjegyzés

A parancsmagok nem használhatják a System.Console API-t.

Parancsmag súgófájljának létrehozása (SD05)

Minden parancsmag-szerelvényhez hozzon létre egy Help.xml fájlt, amely a parancsmaggal kapcsolatos információkat tartalmazza. Ez az információ tartalmazza a parancsmag leírását, a parancsmag paramétereinek leírását, példákat a parancsmag használatára és egyebekre.

Kód irányelvei

A parancsmagok kódolása során a következő irányelveket kell követni, hogy egységes felhasználói élmény legyen a parancsmagok és más parancsmagok használata között. Ha talál egy, a helyzetére vonatkozó kód-útmutatót, mindenképpen tekintse meg a hasonló irányelvekre vonatkozó tervezési irányelveket.

Kódolási paraméterek (SC01)

Paraméter definiálása a Paraméter attribútummal deklarált parancsmagosztály nyilvános tulajdonságának deklarálásával. A paramétereknek nem kell a parancsmag származtatott .NET-keretrendszerosztályának statikus tagjainak lenniük. A paraméterattribútum deklarálásáról további információt a Paraméterattribútum-deklaráció című témakörben talál.

A Windows PowerShell elérési útjainak támogatása

A Windows PowerShell elérési útja a névterekhez való hozzáférés normalizálásának mechanizmusa. Amikor windowsos PowerShell-elérési utat rendel egy paraméterhez a parancsmagban, a felhasználó megadhat egy egyéni "meghajtót", amely egy adott elérési út parancsikonjaként működik. Amikor egy felhasználó kijelöl egy ilyen meghajtót, a tárolt adatok, például a beállításjegyzék adatai konzisztens módon használhatók.

Ha a parancsmag lehetővé teszi a felhasználó számára, hogy egy fájlt vagy adatforrást adjon meg, meg kell adnia egy System.String típusú paramétert. Ha egynél több meghajtó támogatott, a típusnak tömbnek kell lennie. A paraméter nevének a következő aliasával PSPathkell lenniePath: . Emellett a Path paraméternek helyettesítő karaktereket is támogatnia kell. Ha a helyettesítő karakterek támogatása nem szükséges, adjon meg egy paramétert LiteralPath .

Ha a parancsmag által beolvasott vagy írt adatoknak fájlnak kell lenniük, a parancsmagnak el kell fogadnia a Windows PowerShell elérési útjának bemenetét, és a parancsmagnak a System.Management.Automation.SessionState.Path tulajdonsággal kell lefordítani a Windows PowerShell-elérési utakat a fájlrendszer által felismert elérési utakra. Az egyes mechanizmusok a következő módszereket tartalmazzák:

Ha a parancsmag által beolvasott vagy írott adatok csak sztringek egy fájl helyett, a parancsmagnak a szolgáltató tartalomadatait (Content tagját) kell használnia az olvasáshoz és íráshoz. Ez az információ a System.Management.Automation.Provider.CmdletProvider.InvokeProvider tulajdonságból származik. Ezek a mechanizmusok lehetővé teszik más adattárak számára, hogy részt vegyenek az adatok olvasásában és írásában.

Helyettesítő karakterek támogatása

Ha lehetséges, a parancsmagnak támogatnia kell a helyettesítő karaktereket. A helyettesítő karakterek támogatása a parancsmag számos pontján előfordul (különösen akkor, ha egy paraméter egy sztringet vesz igénybe egy objektumkészletből származó objektum azonosításához). A StopProc-oktatóanyag minta Stop-Proc parancsmagja például egy paramétert Name határoz meg a folyamatneveket képviselő sztringek kezelésére. Ez a paraméter támogatja a helyettesítő karaktereket, így a felhasználó egyszerűen megadhatja a leállítandó folyamatokat.

Ha a helyettesítő karakterek támogatása elérhető, a parancsmagművelet általában tömböt hoz létre. Időnként nincs értelme tömböt támogatni, mert előfordulhat, hogy a felhasználó egyszerre csak egyetlen elemet használ. A Set-Location parancsmagnak például nem kell támogatnia egy tömböt, mert a felhasználó csak egyetlen helyet állít be. Ebben a példában a parancsmag továbbra is támogatja a helyettesítő karaktereket, de a felbontást egyetlen helyre kényszeríti.

A helyettesítő karakterek mintáival kapcsolatos további információkért lásd: Helyettesítő karakterek támogatása a parancsmag paramétereiben.

Objektumok definiálása

Ez a szakasz útmutatást tartalmaz a parancsmagok objektumainak meghatározásához és a meglévő objektumok kiterjesztéséhez.

Standard tagok definiálása

Definiáljon standard tagokat egy objektumtípus egyéni Types.ps1xml fájlban való kiterjesztéséhez (sablonként használja a Windows PowerShell Types.ps1xml fájlt). A standard tagokat egy PSStandardMembers nevű csomópont határozza meg. Ezek a definíciók lehetővé teszik más parancsmagok és a Windows PowerShell-futtatókörnyezet számára, hogy konzisztens módon működjenek az objektummal.

Paraméterként használandó objectmemberek definiálása

Ha objektumot tervez egy parancsmaghoz, győződjön meg arról, hogy a tagok közvetlenül a használni kívánt parancsmagok paramétereihez vannak megfeleltetve. Ez a leképezés lehetővé teszi, hogy az objektum könnyen elküldhető legyen a csővezetékbe, és át lehessen adni egyik parancsmagról a másikra.

A parancsmagok által visszaadott , már meglévő .NET-keretrendszer-objektumok gyakran hiányoznak néhány fontos vagy kényelmes tagból, amelyekre a szkript fejlesztőjének vagy felhasználójának szüksége van. Ezek a hiányzó tagok különösen fontosak lehetnek a megjelenítéshez és a megfelelő tagnevek létrehozásához, hogy az objektum megfelelően továbbítható legyen a folyamatnak. Hozzon létre egy egyéni Types.ps1xml fájlt a szükséges tagok dokumentálásához. A fájl létrehozásakor a következő elnevezési konvenciót javasoljuk: <Your_Product_Name>. Types.ps1xml.

Hozzáadhat például egy Mode szkripttulajdonságot a System.IO.FileInfo típushoz, hogy jobban megjelenítse egy fájl attribútumait. Emellett aliastulajdonságot is hozzáadhat Count a System.Array típushoz, hogy lehetővé tegye a tulajdonságnév konzisztens használatát (ahelyett Length).

Az IComparable Interface implementálása

Implementáljon egy System.IComparable interfészt az összes kimeneti objektumon. Ez lehetővé teszi, hogy a kimeneti objektumok egyszerűen át legyenek csövezve a különböző rendezési és elemzési parancsmagokra.

Megjelenítési információk frissítése

Ha egy objektum megjelenítése nem adja meg a várt eredményeket, hozzon létre ehhez az objektumhoz egy egyéni <YourProductName>.Format.ps1xml fájlt.

Jól definiált folyamatcsatorna bemenet (SC02) támogatása

Megvalósítás egy adatfolyam közepére

Implementáljon egy parancsmagot, feltéve, hogy az egy folyamat közepéről lesz meghívva (vagyis más parancsmagok fogják előállítani a bemenetét, vagy felhasználják a kimenetét). Tegyük fel például, hogy a Get-Process parancsmag, mivel adatokat hoz létre, csak a folyamat első parancsmagjaként használatos. Mivel azonban ez a parancsmag egy folyamat közepére van tervezve, ez a parancsmag lehetővé teszi, hogy a folyamat korábbi parancsmagjai vagy adatai megadják a lekérni kívánt folyamatokat.

Az adatcsőből származó bemenet támogatása

A parancsmag minden paraméterkészletében adjon meg legalább egy olyan paramétert, amely támogatja a folyamat bemenetét. A folyamatbemenet támogatása lehetővé teszi, hogy a felhasználó lekérje az adatokat vagy objektumokat, elküldje őket a megfelelő paraméterkészletnek, és közvetlenül egy parancsmagnak adja át az eredményeket.

A paraméter akkor fogadja el a folyamat bemenetét, ha a Paraméter attribútum tartalmazza a ValueFromPipeline kulcsszót, a ValueFromPipelineByPropertyName kulcsszóattribútumot vagy mindkét kulcsszót a deklarációjában. Ha egy paraméterkészlet egyetlen paramétere sem támogatja a ValueFromPipeline vagy ValueFromPipelineByPropertyName kulcsszavakat, a parancsmag nem helyezhető el értelmesen egy másik parancsmag után, mert figyelmen kívül fogja hagyni a folyamat bemenetét.

A ProcessRecord metódus támogatása

A folyamat előző parancsmagjának összes rekordjának elfogadásához a parancsmagnak implementálnia kell a System.Management.Automation.Cmdlet.ProcessRecord metódust . A Windows PowerShell többször hívja meg ezt a metódust, minden olyan rekord esetében, amelyet a rendszer elküld a parancsmagnak.

Önálló rekordok írása a csővezetékbe (SC03)

Amikor egy parancsmag objektumokat ad vissza, a parancsmagnak azonnal meg kell írnia az objektumokat a létrehozásukkor. A parancsmag nem tarthatja őket a kombinált tömbbe történő pufferelés céljából. Az objektumokat bemenetként fogadó parancsmagok ezután késedelem nélkül feldolgozhatják, megjeleníthetik vagy feldolgozhatják a kimeneti objektumokat. A kimeneti objektumokat egyenként létrehozó parancsmagnak a System.Management.Automation.Cmdlet.WriteObject metódust kell meghívnia. Egy olyan parancsmagnak, amely kimeneti objektumokat hoz létre kötegekben (például azért, mert egy mögöttes API kimeneti objektumok tömbjét adja vissza) meghívja a System.Management.Automation.Cmdlet.WriteObject metódust, amelynek második paramétere a truekövetkező.

Cmdletek készítése Case-Insensitive és Case-Preserving (SC04)

Alapértelmezés szerint maga a Windows PowerShell nem érzékeny a kis- és nagybetűkre. Mivel azonban számos régebbi rendszerrel foglalkozik, a Windows PowerShell megőrzi a kis- és nagybetűk kezelését az egyszerű működés és kompatibilitás érdekében. Más szóval, ha egy karaktert nagybetűkben ad meg, a Windows PowerShell nagybetűkben tartja. Ahhoz, hogy a rendszerek jól működjenek, a parancsmagnak követnie kell ezt az egyezményt. Ha lehetséges, a kis- és nagybetűket nem érzékenyítő módon kell működjön. A parancsban vagy a csővezetékben később előforduló cmdletek esetében azonban meg kell őriznie az eredeti esetet.

Lásd még:

szükséges fejlesztési irányelvek

Tanácsadói fejlesztési irányelvek

Windows PowerShell-parancsmag írása

  • Last updated on