Hinzufügen von Parametern, die Befehlszeileneingaben verarbeiten
Eine Eingabequelle für ein Cmdlet ist die Befehlszeile. In diesem Thema wird beschrieben, wie Sie dem Cmdlet einen Parameter hinzufügen Get-Proc
(der unter Erstellen Ihres ersten Cmdletsbeschrieben wird), damit das Cmdlet Eingaben vom lokalen Computer auf der Grundlage expliziter Objekte verarbeiten kann, die an das Cmdlet übergeben werden. Das Get-Proc
hier beschriebene Cmdlet ruft Prozesse basierend auf ihren Namen ab und zeigt dann Informationen zu den Prozessen an einer Eingabeaufforderung an.
Definieren der Cmdlet-Klasse
Der erste Schritt bei der Cmdlet-Erstellung ist die Cmdlet-Benennung und die Deklaration der .NET Framework Klasse, die das Cmdlet implementiert. Dieses Cmdlet ruft Prozessinformationen ab, sodass der hier ausgewählte Verbname "Get" lautet. (Fast jede Art von Cmdlet, das Informationen abrufen kann, kann Befehlszeileneingaben verarbeiten.) Weitere Informationen zu genehmigten Cmdlet-Verben finden Sie unter Cmdlet Verb Names.
Hier ist die Klassendeklaration für das Get-Proc
Cmdlet. Details zu dieser Definition finden Sie unter Erstellen Ihres ersten Cmdlets.
[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet
<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
Inherits Cmdlet
Deklarieren von Parametern
Mit einem Cmdlet-Parameter kann der Benutzer Eingaben für das Cmdlet bereitstellen. Im folgenden Beispiel Get-Proc
sind und die Namen von Get-Member
pipelined-Cmdlets und MemberType
ein Parameter für das Get-Member
Cmdlet. Der Parameter verfügt über das Argument "property".
PS> get-proc ; get-member
-membertype-Eigenschaft
Um Parameter für ein Cmdlet zu deklarieren, müssen Sie zuerst die Eigenschaften definieren, die die Parameter darstellen. Im Get-Proc
Cmdlet ist der einzige Parameter , der Name
in diesem Fall den Namen des abzurufenden .NET Framework Prozessobjekts darstellt. Daher definiert die Cmdlet-Klasse eine Eigenschaft vom Typ string, um ein Array von Namen zu akzeptieren.
Hier ist die Parameterdeklaration für den Name
Parameter des Get-Proc
Cmdlets.
/// <summary>
/// Specify the cmdlet Name parameter.
/// </summary>
[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name
{
get { return processNames; }
set { processNames = value; }
}
private string[] processNames;
#endregion Parameters
<Parameter(Position:=0), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
Get
Return processNames
End Get
Set(ByVal value As String())
processNames = value
End Set
End Property
Um die Windows PowerShell Runtime darüber zu informieren, dass diese Eigenschaft der Name
Parameter ist, wird der Eigenschaftendefinition ein System.Management.Automation.Parameterattribute-Attribut hinzugefügt. Die grundlegende Syntax zum Deklarieren dieses Attributs ist [Parameter()]
.
Hinweis
Ein Parameter muss explizit als öffentlich gekennzeichnet werden. Parameter, die nicht als öffentlicher Standardwert für intern markiert sind und von der Windows PowerShell Runtime nicht gefunden werden.
Dieses Cmdlet verwendet ein Array von Zeichenfolgen für den Name
Parameter. Wenn möglich, sollte Ihr Cmdlet auch einen Parameter als Array definieren, da dies es dem Cmdlet ermöglicht, mehr als ein Element zu akzeptieren.
Zu beachtende Punkte zu Parameterdefinitionen
Vordefinierte Windows PowerShell Parameternamen und Datentypen sollten so weit wie möglich wiederverwendet werden, um sicherzustellen, dass Ihr Cmdlet mit Windows PowerShell Cmdlets kompatibel ist. Wenn beispielsweise alle Cmdlets den vordefinierten
Id
Parameternamen verwenden, um eine Ressource zu identifizieren, kann der Benutzer die Bedeutung des Parameters leicht verstehen, unabhängig davon, welches Cmdlet er verwendet. Im Grunde folgen Parameternamen den gleichen Regeln wie für Variablennamen in der Common Language Runtime (CLR). Weitere Informationen zur Parameterbenennung finden Sie unter Cmdlet-Parameternamen.Windows PowerShell reserviert einige Parameternamen, um eine konsistente Benutzererfahrung zu gewährleisten. Verwenden Sie diese Parameternamen nicht:
WhatIf
, , , , , , , ,Confirm
undVerbose
Debug
Warn
ErrorAction
ErrorVariable
OutVariable
OutBuffer
. Darüber hinaus sind die folgenden Aliase für diese Parameternamen reserviert:vb
, , , , unddb
ea
ev
ov
ob
.Name
ist ein einfacher und allgemeiner Parametername, der für die Verwendung in Ihren Cmdlets empfohlen wird. Es ist besser, einen Parameternamen wie diesen auszuwählen als einen komplexen Namen, der für ein bestimmtes Cmdlet eindeutig und schwer zu merken ist.Bei Parametern wird die Groß-/Kleinschreibung in Windows PowerShell nicht beachtet, obwohl die Groß-/Kleinschreibung von der Shell standardmäßig beibehalten wird. Die Empfindlichkeit der Argumente für die Kleinschreibung hängt vom Betrieb des Cmdlets ab. Argumente werden wie in der Befehlszeile angegeben an einen Parameter übergeben.
Beispiele für andere Parameterdeklarationen finden Sie unter Cmdlet-Parameter.
Deklarieren von Parametern als positional oder benannt
Ein Cmdlet muss jeden Parameter entweder als Positionsparameter oder als benannten Parameter festlegen. Beide Arten von Parametern akzeptieren einzelne Argumente, mehrere durch Kommas getrennte Argumente und boolesche Einstellungen. Ein boolescher Parameter, der auch als Switch bezeichnet wird, verarbeitet nur boolesche Einstellungen. Der Schalter wird verwendet, um das Vorhandensein des Parameters zu bestimmen. Der empfohlene Standardwert ist false
.
Das Get-Proc
Beispiel-Cmdlet definiert den Name
Parameter als Positionsparameter mit Position.
0. Das bedeutet, dass das erste Argument, das der Benutzer in die Befehlszeile eingibt, automatisch für diesen Parameter eingefügt wird. Wenn Sie einen benannten Parameter definieren möchten, für den der Benutzer den Parameternamen über die Befehlszeile angeben muss, lassen Sie das Position
Schlüsselwort aus der Attributdeklaration weg.
Hinweis
Sofern keine Parameter benannt werden müssen, wird empfohlen, die am häufigsten verwendeten Parameter so zu positionieren, dass Benutzer den Parameternamen nicht eingeben müssen.
Deklarieren von Parametern als obligatorisch oder optional
Ein Cmdlet muss jeden Parameter entweder als optionalen oder obligatorischen Parameter festlegen. Im Get-Proc
Beispiel-Cmdlet wird der Name
Parameter als optional definiert, da das Schlüsselwort Mandatory
in der Attributdeklaration nicht festgelegt ist.
Unterstützen der Parametervalidierung
Das Get-Proc
Beispiel-Cmdlet fügt dem Parameter das Eingabevalidierungsattribut System.Management.Automation.Validatenotnulloremptyattributehinzu, Name
um die Überprüfung zu ermöglichen, dass die Eingabe weder noch leer null
ist. Dieses Attribut ist eines von mehreren Validierungsattributen, die von Windows PowerShell bereitgestellt werden. Beispiele für andere Validierungsattribute finden Sie unter Validating Parameter Input.
[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name
Überschreiben einer Eingabeverarbeitungsmethode
Wenn Ihr Cmdlet Befehlszeileneingaben verarbeiten soll, muss es die entsprechenden Eingabeverarbeitungsmethoden überschreiben. Die grundlegenden Eingabeverarbeitungsmethoden werden unter Creating Your First Cmdlet (Erstellen Ihres ersten Cmdlets)eingeführt.
Das Get-Proc
Cmdlet überschreibt die System.Management.Automation.Cmdlet.ProcessRecord-Methode, um die Name
vom Benutzer oder einem Skript bereitgestellte Parametereingabe zu verarbeiten. Diese Methode ruft die Prozesse für jeden angeforderten Prozessnamen oder alle prozesse ab, wenn kein Name angegeben wird. Beachten Sie, dass in System.Management.Automation.Cmdlet.ProcessRecordder Aufruf von System.Management.Automation.Cmdlet.WriteObject%28System.Object%2CSystem.Boolean%29 der Ausgabemechanismus zum Senden von Ausgabeobjekten an die Pipeline ist. Der zweite Parameter dieses Aufrufs enumerateCollection
ist auf festgelegt, true
um die Windows PowerShell Runtime zu informieren, das Ausgabearray von Prozessobjekten aufzuzählen und jeweils einen Prozess in die Befehlszeile zu schreiben.
protected override void ProcessRecord()
{
// If no process names are passed to the cmdlet, get all processes.
if (processNames == null)
{
// Write the processes to the pipeline making them available
// to the next cmdlet. The second argument of this call tells
// PowerShell to enumerate the array, and send one process at a
// time to the pipeline.
WriteObject(Process.GetProcesses(), true);
}
else
{
// If process names are passed to the cmdlet, get and write
// the associated processes.
foreach (string name in processNames)
{
WriteObject(Process.GetProcessesByName(name), true);
}
}
}
Protected Overrides Sub ProcessRecord()
'/ If no process names are passed to the cmdlet, get all processes.
If processNames Is Nothing Then
Dim processes As Process()
processes = Process.GetProcesses()
End If
'/ If process names are specified, write the processes to the
'/ pipeline to display them or make them available to the next cmdlet.
For Each name As String In processNames
'/ The second parameter of this call tells PowerShell to enumerate the
'/ array, and send one process at a time to the pipeline.
WriteObject(Process.GetProcessesByName(name), True)
Next
End Sub 'ProcessRecord
Codebeispiel
Den vollständigen C#-Beispielcode finden Sie unter GetProcessSample02-Beispiel.
Definieren von Objekttypen und Formatierung
Windows PowerShell übergibt Informationen mithilfe .NET Framework -Objekte zwischen Cmdlets. Folglich muss ein Cmdlet möglicherweise einen eigenen Typ definieren, oder ein Cmdlet muss einen vorhandenen Typ erweitern, der von einem anderen Cmdlet bereitgestellt wird. Weitere Informationen zum Definieren neuer Typen oder zum Erweitern vorhandener Typen finden Sie unter Erweitern von Objekttypen und Formatierenvon .
Erstellen des Cmdlets
Nachdem Sie ein Cmdlet implementiert haben, müssen Sie es mithilfe eines Windows PowerShell Snap-Ins bei Windows PowerShell registrieren. Weitere Informationen zum Registrieren von Cmdlets finden Sie unter Registrieren von Cmdlets, Anbietern und Hostanwendungen.
Testen des Cmdlets
Wenn Ihr Cmdlet bei Windows PowerShell registriert ist, können Sie es testen, indem Sie es in der Befehlszeile ausführen. Es gibt zwei Möglichkeiten, den Code für das Beispiel-Cmdlet zu testen. Weitere Informationen zur Verwendung von Cmdlets über die Befehlszeile finden Sie unter Erste Schritte mit Windows PowerShell.
Verwenden Sie an der eingabeaufforderung Windows PowerShell folgenden Befehl, um den Internet Explorer Prozess mit dem Namen "IEXPLORE" aufzulisten.
get-proc -name iexplore
Die folgende Ausgabe wird angezeigt.
Handles NPM(K) PM(K) WS(K) VS(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 354 11 10036 18992 85 0.67 3284 iexplore
Verwenden Sie den folgenden Befehl, um die Internet Explorer, Outlook und Editor Prozesse mit den Namen "IEXPLORE", "OUTLOOK" und "NOTEPAD" aufzulisten. Wenn mehrere Prozesse vorhanden sind, werden alle angezeigt.
get-proc -name iexplore, outlook, notepad
Die folgende Ausgabe wird angezeigt.
Handles NPM(K) PM(K) WS(K) VS(M) CPU(s) Id ProcessName ------- ------ ----- ----- ----- ------ -- ----------- 732 21 24696 5000 138 2.25 2288 iexplore 715 19 20556 14116 136 1.78 3860 iexplore 3917 62 74096 58112 468 191.56 1848 OUTLOOK 39 2 1024 3280 30 0.09 1444 notepad 39 2 1024 356 30 0.08 3396 notepad
Weitere Informationen
Hinzufügen von Parametern, die Pipelineeingaben verarbeiten
Erstellen Ihres ersten Cmdlets
Erweitern von Objekttypen und Formatierung
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für