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ć 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.

Uwaga / Notatka

Wartość atrybutu OutputType nie pochodzi z kodu funkcji ani nie jest porównywana z rzeczywistymi danymi wyjściowymi funkcji. W związku z tym wartość może być niedokładna.

Atrybut OutputType informuje również wyniki ukończenia karty w sytuacjach takich jak: Command | Select <Tab> i Command | Where <Tab>.

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
}

Notatki

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 funkcja nie zapisuje żadnych danych wyjściowych w strumieniu Powodzenie . Jeśli funkcja zapisuje dane wyjściowe, ale nie znasz typu, użyj elementu System.Object.

Zobacz także

  • Last updated on