Aracılığıyla paylaş

Cmdlet yardım konusuna söz dizimi ekleme

Uyarı

XML tabanlı yardımın el ile yazılması çok zordur. PlatyPS modülü, Markdown'da yardım yazmanızı ve xml tabanlı yardıma dönüştürmenizi sağlar. Bu, yardım yazmayı ve sürdürmeyi çok daha kolay hale getirir. PlatyPS sizin için Güncelleştirilebilir Yardım paketlerini de oluşturabilir. Daha fazla bilgi için PlatyPSkullanarak XML tabanlı yardım oluşturma bölümüne bakın.

Cmdlet Yardım dosyasında söz dizimi diyagramı için XML kodunu yazmaya başlamadan önce, parametre öznitelikleri ve söz dizimi diyagramında verilerin nasıl görüntülendiği gibi sağlamanız gereken veri türlerinin net bir resmini almak için bu bölümü okuyun..

Parametre öznitelikleri

  • Gerekli
    • True ise parametresi, parametre kümesini kullanan tüm komutlarda görünmelidir.
    • False ise parametresi, parametre kümesini kullanan tüm komutlarda isteğe bağlıdır.
  • Konum
    • Adlandırılmışsa parametre adı gereklidir.
    • Konumsalsa, parametre adı isteğe bağlıdır. Atlandığında, parametre değeri komutta belirtilen konumda olmalıdır. Örneğin, değer position="1" ise, parametre değeri komuttaki ilk veya yalnızca adlandırılmamış parametre değeri olmalıdır.
  • İşlem Hattı Girişi
    • True (ByValue) ise, girişi parametresine yöneltebilirsiniz. Özellik adı ve nesne türü beklenen türle eşleşmese bile giriş parametresiyle ("ilişkili") ilişkilendirilir. PowerShell parametre bağlama bileşenleri girişi doğru türe dönüştürmeyi dener ve komutu yalnızca tür dönüştürülemiyorsa başarısız olur. Bir parametre kümesindeki yalnızca bir parametre değerle ilişkilendirilebilir.
    • True (ByPropertyName) ise, girişi parametresine yöneltebilirsiniz. Ancak, giriş parametresiyle yalnızca parametre adı giriş nesnesinin bir özelliğinin adıyla eşleştiğinde ilişkilendirilir. Örneğin, parametre adı Pathise, cmdlet'ine yöneltilen nesneler yalnızca nesnenin path adlı bir özelliği olduğunda bu parametreyle ilişkilendirilir.
    • true (ByValue, ByPropertyName) ise, girdiyi özellik adına veya değere göre parametreye yöneltebilirsiniz. Bir parametre kümesindeki yalnızca bir parametre değerle ilişkilendirilebilir.
    • False ise, girişi bu parametreye yöneltemezsiniz.
  • Globbing
    • True ise, kullanıcının parametre değeri için yazdığınız metin joker karakterler içerebilir.
    • False ise, kullanıcının parametre değeri için yazdığınız metin joker karakter içeremez.

Parametre değeri öznitelikleri

  • Gerekli
    • True ise, bir komutta parametresi kullanıldığında belirtilen değerin kullanılması gerekir.
    • False ise parametre değeri isteğe bağlıdır. Genellikle, bir değer yalnızca bir parametre için numaralandırılmış tür gibi birkaç geçerli değerden biri olduğunda isteğe bağlıdır.

Parametre değerinin Gerekli özniteliği, parametrenin Gerekli özniteliğinden farklıdır.

Bir parametrenin gerekli özniteliği, cmdlet'i çağrılırken parametrenin (ve değerinin) eklenip eklenmeyeceğini gösterir. Buna karşılık, parametre değerinin gerekli özniteliği yalnızca parametre komuta eklendiğinde kullanılır. Belirli bir değerin parametresiyle birlikte kullanılması gerekip gerekmediğini gösterir.

Genellikle, parametreyle kullanılabilecek çeşitli değerlerden biri olduğundan, yer tutucu olan parametre değerleri gereklidir ve değişmez değer olan parametre değerleri gerekli değildir.

Söz dizimi bilgilerini toplama

  1. Cmdlet adıyla başlayın.

    SYNTAX
    Get-Tech

  2. Cmdlet'in tüm parametrelerini listeleyin. Her parametre adından önce bir kısa çizgi (-) yazın. Parametreleri parametre kümelerine ayırın (bazı cmdlet'lerde yalnızca bir parametre kümesi olabilir). Bu örnekte Get-Tech cmdlet'i iki parametre kümesine sahiptir.

    SYNTAX
    Get-Tech -Name -Type
    Get-Tech -Id -List -Type

    Her parametre kümesini cmdlet adıyla başlatın.

    İlk olarak varsayılan parametre kümesini listeleyin. Varsayılan parametre cmdlet sınıfı tarafından belirtilir.

    Her parametre kümesi için, önce görünmesi gereken konumsal parametreler olmadığı sürece benzersiz parametresini listeleyin. Önceki örnekte, Ad ve Kimlik parametreleri iki parametre kümesi için benzersiz parametrelerdir (her parametre kümesinin bu parametre kümesine özgü bir parametresi olmalıdır). Bu, kullanıcıların parametre kümesi için hangi parametreyi sağlamaları gerektiğini belirlemelerini kolaylaştırır.

    Parametreleri, komutta görünmeleri gereken sırayla listeleyin. Sıra önemli değilse, önce ilgili parametreleri birlikte listeleyin veya en sık kullanılan parametreleri listeleyin.

    Cmdlet ShouldProcess'i destekliyorsa WhatIf ve Confirm parametrelerini listelemeyi unutmayın.

    Söz dizimi diyagramınızda yaygın parametreleri (Ayrıntılı, Hata Ayıklama ve ErrorAction gibi) listelemeyin. Get-Help cmdlet'i, Yardım konusunu görüntülerken bu bilgileri sizin için ekler.

  3. Parametre değerlerini ekleyin. PowerShell'de parametre değerleri .NET türleriyle temsil edilir. Ancak tür adı, System.String için "dize" gibi kısaltılabilir.

    SYNTAX
    Get-Tech -Name string -Type Basic Advanced
    Get-Tech -Id int -List -Type Basic Advanced

    System.String için dize ve System.Int32için int gibi anlamları açık olduğu sürece türleri kısaltılır.

    Önceki örnekteki -Type parametresi gibi, temel veya gelişmiş olarak ayarlanabilen tüm numaralandırma değerlerini listeleyin.

    Önceki örnekteki -List gibi switch parametrelerinin değerleri yoktur.

  4. Sabit değer olan parametre değerlerine kıyasla yer tutucu olan parametre değerlerine açılı ayraçlar ekleyin.

    SYNTAX
    Get-Tech -Name <string> -Type Basic Advanced
    Get-Tech -Id <int> -List -Type Basic Advanced

  5. İsteğe bağlı parametreleri ve valelerini köşeli ayraç içine alın.

    SYNTAX
    Get-Tech -Name <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

  6. İsteğe bağlı parametre adlarını (konumsal parametreler için) köşeli ayraç içine alın. Aşağıdaki örnekteki Name parametresi gibi konumsal olan parametrelerin adının komuta eklenmesi gerekmez.

    SYNTAX
    Get-Tech [-Name] <string> [-Type Basic Advanced]
    Get-Tech -Id <int> [-List] [-Type Basic Advanced]

  7. Bir parametre değeri Name parametresindeki ad listesi gibi birden çok değer içerebiliyorsa, parametre değerinin hemen ardından bir çift köşeli ayraç ekleyin.

    SYNTAX
    Get-Tech [-Name] <string[]> [-Type Basic Advanced]
    Get-Tech -Id <int[]> [-List] [-Type Basic Advanced]

  8. Kullanıcı Tür parametresi gibi parametrelerden veya parametre değerlerinden seçim yapabilirse, seçenekleri köşeli ayraç içine alın ve bunları özel OR simgesi (;)) ile ayırın.

    SYNTAX
    Get-Tech [-Name] <string[]> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]

  9. Parametre değerinin tırnak işaretleri veya parantezler gibi belirli bir biçimlendirme kullanması gerekiyorsa, biçimi söz diziminde gösterin.

    SYNTAX
    Get-Tech [-Name] <"string[]"> [-Type {Basic | Advanced}]
    Get-Tech -Id <int[]> [-List] [-Type {Basic | Advanced}]

Söz dizimi diyagramı XML'sini kodlama

XML'nin söz dizimi düğümü, </maml:description> etiketiyle biten açıklama düğümünden hemen sonra başlar. Söz dizimi diyagramında kullanılan verileri toplama hakkında bilgi için bkz. Toplama Sözdizimi Bilgileri.

Söz dizimi düğümü ekleme

Cmdlet Yardım konusunda görüntülenen söz dizimi diyagramı, XML'nin söz dizimi düğümündeki verilerden oluşturulur. Söz dizimi düğümü bir çift <command:syntax> etiketi içine alınır. Cmdlet'in her parametre kümesi bir çift <command:syntaxitem> etiketi içine alınır. Ekleyebileceğiniz <command:syntaxitem> etiketlerinin sayısıyla ilgili bir sınır yoktur.

Aşağıdaki örnekte, iki parametre kümesi için söz dizimi öğesi düğümlerine sahip bir söz dizimi düğümü gösterilmektedir.

<command:syntax>
  <command:syntaxItem>
    ...
    <!--Parameter Set 1 (default parameter set) parameters go here-->
    ...
  </command:syntaxItem>
  <command:syntaxItem>
    ...
    <!--Parameter Set 2 parameters go here-->
    ...
  </command:syntaxItem>
</command:syntax>

Cmdlet adını parametre kümesi verilerine ekleme

Cmdlet'in her parametre kümesi bir söz dizimi öğesi düğümünde belirtilir. Her söz dizimi öğesi düğümü, cmdlet'in adını içeren bir çift <maml:name> etiketiyle başlar.

Aşağıdaki örnek, iki parametre kümesi için söz dizimi öğesi düğümlerine sahip bir söz dizimi düğümü içerir.

<command:syntax>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
  <command:syntaxItem>
    <maml:name>Cmdlet-Name</maml:name>
  </command:syntaxItem>
</command:syntax>

Parametre ekleme

Söz dizimi öğesi düğümüne eklenen her parametre, bir çift <command:parameter> etiketi içinde belirtilir. PowerShell tarafından sağlanan ortak parametreler dışında, parametre kümesine dahil edilen her parametre için bir çift <command:parameter> etiketine ihtiyacınız vardır.

Açılış <command:parameter> etiketinin öznitelikleri, parametrenin söz dizimi diyagramında nasıl görüneceğini belirler. Parametre öznitelikleri hakkında bilgi için bkz. Parametre Öznitelikleri.

Uyarı

<command:parameter> etiketi, içeriği hiçbir zaman görüntülenmeyen bir alt öğe <maml:description> destekler. Parametre açıklamaları, XML'nin parametre düğümünde belirtilir. Söz dizimi öğesi bodes ve parametre düğümündeki bilgiler arasındaki tutarsızlıkları önlemek için (<maml:description> atlayın veya boş bırakın.

Aşağıdaki örnek, iki parametreli bir parametre kümesi için söz dizimi öğesi düğümü içerir.

<command:syntaxItem>
  <maml:name>Cmdlet-Name</maml:name>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByValue)" position="1">
    <maml:name>ParameterName1</maml:name>
    <command:parameterValue required="true">
      string[]
    </command:parameterValue>
  </command:parameter>
  <command:parameter required="true" globbing="true"
    pipelineInput="true (ByPropertyName)">
    <maml:name>ParameterName2</maml:name>
    <command:parameterValue required="true">
      int32[]
    </command:parameterValue>
  </command:parameter>
</command:syntaxItem>
  • Last updated on