about_Functions_CmdletBindingAttribute

  • Makale

Kısa açıklama

bir işlevin derlenmiş bir cmdlet gibi çalışmasını sağlayan özniteliği açıklar.

Uzun açıklama

CmdletBinding özniteliği, C# dilinde yazılmış derlenmiş cmdlet'ler gibi çalışmalarına neden olan işlevlerin özniteliğidir. Cmdlet'lerin özelliklerine erişim sağlar.

PowerShell, özniteliğine sahip CmdletBinding işlevlerin parametrelerini, derlenmiş cmdlet'lerin parametrelerini bağlayabilecek şekilde bağlar. Otomatik $PSCmdlet değişken özniteliğine sahip CmdletBinding işlevler için kullanılabilir, ancak $Args değişkeni kullanılamaz.

Özniteliği olan işlevlerde CmdletBinding , eşleşen konumsal parametreleri olmayan bilinmeyen parametreler ve konumsal bağımsız değişkenler parametre bağlamanın başarısız olmasına neden olur.

Not

Derlenmiş cmdlet'ler, bu konuda açıklanan özniteliğe CmdletBinding benzer olan gerekli Cmdlet özniteliği kullanır.

Sözdizimi

Aşağıdaki örnek, özniteliğin tüm isteğe bağlı bağımsız değişkenlerini belirten bir işlevin CmdletBinding biçimini gösterir. Her bağımsız değişkenin kısa bir açıklaması bu örneği izler.

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

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

CmdletBinding özniteliğinin boole bağımsız değişkeni türleri, CmdletBinding özniteliğinden atlandığında varsayılan olarak False olarak ayarlanır. Bağımsız değişken değerini olarak $true ayarlayın veya yalnızca bağımsız değişkeni ada göre listeleyin. Örneğin, aşağıdaki CmdletBinding öznitelikleri eşdeğerdir.

{
    [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

ConfirmImpact bağımsız değişkeni, işlevin eyleminin ShouldProcess yöntemine yapılan bir çağrıyla ne zaman onaylanması gerektiğini belirtir. ShouldProcess yöntemine yapılan çağrı, yalnızca ConfirmImpact bağımsız değişkeni tercih değişkeninin $ConfirmPreference değerine eşit veya ondan büyük olduğunda bir onay istemi görüntüler. (Bağımsız değişkenin varsayılan değeriOrta.) Bu bağımsız değişkeni yalnızca SupportsShouldProcess bağımsız değişkeni de belirtildiğinde belirtin.

Onay istekleri hakkında daha fazla bilgi için bkz . Onay İsteme.

DefaultParameterSetName

DefaultParameterSetName bağımsız değişkeni, Hangi parametre kümesinin kullanılacağını belirleyemediğinde PowerShell'in kullanmayı deneyeceği parametre kümesinin adını belirtir. Her parametre kümesinin benzersiz parametresini zorunlu bir parametre yaparak bu sorundan kaçınabilirsiniz.

YardımURI'sı

HelpURI bağımsız değişkeni, yardım konusunun işlevini açıklayan çevrimiçi sürümünün internet adresini belirtir. HelpURI bağımsız değişkeninin değeri "http" veya "https" ile başlamalıdır.

HelpURI bağımsız değişken değeri, işlev için döndüren CommandInfo nesnesinin HelpURI özelliğinin Get-Command değeri için kullanılır.

Ancak, yardım dosyaları bilgisayara yüklendiğinde ve yardım dosyasının RelatedLinks bölümündeki ilk bağlantının değeri bir URI olduğunda veya açıklama tabanlı yardımdaki ilk .Link yönergenin değeri bir URI olduğunda, yardım dosyasındaki URI işlevin HelpUri özelliğinin değeri olarak kullanılır.

cmdlet' Get-Help inin Online parametresi Get-Help bir komutta belirtildiğinde işlev yardım konusunun çevrimiçi sürümünü bulmak için HelpURI özelliğinin değerini kullanır.

SupportsPaging

SupportsPaging bağımsız değişkeni İşleve First, Skip ve IncludeTotalCount parametrelerini ekler. Bu parametreler kullanıcıların çok büyük bir sonuç kümesinden çıktı seçmesine olanak sağlar. Bu bağımsız değişken, SQL veritabanı gibi veri seçimini destekleyen büyük veri depolarından veri döndüren cmdlet'ler ve işlevler için tasarlanmıştır.

Bu bağımsız değişken Windows PowerShell 3.0'da kullanıma sunulmuştur.

  • İlk: Yalnızca ilk 'n' nesnelerini alır.
  • Atla: İlk 'n' nesnelerini yoksayar ve kalan nesneleri alır.
  • IncludeTotalCount: Veri kümesindeki nesne sayısını (bir tamsayı) ve ardından nesneleri bildirir. Cmdlet toplam sayıyı belirleyemezse, "Bilinmeyen toplam sayısı" döndürür.

PowerShell, döndürülecek toplam sayı değerini alan ve toplam sayı değerinin doğruluğuna ilişkin bir tahmin içeren yardımcı yöntem olan NewTotalCount'ı içerir.

Aşağıdaki örnek işlev, gelişmiş bir işleve disk belleği parametreleri için nasıl destek ekleneceğini gösterir.

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
}

SupportsShouldProcess

SupportsShouldProcess bağımsız değişkeni işlevine Confirm ve WhatIf parametrelerini ekler. Confirm parametresi, işlem hattındaki her nesnede komutu çalıştırmadan önce kullanıcıya sorar. WhatIf parametresi, komutu çalıştırmak yerine komutun yapacağı değişiklikleri listeler.

PositionalBinding

PositionalBinding bağımsız değişkeni, işlevdeki parametrelerin varsayılan olarak konumsal olup olmadığını belirler. Varsayılan değer şudur: $True. Konumsal bağlamayı devre dışı bırakmak için PositionalBinding bağımsız değişkenini $False değeriyle kullanabilirsiniz.

PositionalBinding bağımsız değişkeni Windows PowerShell 3.0'da kullanıma sunulmuştur.

Parametreler konumsal olduğunda, parametre adı isteğe bağlıdır. PowerShell, işlev komutundaki adlandırılmamış parametre değerlerinin sırasına veya konumuna göre adsız parametre değerlerini işlev parametreleriyle ilişkilendirir.

Parametreler konumsal olmadığında ("adlandırılmış") parametre adı (veya adın kısaltması veya diğer adı) komutunda gereklidir.

PositionalBinding olduğunda$True, işlev parametreleri varsayılan olarak konumsaldır. PowerShell, parametrelere işlevde bildirildiği sırayla konum numarası atar.

PositionalBinding olduğunda$False, işlev parametreleri varsayılan olarak konumsal değildir. Parametrede Parameter özniteliğinin Position bağımsız değişkeni bildirilmediği sürece, parametre bir işlevde kullanıldığında parametre adı (veya diğer ad veya kısaltma) eklenmelidir.

Parameter özniteliğinin Position bağımsız değişkeni PositionalBinding varsayılan değerinden önceliklidir. Bir parametre için konum değeri belirtmek için Konum bağımsız değişkenini kullanabilirsiniz. Konum bağımsız değişkeni hakkında daha fazla bilgi için bkz. about_Functions_Advanced_Parameters.

Notlar

SupportsTransactions bağımsız değişkeni gelişmiş işlevlerde desteklenmez.

Anahtar sözcükler

about_Functions_CmdletBinding_Attribute

Ayrıca bkz.