about_Functions_OutputTypeAttribute

Artikel
10/06/2023

Deskripsi singkat

Menjelaskan atribut yang melaporkan jenis objek yang dikembalikan fungsi.

Deskripsi panjang

Atribut OutputType mencantumkan jenis objek .NET yang dikembalikan fungsi. Anda dapat menggunakan parameter ParameterSetName opsional untuk mencantumkan jenis output yang berbeda untuk setiap set parameter.

Atribut OutputType didukung pada fungsi sederhana dan tingkat lanjut. Ini independen dari atribut CmdletBinding .

Atribut OutputType menyediakan nilai properti OutputType dari objek System.Management.Automation.FunctionInfo yang Get-Command dikembalikan cmdlet.

Nilai atribut OutputType hanya catatan dokumentasi. Ini tidak berasal dari kode fungsi atau dibandingkan dengan output fungsi aktual. Dengan demikian, nilainya mungkin tidak akurat.

Sintaks

Atribut OutputType fungsi memiliki sintaks berikut:

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

Parameter ParameterSetName bersifat opsional.

Anda dapat mencantumkan beberapa jenis dalam atribut OutputType .

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

Anda dapat menggunakan parameter ParameterSetName untuk menunjukkan bahwa set parameter yang berbeda mengembalikan jenis yang berbeda.

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

Tempatkan pernyataan atribut OutputType dalam daftar atribut yang mendahului Param pernyataan.

Contoh berikut menunjukkan penempatan atribut OutputType dalam fungsi sederhana.

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

  <function body>
}

Contoh berikut menunjukkan penempatan atribut OutputType dalam fungsi lanjutan.

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

Contoh

Contoh 1: Buat fungsi yang memiliki OutputType string

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

  "Hello, $Name"
}

Untuk melihat properti jenis output yang dihasilkan, gunakan Get-Command cmdlet .

(Get-Command Send-Greeting).OutputType

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

Contoh 2: Gunakan atribut OutputType untuk menunjukkan jenis output dinamis

Fungsi tingkat lanjut berikut menggunakan atribut OutputType untuk menunjukkan bahwa fungsi mengembalikan jenis yang berbeda tergantung pada set parameter yang digunakan dalam perintah fungsi.

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

Contoh 3: Menunjukkan kapan output aktual berbeda dari OutputType

Contoh berikut menunjukkan bahwa nilai properti jenis output menampilkan nilai atribut OutputType , bahkan ketika tidak akurat.

Fungsi mengembalikan Get-Time string yang berisi bentuk singkat waktu dalam objek DateTime apa pun. Namun, atribut OutputType melaporkan bahwa ia mengembalikan objek System.DateTime .

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

  $DateTime.ToShortTimeString()
}

Metode ini GetType() mengonfirmasi bahwa fungsi mengembalikan string.

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

System.String

Namun, properti OutputType , yang mendapatkan nilainya dari atribut OutputType , melaporkan bahwa fungsi mengembalikan objek DateTime .

(Get-Command Get-Time).OutputType

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

Contoh 4: Fungsi yang seharusnya tidak memiliki output

Contoh berikut menunjukkan fungsi kustom yang harus melakukan tindakan tetapi tidak mengembalikan apa pun.

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

Catatan

Nilai properti OutputType dari objek FunctionInfo adalah array objek System.Management.Automation.PSTypeName , yang masing-masing memiliki properti Nama dan Jenis .

Untuk mendapatkan nama setiap jenis output saja, gunakan perintah dengan format berikut.

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

Atau versinya yang lebih pendek.

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

Nilai properti OutputType bisa null. Gunakan nilai null saat output bukan jenis .NET, seperti objek WMI atau tampilan objek yang diformat.