다음을 통해 공유

cmdlet 도움말 항목에 구문을 추가하는 방법

비고

XML 기반 도움말의 수동 작성은 매우 어렵습니다. PlatyPS 모듈을 사용하면 Markdown에서 도움말을 작성한 다음 XML 기반 도움말로 변환할 수 있습니다. 이렇게 하면 도움말을 훨씬 쉽게 작성하고 유지 관리할 수 있습니다. PlatyPS 업데이트 가능한 도움말 패키지를 만들 수도 있습니다. 자세한 내용은 PlatyPS사용하여 XML 기반 도움말 만들기를 참조하세요.

cmdlet 도움말 파일에서 구문 다이어그램에 대한 XML을 코딩하기 전에 이 섹션을 참조하여 매개 변수 특성과 같은 제공해야 하는 데이터의 종류와 해당 데이터가 구문 다이어그램에 표시되는 방식을 명확하게 파악합니다.

매개 변수 특성

  • 필수
    • true이면 매개 변수 집합을 사용하는 모든 명령에 매개 변수가 나타나야 합니다.
    • false이면 매개 변수 집합을 사용하는 모든 명령에서 매개 변수가 선택 사항입니다.
  • 위치
    • 이름이 지정되면 매개 변수 이름이 필요합니다.
    • 위치인 경우 매개 변수 이름은 선택 사항입니다. 생략하면 매개 변수 값이 명령의 지정된 위치에 있어야 합니다. 예를 들어 값이 position="1"인 경우 매개 변수 값은 명령의 첫 번째 또는 명명되지 않은 매개 변수 값이어야 합니다.
  • 파이프라인 입력
    • true(ByValue)이면 입력을 매개 변수로 파이프할 수 있습니다. 입력은 속성 이름 및 개체 형식이 예상된 형식과 일치하지 않는 경우에도 매개 변수와 연결됩니다("바인딩된 대상"). PowerShell 매개 변수 바인딩 구성 요소는 입력을 올바른 형식으로 변환하려고 시도하고 형식을 변환할 수 없는 경우에만 명령을 실패합니다. 매개 변수 집합의 매개 변수 하나만 값으로 연결할 수 있습니다.
    • true인 경우(ByPropertyName) 입력을 매개 변수로 파이프할 수 있습니다. 그러나 입력은 매개 변수 이름이 입력 개체의 속성 이름과 일치하는 경우에만 매개 변수와 연결됩니다. 예를 들어 매개 변수 이름이 Path경우 cmdlet에 파이프된 개체는 개체에 명명된 경로 속성이 있는 경우에만 해당 매개 변수와 연결됩니다.
    • true인 경우(ByValue, ByPropertyName) 속성 이름 또는 값으로 입력을 매개 변수로 파이프할 수 있습니다. 매개 변수 집합의 매개 변수 하나만 값으로 연결할 수 있습니다.
    • false이면 입력을 이 매개 변수로 파이프할 수 없습니다.
  • 글로빙(Globbing)
    • true이면 매개 변수 값에 대해 사용자가 입력하는 텍스트에 와일드카드 문자가 포함될 수 있습니다.
    • false이면 사용자가 매개 변수 값에 대해 입력하는 텍스트에 와일드카드 문자를 포함할 수 없습니다.

매개 변수 값 특성

  • 필수
    • true이면 명령에서 매개 변수를 사용할 때마다 지정된 값을 사용해야 합니다.
    • false이면 매개 변수 값은 선택 사항입니다. 일반적으로 값은 열거형 형식과 같이 매개 변수에 유효한 여러 값 중 하나인 경우에만 선택 사항입니다.

매개 변수 값의 Required 특성은 매개 변수의 Required 특성과 다릅니다.

매개 변수의 필수 특성은 cmdlet을 호출할 때 매개 변수(및 해당 값)를 포함해야 하는지 여부를 나타냅니다. 반면, 매개 변수 값의 필수 특성은 매개 변수가 명령에 포함된 경우에만 사용됩니다. 매개 변수와 함께 특정 값을 사용해야 하는지 여부를 나타냅니다.

일반적으로 자리 표시자인 매개 변수 값은 필수이며 리터럴인 매개 변수 값은 매개 변수와 함께 사용할 수 있는 여러 값 중 하나이기 때문에 필요하지 않습니다.

구문 정보 수집

  1. cmdlet 이름으로 시작합니다.

    SYNTAX
    Get-Tech

  2. cmdlet의 모든 매개 변수를 나열합니다. 각 매개 변수 이름 앞에 하이픈(-)을 입력합니다. 매개 변수를 매개 변수 집합으로 구분합니다(일부 cmdlet에는 하나의 매개 변수 집합만 있을 수 있음). 이 예제에서 Get-Tech cmdlet에는 두 개의 매개 변수 집합이 있습니다.

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

    cmdlet 이름으로 설정된 각 매개 변수를 시작합니다.

    기본 매개 변수 집합을 먼저 나열합니다. 기본 매개 변수는 cmdlet 클래스에 의해 지정됩니다.

    먼저 나타나야 하는 위치 매개 변수가 없는 한 각 매개 변수 집합에 대해 고유한 매개 변수를 먼저 나열합니다. 이전 예제에서 Name 및 Id 매개 변수는 두 매개 변수 집합에 대한 고유 매개 변수입니다(각 매개 변수 집합에는 해당 매개 변수 집합에 고유한 매개 변수가 하나 있어야 함). 이렇게 하면 사용자가 매개 변수 집합에 제공해야 하는 매개 변수를 더 쉽게 식별할 수 있습니다.

    명령에 표시되어야 하는 순서대로 매개 변수를 나열합니다. 순서가 중요하지 않은 경우 관련 매개 변수를 함께 나열하거나 가장 자주 사용되는 매개 변수를 먼저 나열합니다.

    cmdlet이 ShouldProcess를 지원하는 경우 WhatIf 및 Confirm 매개 변수를 나열해야 합니다.

    구문 다이어그램에 일반 매개 변수(예: 자세한 정보 표시, 디버그 및 ErrorAction)를 나열하지 마세요. Get-Help cmdlet은 도움말 항목을 표시할 때 해당 정보를 추가합니다.

  3. 매개 변수 값을 추가합니다. PowerShell에서 매개 변수 값은 해당 .NET 형식으로 표시됩니다. 그러나 System.String의 "string"과 같이 형식 이름을 축약할 수 있습니다.

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

    System.String 대한 문자열, System.Int32int 같은 의미가 명확한 경우 형식의 약어입니다.

    기본 또는 고급 설정할 수 있는 이전 예제의 -Type 매개 변수와 같은 열거형의 모든 값을 나열합니다.

    이전 예제의 -List 같은 스위치 매개 변수에는 값이 없습니다.

  4. 리터럴인 매개 변수 값과 비교하여 자리 표시자인 매개 변수 값에 꺾쇠 괄호를 추가합니다.

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

  5. 선택적 매개 변수와 해당 골짜기 값을 대괄호로 묶습니다.

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

  6. 선택적 매개 변수 이름(위치 매개 변수의 경우)을 대괄호로 묶습니다. 다음 예제의 Name 매개 변수와 같이 위치가 있는 매개 변수의 이름은 명령에 포함될 필요가 없습니다.

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

  7. Name 매개 변수의 이름 목록과 같이 매개 변수 값에 여러 값이 포함될 수 있는 경우 매개 변수 값 바로 다음에 대괄호 쌍을 추가합니다.

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

  8. 사용자가 Type 매개 변수와 같은 매개 변수 또는 매개 변수 값 중에서 선택할 수 있는 경우 선택 항목을 중괄호로 묶고 배타적 OR 기호(;)로 구분합니다.

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

  9. 매개 변수 값이 따옴표 또는 괄호와 같은 특정 서식을 사용해야 하는 경우 구문에 형식을 표시합니다.

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

구문 다이어그램 XML 코딩

XML의 구문 노드는 설명 노드 바로 후에 시작되며 </maml:description> 태그로 끝납니다. 구문 다이어그램에 사용된 데이터를 수집하는 방법에 대한 자세한 내용은 수집 구문 정보참조하세요.

구문 노드 추가

cmdlet 도움말 항목에 표시되는 구문 다이어그램은 XML 구문 노드의 데이터에서 생성됩니다. 구문 노드는 <command:syntax> 태그 쌍으로 묶입니다. cmdlet의 각 매개 변수 집합을 <command:syntaxitem> 태그 쌍으로 묶습니다. 추가할 수 있는 <command:syntaxitem> 태그 수에는 제한이 없습니다.

다음 예제에서는 두 매개 변수 집합에 대한 구문 항목 노드가 있는 구문 노드를 보여 줍니다.

<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 이름 추가

cmdlet의 각 매개 변수 집합은 구문 항목 노드에 지정됩니다. 각 구문 항목 노드는 cmdlet의 이름을 포함하는 <maml:name> 태그 쌍으로 시작합니다.

다음 예제에는 두 매개 변수 집합에 대한 구문 항목 노드가 있는 구문 노드가 포함되어 있습니다.

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

매개 변수 추가

구문 항목 노드에 추가된 각 매개 변수는 <command:parameter> 태그 쌍 내에 지정됩니다. PowerShell에서 제공하는 일반적인 매개 변수를 제외하고 매개 변수 집합에 포함된 각 매개 변수에 대해 한 쌍의 <command:parameter> 태그가 필요합니다.

여는 <command:parameter> 태그의 특성은 매개 변수가 구문 다이어그램에 표시되는 방식을 결정합니다. 매개 변수 특성에 대한 자세한 내용은 매개 변수 특성참조하세요.

비고

<command:parameter> 태그는 콘텐츠가 표시되지 않는 자식 요소 <maml:description> 지원합니다. 매개 변수 설명은 XML의 매개 변수 노드에 지정됩니다. 구문 항목 bodes의 정보와 매개 변수 노드 간의 불일치를 방지하려면 (<maml:description> 생략하거나 비워 둡니다.

다음 예제에서는 두 개의 매개 변수가 있는 매개 변수 집합에 대한 구문 항목 노드를 포함합니다.

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