PowerShell Reflection: Define a MIME type or subtype as a script's output type -

it's possible in powershell define output type on scripts. consider myscript.ps1:

[outputtype([string])] param(     [string]$name ) 

the following returns string:

(get-command .\myscript.ps1).outputtype.name 

but specify script returns text/json or text/xml. way of doing that?

inventing types outputtype (e.g. [string.json]) not work.

there two independent mechanisms declaring output types:

^{if knows why is, let know. both mechanisms have been around since @ least psv2.}

• mechanism a: using outputtype attribute above param() declaration in script or function, in question:

  • only accepts full type names of .net types preloaded or manually loaded current session (and quietly ignores unrecognized ones), , doesn't allow associating description type.
  • accessed via (get-command <command-name>).outputtype

• mechanism b: using .outputs section of comment-based help.

  • accepts free-form descriptions; while referencing actual type names makes sense, doing not enforced.
  • accessed via (get-help <command-name>).returnvalues or, in context of showing whole, get-help -full <command-name>).

important: both ways of declaring output types informative only , aren't enforced powershell @ runtime.

details below, starting answer original question.

---

mechanism a: using outputtype attribute above params():

you may specify .net types arguments outputtype attribute, strings such text/json or text/xml reflect mime types won't work.

if want string output, you've chosen closest approximation of mime types in terms of .net types: [outputtype([string])]

note: for type recognized outputtype attribute (and therefore subsequently reported (get-command <somecommand>).outputtype),

• the full type name must specified (e.g., [system.text.regularexpressions.match] rather [match]), though powershell type shortcuts such [regex] do work.

  • when in doubt, type [<fulltypename>] @ prompt , see if recognized type.

• the assembly containing type must have been loaded session first (unless type loaded default).

---

beyond that,

• either: describe specific types of strings cmdlet outputs in text, such via mechanism b described below,

• or: create custom .net types names reflect desired conceptual type, , specify them in outputtype attribute - see below.

as stated, despite constrained nature, the outputtype attribute purely informative - specifies not enforced @ runtime.

---

example of using custom type:

# define empty custom type sole purpose being able use # outputtype attribute. # note: on first call, may take second or two, code being #       compiled. add-type @'   namespace org.example {    public class text_json {}   } '@  function foo {   # reference custom type defined above; full type name required.   [outputtype([org.example.text_json])]   param(       [string]$name   ) } 

you get:

> (get-command foo).outputtype.name org.example.text_json 

note [system.management.automation.pstypename] instances .outputtype outputs not same [type] instances when inspect type directly:

the .name property of [system.management.automation.pstypename] corresponds .fullname property of [type], full type name.

---

mechanism b: using .outputs section in comment-based help:

conceptual topic get-help about_comment_based_help describes how section .outputs inside comment-based scripts , functions can used list and describe output types.

^{note: similarly, .inputs section can used describe supported input types, though arguably less interesting, given specifying input types integral part of parameter declaration , documentation. , large, .inputs functions analogously .outputs, differences mentioned below.}

an .outputs section uses following format suggested examples in topic, note text free-form, , no structure enforced.

<type-name> <optional-description> 

even though topic (as of psv5) doesn't mention it, seems in event of multiple output types, each should described in own .outputs section.
said, free-form format allows describe multiple output-type descriptions in single section.

example, taking advantage of free-form format describe output in terms of mime types:

<# .synopsis stuff.  .outputs text/json. in case of x, returns json [string].  .outputs text/xml. in case of y, returns xml [string]. #> function foo {   param() } 

note when using get-help view whole, (aggregated) .outputs (and .inputs) sections shown get-help -full.

querying information programmatically yields outputs section get-help -full verbatim (with individual .outputs sections in source concatenated empty line in between, , trailing empty lines):

> (get-help foo).returnvalues  text/json. in case of x, returns json [string].  text/xml. in case of y, returns xml [string]. 

to access descriptions individually, index:

> (get-help foo).returnvalues.returnvalue[0].type.name text/json. in case of x, returns json [string]. 

however, given free-form nature of descriptions , they're intended human consumption, granular access may not needed.

that said, using form returns text without whitespace, (get-help foo).returnvalues.returnvalue.type.name can used return text without empty lines.

this works analogously .inputs sections:
(get-help foo).inputtypes.inputtype.type.name