about_Functions_OutputTypeAttribute

  • Artykuł

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ć 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 funkcjach prostych i zaawansowanych. 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 notatką 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.

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

[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óre 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ć wynikowy typ 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 zawierający 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

Poniższy przykład przedstawia funkcję niestandardową, która powinna wykonać akcję, ale 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-Date).OutputType | Select-Object -ExpandProperty Name

Lub jego krótsza wersja.

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

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

Zobacz też