about_Functions_OutputTypeAttribute

[アーティクル]
11/16/2015

適用対象: Windows PowerShell 3.0, Windows PowerShell 4.0

トピック

概要

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

詳細説明

OutputType 属性は、関数から返されるオブジェクトの .NET 型を一覧表示します。そのオプションの ParameterSetName パラメーターを使用して、パラメーターセットごとに異なる出力の種類を一覧表示できます。

OutputType 属性は、単純な関数でも高度な関数でもサポートされています。CmdletBinding 属性から独立しています。

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

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

例

次の関数は、OutputType 属性を使用して、文字列の値が返されることを示しています。

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

          Hello, $Name      
        }

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

        PS C:\> (Get-Command Send-Greeting).OutputType

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

次の高度な関数は、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>
       }

次の例では、正確な値でない場合でも、OutputType 属性の値が出力の種類のプロパティ値に表示されることを示しています。

Get-Time 関数は、DateTime オブジェクトの短い形式の時間が含まれている文字列を返します。一方、OutputType 属性は System.DateTime オブジェクトを返していることを報告します。

        function Get-Time
        { 
            [OutputType([DateTime])]
            Param
            (
               [parameter(Mandatory=$true)]
               [Datetime]$DateTime       
            )
            $DateTime.ToShortTimeString()
        }

Get-Type メソッドは、関数が文字列を返すことを確認します。

        PS C:\> (Get-Time -DateTime (Get-Date)).Gettype().FullName
        System.String

一方、OutputType 属性は、自身の値を OutputType プロパティから取得し、関数が DateTime オブジェクトを返していることを報告します。

        PS C:\> (Get-Command Get-Time).OutputType

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

注意事項

FunctionInfo オブジェクトの OutputType プロパティの値は System.Management.Automation.PSTypeName オブジェクトの配列で、この各オブジェクトには Name プロパティと Type プロパティがあります。

各出力の種類の名前のみを取得するには、次の形式でコマンドを使用します。

        (Get-Command Get-Time).OutputType | ForEach {$_.Name}

OutputType プロパティの値を null にできます。WMI オブジェクトやビューが書式設定されたオブジェクトなど、出力が .NET 型でない場合には、null 値を使用します。

about_Functions_OutputTypeAttribute

トピック

概要

詳細説明

例

注意事項

関連項目

その他のリソース