about_Functions_OutputTypeAttribute

  • Artikel

Korte beschrijving

Beschrijft een kenmerk dat het type object rapporteert dat door de functie wordt geretourneerd.

Lange beschrijving

Het kenmerk OutputType bevat de .NET-typen objecten die door de functies worden geretourneerd. U kunt de optionele parameter ParameterSetName gebruiken om verschillende uitvoertypen voor elke parameterset weer te geven.

Het kenmerk OutputType wordt ondersteund voor eenvoudige en geavanceerde functies. Het is onafhankelijk van het cmdletBinding-kenmerk .

Het kenmerk OutputType biedt de waarde van de eigenschap OutputType van het object System.Management.Automation.FunctionInfo die door de Get-Command cmdlet wordt geretourneerd.

De waarde van het kenmerk OutputType is alleen een documentatienotitie. Deze is niet afgeleid van de functiecode of vergeleken met de werkelijke functie-uitvoer. Als zodanig kan de waarde onnauwkeurig zijn.

Syntaxis

Het kenmerk OutputType van functies heeft de volgende syntaxis:

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

De parameter ParameterSetName is optioneel.

U kunt meerdere typen weergeven in het kenmerk OutputType .

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

U kunt de parameter ParameterSetName gebruiken om aan te geven dat verschillende parametersets verschillende typen retourneren.

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

Plaats de outputType-kenmerkinstructies in de lijst met kenmerken die voorafgaan aan de Param instructie.

In het volgende voorbeeld ziet u de plaatsing van het kenmerk OutputType in een eenvoudige functie.

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

  <function body>
}

In het volgende voorbeeld ziet u de plaatsing van het kenmerk OutputType in geavanceerde functies.

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

Voorbeelden

Voorbeeld 1: Een functie maken met het OutputType van tekenreeks

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

  "Hello, $Name"
}

Gebruik de cmdlet om de resulterende eigenschap van het uitvoertype weer te Get-Command geven.

(Get-Command Send-Greeting).OutputType

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

Voorbeeld 2: het kenmerk OutputType gebruiken om dynamische uitvoertypen aan te geven

De volgende geavanceerde functie gebruikt het kenmerk OutputType om aan te geven dat de functie verschillende typen retourneert, afhankelijk van de parameterset die in de functieopdracht wordt gebruikt.

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

Voorbeeld 3: Toont wanneer een werkelijke uitvoer verschilt van het OutputType

In het volgende voorbeeld ziet u dat de eigenschapswaarde van het uitvoertype de waarde van het kenmerk OutputType weergeeft, zelfs wanneer deze onjuist is.

De Get-Time functie retourneert een tekenreeks die de korte vorm van de tijd in een DateTime-object bevat. Het kenmerk OutputType rapporteert echter dat het een System.DateTime-object retourneert.

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

  $DateTime.ToShortTimeString()
}

De GetType() methode bevestigt dat de functie een tekenreeks retourneert.

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

System.String

De eigenschap OutputType, die de waarde ophaalt uit het kenmerk OutputType, rapporteert echter dat de functie een DateTime-object retourneert.

(Get-Command Get-Time).OutputType

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

Voorbeeld 4: Een functie die geen uitvoer mag hebben

In het volgende voorbeeld ziet u een aangepaste functie die een actie moet uitvoeren, maar niets retourneert.

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

Opmerkingen

De waarde van de eigenschap OutputType van een FunctionInfo-object is een matrix van System.Management.Automation.PSTypeName-objecten, die elk de eigenschappen Name en Type hebben.

Als u alleen de naam van elk uitvoertype wilt ophalen, gebruikt u een opdracht met de volgende indeling.

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

Of de kortere versie.

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

De waarde van de eigenschap OutputType kan null zijn. Gebruik een null-waarde als de uitvoer geen .NET-type is, zoals een WMI-object of een opgemaakte weergave van een object.

Zie ook