powershell - PowerShell反射:将MIME类型或子类型定义为脚本的输出类型

Question

在PowerShell中可以在脚本上定义输出类型。考虑myScript.ps1:

[OutputType([String])]
param(
    [string]$name
)

以下返回 String:

(Get-Command .\myScript.ps1).OutputType.Name

但我想指定一个脚本返回 text/json或 text/xml。这样做的一个好方法是什么？

为OutputType发明类型(例如 [String.JSON])不起作用。

Answer 1

有两种声明输出类型的独立但互补的机制:

重要提示:两种声明输出类型的方法都仅提供信息，PowerShell在运行时不会强制执行。

机制:在脚本或函数中使用OutputType声明上方的 param() attribute，如下所示:

始终使用此机制，并在必要时补充机制B。

仅识别.NET类型的完整类型名称或PowerShell的名称类型加速器，并且不执行前期验证，但是如果在调用时遇到无法识别的类型:

(如果最初指定为字符串)(例如'System.Text.Encoding'):将被静默忽略。

(如果最初指定为类型文字)(例如[System.Text.Encoding]):函数调用在调用

时中断

这种严格的，基于类型的集成启用选项卡补全/ IntelliSense(命令行/ Visual Studio代码)

关于，当您可能也想使用机制B时:

如果问题中的.NET类型名称不完整，请参见问题。

如果一个函数输出多个类型，并且您想口头描述什么时候输出什么类型。

[补充] 机制B :使用基于注释的帮助的 .OUTPUTS部分:

接受自由格式描述；虽然引用实际的类型名称是有意义的，但不强制这样做。

虽然可以单独使用此机制，但是这样做可以放弃制表符完成和IntelliSense的优点。

因此，使用它来补充机制A(如果需要)，但请注意:

如果同时使用两种机制， Get-Help仅显示机制B的定义。

由于这两种机制是独立的，因此必须手动确保指定的自由格式信息完整且与机制A声明一致。

要用人的眼球检查输出类型信息，请使用(Get-Help <cmd>).returnvalues(注意:需要定义帮助，例如通过基于注释的帮助)，或从OUTPUTS 中读取输出的Get-Help -Full <cmd>部分。
这将显示自由格式的.OUTPUTS内容，或者显示不存在的[OutputType[]]声明的类型的完整类型名称。
要进行编程访问，请使用(Get-Command <cmd>).OutputType ，它返回其[System.Management.Automation.PSTypeName]属性包含实际类型的.Type实例。

下面的详细信息，从原始问题的答案开始。

机制A:在OutputType之上使用params()属性:

您只能将.NET类型指定为OutputType属性的参数，因此诸如反射(reflect)MIME类型的text/json或text/xml之类的字符串将不起作用。

如果要输出字符串，则已经选择了.NET类型下与MIME类型最接近的近似值:[OutputType([String])]
您可以在单个[OutputType()]属性中指定多种类型，也可以使用单独的属性。
如果要将将输出类型映射到特定的参数集(例如[OutputType([string], ParameterSetName='NameOnly')])，则必须使用单个属性。
但是，从Windows PowerShell v5.1 / PowerShell Core v6.0.1开始，选项卡补全/ IntelliSense既不使用此信息，也不在Get-Help -Full的输出中反射(reflect)此信息。

注意:对于要在调用时由OutputType属性识别的类型，

可以使用全类型名称(例如[System.Text.RegularExpressions.Match]而不是[Match])或PowerShell 类型加速器的名称，例如[regex]。

如有疑问，请在提示符下键入[<fullTypeName>]，以查看其是否被识别为类型。此外，您还可以选择，也可以选择将类型指定为字符串(例如'System.Text.Encoding')还是类型文字(例如(例如[System.Text.Encoding]))，这会影响行为-参见下文。

如果调用时不存在指定的类型，例如，由于尚未加载包含该类型的程序集，则行为取决于如何声明输出:

(如果最初指定为字符串):将被静默忽略。

(如果最初指定为类型文字):函数调用在调用

时中断


除此之外，

之一:仅在其帮助文本中描述cmdlet输出的字符串的特定类型，例如通过以下所述的机制B

或:创建名称反射(reflect)所需概念类型的自定义.NET类型，并在OutputType属性中进行指定-参见下文。

如前所述，尽管具有约束性，但OutputType属性在运行时只是提供信息-但是，用于制表符完成和IntelliSense(Visual Studio代码)。

使用自定义类型的示例:

# Define an empty custom type for the sole purpose for being able to use
# it with the OutputType attribute.
# Note: On first call, this may take a second or two, as the code is being
#       compiled.
Add-Type @'
  namespace org.example {
   public class text_json {}
  }
'@

function foo {
  # Reference the custom type defined above; full type name required.
  [OutputType([org.example.text_json])]
  param(
      [string]$name
  )
}

然后，您将获得:

> (Get-Command foo).OutputType.Name
org.example.text_json

请注意，[System.Management.Automation.PSTypeName]输出的.OutputType实例与直接检查类型时获得的[type]实例不同:
.Name的[System.Management.Automation.PSTypeName]属性与.FullName的[type]属性相对应，因此，如果识别出类型(在 session 中可用)，您将获得完整的类型名；否则，它是最初指定的名称。

机制B:在基于注释的帮助中使用.OUTPUTS部分:

概念性帮助主题 Get-Help about_Comment_Based_Help 描述了如何在基于注释的脚本和函数帮助内的.OUTPUTS部分可用于列出和描述输出类型。

注意:类似地，.INPUTS部分可用于描述受支持的输入类型，尽管考虑到指定输入类型是参数声明和文档的组成部分，但可以说不那么有趣。总的来说，.INPUTS的功能类似于.OUTPUTS，下面仅介绍不同之处。
.OUTPUTS部分使用帮助主题中的示例建议的以下格式，但是请注意，文本最终是自由格式的，并且不强制执行任何结构。

<type-name> <optional-description>

即使帮助主题(从PSv5开始)没有提及，似乎在有多种输出类型的情况下，每种类型都应在其自己的.OUTPUTS部分中进行描述。
也就是说，自由格式格式允许您在一个部分中描述多个输出类型的描述。

示例，利用自由格式格式以MIME类型描述输出:

<#
.SYNOPSIS
Does stuff.

.OUTPUTS
text/json. In case of x, returns a JSON [string].

.OUTPUTS
text/xml. In case of y, returns an XML [string].
#>
function foo {
  param()
}

请注意，当使用Get-Help整体查看帮助时，(汇总的).OUTPUTS(和.INPUTS)部分仅显示为Get-Help -Full。

以编程方式查询该信息实际上会产生以下内容的OUTPUTS部分:
逐字记录Get-Help -Full(源中的各个.OUTPUTS部分之间用空行连接，并在结尾加上多余的空行):

> (Get-Help foo).returnvalues

text/json. In case of x, returns a JSON [string].

text/xml. In case of y, returns an XML [string].

要按索引分别访问描述:

> (Get-Help foo).returnvalues.returnvalue[0].type.name
text/json. In case of x, returns a JSON [string].

但是，鉴于描述的自由形式性质以及它们旨在供人类使用，因此可能不需要这种精细的访问。

就是说，使用这种形式返回的文本没有多余的空格，因此(Get-Help foo).returnvalues.returnvalue.type.name可用于返回所有没有空行的文本。

这对于.INPUTS部分类似地起作用:(Get-Help foo).inputTypes.inputType.type.name