This is the third blog in a multi-part series about designing a Windows PowerShell scripts that will be packaged in an executable file.<\/p>\n
—– When you wrap a Windows PowerShell script in an executable file, even if the script has comment-based or XML help, Get-Help cannot find the help file. However, you can use a few techniques to restore some help functionality.<\/p>\n As we learned in Part 1 of this series<\/a>, all parameters in a script that is wrapped in an executable file must take string types or types that Windows PowerShell converts from strings. So, we can use selected strings to recognize that the user is looking for help, instead of trying to run the command.<\/p>\n For example, I have a Get-InputTypes.ps1 script that finds parameters that take pipeline input. The script has a mandatory CmdletName parameter that specifies the name of the command to analyze.<\/p>\n When I run the .exe normally, it returns input type information.<\/p>\n The CmdletName parameter is positional, so I don’t need to type the parameter name.<\/p>\n But, when I run it with a value of ‘Help’ or ‘\/?’, it displays\u00a0help.<\/p>\n Here’s how I did it.<\/p>\n First, I added a $HelpString variable that contains help for the cmdlet. (For details, see Create a Help String<\/a>‘. Next, I changed the\u00a0first parameter in the script (Position 0)\u00a0to recognize values of ‘\/?’ and ‘Help’. Windows PowerShell has special processing for the ‘-?’ string, so I avoid that one.<\/p>\n This script has a CmdletName parameter that is mandatory and, by default, position 0.<\/p>\n To add help functionality, removed the ValidateScript attribute.<\/p>\n Then, I added a condition that looks for CmdletName values of ‘Help’ and ‘\/?’. If found, the script displays a $HelpString string, instead of its regular processing.<\/p>\n If you want to be a bit more sophisticated, rather than using the CmdletName parameter for an unintended use, you can add a Help parameter.<\/p>\n Here’s the original parameter set of the script:<\/p>\n I added a Help parameter that takes a string value. Then, because the CmdletName and Help parameters are exclusive, I’ve created separate ‘DefaultSet’ and ‘HelpSet’ parameter sets.<\/p>\n In a script or function, the parameters are positional by default. But when you add parameter sets, all parameters become named. For most cases, named parameters are a best practice. However, in this case, I want the user to be able to type: ‘Get-InputTypes.exe \/?’ so I make the Help parameter mandatory and position 0 in the HelpSet parameter set.<\/p>\n Here’s the result.<\/p>\n I also added code to take any value of the Help parameter.<\/p>\n Now, when I wrap the script in an exe and run it:<\/p>\n Many traditional command-line tools display help as the default. That is, if you run the command without parameters, it displays help. This is not true for Windows PowerShell. In fact, many PowerShell cmdlets, including Get-Command, Get-Process, and Get-Module, have very useful default displays. But, if you want to make your .exe file display help by default, it’s pretty easy to do that.<\/p>\n If you made your Position 0 parameter accepts special values, like ‘\/?’ and ‘Help’, you can make that parameter optional. Then, add a case for a $Null or empty string value (if !$CmdletName…).<\/p>\n If you created a Help parameter in its own parameter set, to make the Help parameter accept an empty value:<\/p>\n — Make the Help parameter optional For example:<\/p>\n Now, when I wrap the script in an exe and run it with no parameters, I get the help.<\/p>\n And, I can still use the Help parameter explicitly with any value.<\/p>\n <\/a><\/p>\n There are many ways to create the $HelpString value for a Windows PowerShell script in an executable file.<\/p>\n To make it look like the Get-Help display, I write comment-based or XML help for script, run ‘Get-Help <ScriptName>.ps1 -Full,’ copy the content that Get-Help returns, and paste it in a here-string in my script. To make it easier to read, I add a few blank lines at the top and bottom of the string.<\/p>\n It’s much easier to use Get-Help to display help, but when it’s not available, it’s great to have easy substitutes.<\/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><\/p>\n","protected":false},"excerpt":{"rendered":" This is the third blog in a multi-part series about designing a Windows PowerShell scripts 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":[932,1034,2,283,703,410,25],"tags":[1042,934,28,1016,37,48,997],"class_list":["post-10370","post","type-post","status-publish","format-standard","hentry","category-beginners","category-best-practices","category-general","category-howto","category-powershell-studio","category-primalscript-software-news","category-windows-powershell","tag-executable-files","tag-juneb","tag-powershell","tag-powershell-studio","tag-primalscript","tag-training","tag-windows-powershell"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/10370","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=10370"}],"version-history":[{"count":53,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/10370\/revisions"}],"predecessor-version":[{"id":10626,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/10370\/revisions\/10626"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=10370"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=10370"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=10370"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\nThe Get-Help<\/a> cmdlet displays help topics about concepts and modules (About topics) and about commands (cmdlets, scripts, functions, workflows, and CIM commands). It does not display help topics for applications in executable files.<\/p>\nRecognize Help Strings<\/h1>\n
PS C:\\> .\\Get-InputTypes.exe -CmdletName Get-Command\r\n\r\nTypeNames ParameterName ValueFromPipelineByPropertyName\r\n--------- ------------- -------------------------------\r\nSystem.String[] Name True<\/pre>\n
.\\Get-InputTypes.exe Invoke-Command\r\n\r\nTypeNames ParameterName ValueFromPipelineByPropertyName\r\n--------- ------------- ---------------------------\r\nSystem.Management.Automation.PSObject InputObject True<\/pre>\n
PS C:\\> .\\Get-InputTypes.exe \/?\r\nNAME\r\nGet-InputTypes.exe\r\nSYNOPSIS\r\nGets input types for cmdlet help topics.\r\nSYNTAX\r\nGet-InputTypes.ps1 [-CmdletName] <String> [-Full <String>]\r\n\r\nDESCRIPTION\r\nThis app gets the input types for a cmdlet help topic, that is, it gets the .NET types that\r\nyou can pipe to the cmdlet. By default, it gets only types that can be piped\r\n...<\/pre>\n
[CmdletBinding()]\r\nParam\r\n(\r\n[Parameter(Mandatory = $true)]\r\n[ValidateScript({Get-Command $_})]\r\n[String]$CmdletName,\r\n\r\n[Parameter()]\r\n[ValidateSet('True', 'False')]\r\n[String]$Full\r\n)<\/pre>\n[CmdletBinding()]\r\nParam\r\n(\r\n[Parameter(Mandatory = $true)]\r\n[String]$CmdletName,\r\n\r\n[Parameter()]\r\n[ValidateSet('True', 'False')]\r\n[String]$Full\r\n)<\/pre>\nif ($CmdletName -eq 'Help' -or $CmdletName -eq '\/?')\r\n{\r\n $HelpString\r\n}\r\nelseif ($full -eq 'True')\r\n...<\/pre>\nAdd a Help Parameter<\/h1>\n
[CmdletBinding()]\r\nParam\r\n(\r\n[Parameter(Mandatory = $true)]\r\n[ValidateScript({Get-Command $_})]\r\n[String]$CmdletName,\r\n\r\n[Parameter()]\r\n[ValidateSet('True', 'False')]\r\n[String]$Full\r\n)<\/pre>\n[CmdletBinding(DefaultParameterSetName = 'DefaultSet')]\r\nparam\r\n(\r\n[Parameter(ParameterSetName = 'DefaultSet', Mandatory = $true. Position=0)]\r\n[ValidateScript({Get-Command $_})]\r\n[String]$CmdletName,\r\n\r\n[Parameter(ParameterSetName = 'DefaultSet', Position=1)]\r\n[ValidateSet('True', 'False')]\r\n[String]$Full,\r\n\r\n[Parameter(ParameterSetName = 'HelpSet', Mandatory = $true, Position = 0)]\r\n[String]$Help\r\n)<\/pre>\nif ($Help)\r\n{ \r\n $HelpString\r\n}\r\nelseif ($Full -eq 'True')\r\n{\r\n...<\/pre>\nPS C:\\>.\\Get-InputTypes.exe -CmdletName Set-ExecutionPolicy\r\n\r\nTypeNames ParameterName ValueFromPipelineByPropertyName\r\n--------- ------------- --------------------------\r\nMicrosoft.PowerShell.ExecutionPolicy ExecutionPolicy True\r\n\r\nPS C:\\> .\\Get-InputTypes.exe -Help True\r\nNAME\r\nGet-InputTypes.exe\r\nSYNOPSIS\r\nGets input types for cmdlet help\r\nSYNTAX\r\nGet-InputTypes.exe [-CmdletName] <String> [-Full <String>]\r\nGet-InputTypes.exe [-Help] <String>\r\n...\r\n\r\nPS C:\\> .\\Get-InputTypes.exe \/?\r\nNAME\r\nGet-InputTypes.exe\r\nSYNOPSIS\r\nGets input types for cmdlet help\r\nSYNTAX\r\nGet-InputTypes.exe [-CmdletName] <String> [-Full <:String>]\r\nGet-InputTypes.exe [-Help] <String>\r\n...<\/pre>\n
Make Help the Default<\/h1>\n
[CmdletBinding()]\r\nParam\r\n(\r\n[Parameter()]\r\n[String]$CmdletName,\r\n\r\n[Parameter()]\r\n[ValidateSet('True', 'False')]\r\n[String]$Full\r\n)\r\n\r\nif (!$CmdletName -or $CmdletName -eq 'Help' -or $CmdletName -eq '\/?')\r\n{\r\n $HelpString\r\n}\r\nelseif ($full -eq 'True')\r\n...<\/pre>\n
\n— Make the HelpSet parameter set the default
\n— Check for the HelpSet parameter set in the script<\/p>\n[CmdletBinding(DefaultParameterSetName = 'HelpSet')]\r\nparam\r\n(\r\n[Parameter(ParameterSetName = 'DefaultSet', Mandatory = $true)]\r\n[ValidateScript({Get-Command $_})]\r\n[String]$CmdletName,\r\n\r\n[Parameter(ParameterSetName = 'DefaultSet')]\r\n[ValidateSet('True', 'False')]\r\n[String]$Full,\r\n\r\n[Parameter(ParameterSetName = 'HelpSet', Mandatory = $false, Position = 0)]\r\n[String]$Help\r\n)\r\n\r\nif ($PSCmdlet.ParameterSetName -eq 'HelpSet')\r\n{ \r\n $HelpString\r\n}\r\nelseif ($Full -eq 'True')\r\n{\r\n...<\/pre>\nPS C:\\> .\\Get-InputTypes.exe\r\nNAME\r\nGet-InputTypes.exe\r\nSYNOPSIS\r\nGets input types for cmdlet help topics.\r\nSYNTAX\r\nGet-InputTypes.ps1 [[-Help] <String>]\r\nGet-InputTypes.ps1 [-CmdletName] <String> [-Full <String>]\r\n\r\nDESCRIPTION\r\nThis app gets the input types for a cmdlet help topic, that is, it gets the .NET types that\r\nyou can pipe to the cmdlet. By default, it gets only types that can be piped\r\n...<\/pre>\n
PS C:\\> .\\Get-InputTypes.exe -Help \/?\r\nNAME\r\nGet-InputTypes.exe\r\nSYNOPSIS\r\nGets input types for cmdlet help topics.\r\nSYNTAX\r\nGet-InputTypes.ps1 [[-Help] <String>]\r\nGet-InputTypes.ps1 [-CmdletName] <String> [-Full <String>]\r\n\r\nDESCRIPTION\r\nThis app gets the input types for a cmdlet help topic, that is, it gets the .NET types that\r\nyou can pipe to the cmdlet. By default, it gets only types that can be piped\r\n...<\/pre>\n
Create a Help String<\/h1>\n
$helpString = @\"\r\n\r\nNAME\r\nC:\\ps-test\\Get-InputTypes.ps1\r\n\r\nSYNOPSIS\r\nGets input types for cmdlet help\r\n\r\nSYNTAX\r\nGet-InputTypes.exe [-CmdletName] <String> [-Full <:String>]\r\nGet-InputTypes.exe [-Help] <String>\r\n\r\nDESCRIPTION\r\nThis script gets the input types for a cmdlet\r\nhelp topic, that is, it gets the .NET types that\r\nyou can pipe to the cmdlet.\r\n\r\n\u2026\r\n\"@<\/pre>\n