about_Functions_OutputTypeAttribute

Krótki opis

Opisuje atrybut zgłaszający typ obiektu zwracanego przez funkcję.

Długi opis

Atrybut OutputType zawiera listę typów obiektów platformy .NET zwracanych przez funkcje. Możesz użyć jego opcjonalnego parametru ParameterSetName, aby wyświetlić listę różnych typów danych wyjściowych dla każdego zestawu parametrów.

Atrybut OutputType jest obsługiwany w prostych i zaawansowanych funkcjach. Jest niezależny od atrybutu CmdletBinding.

Atrybut OutputType udostępnia wartość właściwości OutputType obiektu System.Management.Automation.FunctionInfo zwracanego przez Get-Command polecenie cmdlet.

Wartość atrybutu OutputType jest tylko uwagą dotyczącą dokumentacji. Nie pochodzi on z kodu funkcji ani nie jest porównywany z rzeczywistymi danymi wyjściowymi funkcji. W związku z tym wartość może być niedokładna.

Składnia

Atrybut OutputType funkcji ma następującą składnię:

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

Parametr ParameterSetName jest opcjonalny.

Można wyświetlić wiele typów w atrybucie OutputType.

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

Możesz użyć parametru ParameterSetName , aby wskazać, że różne zestawy parametrów zwracają różne typy.

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

Umieść instrukcje atrybutu OutputType na liście atrybutów, która poprzedza instrukcję Param .

W poniższym przykładzie pokazano umieszczenie atrybutu OutputType w prostej funkcji.

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

  <function body>
}

W poniższym przykładzie pokazano umieszczenie atrybutu OutputType w funkcjach zaawansowanych.

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

Przykłady

Przykład 1. Tworzenie funkcji z parametrem OutputType ciągu

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

  "Hello, $Name"
}

Aby wyświetlić wynikowe właściwości typu danych wyjściowych, użyj Get-Command polecenia cmdlet .

(Get-Command Send-Greeting).OutputType
Name                                               Type
----                                               ----
System.String                                      System.String

Przykład 2. Użyj atrybutu OutputType, aby wskazać dynamiczne typy danych wyjściowych

Poniższa funkcja zaawansowana używa atrybutu OutputType, aby wskazać, że funkcja zwraca różne typy w zależności od zestawu parametrów używanego w poleceniu funkcji.

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

Przykład 3: pokazuje, kiedy rzeczywiste dane wyjściowe różnią się od parametru OutputType

W poniższym przykładzie pokazano, że wartość właściwości typu danych wyjściowych wyświetla wartość atrybutu OutputType, nawet jeśli jest niedokładna.

Funkcja Get-Time zwraca ciąg, który zawiera krótką formę godziny w dowolnym obiekcie DateTime. Jednak atrybut OutputType zgłasza, że zwraca obiekt System.DateTime .

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

  $DateTime.ToShortTimeString()
}

Metoda GetType() potwierdza, że funkcja zwraca ciąg.

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

Jednak właściwość OutputType, która pobiera jej wartość z atrybutu OutputType, zgłasza, że funkcja zwraca obiekt DateTime .

(Get-Command Get-Time).OutputType
Name                                      Type
----                                      ----
System.DateTime                           System.DateTime

Przykład 4. Funkcja, która nie powinna mieć danych wyjściowych

W poniższym przykładzie pokazano funkcję niestandardową, która powinna wykonywać operacje i nie zwracać niczego.

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

Uwagi

Wartość właściwości OutputType obiektu FunctionInfo jest tablicą obiektów System.Management.Automation.PSTypeName , z których każda ma właściwości Name i Type.

Aby uzyskać tylko nazwę każdego typu danych wyjściowych, użyj polecenia w następującym formacie.

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

Lub jego krótsza wersja.

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

Wartość właściwości OutputType może mieć wartość null. Użyj wartości null, jeśli dane wyjściowe nie są typem platformy .NET, takim jak obiekt WMI lub sformatowany widok obiektu.

Zobacz też