PowerShell Basics–Using the Help Subsystem

Before we start running commands one of the fist things we have to do is to understand the rich help subsystem in PowerShell or as we say to many users in our IT life, RTFM. One of the first things to cover is that Help Subsystem in PowerShell v3 was improved so as to be able to update its contents.

Updating PowerShell v3 Help

We can update the help system from Microsoft it self or from a share or drive in the case the machine does not have access to the internet. Windows 8 and Windows 2012 come with no PowerShell help files as does a install of PowerShell v3 on a Windows 7, 2008 or 2008 R2 system so the first step we have to take is to run the Get-Help cmdlet to update our help files if our system has internet connection. Things to consider when running the Get-Help cmdlet for updating the help files from the internet:

  • To update the help files the account you run the command from must be part of the Local Administrators group and it must be ran from a PowerShell console running as elevated privileges.
  • It will use the Proxy settings configured on Internet Explorer.
  • If the proxy requires NTLM, negotiate, or Kerberos-based authentication the –UseDefaultCredentials parameter must be used so ad to use the current user credentials to authenticate with the proxy.
  • We can only update the help files once every 24 hours  if we want to update inside the 24 hours we would have to use the –Force parameter.

    When it executes it will perform the following actions:

  • Determines which modules support Updatable Help.
  • Finds the Internet location where each module stores its Updatable Help files.
  • Compares the help files for each module on your computer to the newest help files that are available for each module.
  • Downloads the new files from the Internet.
  • Unwraps the help file package.
  • Verifies that the files are valid help files.
  • Installs the help files in the language-specific subdirectory of the module directory.

    We can also update from a share in the network or from a location on the computer (USB Stick, External Hard Drive..) for those hosts that we decided to limit the risk of data exfiltration by not permitting them access to the internet or the machines are isolated for other reasons. So lets cover how this would be done:

  • We start by downloading from a machines that has internet access to a local folder or file share the machine has access to. 
    Save-Help –DestinationPath \\fps1.acmelabs.com\resources\PSv3Help
  • We can move the files to a USB Drive or Share  and them from the host that we want to update the help files we specify the –SourcePath and the path to where the files are located 
    Update-Help –SourcePath \\fps1.acmelabs.com\resources\PSv3Help

    We can configure a scheduled task to update each day the PowerShell help files either from the internet or from a share as in the example above:

    Register-ScheduledJob -Name UpdatePSHelp `
      -ScheduledJobOption @{RunElevated=$true} `
  -ScriptBlock {Update-Help -Force -Verbose} `
  -Trigger @{At='6:00 AM';Frequency='Daily'}

    We can take a look at the output of the scheduled jobs with:

    Get-Job -Name UpdateHelp | Receive-Job

    Now if you are using PowerShell v2 and you also want the latest help information you can use the –Online parameter and this will open Internet Explorer to the page with the latest information you requested.

    Using Get-Help

    We use the Get-Help cmdlet displays information about Windows PowerShell concepts and commands, including cmdlets, functions, CIM commands, workflows, providers, aliases and scripts.

    The cmdlet has also an Aliases set in the shell by default as help and man. It can be used in either of two ways, the first one to search for help information across the entire help with the use of wildcards. help <wildcard expression> will look for the word or expression in the titles of the help files, if none is found it will look in the content of the help for it. We can also limit to what type of information we may want with the –Category parameter

      help -Category Cmdlet -Name *service*

    The cmdlet can also be ran against a specific cmdlets, functions, CIM commands, workflows, providers, aliases or scripts. Wen used against a cmdlet with no options it will show Name, Synopsis, Syntax, Description, Related Links and Remarks. One can select what parts of a help file we want to see by specifying the parameter for the level of information one wants

    • –Detailed parameter is given it will show Parameter information and Examples.
    •  –Full parameter is given it will show a more detailed list of info for Parameters.
    • –Examples parameter is given only examples are shown.

    A cmdlet can have more than one way for it to be invoked and this can be seen in the syntax. They will typically have one or more Parameter Sets that will differ from syntax to syntax.

    image

    The parameters can be read as:

    • Required for required options or values they will not be enclosed in any bracket.
    • Options or values enclosed in [ ] are optional
    • Values are represent with the type they take between < >
    • Those values that can be lists are represented as <type[ ]> 
    • Those that have a predefined list of options it can take are represented as < option1 | option2 | option3>

    When the help cmdlet is used with the -full option is used we get additional information on the parameters:

    • required? - specifies if the option is required or not.
    • position? - specified if the position is a named one or an order one. For ordered one it will give the number of the position for the value it will map to it.
    • Default value - Default value the option has. (Some times on PSv2 it does not display properly)
    • Accept pipeline input? - specified if the option accepts input from the pipeline and if the input is by value type or by property name.
    • Accept Wildcard Characters? - specifies if wildcard characters can be used.

    With PowerShell v3 the –ShowWindow parameter was added to open a separate window that can be used as reference while one works construction a command

    image

    Conceptual Help Topics

    PowerShell contains what is called Conceptual help topics that contains detailed information about several subjects and areas of Powershell. These can be found at  http://technet.microsoft.com/en-us/library/jj583016 or from the PowerShell console just run

    help about

    This will list all conceptual topics.

    image

    Conclusion

    I invite you to run help against the command shown here and explore the conceptual help topics. Hope you find the blog post useful.