Parametre bilgisi nasıl eklenir

Not

XML tabanlı yardımın manuel olarak yazılması çok zordur. PlatyPS modülü, Markdown'da yardım yazmanıza ve ardından bunu XML tabanlı yardıma dönüştürmenize olanak tanır. Bu, yardım yazmayı ve sürdürmeyi çok daha kolaylaştırır. PlatyPS ayrıca sizin için Güncellenebilir Yardım paketleri de oluşturabilir. Daha fazla bilgi için PlatyPS kullanarak XML tabanlı yardım oluşturma konusuna bakın.

Bu bölümde, cmdlet Yardım konusunun PARAMETRELER bölümünde görüntülenen içeriğin nasıl ekleneceği açıklanmaktadır. Yardım konusunun PARAMETRELER bölümü, cmdlet'in parametrelerinin her birini listeler ve her parametrenin ayrıntılı bir açıklamasını sağlar.

PARAMETRELER bölümünün içeriği, Yardım konusunun SÖZ DİZİMİ bölümünün içeriğiyle tutarlı olmalıdır. Hem Söz Dizimi hem de Parametreler düğümünün benzer XML öğeleri içerdiğinden emin olmak Yardım yazarının sorumluluğundadır.

Not

Yardım dosyasının tam görünümü için PowerShell kurulum dizininde bulunan dll-Help.xml dosyalarından birini açın. Örneğin, Microsoft.PowerShell.Commands.Management.dll-Help.xml dosyası birçok PowerShell cmdlet'ine ilişkin içerik içerir.

Parametre eklemek için

Cmdlet Yardım dosyasını açın ve belgelediğiniz cmdlet'in Komut düğümünü bulun. Yeni bir cmdlet ekliyorsanız yeni bir Komut düğümü oluşturmanız gerekecektir. Yardım dosyanız, Yardım içeriği sağladığınız her cmdlet için bir Komut düğümü içerecektir. Boş bir Komut düğümünün bir örneğini burada bulabilirsiniz.
```
<command:command>
</command:command>
```
Komut düğümünde Açıklama düğümünü bulun ve aşağıda gösterildiği gibi bir Parametreler düğümü ekleyin. Yalnızca bir Parametreler düğümüne izin verilir ve bu düğümün hemen Sözdizimi düğümünü takip etmesi gerekir.
```
<command:command>
  <command:details></command:details>
  <maml:description></maml:description>
  <command:syntax></command:syntax>
  <command:parameters>
  </command:parameters>
</command:command>
```
Parametreler düğümü içine, cmdlet'in her parametresi için aşağıda gösterildiği gibi bir Parametre düğümü ekleyin.
Bu örnekte, üç parametre için bir Parametre düğümü eklenmiştir.
```
<command:parameters>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
  <command:parameter></command:parameter>
</command:parameters>
```
Bunlar Sözdizimi düğümünde kullanılan XML etiketleriyle aynı olduğundan ve burada belirtilen parametrelerin Sözdizimi düğümü tarafından belirtilen parametrelerle eşleşmesi gerektiğinden, <Parametre düğümlerini Sözdizimi düğümünden alın ve bunları Parametreler düğümüne yapıştırın. Ancak, parametre sözdiziminde birden çok parametre kümesinde belirtilmiş olsa bile, Parametre düğümünün yalnızca bir örneğini kopyaladığınızdan emin olun.

Her Parametre düğümü için, her parametrenin özelliklerini tanımlayan nitelik değerlerini ayarlayın. Bu özellikler şunları içerir: gerekli, globbing, ardışık düzen girişi ve konum.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named">
  </command:parameter>
  <command:parameter required="false" globbing="false"
           pipelineInput="false" position="named" ></command:parameter>
</command:parameters>

Her Parametre düğümü için parametrenin adını ekleyin. Burada Parametre düğümüne eklenen parametre adının bir örneği verilmiştir.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
  </command:parameter>
</command:parameters>

Her Parametre düğümü için parametrenin açıklamasını ekleyin. Burada Parametre düğümüne eklenen parametre açıklamasının bir örneği verilmiştir.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
  </command:parameter>
</command:parameters>

Her Parametre düğümü için parametrenin .NET türünü ekleyin. Parametre türü, parametre adıyla birlikte görüntülenir.

Aşağıda, Parametre düğümüne eklenen .NET parametresi türünün bir örneği verilmiştir.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
  </command:parameter>
</command:parameters>

Her Parametre düğümü için parametrenin varsayılan değerini ekleyin. İçerik görüntülendiğinde parametre açıklamasına aşağıdaki cümle eklenir: DefaultValue varsayılandır.

Aşağıda, Parametre düğümüne eklenen varsayılan parametre değerinin bir örneği verilmiştir.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Add parameter name...  </maml:name>
    <maml:description>
      <maml:para> Add parameter description... </maml:para>
    </maml:description>
    <dev:type> Add .NET Framework type... </dev:type>
    <dev:defaultvalue> Add default value...</dev:defaultvalue>
  </command:parameter>
</command:parameters>

Birden çok değeri olan her Parametre için bir possibleValues düğümü ekleyin.

Burada, parametre için iki olası değeri tanımlayan possibleValues düğümünün bir örneği verilmiştir.

<dev:possibleValues>
  <dev:possibleValue>
    <dev:value>Unknown</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
  <dev:possibleValue>
    <dev:value>String</dev:value>
    <maml:description>
      <maml:para></maml:para>
    </maml:description>
  </dev:possibleValue>
</dev:possibleValues>

Parametre eklerken hatırlamanız gereken bazı noktalar şunlardır.

Parametrenin öznitelikleri cmdlet Yardım konusunun tüm görünümlerinde görüntülenmez. Ancak kullanıcı Tam (Get-Help -Full) veya Parametre< değerini istediğinde parametre açıklamasını takip eden bir tabloda görüntülenirler. Konunun (Get-Help -Parameter) görünümü.
Parametre açıklaması cmdlet Yardım konusunun en önemli parçalarından biridir. Açıklama kısa ve kapsamlı olmalıdır. Ayrıca, parametre açıklaması çok uzun olursa (örneğin, iki parametrenin birbiriyle etkileşime girmesi durumunda) cmdlet Yardımı konusunun NOTLAR bölümüne daha fazla içerik ekleyebileceğinizi unutmayın.
Parametre açıklaması iki tür bilgi sağlar.
Parametre kullanıldığında cmdlet'in yaptığı şey.
Parametrenin yasal değeri nedir?
Parametre değerleri .NET nesneleri olarak ifade edildiğinden, kullanıcıların bu değerler hakkında geleneksel komut satırı Yardımından daha fazla bilgiye ihtiyacı vardır. Kullanıcıya parametrenin ne tür verileri kabul etmek üzere tasarlandığını söyleyin ve örnekler ekleyin.

Parametrenin varsayılan değeri, parametrenin komut satırında belirtilmemesi durumunda kullanılan değerdir. Varsayılan değerin isteğe bağlı olduğunu ve gerekli parametreler gibi bazı parametreler için gerekli olmadığını unutmayın. Ancak isteğe bağlı parametrelerin çoğu için varsayılan bir değer belirtmeniz gerekir.

Varsayılan değer, kullanıcının parametreyi kullanmamanın etkisini anlamasına yardımcı olur. İsteğe bağlı bir yol için "Geçerli dizin" veya "PowerShell yükleme dizini ($PSHOME)" gibi varsayılan değeri çok spesifik bir şekilde açıklayın. Ayrıca, PassThru parametresi için kullanılan aşağıdaki cümle gibi, varsayılanı açıklayan bir cümle de yazabilirsiniz: "PassThru belirtilmezse, cmdlet nesneleri işlem hattından aşağıya aktarmaz." Ayrıca değer, Varsayılan değer alan adının karşısında görüntülendiğinden, girişe "varsayılan değer" terimini eklemeniz gerekmez.

Parametrenin varsayılan değeri cmdlet Yardım konusunun tüm görünümlerinde görüntülenmez. Ancak, kullanıcı Tam (Get-Help -Tam) veya değerini istediğinde parametre açıklamasını takip eden bir tabloda (parametre nitelikleriyle birlikte) görüntülenir. Konunun Parametre (Get-Help -Parameter) görünümü.

Aşağıdaki XML, <command:parameter> düğümüne eklenen bir çift <dev:defaultValue> etiketini gösterir. Varsayılan değerin, kapatma </command:parameterValue> etiketinden (parametre değeri belirtildiğinde) veya kapatma </maml:description> etiketinden hemen sonra geldiğine dikkat edin. parametre açıklaması. isim.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
  </command:parameter>
</command:parameters>

Numaralandırılmış Türler için Değer Ekleme

Parametrenin birden fazla değeri veya numaralandırılmış türde değerleri varsa isteğe bağlı bir <dev:possibleValues> düğümü kullanabilirsiniz. Bu düğüm, birden çok değer için bir ad ve açıklama belirtmenize olanak tanır.

Numaralandırılmış değerlerin açıklamalarının Get-Help cmdlet'i tarafından görüntülenen varsayılan Yardım görünümlerinin hiçbirinde görünmediğini, ancak diğer Yardım görüntüleyicilerinin bu içeriği kendi görünümlerinde görüntüleyebileceğini unutmayın.

Aşağıdaki XML, belirtilen iki değere sahip bir <dev:possibleValues> düğümünü gösterir.

<command:parameters>
  <command:parameter required="true" globbing="true"
           pipelineInput="false" position="named">
    <maml:name> Parameter name </maml:name>
    <maml:description>
      <maml:para> Parameter Description </maml:para>
    </maml:description>
    <command:parameterValue required="true">
      Value
    </command:parameterValue>
    <dev:defaultValue> Default parameter value </dev:defaultValue>
    <dev:possibleValues>
      <dev:possibleValue>
        <dev:value> Value 1 </dev:value>
        <maml:description>
          <maml:para> Description 1 </maml:para>
        </maml:description>
      <dev:possibleValue>
      <dev:possibleValue>
        <dev:value> Value 2 </dev:value>
        <maml:description>
          <maml:para> Description 2 </maml:para>
        </maml:description>
      <dev:possibleValue>
    </dev:possibleValues>
  </command:parameter>
</command:parameters>

Parametre bilgisi nasıl eklenir

Parametre eklemek için

İlgili makaleler