about_Functions_CmdletBindingAttribute

Artikel
10/04/2023

Deskripsi singkat

Menjelaskan atribut yang membuat fungsi berfungsi seperti cmdlet yang dikompilasi.

Deskripsi panjang

Atribut CmdletBinding adalah atribut fungsi yang membuatnya beroperasi seperti cmdlet yang dikompilasi yang ditulis dalam C#. Ini menyediakan akses ke fitur cmdlet.

PowerShell mengikat parameter fungsi yang memiliki CmdletBinding atribut dengan cara yang sama seperti mengikat parameter cmdlet yang dikompilasi. Variabel $PSCmdlet otomatis tersedia untuk fungsi dengan CmdletBinding atribut , tetapi $Args variabel tidak tersedia.

Dalam fungsi yang memiliki CmdletBinding atribut , parameter yang tidak diketahui dan argumen posisi yang tidak memiliki parameter posisi yang cocok menyebabkan pengikatan parameter gagal.

Catatan

Cmdlet yang dikompilasi menggunakan atribut yang diperlukan Cmdlet , yang mirip CmdletBinding dengan atribut yang dijelaskan dalam topik ini.

Sintaks

Contoh berikut menunjukkan format fungsi yang menentukan semua argumen CmdletBinding opsional atribut. Deskripsi singkat dari setiap argumen mengikuti contoh ini.

{
    [CmdletBinding(ConfirmImpact=<String>,
    DefaultParameterSetName=<String>,
    HelpURI=<URI>,
    SupportsPaging=<Boolean>,
    SupportsShouldProcess=<Boolean>,
    PositionalBinding=<Boolean>)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

Jenis argumen boolean dari atribut CmdletBinding default ke False saat dihilangkan dari atribut CmdletBinding . Atur nilai argumen ke $true atau cukup cantumkan argumen menurut nama. Misalnya, atribut CmdletBinding berikut setara.

{
    [CmdletBinding(SupportsPaging=$true)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

# Boolean arguments can be defined using this shorthand syntax

{
    [CmdletBinding(SupportsPaging)]

    Param ($Parameter1)
    Begin{}
    Process{}
    End{}
}

ConfirmImpact

Argumen ConfirmImpact menentukan kapan tindakan fungsi harus dikonfirmasi oleh panggilan ke metode ShouldProcess . Panggilan ke metode ShouldProcess menampilkan perintah konfirmasi hanya ketika argumen ConfirmImpact sama dengan atau lebih besar dari $ConfirmPreference nilai variabel preferensi. (Nilai default argumen adalah Sedang.) Tentukan argumen ini hanya ketika argumen SupportsShouldProcess juga ditentukan.

Untuk informasi selengkapnya tentang permintaan konfirmasi, lihat Meminta Konfirmasi.

DefaultParameterSetName

Argumen DefaultParameterSetName menentukan nama kumpulan parameter yang akan coba digunakan PowerShell saat tidak dapat menentukan parameter mana yang diatur untuk digunakan. Anda dapat menghindari masalah ini dengan membuat parameter unik dari setiap parameter menetapkan parameter wajib.

HelpURI

Argumen HelpURI menentukan alamat internet dari versi online topik bantuan yang menjelaskan fungsi. Nilai argumen HelpURI harus dimulai dengan "http" atau "https".

Nilai argumen HelpURI digunakan untuk nilai properti HelpURI objek CommandInfo yang Get-Command dikembalikan untuk fungsi tersebut.

Namun, ketika file bantuan diinstal di komputer dan nilai tautan pertama di bagian RelatedLinks dari file bantuan adalah URI, atau nilai arahan pertama .Link dalam bantuan berbasis komentar adalah URI, URI dalam file bantuan digunakan sebagai nilai properti HelpUri fungsi.

Get-Help Cmdlet menggunakan nilai properti HelpURI untuk menemukan versi online topik bantuan fungsi saat parameter Get-Help Online ditentukan dalam perintah.

SupportsPaging

Argumen SupportsPaging menambahkan parameter First, Skip, dan IncludeTotalCount ke fungsi . Parameter ini memungkinkan pengguna untuk memilih output dari kumpulan hasil yang sangat besar. Argumen ini dirancang untuk cmdlet dan fungsi yang mengembalikan data dari penyimpanan data besar yang mendukung pemilihan data, seperti database SQL.

Argumen ini diperkenalkan di Windows PowerShell 3.0.

Pertama: Hanya mendapatkan objek 'n' pertama.
Lewati: Mengabaikan objek 'n' pertama lalu mendapatkan objek yang tersisa.
IncludeTotalCount: Melaporkan jumlah objek dalam himpunan data (bilangan bulat) diikuti oleh objek. Jika cmdlet tidak dapat menentukan jumlah total, cmdlet mengembalikan "Jumlah total tidak diketahui".

PowerShell menyertakan NewTotalCount, metode pembantu yang mendapatkan nilai jumlah total untuk dikembalikan dan menyertakan perkiraan akurasi nilai jumlah total.

Contoh fungsi berikut menunjukkan cara menambahkan dukungan untuk parameter halaman ke fungsi tingkat lanjut.

function Get-Numbers {
    [CmdletBinding(SupportsPaging)]
    param()

    $FirstNumber = [Math]::Min($PSCmdlet.PagingParameters.Skip, 100)
    $LastNumber = [Math]::Min($PSCmdlet.PagingParameters.First +
      $FirstNumber - 1, 100)

    if ($PSCmdlet.PagingParameters.IncludeTotalCount) {
        $TotalCountAccuracy = 1.0
        $TotalCount = $PSCmdlet.PagingParameters.NewTotalCount(100,
          $TotalCountAccuracy)
        Write-Output $TotalCount
    }
    $FirstNumber .. $LastNumber | Write-Output
}

MendukungShouldProcess

Argumen SupportsShouldProcess menambahkan parameter Konfirmasi dan WhatIf ke fungsi . Parameter Konfirmasi meminta pengguna sebelum menjalankan perintah pada setiap objek dalam alur. Parameter WhatIf mencantumkan perubahan yang akan dilakukan perintah, alih-alih menjalankan perintah.

PositionalBinding

Argumen PositionalBinding menentukan apakah parameter dalam fungsi berposisi secara default. Nilai defaultnya adalah $True. Anda dapat menggunakan argumen PositionalBinding dengan nilai $False untuk menonaktifkan pengikatan posisi.

Argumen PositionalBinding diperkenalkan di Windows PowerShell 3.0.

Ketika parameter berposisi, nama parameter bersifat opsional. PowerShell mengaitkan nilai parameter yang tidak disebutkan namanya dengan parameter fungsi sesuai dengan urutan atau posisi nilai parameter yang tidak disebutkan namanya dalam perintah fungsi.

Ketika parameter tidak berposisi (mereka "bernama"), nama parameter (atau singkatan atau alias nama) diperlukan dalam perintah.

Ketika PositionalBinding adalah $True, parameter fungsi berposisi secara default. PowerShell menetapkan nomor posisi ke parameter dalam urutan di mana mereka dideklarasikan dalam fungsi.

Ketika PositionalBinding adalah $False, parameter fungsi tidak berposisi secara default. Kecuali argumen Posisi atribut Parameter dideklarasikan pada parameter, nama parameter (atau alias atau singkatan) harus disertakan saat parameter digunakan dalam fungsi.

Argumen Posisi atribut Parameter lebih diutamakan daripada nilai default PositionalBinding. Anda dapat menggunakan argumen Posisi untuk menentukan nilai posisi untuk parameter. Untuk informasi selengkapnya tentang argumen Posisi , lihat about_Functions_Advanced_Parameters.