Javasolt fejlesztői útmutatóStrongly Encouraged Development Guidelines

Ez a szakasz a parancsmagok írásakor követendő útmutatást ismerteti.This section describes guidelines that you should follow when you write your cmdlets. A parancsmagok megtervezéséhez és a parancsmag kódjának írásához szükséges irányelvek elválasztásához vannak elkülönítve.They are separated into guidelines for designing cmdlets and guidelines for writing your cmdlet code. Előfordulhat, hogy ezek az irányelvek minden forgatókönyv esetében nem alkalmazhatók.You might find that these guidelines are not applicable for every scenario. Ha azonban ezek az irányelvek érvényesek, és nem követi ezeket az irányelveket, előfordulhat, hogy a felhasználók a parancsmagok használata során gyenge élményben vannak.However, if they do apply and you do not follow these guidelines, your users might have a poor experience when they use your cmdlets.

Tervezési irányelvekDesign Guidelines

A következő irányelveket kell követni a parancsmagok tervezésekor, hogy konzisztens felhasználói élményt biztosítson a parancsmagok és más parancsmagok használata között.The following guidelines should be followed when designing cmdlets to ensure a consistent user experience between using your cmdlets and other cmdlets. Ha olyan tervezési útmutatót talál, amely az adott helyzetre vonatkozik, tekintse meg a hasonló irányelvek kódját ismertető útmutatót.When you find a Design guideline that applies to your situation, be sure to look at the Code guidelines for similar guidelines.

A parancsmag neve (SD01) egy adott főnév használataUse a Specific Noun for a Cmdlet Name (SD01)

A parancsmagok elnevezéséhez használt főszótárnak nagyon konkrétnak kell lennie, hogy a felhasználó fel tudja deríteni a parancsmagokat.Nouns used in cmdlet naming need to be very specific so that the user can discover your cmdlets. Előtag – általános nevek, például "kiszolgáló", a terméknév rövidített verziójával.Prefix generic nouns such as "server" with a shortened version of the product name. Ha például egy főnév a Microsoft SQL Server egy példányát futtató kiszolgálóra hivatkozik, használjon olyan főnévot, mint például a "SQLServer".For example, if a noun refers to a server that is running an instance of Microsoft SQL Server, use a noun such as "SQLServer". A speciális főnevek és a jóváhagyott műveletek rövid listája lehetővé teszi, hogy a felhasználó gyorsan felderítse és megjósolja a funkcionalitást, miközben elkerüli a parancsmagok nevei közötti ismétlődést.The combination of specific nouns and the short list of approved verbs enable the user to quickly discover and anticipate functionality while avoiding duplication among cmdlet names.

A felhasználói élmény fokozása érdekében a parancsmagok nevében kiválasztott főnév csak szám lehet.To enhance the user experience, the noun that you choose for a cmdlet name should be singular. Például a Get-Process Get-processs helyett használja a nevet.For example, use the name Get-Process instead of Get-Processes. Ezt a szabályt az összes parancsmag neve esetében érdemes követni, még akkor is, ha egy parancsmag egynél több elemen fog működni.It is best to follow this rule for all cmdlet names, even when a cmdlet is likely to act upon more than one item.

Pascal-eset használata a parancsmagok neveihez (SD02)Use Pascal Case for Cmdlet Names (SD02)

A paraméterek neveként a Pascal Case paramétert használja.Use Pascal case for parameter names. Más szóval kihasználja a művelet első betűjét és a főnév összes feltételét.In other words, capitalize the first letter of verb and all terms used in the noun. Például: „Clear-ItemProperty”.For example, "Clear-ItemProperty".

Paraméterek tervezési iránymutatásai (SD03)Parameter Design Guidelines (SD03)

A parancsmagoknak olyan paraméterekre van szükségük, amelyek a működéséhez szükséges adatokat kapják meg, valamint azokat a paramétereket, amelyek a művelet jellemzőinek meghatározására szolgálnak.A cmdlet needs parameters that receive the data on which it must operate, and parameters that indicate information that is used to determine the characteristics of the operation. Előfordulhat például, hogy egy parancsmag olyan Name paraméterrel rendelkezik, amely a folyamatból fogadja az adatait, és a parancsmagnak van egy Force paramétere, amely azt jelzi, hogy a parancsmag kényszeríthető a művelet végrehajtására.For example, a cmdlet might have a Name parameter that receives data from the pipeline, and the cmdlet might have a Force parameter to indicate that the cmdlet can be forced to perform its operation. A parancsmagok által definiálható paraméterek száma nincs korlátozva.There is no limit to the number of parameters that a cmdlet can define.

Szabványos paraméterek neveinek használataUse Standard Parameter Names

A parancsmagnak a szabványos paraméterek nevét kell használnia, így a felhasználó gyorsan meghatározhatja, hogy mit jelent az adott paraméter.Your cmdlet should use standard parameter names so that the user can quickly determine what a particular parameter means. Ha pontosabb nevet igényel, használja a szabványos paraméter nevét, majd adjon meg egy pontosabb nevet aliasként.If a more specific name is required, use a standard parameter name, and then specify a more specific name as an alias. A Get-Service parancsmag például egy olyan paraméterrel rendelkezik, amely egy általános névvel ( Name ) és egy konkrétabb aliassal ( ServiceName ) rendelkezik.For example, the Get-Service cmdlet has a parameter that has a generic name (Name) and a more specific alias (ServiceName). Mindkét kifejezés használható a paraméter megadására.Both terms can be used to specify the parameter.

A paraméterek neveivel és azok adattípusaival kapcsolatos további információkért lásd a parancsmag paraméterének nevét és a funkciókra vonatkozó irányelveket.For more information about parameter names and their data types, see Cmdlet Parameter Name and Functionality Guidelines.

Az egyes paraméterek neveinek használataUse Singular Parameter Names

Kerülje a többek között olyan paraméterek használatát, amelyek értéke egyetlen elem.Avoid using plural names for parameters whose value is a single element. Ide tartoznak a tömböket vagy listákat tartalmazó paraméterek, mivel a felhasználó csak egy elemmel rendelkezhet tömb vagy lista formájában.This includes parameters that take arrays or lists because the user might supply an array or list with only one element.

A többes számú paraméter nevét csak azokban az esetekben szabad használni, ahol a paraméter értéke mindig egy többelemes érték.Plural parameter names should be used only in those cases where the value of the parameter is always a multiple-element value. Ezekben az esetekben a parancsmagnak meg kell győződnie arról, hogy több elem is meg van adva, és a parancsmagnak figyelmeztetést kell megjelenítenie a felhasználónak, ha nincs megadva több elem.In these cases, the cmdlet should verify that multiple elements are supplied, and the cmdlet should display a warning to the user if multiple elements are not supplied.

Pascal-eset használata a paraméterek neveihezUse Pascal Case for Parameter Names

A paraméterek neveként a Pascal Case paramétert használja.Use Pascal case for parameter names. Más szóval kihasználja az egyes szavak első betűjét a paraméter nevében, beleértve a név első betűjét is.In other words, capitalize the first letter of each word in the parameter name, including the first letter of the name. A paraméter neve például ErrorAction a megfelelő nagybetűket használja.For example, the parameter name ErrorAction uses the correct capitalization. A következő paraméterek nevei helytelen betűket használnak:The following parameter names use incorrect capitalization:

  • errorAction
  • erroraction

Beállítások listáját tartalmazó paraméterekParameters That Take a List of Options

Kétféleképpen hozhat létre egy olyan paramétert, amelynek értéke kiválasztható a különböző lehetőségek közül.There are two ways to create a parameter whose value can be selected from a set of options.

  • Definiáljon egy enumerálási típust (vagy használjon egy meglévő számbavételi típust), amely megadja az érvényes értékeket.Define an enumeration type (or use an existing enumeration type) that specifies the valid values. Ezután a számbavételi típus használatával hozzon létre egy adott típusú paramétert.Then, use the enumeration type to create a parameter of that type.

  • Adja hozzá a ValidateSet attribútumot a paraméter deklarációjában.Add the ValidateSet attribute to the parameter declaration. További információ erről az attribútumról: ValidateSet-attribútum deklarációja.For more information about this attribute, see ValidateSet Attribute Declaration.

Szabványos típusok használata paraméterekhezUse Standard Types for Parameters

A más parancsmagokkal való konzisztencia biztosításához használja a szabványos típusokat a paraméterekhez, ahol az mindig lehetséges.To ensure consistency with other cmdlets, use standard types for parameters where ever possible. További információ a különböző paraméterekhez használandó típusokról: standard parancsmag paraméterének nevei és típusai.For more information about the types that should be used for different parameter, see Standard Cmdlet Parameter Names and Types. Ez a témakör számos olyan témakörre mutató hivatkozásokat tartalmaz, amelyek a nevek és a .NET-keretrendszer szabványos paraméterek (például a "tevékenység paramétereinek") csoportjának típusait írják le.This topic provides links to several topics that describe the names and .NET Framework types for groups of standard parameters, such as the "activity parameters".

Strongly-Typed .NET-keretrendszer típusainak használataUse Strongly-Typed .NET Framework Types

A paramétereket a .NET-keretrendszer típusaként kell definiálni, hogy jobb legyen a paraméterek érvényesítése.Parameters should be defined as .NET Framework types to provide better parameter validation. Például az értékek egy értékére korlátozódó paramétereket enumerálási típusként kell definiálni.For example, parameters that are restricted to one value from a set of values should be defined as an enumeration type. Uniform Resource Identifier (URI) érték támogatásához adja meg a paramétert System. URI típusként.To support a Uniform Resource Identifier (URI) value, define the parameter as a System.Uri type. Kerülje az alapszintű karakterlánc-paramétereket az összes, de szabad formátumú szöveg tulajdonságaihoz.Avoid basic string parameters for all but free-form text properties.

Konzisztens paraméterek típusának használataUse Consistent Parameter Types

Ha ugyanazt a paramétert több parancsmag is használja, mindig ugyanazt a paraméter-típust használja.When the same parameter is used by multiple cmdlets, always use the same parameter type. Ha például a paraméter egy Process System. Int16 típus egy parancsmaghoz, ne hajtsa végre a Process paramétert egy System. Uint16 típusú másik parancsmaghoz.For example, if the Process parameter is an System.Int16 type for one cmdlet, do not make the Process parameter for another cmdlet a System.Uint16 type.

Igaz és hamis paraméterekParameters That Take True and False

Ha a paraméter csak a és a paramétert veszi igénybe true false , adja meg a következőt: System. Management. Automation. SwitchParameter.If your parameter takes only true and false, define the parameter as type System.Management.Automation.SwitchParameter. A Switch paraméter úgy van kezelve, ahogy true egy parancsban van megadva.A switch parameter is treated as true when it is specified in a command. Ha a paraméter nem szerepel a parancsban, a Windows PowerShell a paraméter értékét fogja figyelembe venni false .If the parameter is not included in a command, Windows PowerShell considers the value of the parameter to be false. Ne adjon meg logikai paramétereket.Do not define Boolean parameters.

Ha a paraméternek különbséget kell tennie 3 érték között: $true, $false és "meghatározatlan", akkor adjon meg egy NULL értékű paramétert <bool> .If your parameter needs to differentiate between 3 values: $true, $false and "unspecified", then define a parameter of type Nullable<bool>. A harmadik, "meghatározatlan" érték általában akkor fordul elő, ha a parancsmag módosíthatja egy objektum logikai tulajdonságát.The need for a 3rd, "unspecified" value typically occurs when the cmdlet can modify a Boolean property of an object. Ebben az esetben a "meghatározatlan" érték azt jelenti, hogy nem módosítható a tulajdonság aktuális értéke.In this case "unspecified" means to not change the current value of the property.

Paraméterek támogatása a tömbbenSupport Arrays for Parameters

Gyakran a felhasználóknak ugyanazokat a műveleteket kell elvégezniük több argumentumon.Frequently, users must perform the same operation against multiple arguments. Ezekhez a felhasználókhoz a parancsmagnak el kell fogadnia egy tömböt paraméterként, hogy a felhasználó átadja az argumentumokat a paraméternek Windows PowerShell-változóként.For these users, a cmdlet should accept an array as parameter input so that a user can pass the arguments into the parameter as a Windows PowerShell variable. A Get-Process parancsmag például egy tömböt használ a lekérdezni kívánt folyamatok nevét azonosító karakterláncok számára.For example, the Get-Process cmdlet uses an array for the strings that identify the names of the processes to retrieve.

A PassThru paraméter támogatásaSupport the PassThru Parameter

Alapértelmezés szerint számos, a rendszer módosítására szolgáló parancsmag, például a stop-Process parancsmag "mosogatóként" viselkedik az objektumok esetében, és nem ad vissza eredményt.By default, many cmdlets that modify the system, such as the Stop-Process cmdlet, act as "sinks" for objects and do not return a result. A parancsmagnak meg kell valósítania a PassThru paramétert, hogy kényszerítse a parancsmagot egy objektum visszaadására.These cmdlet should implement the PassThru parameter to force the cmdlet to return an object. Ha a PassThru paraméter meg van adva, a parancsmag egy objektumot ad vissza a System. Management. Automation. parancsmag. WriteObject metódus hívásával.When the PassThru parameter is specified, the cmdlet returns an object by using a call to the System.Management.Automation.Cmdlet.WriteObject method. Az alábbi parancs például leállítja a számítás folyamatát, és átadja az eredő folyamatot a folyamatnak.For example, the following command stops the Calc process and passes the resultant process to the pipeline.

Stop-Process calc -passthru

A legtöbb esetben a Hozzáadás, a beállítás és az új parancsmagnak támogatnia kell a PassThru paramétert.In most cases, Add, Set, and New cmdlets should support a PassThru parameter.

Támogatási paraméterek készleteiSupport Parameter Sets

A parancsmag egyetlen cél megvalósítására szolgál.A cmdlet is intended to accomplish a single purpose. Azonban a művelet vagy a művelet céljának gyakran több módja is van.However, there is frequently more than one way to describe the operation or the operation target. Előfordulhat például, hogy egy folyamatot a neve, az azonosítója vagy egy Process objektum azonosít.For example, a process might be identified by its name, by its identifier, or by a process object. A parancsmagnak támogatnia kell a célok összes ésszerű ábrázolását.The cmdlet should support all the reasonable representations of its targets. Általában a parancsmag megfelel ennek a követelménynek úgy, hogy meghatározza azokat a paramétereket (más néven paraméter-készleteket), amelyek együtt működnek.Normally, the cmdlet satisfies this requirement by specifying sets of parameters (referred to as parameter sets) that operate together. Egyetlen paraméter tetszőleges számú paraméterhez tartozhat.A single parameter can belong to any number of parameter sets. További információ a paraméter-készletekről: parancsmag-paraméterek készletei.For more information about parameter sets, see Cmdlet Parameter Sets.

A paraméterek megadásakor a készletben csak egy paramétert állítson be ValueFromPipeline értékre.When you specify parameter sets, set only one parameter in the set to ValueFromPipeline. További információ a paraméter attribútumának deklaráláról: ParameterAttribute deklaráció.For more information about how to declare the Parameter attribute, see ParameterAttribute Declaration.

A paraméterek használatakor az alapértelmezett paramétert a parancsmag attribútum határozza meg.When parameter sets are used, the default parameter set is defined by the Cmdlet attribute. Az alapértelmezett paraméternek tartalmaznia kell azokat a paramétereket, amelyek valószínűleg egy interaktív Windows PowerShell-munkamenetben lesznek felhasználva.The default parameter set should include the parameters most likely to be used in an interactive Windows PowerShell session. További információ a parancsmag -attribútum deklaráláról: CmdletAttribute deklaráció.For more information about how to declare the Cmdlet attribute, see CmdletAttribute Declaration.

Visszajelzés küldése a felhasználó számára (SD04)Provide Feedback to the User (SD04)

A jelen szakaszban található irányelvek segítségével visszajelzést adhat a felhasználónak.Use the guidelines in this section to provide feedback to the user. Ez a visszajelzés lehetővé teszi, hogy a felhasználó tisztában legyen azzal, hogy mi történik a rendszeren, és hogy jobb felügyeleti döntéseket hozzon.This feedback allows the user to be aware of what is occurring in the system and to make better administrative decisions.

A Windows PowerShell-futtatókörnyezet lehetővé teszi, hogy a felhasználó megadhatja, hogyan kezelje az egyes hívások kimenetét a Write metódushoz egy preferencia változó beállításával.The Windows PowerShell runtime allows a user to specify how to handle output from each call to the Write method by setting a preference variable. A felhasználó beállíthat számos preferencia-változót, például egy olyan változót, amely meghatározza, hogy a rendszernek meg kell-e jelennie az információknak és egy változónak, amely meghatározza, hogy a rendszer lekérdezze-e a felhasználót a további műveletThe user can set several preference variables, including a variable that determines whether the system should display information and a variable that determines whether the system should query the user before taking further action.

A WriteWarning, a WriteVerbose és a WriteDebug metódus támogatásaSupport the WriteWarning, WriteVerbose, and WriteDebug Methods

A parancsmagnak meg kell hívnia a System. Management. Automation. parancsmag. WriteWarning metódust, ha a parancsmag olyan műveletet hajt végre, amelynek nem kívánt eredménye lehet.A cmdlet should call the System.Management.Automation.Cmdlet.WriteWarning method when the cmdlet is about to perform an operation that might have an unintended result. Egy parancsmagnak például meg kell hívnia ezt a metódust, ha a parancsmag egy írásvédett fájl felülírására készül.For example, a cmdlet should call this method if the cmdlet is about to overwrite a read-only file.

A parancsmagnak meg kell hívnia a System. Management. Automation. parancsmag. WriteVerbose metódust, ha a felhasználónak némi részletre van szüksége a parancsmag működéséről.A cmdlet should call the System.Management.Automation.Cmdlet.WriteVerbose method when the user requires some detail about what the cmdlet is doing. Egy parancsmagnak például meg kell hívnia ezeket az információkat, ha a szerző úgy véli, hogy olyan forgatókönyvek vannak, amelyeknek további információra lehet szüksége a parancsmag működéséről.For example, a cmdlet should call this information if the cmdlet author feels that there are scenarios that might require more information about what the cmdlet is doing.

A parancsmagnak meg kell hívnia a System. Management. Automation. parancsmag. WriteDebug metódust, ha egy fejlesztő vagy terméktámogatási mérnöknek tisztában kell lennie azzal, hogy mi sérült a parancsmag-művelettel.The cmdlet should call the System.Management.Automation.Cmdlet.WriteDebug method when a developer or product support engineer must understand what has corrupted the cmdlet operation. A (z) parancsmagnak nem kell meghívnia a System. Management. Automation. parancsmag. WriteDebug metódust ugyanabban a kódban, amely meghívja a System. Management. Automation. parancsmag. WriteVerbose metódust, mert a Debug paraméter mindkét adatkészletet megjeleníti.It is not necessary for the cmdlet to call the System.Management.Automation.Cmdlet.WriteDebug method in the same code that calls the System.Management.Automation.Cmdlet.WriteVerbose method because the Debug parameter presents both sets of information.

A hosszú időt igénybe tartó műveletek WriteProgress támogatásaSupport WriteProgress for Operations that take a Long Time

A hosszú ideig tartó és a háttérben nem futtatható parancsmag-műveletek támogatják a System. Management. Automation. parancsmag. WriteProgress metódus rendszeres hívásával végzett jelentéskészítést.Cmdlet operations that take a long time to complete and that cannot run in the background should support progress reporting through periodic calls to the System.Management.Automation.Cmdlet.WriteProgress method.

A gazdagép felületének használataUse the Host Interfaces

Esetenként a parancsmagnak közvetlenül kell kommunikálnia a felhasználóval a különböző írási vagy a System. Management. Automation. parancsmag osztály által támogatott metódusok használatával.Occasionally, a cmdlet must communicate directly with the user instead of by using the various Write or Should methods supported by the System.Management.Automation.Cmdlet class. 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.In this case, the cmdlet should derive from the System.Management.Automation.PSCmdlet class and use the System.Management.Automation.PSCmdlet.Host* property. Ez a tulajdonság a kommunikációs típusok különböző szintjeit támogatja, beleértve a PromptForChoice, a promptot és a WriteLine/ReadLine típusokat.This property supports different levels of communication type, including the PromptForChoice, Prompt, and WriteLine/ReadLine types. A legpontosabb szinten az is lehetővé teszi az egyes kulcsok olvasását és írását, valamint a pufferek kezelését.At the most specific level, it also provides ways to read and write individual keys and to deal with buffers.

Ha egy parancsmagot kifejezetten grafikus felhasználói felület létrehozásához terveztek, akkor a gazdagépet nem szabad megkerülni a System. Management. Automation. PSCmdlet. Host * tulajdonság használatával.Unless a cmdlet is specifically designed to generate a graphical user interface (GUI), it should not bypass the host by using the System.Management.Automation.PSCmdlet.Host* property. A grafikus felhasználói felület létrehozásához tervezett parancsmag például a out-GridView parancsmag.An example of a cmdlet that is designed to generate a GUI is the Out-GridView cmdlet.

Megjegyzés

A parancsmagok nem használhatják a System. Console API-t.Cmdlets should not use the System.Console API.

Parancsmag-súgófájl létrehozása (SD05)Create a Cmdlet Help File (SD05)

Az egyes parancsmag-szerelvényekhez hozzon létre egy Help.xml fájlt, amely a parancsmaggal kapcsolatos információkat tartalmaz.For each cmdlet assembly, create a Help.xml file that contains information about the cmdlet. Ezek az adatok tartalmazzák a parancsmag leírását, a parancsmag paramétereinek leírását, a parancsmagok használatának példáit és egyebeket.This information includes a description of the cmdlet, descriptions of the cmdlet's parameters, examples of the cmdlet's use, and more.

Kód irányelvekCode Guidelines

A következő irányelveket kell követni, ha a kódolási parancsmagokkal konzisztens felhasználói élményt biztosít a parancsmagok és más parancsmagok használata között.The following guidelines should be followed when coding cmdlets to ensure a consistent user experience between using your cmdlets and other cmdlets. Ha olyan kódrészletet talál, amely az adott helyzetre vonatkozik, tekintse meg a hasonló irányelvek tervezési irányelveit.When you find a Code guideline that applies to your situation, be sure to look at the Design guidelines for similar guidelines.

Kódolási paraméterek (SC01)Coding Parameters (SC01)

Adjon meg egy paramétert úgy, hogy deklarálja a paraméter attribútummal díszített parancsmag osztály nyilvános tulajdonságát.Define a parameter by declaring a public property of the cmdlet class that is decorated with the Parameter attribute. A paramétereknek nem kell statikus tagoknak lenniük a származtatott .NET-keretrendszer osztályból a parancsmaghoz.Parameters do not have to be static members of the derived .NET Framework class for the cmdlet. További információ a paraméter attribútumának deklaráláról: paraméter attribútumának deklarációja.For more information about how to declare the Parameter attribute, see Parameter Attribute Declaration.

Windows PowerShell-elérési utak támogatásaSupport Windows PowerShell Paths

A Windows PowerShell elérési útja a névterek hozzáférésének normalizálása.The Windows PowerShell path is the mechanism for normalizing access to namespaces. Ha egy Windows PowerShell-elérési utat rendel a parancsmag egyik paraméteréhez, a felhasználó meghatározhat egy egyéni "meghajtót", amely egy adott elérési útra mutató parancsikonként működik.When you assign a Windows PowerShell path to a parameter in the cmdlet, the user can define a custom "drive" that acts as a shortcut to a specific path. Ha egy felhasználó kijelöl egy ilyen meghajtót, a tárolt adatait (például a beállításjegyzékben lévő adatait) konzisztens módon lehet használni.When a user designates such a drive, stored data, such as data in the Registry, can be used in a consistent way.

Ha a parancsmag lehetővé teszi, hogy a felhasználó megadjon egy fájlt vagy egy adatforrást, meg kell határoznia a System. Stringtípusú paramétereket.If your cmdlet allows the user to specify a file or a data source, it should define a parameter of type System.String. Ha több meghajtó is támogatott, a típusnak tömbnek kell lennie.If more than one drive is supported, the type should be an array. A paraméter nevének a (z Path ) aliasával kell rendelkeznie PSPath .The name of the parameter should be Path, with an alias of PSPath. Emellett a Path paraméternek támogatnia kell a helyettesítő karaktereket.Additionally, the Path parameter should support wildcard characters. Ha a helyettesítő karakterek támogatása nem kötelező, adjon meg egy LiteralPath paramétert.If support for wildcard characters is not required, define a LiteralPath parameter.

Ha a parancsmag által beolvasott vagy írt adatoknak fájlnak kell lennie, a parancsmagnak el kell fogadnia a Windows PowerShell elérési útjának bevitelét, és a parancsmagnak a System. Management. Automation. sessionstate. Path tulajdonságot kell használnia a Windows PowerShell elérési útjának fordításához a fájlrendszer által felismert elérési utakra.If the data that the cmdlet reads or writes has to be a file, the cmdlet should accept Windows PowerShell path input, and the cmdlet should use the System.Management.Automation.Sessionstate.Path property to translate the Windows PowerShell paths into paths that the file system recognizes. Az adott mechanizmusok a következő módszerekkel rendelkeznek:The specific mechanisms include the following methods:

Ha a parancsmag által beolvasott vagy írt adatok csak sztringek egy halmaza, akkor a parancsmagnak a szolgáltatói tartalommal kapcsolatos információkat (tag) kell használnia az Content olvasáshoz és az íráshoz.If the data that the cmdlet reads or writes is only a set of strings instead of a file, the cmdlet should use the provider content information (Content member) to read and write. Ezek az információk a System. Management. Automation. Provider. CmdletProvider. InvokeProvider tulajdonságból származnak.This information is obtained from the System.Management.Automation.Provider.CmdletProvider.InvokeProvider property. Ezek a mechanizmusok lehetővé teszik más adattárak számára, hogy részt vegyenek az adatolvasásban és az írásban.These mechanisms allow other data stores to participate in the reading and writing of data.

Helyettesítő karakterek támogatásaSupport Wildcard Characters

Ha lehetséges, A parancsmagnak támogatnia kell A helyettesítő karaktereket.A cmdlet should support wildcard characters if possible. A helyettesítő karakterek támogatása a parancsmag számos helyén történik (különösen akkor, ha egy paraméter egy karakterláncot hoz létre egy objektum egy csoportból való azonosításához).Support for wildcard characters occurs in many places in a cmdlet (especially when a parameter takes a string to identify one object from a set of objects). Például a StopProc-oktatóanyagban szereplő stop-proc parancsmag egy olyan Name paramétert határoz meg, amely a folyamatok nevét jelképező karakterláncok kezelésére szolgál.For example, the sample Stop-Proc cmdlet from the StopProc Tutorial defines a Name parameter to handle strings that represent process names. Ez a paraméter támogatja a helyettesítő karaktereket, így a felhasználó könnyedén megadhatja a leállítani kívánt folyamatokat.This parameter supports wildcard characters so that the user can easily specify the processes to stop.

Ha a helyettesítő karakterek támogatása elérhető, a parancsmagok működése általában tömböt hoz létre.When support for wildcard characters is available, a cmdlet operation usually produces an array. Időnként nem érdemes egy tömböt támogatni, mert a felhasználó egyszerre csak egyetlen elem használatát használhatja.Occasionally, it does not make sense to support an array because the user might use only a single item at a time. Például a set-Location parancsmagnak nem kell egy tömböt támogatnia, mert a felhasználó csak egyetlen helyet állít be.For example, the Set-Location cmdlet does not need to support an array because the user is setting only a single location. Ebben az esetben a parancsmag továbbra is támogatja a helyettesítő karaktereket, de egyetlen helyre kényszeríti a feloldást.In this instance, the cmdlet still supports wildcard characters, but it forces resolution to a single location.

További információ a helyettesítő karakteres mintákról: a helyettesítő karakterek támogatása a parancsmag paraméterei között.For more information about wildcard-character patterns, see Supporting Wildcard Characters in Cmdlet Parameters.

Objektumok definiálásaDefining Objects

Ez a szakasz útmutatást tartalmaz a parancsmagok objektumainak definiálásához és a meglévő objektumok kiterjesztéséhez.This section contains guidelines for defining objects for cmdlets and for extending existing objects.

Szabványos tagok definiálásaDefine Standard Members

Meghatározhatja a szabványos tagokat egy adott objektum típusának kibővítéséhez egy egyéni Types.ps1XML-fájlban (használja sablonként a Windows PowerShell Types.ps1XML-fájlt).Define standard members to extend an object type in a custom Types.ps1xml file (use the Windows PowerShell Types.ps1xml file as a template). A standard tagokat a PSStandardMembers nevű csomópont határozza meg.Standard members are defined by a node with the name PSStandardMembers. Ezek a definíciók lehetővé teszik, hogy a többi parancsmag és a Windows PowerShell-futtatókörnyezet konzisztens módon működjön az objektummal.These definitions allow other cmdlets and the Windows PowerShell runtime to work with your object in a consistent way.

Paraméterekként használandó ObjectMembers definiálásaDefine ObjectMembers to Be Used as Parameters

Ha egy parancsmaghoz tervez objektumokat, győződjön meg arról, hogy a tagjai közvetlenül a használni kívánt parancsmagok paramétereit képezik le.If you are designing an object for a cmdlet, ensure that its members map directly to the parameters of the cmdlets that will use it. Ez a leképezés lehetővé teszi, hogy az objektum könnyen elküldhető legyen a folyamatba, és az egyik parancsmagról egy másikra legyen továbbítva.This mapping allows the object to be easily sent to the pipeline and to be passed from one cmdlet to another.

A parancsmagok által visszaadott meglévő .NET-keretrendszerbeli objektumok gyakran hiányoznak a parancsfájl fejlesztője vagy felhasználója által igényelt fontos vagy kényelmes tagok közül.Preexisting .NET Framework objects that are returned by cmdlets are frequently missing some important or convenient members that are needed by the script developer or user. Ezek a hiányzó tagok különösen fontosak lehetnek a megjelenítéshez és a helyes tagok nevének létrehozásához, hogy az objektumot helyesen lehessen átadni a folyamatnak.These missing members can be particularly important for display and for creating the correct member names so that the object can be correctly passed to the pipeline. Hozzon létre egy egyéni Types.ps1XML-fájlt a szükséges tagok dokumentálására.Create a custom Types.ps1xml file to document these required members. A fájl létrehozásakor a következő elnevezési konvenciót javasoljuk: <Your_Product_Name>.Types.ps1XML.When you create this file, we recommend the following naming convention: <Your_Product_Name>.Types.ps1xml.

Hozzáadhat például egy Mode script tulajdonságot a System. IO. fileinfo típushoz, ha egy fájl attribútumainak megjelenítését világosabban szeretné megjeleníteni.For example, you could add a Mode script property to the System.IO.FileInfo type to display the attributes of a file more clearly. Emellett hozzáadhat egy Count alias-tulajdonságot a System. Array típushoz, hogy lehetővé váljon a tulajdonságnév (a helyett) konzisztens használata Length .Additionally, you could add a Count alias property to the System.Array type to allow the consistent use of that property name (instead of Length).

A IComparable felület implementálásaImplement the IComparable Interface

Hozzon létre egy System. IComparable felületet az összes kimeneti objektumon.Implement a System.IComparable interface on all output objects. Ez lehetővé teszi, hogy a kimeneti objektumok könnyen, különböző rendezési és elemzési parancsmagokra legyenek átirányítva.This allows the output objects to be easily piped to various sorting and analysis cmdlets.

Megjelenítési adatok frissítéseUpdate Display Information

Ha egy objektum megjelenítése nem biztosítja a várt eredményeket, hozzon létre egy egyéni <YourProductName>.Format.ps1XML-fájlt az adott objektumhoz.If the display for an object does not provide the expected results, create a custom <YourProductName>.Format.ps1xml file for that object.

Jól meghatározott adatcsatorna-bemenet (SC02) támogatásaSupport Well Defined Pipeline Input (SC02)

Megvalósítás a folyamat közepéhezImplement for the Middle of a Pipeline

Hozzon létre egy parancsmagot, amely azt feltételezi, hogy egy folyamat közepétől fogja hívni (azaz más parancsmagok a bemenetét vagy a kimenetét használják).Implement a cmdlet assuming that it will be called from the middle of a pipeline (that is, other cmdlets will produce its input or consume its output). Tegyük fel például, hogy a Get-Process parancsmag az adatgenerálás miatt csak a folyamat első parancsmagját használja.For example, you might assume that the Get-Process cmdlet, because it generates data, is used only as the first cmdlet in a pipeline. Mivel azonban ez a parancsmag egy folyamat közepéhez lett tervezve, ez a parancsmag lehetővé teszi az előző parancsmagok vagy a folyamatban lévő adatmennyiség megadását a beolvasandó folyamatok számára.However, because this cmdlet is designed for the middle of a pipeline, this cmdlet allows previous cmdlets or data in the pipeline to specify the processes to retrieve.

Támogatás bemenet a folyamatbólSupport Input from the Pipeline

A parancsmaghoz beállított minden paraméterhez tartalmaznia kell legalább egy olyan paramétert, amely támogatja a folyamat bemenetét.In each parameter set for a cmdlet, include at least one parameter that supports input from the pipeline. A folyamat bemenetének támogatása lehetővé teszi a felhasználó számára az adatok vagy objektumok beolvasását, hogy azok a megfelelő típusparaméter számára legyenek elküldve, és közvetlenül a parancsmagnak adják át az eredményeket.Support for pipeline input allows the user to retrieve data or objects, to send them to the correct parameter set, and to pass the results directly to a cmdlet.

Egy paraméter fogadja a folyamat bemenetét, ha a paraméter attribútuma tartalmazza a ValueFromPipeline kulcsszót, a ValueFromPipelineByPropertyName kulcsszó attribútumot vagy mindkét kulcsszót a deklarációjában.A parameter accepts input from the pipeline if the Parameter attribute includes the ValueFromPipeline keyword, the ValueFromPipelineByPropertyName keyword attribute, or both keywords in its declaration. Ha egy paraméter egyik paramétere sem támogatja a ValueFromPipeline vagy a ValueFromPipelineByPropertyName kulcsszavakat, a parancsmagot nem lehet értelmesen elhelyezni egy másik parancsmag után, mert figyelmen kívül hagyja a folyamat összes bemenetét.If none of the parameters in a parameter set support the ValueFromPipeline or ValueFromPipelineByPropertyName keywords, the cmdlet cannot meaningfully be placed after another cmdlet because it will ignore any pipeline input.

A ProcessRecord metódus támogatásaSupport the ProcessRecord Method

A folyamat előző parancsmagjának összes rekordjának elfogadásához a parancsmagnak meg kell valósítania a System. Management. Automation. parancsmag. ProcessRecord metódust.To accept all the records from the preceding cmdlet in the pipeline, your cmdlet must implement the System.Management.Automation.Cmdlet.ProcessRecord method. A Windows PowerShell többször is meghívja ezt a metódust, a parancsmagnak eljuttatott összes rekord esetében.Windows PowerShell calls this method multiple times, once for every record that is sent to your cmdlet.

Egyetlen rekord írása a folyamatba (SC03)Write Single Records to the Pipeline (SC03)

Ha egy parancsmag objektumokat ad vissza, a parancsmagnak azonnal el kell írnia az objektumokat a létrehozásuk során.When a cmdlet returns objects, the cmdlet should write the objects immediately as they are generated. A parancsmagnak nem szabad megtartania őket, hogy egy kombinált tömbben lehessen őket kiosztani.The cmdlet should not hold them in order to buffer them into a combined array. Azok a parancsmagok, amelyek bemenetként fogadják az objektumokat, a kimeneti objektumok feldolgozását, megjelenítését és feldolgozását, valamint késleltetés nélküli megjelenítését teszik lehetővé.The cmdlets that receive the objects as input will then be able to process, display, or process and display the output objects without delay. A kimeneti objektumokat egyszerre létrehozó parancsmagnak meg kell hívnia a System. Management. Automation. parancsmag. WriteObject metódust.A cmdlet that generates output objects one at a time should call the System.Management.Automation.Cmdlet.WriteObject method. A kötegekben kimeneti objektumokat létrehozó parancsmagok (például azért, mert egy mögöttes API kimeneti objektumok tömbjét adja vissza) meg kell hívnia a System. Management. Automation. parancsmag. WriteObject metódust a második paraméterrel true .A cmdlet that generates output objects in batches (for example, because an underlying API returns an array of output objects) should call the System.Management.Automation.Cmdlet.WriteObject Method with its second parameter set to true.

Parancsmagok készítése Case-Insensitive és Case-Preserving (SC04)Make Cmdlets Case-Insensitive and Case-Preserving (SC04)

Alapértelmezés szerint a Windows PowerShell maga a kis-és nagybetűk megkülönböztetése.By default, Windows PowerShell itself is case-insensitive. Mivel azonban számos meglévő rendszerrel foglalkozik, a Windows PowerShell megőrzi a kis-és nagybetűket, így megkönnyíti a működést és a kompatibilitást.However, because it deals with many preexisting systems, Windows PowerShell does preserve case for ease of operation and compatibility. Más szóval, ha a karakter nagybetűvel van megadva, a Windows PowerShell nagybetűvel tartja.In other words, if a character is supplied in uppercase letters, Windows PowerShell keeps it in uppercase letters. Ahhoz, hogy a rendszerek jól működjenek, a parancsmagnak követnie kell ezt az egyezményt.For systems to work well, a cmdlet needs to follow this convention. Ha lehetséges, kis-és nagybetűket nem megkülönböztető módon kell működnie.If possible, it should operate in a case-insensitive way. Ugyanakkor meg kell őriznie az eredeti esetet olyan parancsmagok esetében, amelyek később egy parancs vagy a folyamat során történnek.It should, however, preserve the original case for cmdlets that occur later in a command or in the pipeline.

Lásd még:See Also

Kötelező fejlesztői útmutatóRequired Development Guidelines

Tanácsolt fejlesztői útmutatóAdvisory Development Guidelines

Windows PowerShell-parancsmag írásaWriting a Windows PowerShell Cmdlet