{"id":10321,"date":"2006-05-09T23:15:00","date_gmt":"2006-05-09T23:15:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/powershell\/2006\/05\/09\/programmatic-way-to-get-valid-string-values-for-a-parameter\/"},"modified":"2019-02-18T13:21:43","modified_gmt":"2019-02-18T20:21:43","slug":"programmatic-way-to-get-valid-string-values-for-a-parameter","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/programmatic-way-to-get-valid-string-values-for-a-parameter\/","title":{"rendered":"Programmatic way to get valid string values for a parameter"},"content":{"rendered":"

<WIZARD WARNING>  ISVs and Tool vendors may find this important, Advanced users may find this interesting, Casual users may want to skip this.<\/em><\/font><\/p>\n

Someone asked me if there was a programmatic way to tell what the legal values for a string parameter to a cmdlet was.  The example was OUT-FILE -ENCODING xxx<\/p>\n

Out current help doesn’t tell you this information (and it wouldn’t be a great programmatic experience even if it did) and neither does Get-Command:<\/p>\n

PS> get-command out-file |fl Definition<\/strong>
Definition : Out-File [-FilePath] <String> [[-Encoding] <String>]<\/font><\/strong> [-Append]
              [-Force] [-NoClobber] [-Width <Int32>] [-InputObject <PSObjec
             t>] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-Er
             rorVariable <String>] [-OutVariable <String>] [-OutBuffer <Int
             32>] [-WhatIf] [-Confirm]<\/font><\/p>\n

It tells me that it takes a string but not what the values are.  When you try to assign an incorrect value, you’ll be told what the correct values are:<\/p>\n

PS> gps |out-file foo.txt -Encoding UTF-8
<\/strong>Out-File : Cannot validate argument “UTF-8” because it does not belong to t
he set “unicode, utf7, utf8, utf32, ascii, bigendianunicode, default, oem”.
At line:1 char:32
+ gps |out-file foo.txt -Encoding  <<<< UTF-8<\/font><\/p>\n

That is fine for the interactive case but what about the programmatic case – can you find this info out?  The answer is: maybe.  <\/p>\n

We designed PowerShell (formerly known as Monad) for this scenario. When a cmdlet developer declares their parameters, we provide them a set of VALIDATION attributes that we encourage them to use.  At first glance, a developer might say – the heck with those, it would be just as simple to code this myself.  BUT WAIT — DON’T DO THAT.  <\/p>\n

      PSTIP: Use the Attributes Luke<\/font><\/em><\/p>\n

There are 2 primary benefits of using the attributes instead of coding them yourself <\/p>\n

    \n
  1. PowerShell engine does the work and will generate the error messages.  That might sound trivial but I can guarantee you that if 100 cmdlet developers write their own code, you’ll get at least 200 error messages for the exact same condition. Using the Attributes ensures a consistent user experience.  \n

    Don’t care about your user’s experience?  Then there is an economic advantage to using the attributes.  Use them and Microsoft will pick up the bill for translating them into all the languages your customers want.  (Consistency through economics – do you see the pattern here?)<\/p>\n

  2. The attributes provide a programmable way to discover the capabilities of the cmdlet.  This can be used in all sorts of wonderful ways – e.g. autogenerating GUI front end to the cmdlets.  If we know what the parameters are and we also know what the valid values are, we can turn that into a combo-box instead of having the user TYPE the values.<\/li>\n<\/ol>\n

    If Cmdlet developers don’t do use the Attributes, you get none of this.  <\/p>\n

    Let’s explore the CmdletInfo datastructure. This is what is returned when you do a Get-Command (gcm) on a cmdlet. <\/p>\n

    PS> gcm out-file |gm param*
    <\/strong>   TypeName: System.Management.Automation.CmdletInfo<\/font><\/p>\n

    Name          MemberType Definition
    —-          ———- ———-
    ParameterSets Property   System.Collections.ObjectModel.ReadOnlyCollecti…<\/font><\/p>\n

    ParameterSets are the Sets of valid parameters (are we good at naming or what?).  For instance, Get-Process (gps) can be provided an -ID parameter or a -NAME parameter.  These are 2 ParameterSets for that cmdlet.<\/p>\n

    P<\/font>S> gps -Name powershell<\/strong><\/font><\/font><\/font><\/p>\n

    Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
    ——-  ——    —–      —– —–   ——     — ———–
       1112      15   112816      19812   250   206.61    936 powershell<\/font><\/p>\n

    PS> gps -ID 936<\/strong><\/font><\/p>\n

    Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
    ——-  ——    —–      —– —–   ——     — ———–
       1119      15   112920      19984   250   206.66    936 powershell
    <\/font><\/p>\n

    Out-File has only one parameterSet<\/p>\n

    PS> (gcm out-file).Parametersets |fl name
    <\/strong>Name : __AllParameterSets<\/font><\/p>\n

    ParameterSets have a set of Parameters.  One of those is the Encoding parameter:<\/p>\n

    PS> $p=(gcm out-file).Parametersets[0].parameters |?{$_.name -eq “Encoding”}<\/strong><\/font><\/p>\n

    PS> $p
    Name                            : Encoding
    ParameterType                   : System.String
    IsMandatory                     : False
    IsDynamic                       : False
    Position                        : 1
    ValueFromPipeline               : False
    ValueFromPipelineByPropertyName : False
    ValueFromRemainingArguments     : False
    HelpMessage                     :
    Aliases                         : {}
    Attributes<\/font><\/strong>                      : {System.Management.Automation.ValidateSet
                                      Attribute, __AllParameterSets, System.Man
                                      agement.Automation.ValidateNotNullOrEmpty
                                      Attribute}<\/font><\/p>\n

    Notice that this also tells you if the parameter has an alias, is positional, etc.  That parameter has a set of Attributes:<\/p>\n

    PS> $p.Attributes |ft Typeid<\/strong><\/font><\/p>\n

    TypeId
    ——
    System.Management.Automation.ValidateSetAttribute
    <\/font><\/strong>System.Management.Automation.ParameterAttribute
    System.Management.Automation.ValidateNotNullOrEmptyAttribute<\/font><\/p>\n

    The ValidateSetAttribute has the list of valid strings for this Parameter:<\/p>\n

    PS> ($p.Attributes|? {$_.Typeid -match “ValidateSetAttribute” }).ValidValues<\/strong>
    unicode
    utf7
    utf8
    utf32
    ascii
    bigendianunicode
    default
    oem<\/font><\/p>\n

    And there you have it.  A little chewy yes but I don’t expect end-users to ever care about this but system programmers and tool vendors will.<\/p>\n

    Enjoy!
    Jeffrey Snover [MSFT]
    Windows PowerShell Architect<\/p>\n

    PSMDTAG:FAQ: Is there a programmatic way to get valid string values for a parameter?
    PSMDTAG:PHILOSOPHY: Use Attributes instead of code for validating parameters.
    PSMDTAG:INTERNAL: walk through of the Parameter data for cmdlets<\/p>\n","protected":false},"excerpt":{"rendered":"

    <WIZARD WARNING>  ISVs and Tool vendors may find this important, Advanced users may find this interesting, Casual users may want to skip this. Someone asked me if there was a programmatic way to tell what the legal values for a string parameter to a cmdlet was.  The example was OUT-FILE -ENCODING xxx Out current help doesn’t […]<\/p>\n","protected":false},"author":600,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[10,19,11],"class_list":["post-10321","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-faq","tag-internal","tag-philosophy"],"acf":[],"blog_post_summary":"

    <WIZARD WARNING>  ISVs and Tool vendors may find this important, Advanced users may find this interesting, Casual users may want to skip this. Someone asked me if there was a programmatic way to tell what the legal values for a string parameter to a cmdlet was.  The example was OUT-FILE -ENCODING xxx Out current help doesn’t […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/10321","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/600"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=10321"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/10321\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=10321"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=10321"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=10321"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}