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 が String である関数をCreateする
function Send-Greeting
{
[OutputType([String])]
Param ($Name)
"Hello, $Name"
}
結果の出力型プロパティを表示するには、 コマンドレットを使用します Get-Command
。
(Get-Command Send-Greeting).OutputType
Name Type
---- ----
System.String System.String
例 2: Output 属性を使用して動的出力の種類を示す
次の高度な関数では、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-Time).OutputType | ForEach {$_.Name}
OutputType プロパティの値は null にすることができます。 WMI オブジェクトやオブジェクトの書式設定されたビューなど、出力が .NET 型ではない場合は null 値を使用します。