{"id":15040,"date":"2018-06-05T06:00:01","date_gmt":"2018-06-05T13:00:01","guid":{"rendered":"https:\/\/www.sapien.com\/blog\/?p=15040"},"modified":"2018-06-18T15:25:09","modified_gmt":"2018-06-18T22:25:09","slug":"powershell-helpwriter-2018-create-a-single-function-help-file","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2018\/06\/05\/powershell-helpwriter-2018-create-a-single-function-help-file\/","title":{"rendered":"PowerShell HelpWriter 2018: Create a Single Function Help File"},"content":{"rendered":"

PowerShell HelpWriter<\/a>™ is an essential application to have in your toolbox, especially when working with existing scripts, functions, or modules. Eventually, your scripts will be shared or given to someone else to maintain, and no one wants to inherit a script that is hard to follow or difficult to understand.<\/p>\n

Including Help documentation with your scripts is a best practice that takes very little time to do, and demonstrates your quality of work to your IT peers. In this blog post we will show you how to create a PowerShell XML Help file and add it to a script.<\/p>\n

\"\"<\/a><\/p>\n

Ease Of Use<\/h3>\n

PowerShell HelpWriter has the ability to build an XML Powershell Help file that can be included in a script file.<\/p>\n

You can start using the tool as soon as you open the application\u2014it’s as easy as filling in the blanks.<\/p>\n

Use the application Menu<\/em>, or both the Navigation<\/em>\u00a0panel and the Designer<\/em>\u00a0panel to build the Help file.<\/p>\n

\"\"<\/a><\/p>\n

When the Help file is complete, the XML file can be validated before being implemented in the script file.<\/p>\n

\"\"<\/a><\/p>\n

Create a Help File<\/h3>\n

We are going to create a new Help file for an existing function called\u00a0Get-MySQLServices<\/strong>.<\/p>\n

On the File<\/em> menu, click on New<\/em>\u00a0then select New Help File<\/em>. This will open an empty New-Cmdlet<\/strong>\u00a0Help file.<\/p>\n

\"\"<\/a><\/p>\n

We will change the name from New-Cmdlet<\/strong>\u00a0to Get-MySQLServices<\/strong>\u00a0and start to fill in the information in the Synopsis<\/em>\u00a0and Detailed Description<\/em>\u00a0sections.<\/p>\n

The Synopsis<\/em>\u00a0is a short description about the function and the Detailed Description<\/em>\u00a0explains more about the function.<\/p>\n

\"\"<\/a><\/p>\n

Adding Syntax and Parameters<\/h4>\n

In the Syntax<\/em>\u00a0and Parameters<\/em>\u00a0sections we will configure how the function will work and what parameters are going to be used by the function.<\/p>\n

\"\"<\/a><\/p>\n

First, we need to add all of the parameters used by this function in the Parameters<\/em>\u00a0section. To start adding parameters click on the Add New Parameter<\/em>\u00a0button.<\/p>\n

\"\"<\/a><\/p>\n

Parameter1<\/em>\u00a0will be added first, then we will rename it to\u00a0Status<\/em>.<\/p>\n

\"\"<\/a>\u00a0\"\"<\/a><\/p>\n

Next we will update the properties for each parameter by clicking on the “tool” icon next to the parameter name.<\/p>\n

\"\"<\/a><\/p>\n

The following parameter properties can be modified in the Parameters<\/em>\u00a0tool editor:<\/p>\n