This is the first blog in a multi-part series about designing a Windows PowerShell script that will be packaged in an executable file.<\/p>\n
—–<\/p>\n
PowerShell Studio and PrimalScript have great support for packing scripts in executable files. Windows PowerShell is an interpreted language, so you cannot compile it, but you can wrap scripts (.psm1) and simple modules (.psm1) files in an executable file<\/p>\n
I typically build executable files for GUI apps don’t have parameters, but you can build executable files for any script, including scripts that take parameters.<\/p>\n
However, passing parameters to a script inside a native .exe is not simple, because executable files don’t have built-in features to support objects other than strings or to support PowerShell’s parameter name and parameter value syntax.<\/p>\n
In the past, all parameters had to be positional, users had to enter parameter values without names, and enter them in the specified order, or your script would have to parse the input string and associate the values with the correct parameters.<\/p>\n
But, a new feature of PowerShell Studio<\/a> (beginning in 4.2.96) and PrimalScript<\/a> (beginning in 7.1.72), makes this much easier. You are still limited to strings values (and types that can parse string values). But, users can now enter parameter names and values, just as they do for a script. And new code in the executable file that PowerShell Studio and PrimalScript\u00a0builds\u00a0parses the input string and associates the parameter values with the correct parameters, so you don’t have to.<\/p>\n An executable file can pass a string or an array of string values to the PowerShell script inside. It can’t handle any other value type. So, the first rule of writing scripts for exes is to use only parameters that take string values.<\/p>\n Let’s start with a very simple script, New-WordTree.ps1, that repeats a specified word for an increasing number of specified times (default = 1). (Credit to PowerShell MVP Doug Finke<\/a> for the neat idea<\/a>.) The script has a string parameter, Word, and an integer parameter, Number.<\/p>\n When you run this script as a .ps1 file, you can use parameter names and values.<\/p>\n When you wrap this script in an executable file and use the same command line, it used to fail, because all input strings were interpreted as parameter values. In this case, ‘-Parameter’ was interpreted as the value of the Word parameter and ‘PowerShell’ was interpreted as the value of the Number parameter. The script failed when Windows PowerShell couldn’t convert ‘PowerShell’ to a integer.<\/p>\n But, the new input string parsing feature of PowerShell Studio and PrimalScript parses the input string for you so commands with parameter names and parameter values work correctly. You do not need to give the user special instructions or do any parsing in your script.<\/p>\n I can even enter the parameters in an unspecified order, just as I can do in a script.<\/p>\n If the parameters are positional, which they are by default in a script or function with only one parameter set, you can omit parameter names, just as you can in a script.<\/p>\n When writing a script that will be wrapped in an exe, use parameters that take string values. When you convert existing scripts for use in an exe, remember to change parameter input types to strings.<\/p>\n You don’t need to rely solely on string parameters . Notice that the Number parameter in New-WordTree takes an Integer value, but you can use it in an executable file, because Windows PowerShell automatically converts the values from String to Integer for you. This conversion works for System.Double, too. For more complex objects, like process objects (System.Diagnostics.Process), the conversion associates only the name of the process with a string parameter. Its utility depends on what you intend to do with the object inside your script.<\/p>\n This version of the New-WordTree.ps1 script has a Switch parameter that adds a space between the repeated words.<\/p>\n I can run this as a script.<\/p>\n But, if I run it as an executable file, the AddSpace switch parameter is ignored.<\/p>\n If I add a value for the AddSpace parameter, such as $True, the command fails, because Windows PowerShell cannot convert the string to a type that the Switch parameter accepts.<\/p>\n Instead, you need to change the switch parameter to a type that takes a string value. In this example, I change the AddSpace switch parameter to a string parameter that takes values of True and False. I also change the IF statement to interpret the new values.<\/p>\n When I package this script in an executable, you can now run it by submitting a string value.<\/p>\n If any script in an executable file has a parameter that takes multiple values, like a collection of strings or integers, the end-user must submit the value collection in a single comma-separated string enclosed in quotation marks. Then, in your script, you need to split the quoted string.<\/p>\n Because the quoted string is submitted to the executable, not to Windows PowerShell, the standard PowerShell rules for quoted strings<\/a> do not<\/u><\/b> apply.<\/p>\n For example, in this version of New-WordTree.exe, the Word parameter takes multiple words.<\/p>\n To call the script in an exe, the user must enclose the value collection in single or double quotes. (This is unusual, so be sure to show the user how to do this in your help topic<\/a>.)<\/p>\n To handle these quoted strings in the script, you have to split the parameter value string on each comma. Also, to get rid of spaces, I call the Trim() method of strings. It’s a good habit to develop.<\/p>\n And, as you would in any script, you need to change your code to to handle multiple values, such as using a ForEach statement.<\/p>\n Here’s the result.<\/p>\n This once-difficult task of parsing input in an exe-wrapped script is now much easier. But, if you need to parse the input string manually, you can do that, too. In the a href=”https:\/\/wp.me\/p3tXTf-2Hg” target=”_blank”>next post, we’ll display help for an executable file.<\/p>\n June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at <\/i>juneb@sapien.com<\/em><\/a> or follow her on Twitter at <\/em>@juneb_get_help<\/em><\/a>.<\/em>Parsing Parameters for a Script in an Executable File<\/a><\/p>\n","protected":false},"excerpt":{"rendered":" This is the first blog in a multi-part series about designing a Windows PowerShell script that will be packaged in an executable file. Passing Parameters to a Script in an Executable File explains how to use the special parsing features of PowerShell Studio and PrimalScript to make passing parameters easy for PowerShell users and authors. […]<\/p>\n","protected":false},"author":31,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[946,703,410],"tags":[1042,28,94,988,1016,37],"class_list":["post-10270","post","type-post","status-publish","format-standard","hentry","category-guiprogramming","category-powershell-studio","category-primalscript-software-news","tag-executable-files","tag-powershell","tag-powershell-development","tag-powershell-gui","tag-powershell-studio","tag-primalscript"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/10270","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/31"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=10270"}],"version-history":[{"count":63,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/10270\/revisions"}],"predecessor-version":[{"id":10621,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/10270\/revisions\/10621"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=10270"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=10270"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=10270"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}New input parsing for scripts in .exe files<\/h1>\n
Param\r\n(\r\n [Parameter(Mandatory = $true)]\r\n [String]$Word,\r\n [int]$Number = 1\r\n)\r\n1..$Number | foreach { \"$Word\" * $_}<\/pre>\nPS C:\\> .\\New-WordTree.ps1 -Word PowerShell -Number 3\r\nPowerShell\r\nPowerShellPowerShell\r\nPowerShellPowerShellPowerShell<\/pre>\n
PS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 \r\nLine 1: A positional parameter cannot be found that accepts argument 'PowerShell'.PS C:\\><\/pre>\n
PS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3\r\nPowerShell \r\nPowerShellPowerShell \r\nPowerShellPowerShellPowerShell<\/pre>\n
PS C:\\> .\\New-WordTree.exe\u00a0 -Number 3 -Word PowerShell\r\nPowerShell\r\nPowerShellPowerShell\r\nPowerShellPowerShellPowerShell<\/pre>\n
PS C:\\> .\\New-WordTree.exe PowerShell 3\r\nPowerShell\r\nPowerShellPowerShell\r\nPowerShellPowerShellPowerShell<\/pre>\n
Change Parameter Values to Strings<\/h1>\n
Param\r\n(\r\n [Parameter(Mandatory = $true)]\r\n [String]$Word,\r\n\r\n [int]$Number = 1,\r\n\r\n [Switch]$AddSpace\r\n)\r\n\r\n$space = ''\r\nif ($AddSpace){ $space = ' ' }\r\n\r\n1..$Number | foreach { \"$Word$space\" * $_}<\/pre>\nPS C:\\> .\"C:\\ps-test\\New-WordTree.ps1\" -Word PowerShell -Number 3\r\nPowerShell\r\nPowerShellPowerShell\r\nPowerShellPowerShellPowerShell\r\n\r\nPS C:\\> .\"C:\\ps-test\\New-WordTree.ps1\" -Word PowerShell -Number 3 -AddSpace\r\nPowerShell\r\nPowerShell PowerShell\r\nPowerShell PowerShell PowerShell<\/pre>\n
PS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 -AddSpace\r\nPowerShell \r\nPowerShellPowerShell \r\nPowerShellPowerShellPowerShell<\/pre>\n
PS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 -AddSpace $True\r\nLine 1: A positional parameter cannot be found that accepts argument 'True'.PS C:\\>\r\n\r\nPS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 -AddSpace \"$True\"\r\nLine 1: A positional parameter cannot be found that accepts argument 'True'.PS C:\\>\r\n\r\nPS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 -AddSpace:$True\r\nLine 1: A parameter cannot be found that matches parameter name 'Addspace:True'.PS C:\\><\/pre>\n
Param\r\n(\r\n [Parameter(Mandatory = $true)]\r\n [String]$Word,\r\n\r\n [int]$Number = 1,\r\n\r\n [ValidateSet('True', 'False')]\r\n [string]$AddSpace #Change Switch to String\r\n)\r\n$space = ''\r\nif ($AddSpace -eq 'True'){ $space = ' ' }\r\n\r\n1..$Number | foreach { \"$Word$space\" * $_}<\/pre>\nPS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 -AddSpace True\r\nPowerShell\r\nPowerShell PowerShell\r\nPowerShell PowerShell PowerShell\r\n\r\nPS C:\\> .\\New-WordTree.exe -Word PowerShell -Number 3 -AddSpace $True\r\nPowerShell\r\nPowerShell PowerShell\r\nPowerShell PowerShell PowerShell<\/pre>\n
Handling Multiple Values for a Parameter<\/h1>\n
[Parameter(Mandatory = $true)]\r\n[String[]]$Word<\/pre>\n
PS C:\\> .\\New-WordTree.exe -Word \"PowerShell, NanoServer, DSC\" -Number 3 -AddSpace True\r\nPowerShell\r\nPowerShell PowerShell\r\nPowerShell PowerShell PowerShell\r\nNanoServer\r\nNanoServer NanoServer\r\nNanoServer NanoServer NanoServer\r\nDSC\r\nDSC DSC\r\nDSC DSC DSC\r\n<\/pre>\n
$words = ($Word -split ',').Trim()<\/pre>\n
foreach ($item in $words)\r\n{\r\n \r\n}<\/pre>\nParam\r\n(\r\n [Parameter(Mandatory = $true)]\r\n [String[]]$Word,\r\n\r\n [int]$Number = 1,\r\n\r\n [ValidateSet('True', 'False')]\r\n [string]$AddSpace\r\n)\r\n\r\n# Split the parameter value array into strings\r\n$words = ($Word -split ',').Trim()\r\n\r\nforeach ($item in $words)\r\n{\r\n $space = ''\r\n if ($AddSpace -eq 'True')\r\n { $space = ' ' }\r\n\r\n 1..$Number | foreach { \"$item$space\" * $_ }\r\n}<\/pre>\n