Menambahkan Parameter yang Memproses Input Baris Perintah

2025-03-25

Salah satu sumber input untuk cmdlet adalah baris perintah. Topik ini menjelaskan cara menambahkan parameter ke cmdlet Get-Proc (yang dijelaskan dalam Membuat Cmdlet Pertama Anda) sehingga cmdlet dapat memproses input dari komputer lokal berdasarkan objek eksplisit yang diteruskan ke cmdlet. cmdlet Get-Proc yang dijelaskan di sini mengambil proses berdasarkan namanya, lalu menampilkan informasi tentang proses pada prompt perintah.

Menentukan Kelas Cmdlet

Langkah pertama dalam pembuatan cmdlet adalah penamaan cmdlet dan deklarasi kelas .NET Framework yang mengimplementasikan cmdlet. Cmdlet ini mengambil informasi proses, sehingga nama kata kerja yang dipilih di sini adalah "Dapatkan." (Hampir semua jenis cmdlet yang mampu mengambil informasi dapat memproses input baris perintah.) Untuk informasi selengkapnya tentang kata kerja cmdlet yang disetujui, lihat Nama Kata Kerja Cmdlet.

Berikut adalah deklarasi kelas untuk cmdlet Get-Proc. Detail tentang definisi ini disediakan dalam Membuat Cmdlet Pertama Anda.

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand: Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

Mendeklarasikan Parameter

Parameter cmdlet memungkinkan pengguna untuk memberikan input ke cmdlet. Dalam contoh berikut, Get-Proc dan Get-Member adalah nama cmdlet yang disalurkan, dan MemberType adalah parameter untuk cmdlet Get-Member. Parameter memiliki argumen "properti."

PS> Get-Proc; Properti Get-Member -MemberType

Untuk mendeklarasikan parameter untuk cmdlet, Anda harus terlebih dahulu menentukan properti yang mewakili parameter. Dalam cmdlet Get-Proc, satu-satunya parameter adalah Name, yang dalam hal ini mewakili nama objek proses .NET Framework yang akan diambil. Oleh karena itu, kelas cmdlet mendefinisikan properti jenis string untuk menerima array nama.

Berikut adalah deklarasi parameter untuk parameter Name cmdlet Get-Proc.

/// <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

Untuk menginformasikan runtime Windows PowerShell bahwa properti ini adalah parameter Name, atribut System.Management.Automation.ParameterAttribute ditambahkan ke definisi properti. Sintaks dasar untuk mendeklarasikan atribut ini adalah [Parameter()].

Nota

Parameter harus secara eksplisit ditandai sebagai publik. Parameter yang tidak ditandai sebagai default publik ke internal dan tidak ditemukan oleh runtime Windows PowerShell.

Cmdlet ini menggunakan array string untuk parameter Name. Jika memungkinkan, cmdlet Anda juga harus menentukan parameter sebagai array, karena ini memungkinkan cmdlet untuk menerima lebih dari satu item.

Hal-hal yang Perlu Diingat Tentang Definisi Parameter

Nama parameter dan jenis data Windows PowerShell yang telah ditentukan sebelumnya harus digunakan kembali sebanyak mungkin untuk memastikan bahwa cmdlet Anda kompatibel dengan cmdlet Windows PowerShell. Misalnya, jika semua cmdlet menggunakan nama parameter Id yang telah ditentukan sebelumnya untuk mengidentifikasi sumber daya, pengguna akan dengan mudah memahami arti parameter, terlepas dari cmdlet apa yang mereka gunakan. Pada dasarnya, nama parameter mengikuti aturan yang sama dengan yang digunakan untuk nama variabel dalam runtime bahasa umum (CLR). Untuk informasi selengkapnya tentang penamaan parameter, lihat Nama Parameter Cmdlet .
Windows PowerShell mencadangkan beberapa nama parameter untuk memberikan pengalaman pengguna yang konsisten. Jangan gunakan nama parameter ini: WhatIf, Confirm, Verbose, Debug, Warn, ErrorAction, ErrorVariable, OutVariable, dan OutBuffer. Selain itu, alias berikut untuk nama parameter ini dicadangkan: vb, db, ea, ev, ov, dan ob.
Name adalah nama parameter sederhana dan umum, direkomendasikan untuk digunakan dalam cmdlet Anda. Lebih baik memilih nama parameter seperti ini daripada nama kompleks yang unik untuk cmdlet tertentu dan sulit diingat.
Parameter tidak peka huruf besar/kecil di Windows PowerShell, meskipun secara default shell mempertahankan kasus. Sensitivitas huruf besar/kecil argumen tergantung pada pengoperasian cmdlet. Argumen diteruskan ke parameter seperti yang ditentukan di baris perintah.
Untuk contoh deklarasi parameter lainnya, lihat Parameter Cmdlet .

Mendeklarasikan Parameter sebagai Posisi atau Bernama

Cmdlet harus mengatur setiap parameter sebagai parameter posisi atau bernama. Kedua jenis parameter menerima argumen tunggal, beberapa argumen yang dipisahkan oleh koma, dan pengaturan Boolean. Parameter Boolean, juga disebut sakelar , hanya menangani pengaturan Boolean. Sakelar digunakan untuk menentukan keberadaan parameter. Default yang disarankan adalah false.

Cmdlet Get-Proc sampel mendefinisikan parameter Name sebagai parameter posisi dengan posisi 0. Ini berarti bahwa argumen pertama yang dimasukkan pengguna pada baris perintah secara otomatis dimasukkan untuk parameter ini. Jika Anda ingin menentukan parameter bernama, di mana pengguna harus menentukan nama parameter dari baris perintah, biarkan kata kunci Position keluar dari deklarasi atribut.

Nota

Kecuali parameter harus diberi nama, kami sarankan Anda membuat parameter yang paling banyak digunakan posisi sehingga pengguna tidak perlu mengetik nama parameter.

Mendeklarasikan Parameter sebagai Wajib atau Opsional

Cmdlet harus mengatur setiap parameter sebagai parameter opsional atau wajib. Dalam cmdlet Get-Proc sampel, parameter Name didefinisikan sebagai opsional karena kata kunci Mandatory tidak diatur dalam deklarasi atribut.

Validasi Parameter Pendukung

Cmdlet Get-Proc sampel menambahkan atribut validasi input, System.Management.Automation.ValidateNotNullOrEmptyAttribute, ke parameter Name untuk mengaktifkan validasi bahwa input tidak null atau kosong. Atribut ini adalah salah satu dari beberapa atribut validasi yang disediakan oleh Windows PowerShell. Untuk contoh atribut validasi lainnya, lihat Memvalidasi Input Parameter.

[Parameter(Position = 0)]
[ValidateNotNullOrEmpty]
public string[] Name

Mengesampingkan Metode Pemrosesan Input

Jika cmdlet Anda adalah menangani input baris perintah, cmdlet harus mengambil alih metode pemrosesan input yang sesuai. Metode pemrosesan input dasar diperkenalkan dalam Membuat Cmdlet Pertama Anda.

Cmdlet Get-Proc mengambil alih metode System.Management.Automation.Cmdlet.ProcessRecord untuk menangani input parameter Name yang disediakan oleh pengguna atau skrip. Metode ini mendapatkan proses untuk setiap nama proses yang diminta, atau semua untuk proses jika tidak ada nama yang disediakan. Perhatikan bahwa dalam System.Management.Automation.Cmdlet.ProcessRecord, panggilan ke System.Management.Automation.Cmdlet.WriteObject adalah mekanisme output untuk mengirim objek output ke alur. Parameter kedua dari panggilan ini, enumerateCollection, diatur ke true untuk menginformasikan runtime Windows PowerShell untuk menghitung array output objek proses dan menulis satu proses sekaligus ke baris perintah.

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

Sampel Kode

Untuk kode sampel C# lengkap, lihat Sampel GetProcessSample02.

Menentukan Tipe objek dan Pemformatan

Windows PowerShell meneruskan informasi antar cmdlet dengan menggunakan objek .NET Framework. Akibatnya, cmdlet mungkin perlu menentukan jenisnya sendiri, atau cmdlet mungkin perlu memperluas jenis yang ada yang disediakan oleh cmdlet lain. Untuk informasi selengkapnya tentang menentukan jenis baru atau memperluas jenis yang sudah ada, lihat Memperluas Tipe Objek dan Pemformatan.

Membangun Cmdlet

Setelah menerapkan cmdlet, Anda harus mendaftarkannya dengan Windows PowerShell dengan menggunakan snap-in Windows PowerShell. Untuk informasi selengkapnya tentang mendaftarkan cmdlet, lihat Cara Mendaftarkan Cmdlet, Penyedia, dan Aplikasi Host.

Menguji Cmdlet

Ketika cmdlet Anda terdaftar di Windows PowerShell, Anda dapat mengujinya dengan menjalankannya di baris perintah. Berikut adalah dua cara untuk menguji kode untuk cmdlet sampel. Untuk informasi selengkapnya tentang menggunakan cmdlet dari baris perintah, lihat Memulai Windows PowerShell.

Pada prompt Windows PowerShell, gunakan perintah berikut untuk mencantumkan proses Internet Explorer, yang diberi nama "IEXPLORE."

Get-Proc -Name iexplore

Output berikut muncul.

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)   Id   ProcessName
-------  ------  -----   -----  -----   ------ --   -----------
    354      11  10036   18992    85   0.67   3284   iexplore

Untuk mencantumkan proses Internet Explorer, Outlook, dan Notepad bernama "IEXPLORE," "OUTLOOK," dan "NOTEPAD," gunakan perintah berikut. Jika ada beberapa proses, semuanya ditampilkan.

Get-Proc -Name iexplore, outlook, notepad

Output berikut muncul.

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