about_Functions_OutputTypeAttribute

  • [アーティクル]

簡単な説明

関数が返すオブジェクトの種類を報告する属性について説明します。

詳細な説明

OutputType 属性は、関数が返すオブジェクトの .NET 型を一覧表示します。 省略可能な ParameterSetName パラメーターを使用すると、パラメーター セットごとに異なる出力の種類を一覧表示できます。

OutputType 属性は、単純関数と高度な関数でサポートされています。 これは、CmdletBinding 属性とは無関係です。

OutputType 属性は、コマンドレットが返す System.Management.Automation.FunctionInfo オブジェクトの OutputType プロパティの値をGet-Command提供します。

OutputType 属性値は、ドキュメントのメモにすぎません。 関数コードから派生したり、実際の関数の出力と比較したりしていません。 そのため、値が不正確になる可能性があります。

構文

関数の 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>
}

例

例 1: 文字列の OutputType を持つ関数を作成する

function Send-Greeting
{
  [OutputType([String])]
  Param ($Name)

  "Hello, $Name"
}

結果の出力の種類のプロパティを表示するには、コマンドレットを Get-Command 使用します。

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

メモ

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 にすることができます。 WMI オブジェクトやオブジェクトの書式設定されたビューなど、出力が .NET 型でない場合は、null 値を使用します。

関連項目