about_Functions_OutputTypeAttribute

이 문서는 PowerShell 함수의 출력 형식을 선언하는 OutputType 특성(attribute)에 대해 다뤄요. 함수가 돌려주는 개체의 .NET 형식을 어떻게 명시하고, 그 값이 어디에 쓰이며, 실제 출력과 다를 수 있다는 점까지 함께 살펴볼게요.

출처: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_outputtypeattribute

본문

간단 설명 (Short description)

함수가 반환하는 개체의 형식을 알려 주는 특성에 대한 설명이에요.

자세한 설명 (Long description)

OutputType 특성은 함수가 반환하는 개체의 .NET 형식을 나열해 줘요. 선택 매개 변수인 ParameterSetName을 사용하면 매개 변수 집합(parameter set)별로 서로 다른 출력 형식을 지정할 수도 있어요.

이 OutputType 특성은 간단 함수(simple function)와 고급 함수(advanced function) 모두에서 쓸 수 있고, CmdletBinding 특성과는 독립적으로 동작해요. Get-Command cmdlet이 반환하는 System.Management.Automation.FunctionInfo 개체의 OutputType 속성 값이 바로 여기서 채워져요.

한 가지 알아둘 점이 있어요. OutputType 특성의 값은 함수 코드에서 자동으로 유도되거나 실제 함수 출력과 비교해 검증되지 않아요. 그래서 이 값이 실제와 다를 수도 있어요.

또한 OutputType 특성은 Command | Select <Tab>이나 Command | Where <Tab>처럼 탭 완성(tab completion) 결과에도 영향을 줘요.

구문 (Syntax)

함수의 OutputType 특성은 다음과 같은 구문을 가져요.

[OutputType([<TypeLiteral>], ParameterSetName="<Name>")]
[OutputType("<TypeNameString>", ParameterSetName="<Name>")]

ParameterSetName 매개 변수는 생략할 수 있어요.

OutputType 특성에는 여러 형식을 나열할 수도 있어요.

[OutputType([<Type1>],[<Type2>],[<Type3>])]

ParameterSetName 매개 변수를 쓰면 매개 변수 집합에 따라 서로 다른 형식을 반환한다는 뜻을 나타낼 수 있어요.

[OutputType([<Type1>], ParameterSetName=("<Set1>","<Set2>"))]
[OutputType([<Type2>], ParameterSetName="<Set3>")]

OutputType 특성 문은 param 문 앞에 오는 특성 목록에 넣어 주세요.

간단 함수에서 OutputType 특성의 위치를 보여 주는 예시예요.

function SimpleFunction2
{
  [OutputType([<Type>])]
  param ($Parameter1)

  <function body>
}

고급 함수에서 OutputType 특성의 위치를 보여 주는 예시예요.

function AdvancedFunction1
{
  [OutputType([<Type>])]
  param (
    [Parameter(Mandatory=$true)]
    [string[]]
    $Parameter1
  )

  <function body>
}

function AdvancedFunction2
{
  [CmdletBinding(SupportsShouldProcess=<Boolean>)]
  [OutputType([<Type>])]
  param (
    [Parameter(Mandatory=$true)]
    [string[]]
    $Parameter1
  )

  <function body>
}

예시 (Examples)

예시 1: OutputType이 String인 함수 만들기

function Send-Greeting
{
  [OutputType([string])]
  param ($Name)

  "Hello, $Name"
}

결과로 나오는 출력 형식 속성을 확인하려면 Get-Command cmdlet을 쓰면 돼요.

(Get-Command Send-Greeting).OutputType

Name                                               Type
----                                               ----
System.String                                      System.String

예시 2: OutputType 특성으로 동적 출력 형식 나타내기

아래 고급 함수는 함수 명령에서 사용된 매개 변수 집합에 따라 서로 다른 형식을 반환한다는 것을 OutputType 특성으로 나타내는 예시예요.

function Get-User
{
  [CmdletBinding(DefaultParameterSetName="ID")]

  [OutputType("System.Int32", ParameterSetName="ID")]
  [OutputType([string], ParameterSetName="Name")]

  param (
    [Parameter(Mandatory=$true, ParameterSetName="ID")]
    [int]
    $UserID,

    [Parameter(Mandatory=$true, ParameterSetName="Name")]
    [string[]]
    $UserName
  )

  <function body>
}

예시 3: 실제 출력이 OutputType과 다를 때

이 예시는 출력 형식 속성 값이 실제와 다르더라도 OutputType 특성의 값을 그대로 보여 준다는 점을 보여 줘요.

Get-Time 함수는 어떤 DateTime 개체에서든 시간의 짧은 형태를 담은 문자열을 반환해요. 그런데 OutputType 특성은 이 함수가 System.DateTime 개체를 반환한다고 보고해요.

function Get-Time
{
  [OutputType([datetime])]
  param (
    [Parameter(Mandatory=$true)]
    [datetime]$DateTime
  )

  $DateTime.ToShortTimeString()
}

GetType() 메서드를 쓰면 이 함수가 문자열을 반환한다는 걸 확인할 수 있어요.

(Get-Time -DateTime (Get-Date)).GetType().FullName

System.String

하지만 OutputType 특성에서 값을 가져오는 OutputType 속성은 이 함수가 DateTime 개체를 반환한다고 보고해요.

(Get-Command Get-Time).OutputType

Name                                      Type
----                                      ----
System.DateTime                           System.DateTime

예시 4: 출력이 없어야 하는 함수

다음은 어떤 동작을 수행하지만 아무것도 반환하지 않아야 하는 사용자 정의 함수를 보여 주는 예시예요.

function Invoke-Notepad
{
  [OutputType([System.Void])]
  param ()
  & notepad.exe | Out-Null
}

참고 사항 (Notes)

FunctionInfo 개체의 OutputType 속성 값은 System.Management.Automation.PSTypeName 개체의 배열이에요. 각 개체는 Name 속성과 Type 속성을 가지고 있어요.

각 출력 형식의 이름만 가져오려면 다음과 같은 형식의 명령을 쓰면 돼요.

(Get-Command Get-Date).OutputType | Select-Object -ExpandProperty Name

더 짧은 버전도 있어요.

(Get-Command Get-Date).OutputType.Name

OutputType 속성 값은 null이 될 수도 있어요. 함수가 Success 스트림에 아무 출력도 쓰지 않을 때는 null 값을 쓰세요. 출력은 쓰지만 형식을 모른다면 System.Object를 쓰면 돼요.

about_Functions_OutputTypeAttribute