Discover commands in PowerShell

 

Learning objectives

 

Prerequisites

• Be able to start a terminal.

 

Introduction

 

 

PowerShell comes preinstalled with numerous commands. To use PowerShell commands efficiently, you need to understand how they work. For example, you need to know what parameters the commands take and that there might be more than one way to call a command.

It's also helpful to know what a command returns, what type it returns, and the command's properties. By knowing these things, you can configure how help is shown. You also get a hint of how a specific command fits with another command if you combine them.

Learning objectives

 

When you finish this module, you'll be able to:

• Inspect commands to understand how to call them.
• Understand what a command returns and customize what it returns.

Prerequisites

 

To complete this module, you should:

• Be able to start a terminal.
• Understand what PowerShell is.
• Know how to run a command in PowerShell.

 

 

 

 

Discover a command by using the help system

By using the built-in help system in PowerShell, you can find out more about a specific command. You use the Get-Command cmdlet to locate a command that you need. After you've located the command, you might want to know more about what the command does and various ways to call it.

Discover cmdlets by using the help system and Get-Help

You can use the Get-Help core cmdlet to learn more about a command. Typically, you invoke Get-Help by specifying it by name and adding the -Name flag that contains the name of the cmdlet you want to learn about. Here's an example:

>Get-Help -Name Get-Help

Update help

New versions of PowerShell don't include the help system by default. The first time you run Get-Help, you're asked to install the help files. You can also run the Update-Help cmdlet to install the help files. Because a call to Update-Help downloads many help files, the command can fetch only once per day by default. You can override this fetching behavior by using the -Force flag.

You update the help files differently on Windows compared to Linux or macOS. The process differs because when you run the Update-Help cmdlet, help files are fetched over the internet by matching your computer's culture. On Windows, a culture is already installed, but it's missing on Linux and macOS. So you need to specify a culture when you update help files on Linux and macOS.

Here's an example command:

>Update-Help -UICulture en-US -Verbose

This command specifies the -UICulture flag. It gives it the value en-US, which fetches US English help files. To update your help files on macOS or Linux, use a culture that corresponds to your machine's culture.

Explore help sections

When you invoke Get-Help on a cmdlet, a help page is returned. The page includes many sections. You'll likely see these common sections:

• NAME: Provides the name of the command.
• SYNTAX: Shows ways to call the command by using a combination of flags, and sometimes, allowed parameters.
• ALIASES: Lists any aliases for a command. An alias is a different name for a command, and it can be used to invoke the command.
• REMARKS: Provides information about what commands to run to get more help for this command.
• PARAMETERS: Provides details about the parameter. It lists its type, a longer description, and acceptable values, if applicable.

Filter the help response

If you don't want to display the full help page, narrow the response by adding flags to your Get-Help command. Here are some flags you can use:

• Full: Returns a detailed help page. It specifies information like parameters, inputs, and outputs that you don't get in the standard response.
• Detailed: Returns a response that looks like the standard response, but it includes a section for parameters.
• Examples: Returns only examples, if any exist.
• Online: Opens a web page for your command.
• Parameter: Requires a parameter name as an argument. It lists a specific parameter's properties.

For example, you can use the following command to return only the Examples section of the help page.

>Get-Help Get-FileHash -Examples

Improve the reading experience

Running Get-Help returns the entire help page. The page might not provide the best reading experience. You might have to scroll to find the section you want to read. A better approach is to use the help alias. The help alias pipes Get-Help into a function that ensures that your output is readable line by line. It also makes the response readable page by page, by paginating the output. 

 

 

Exercise - Using help

 

 

Use Get-Help to discover commands

Use the Get-Help cmdlet to learn about cmdlets.

1. Run the command Get-Help:

   PowerShell Copy

    

   Get-Help -Name Get-FileHash
   

   This command produces an output similar to the following text:

   Output Copy

    

   NAME
       Get-FileHash
   
   SYNOPSIS
       Computes the hash value for a file by using a specified hash algorithm.
   
   SYNTAX
       Get-FileHash [-InputStream] <System.IO.Stream> [[-Algorithm] {SHA1 | SHA256 | SHA384 | SHA512 | MD5}] 
       [<CommonParameters>]
   
       Get-FileHash [-LiteralPath] <System.String[]> [[-Algorithm] {SHA1 | SHA256 | SHA384 | SHA512 | MD5}] 
       [<CommonParameters>]
   
       Get-FileHash [-Path] <System.String[]> [[-Algorithm] {SHA1 | SHA256 | SHA384 | SHA512 | MD5}] 
       [<CommonParameters>]
   
   DESCRIPTION
       The `Get-FileHash` cmdlet computes the hash value for a file by using a specified hash algorithm. A hash value 
       is a unique value that corresponds to the content of the file. Rather than identifying the contents of a file 
       by its file name, extension, or other designation, a hash assigns a unique value to the contents of a file. 
       File names and extensions can be changed without altering the content of the file, and without changing the 
       hash value. Similarly, the file's content can be changed without changing the name or extension. However, 
       changing even a single character in the contents of a file changes the hash value of the file.
   
       The purpose of hash values is to provide a cryptographically-secure way to verify that the contents of a file 
       have not been changed. While some hash algorithms, including MD5 and SHA1, are no longer considered secure 
       against attack, the goal of a secure hash algorithm is to render it impossible to change the contents of a file 
       -- either by accident, or by malicious or unauthorized attempt -- and maintain the same hash value. You can 
       also use hash values to determine if two different files have exactly the same content. If the hash values of 
       two files are identical, the contents of the files are also identical.
   
       By default, the `Get-FileHash` cmdlet uses the SHA256 algorithm, although any hash algorithm that is supported 
       by the target operating system can be used.
   
   RELATED LINKS
       Online Version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/get-filehash?view=powe
       rshell-7.2&WT.mc_id=ps-gethelp
       Format-List 
   
   REMARKS
       To see the examples, type: "Get-Help Get-FileHash -Examples"
       For more information, type: "Get-Help Get-FileHash -Detailed"
       For technical information, type: "Get-Help Get-FileHash -Full"
       For online help, type: "Get-Help Get-FileHash -Online"
   

   Because this output is difficult to read, you decide to use an alternative that is less verbose. That is, you use the help alias.

2. Enter the help command:

   help Get-FileHash
   

   Now, a reduced version of the help output is shown. It looks like the following text:

   Output Copy

    

   NAME
       Get-FileHash
   
   SYNOPSIS
       Computes the hash value for a file by using a specified hash algorithm.
   
   SYNTAX
       Get-FileHash [-InputStream] <System.IO.Stream> [[-Algorithm] {SHA1 | SHA256 | SHA384 | SHA512 | MD5}] 
       [<CommonParameters>]
   
       Get-FileHash [-LiteralPath] <System.String[]> [[-Algorithm] {SHA1 | SHA256 | SHA384 | SHA512 | MD5}] 
       [<CommonParameters>]
   
       Get-FileHash [-Path] <System.String[]> [[-Algorithm] {SHA1 | SHA256 | SHA384 | SHA512 | MD5}] 
       [<CommonParameters>]
   
   DESCRIPTION
       The `Get-FileHash` cmdlet computes the hash value for a file by using a specified hash algorithm. A hash value 
       is a unique value that corresponds to the content of the file. Rather than identifying the contents of a file 
       by its file name, extension, or other designation, a hash assigns a unique value to the contents of a file. 
       File names and extensions can be changed without altering the content of the file, and without changing the 
       hash value. Similarly, the file's content can be changed without changing the name or extension. However, 
       changing even a single character in the contents of a file changes the hash value of the file.
   
       The purpose of hash values is to provide a cryptographically-secure way to verify that the contents of a file 
       have not been changed. While some hash algorithms, including MD5 and SHA1, are no longer considered secure 
       against attack, the goal of a secure hash algorithm is to render it impossible to change the contents of a file 
       -- either by accident, or by malicious or unauthorized attempt -- and maintain the same hash value. You can 
       also use hash values to determine if two different files have exactly the same content. If the hash values of 
       two files are identical, the contents of the files are also identical.
   
       By default, the `Get-FileHash` cmdlet uses the SHA256 algorithm, although any hash algorithm that is supported 
       by the target operating system can be used.
   

   You can move through the results vertically, row by row, by using the arrow keys. To view the results page by page, use the Spacebar.

3. Run help Get-FileHash -Examples:

   PowerShell Copy

    

   help Get-FileHash -Examples
   

   The output looks like the following text:

   Output Copy

    

   NAME
       Get-FileHash
   
   SYNOPSIS
       Computes the hash value for a file by using a specified hash algorithm.
   
   
       --------- Example 1: Compute the hash value for a file ---------
   
      > Get-FileHash /etc/apt/sources.list | Format-List
   
       Algorithm : SHA256
       Hash      : 3CBCFDDEC145E3382D592266BE193E5BE53443138EE6AB6CA09FF20DF609E268
       Path      : /etc/apt/sources.list
   
   
       ------ Example 2: Compute the hash value for an ISO file ------
   
       >Get-FileHash C:\Users\user1\Downloads\Contoso8_1_ENT.iso -Algorithm SHA384 | Format-List
   
       Algorithm : SHA384
       Hash      : 20AB1C2EE19FC96A7C66E33917D191A24E3CE9DAC99DB7C786ACCE31E559144FEAFC695C58E508E2EBBC9D3C96F21FA3
       Path      : C:\Users\user1\Downloads\Contoso8_1_ENT.iso   
   

   This output contains a list of examples that use the cmdlet. Locate the part of the response that contains the text Example 1. This portion of the text shows how you can use Get-FileHash with a file path by piping it to the cmdlet Format-List.

    Tip

   To quickly see an example, add the flag -Examples when you search for help.

 

 

Discover objects

 

When a cmdlet runs, it returns an object. When you invoke a cmdlet, the response you see has been formatted and might not necessarily represent all the available information for the response. To know more about what's being returned and how you can modify what is returned, you can use the command Get-Member.

Discover objects by using Get-Member

The Get-Member cmdlet is meant to be piped on top of the command you run so that you can filter the output. A typical command-line invocation of Get-Member might look like the following example:

>Get-Process -Name 'name-of-process' | Get-Member

This command first produces an object result by calling Get-Process. That result is passed as an input to Get-Member by using the pipe (|). In return, you get a table result that includes the Name, MemberType, and Definition columns. You also get the type of the returned object.

Search by type

The first line of the response, running the Get-Member command, is the type of the returned object. When you know the type, you can search for other cmdlets that operate on the same type. Explore these related commands to quickly build your knowledge in the domain you're working in.

Let's say you invoked the PowerShell command that lists all members for a specific process. The first few rows of the result look something like this output:

  TypeName: System.Diagnostics.Process

Name                       MemberType     Definition
----                       ----------     ----------
Handles                    AliasProperty  Handles = Handlecount

The first row indicates that the type is System.Diagnostics.Process. Use this type as a search argument to look for other cmdlets that use this type. Here's an example command:

>Get-Command -ParameterType Process

The result is a list of cmdlets that operate on this type. Little by little, you can learn more about PowerShell by using Get-Member and by learning to interpret its result.

Filter a Get-Member result by using Select-Object

When you run Get-Member, the result is verbose. That is, many rows are returned. The object might have properties, like events and methods. To make the answer less verbose, you can filter on specific columns and also decide which columns to display. Keep in mind that the returned answer is already a subset of all the columns in the response.

Take a look at a Get-Member response that includes many columns. By introducing the Select-Object cmdlet, you can choose which columns appear in the response. The command expects either a comma-separated list of column names or a wildcard character, such as an asterisk (*), which indicates all columns.

When you use the Select-Object command in the context of Select-Object Name, MemberType, you specify only the columns you want. In this case, the columns are Name and MemberType. The command line would look like this:

Get-Process -Name 'name-of-process' | Get-Member | Select-Object Name, MemberType

This filtering pattern returns an output that includes fewer columns. Here's an example of the result:

Name                           MemberType
----                           ----------
Handles                     AliasProperty

You also can filter the response by rows. For example, you can use the -MemberType Method flag to specify that you're interested in the rows in which the member type is a method. You might want to show only specific rows, for example, if you want to locate and run a specific method.