From 9a74b489a031c03172220a307fb2581cb22b07b0 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" Date: Wed, 26 Jun 2024 16:42:37 -0500 Subject: [PATCH 1/3] Refresh of ps101 chapter 2 --- .../learn/ps101/02-help-system.md | 1104 +++++++++++------ reference/docs-conceptual/toc.yml | 2 +- 2 files changed, 701 insertions(+), 405 deletions(-) diff --git a/reference/docs-conceptual/learn/ps101/02-help-system.md b/reference/docs-conceptual/learn/ps101/02-help-system.md index a1f76e6eb44..ca852e15803 100644 --- a/reference/docs-conceptual/learn/ps101/02-help-system.md +++ b/reference/docs-conceptual/learn/ps101/02-help-system.md @@ -1,92 +1,95 @@ --- -description: Mastering the help system is the key to being successful with PowerShell. +description: Becoming proficient with the help system is the key to success with PowerShell ms.custom: Contributor-mikefrobbins -ms.date: 12/08/2022 +ms.date: 06/25/2024 ms.reviewer: mirobb title: The Help System --- -# Chapter 2 - The Help System -Two groups of IT pros were given a written test without access to a computer to determine their -skill level with PowerShell. PowerShell beginners were placed in one group and experts in another. -Based on the results of the test, there didn't seem to be much difference in the skill level between -the two groups. Both groups were given a second test similar to the first one. This time they were -given access to a computer with PowerShell that didn't have access to the internet. The results of -the second test showed a huge difference in the skill level between the two groups. Experts don't -always know the answers, but they know how to figure out the answers. +# Chapter 2 - The help system -What was the difference in the results of the first and second test between these two groups? +In an experiment designed to assess proficiency in PowerShell, two distinct groups of IT +professionals —beginners and experts— were first given a written examination without access to a +computer. Surprisingly, the test scores indicated comparable skills across both groups. A subsequent +test was then administered, mirroring the first but with one key difference: participants had access +to an offline computer equipped with PowerShell. The results revealed a significant skills gap +between the two groups this time. -The differences observed in these two tests were because experts don't memorize how to use thousands -of commands in PowerShell. They learn how to use the help system within PowerShell extremely well. -This allows them to find the necessary commands when needed and how to use those commands once -they've found them. +What factors contributed to the outcomes observed between the two assessments? -I've heard Jeffrey Snover, the inventor of PowerShell, tell a similar story a number of times. +> Experts don't always know the answers, but they know how to figure out the answers. -Mastering the help system is the key to being successful with PowerShell. +The outcomes observed in the results of the two tests were because experts don't memorize thousands +of PowerShell commands. Instead, they excel at using the help system within PowerShell, enabling +them to discover and learn how to use commands when necessary. + +> Becoming proficient with the help system is the key to success with PowerShell. + +I heard Jeffrey Snover, the creator of PowerShell, share a similar story on multiple occasions. ## Discoverability -Compiled commands in PowerShell are called cmdlets. Cmdlet is pronounced "command-let" (not -CMD-let). Cmdlets names have the form of singular "Verb-Noun" commands to make them easily -discoverable. For example, the cmdlet for determining what processes are running is `Get-Process` -and the cmdlet for retrieving a list of services and their statuses is `Get-Service`. There are -other types of commands in PowerShell such as aliases and functions that will be covered later in -this book. The term PowerShell command is a generic term that's often used to refer to any type of -command in PowerShell, regardless of whether or not it's a cmdlet, function, or alias. +Compiled commands in PowerShell are known as cmdlets, pronounced as _"command-let"_, not +_"CMD-let"_. The naming convention for cmdlets follows a singular **Verb-Noun** format to make them +easily discoverable. For instance, `Get-Process` is the cmdlet to determine what processes are +running, and `Get-Service` is the cmdlet to retrieve a list of services. Other types of commands in +PowerShell, such as aliases and functions, are discussed later in this book. The term _"PowerShell +command"_ describes any command in PowerShell, regardless of whether it's a cmdlet, function, or +alias. -## The Three Core Cmdlets in PowerShell +## The three core cmdlets in PowerShell -- `Get-Command` - `Get-Help` +- `Get-Command` - `Get-Member` (covered in chapter 3) -One question I'm often asked is how do you figure out what the commands are in PowerShell? Both -`Get-Command` and `Get-Help` can be used to determine the commands. +I'm often asked: _"How do you figure out what the commands are in PowerShell?"_. Both `Get-Help` and +`Get-Command` are invaluable resources for discovering and understanding commands in PowerShell. ## Get-Help -`Get-Help` is a multipurpose command. `Get-Help` helps you learn how to use commands once you find -them. `Get-Help` can also be used to help locate commands, but in a different and more indirect way -when compared to `Get-Command`. +The first thing you need to know about the help system in PowerShell is how to use the `Get-Help` +cmdlet. -When `Get-Help` is used to locate commands, it first searches for wildcard matches of command names -based on the provided input. If it doesn't find a match, it searches through the help topics -themselves, and if no match is found an error is returned. Contrary to popular belief, `Get-Help` -can be used to find commands that don't have help topics. +`Get-Help` is a multipurpose command that helps you learn how to use commands once you find them. +You can also use `Get-Help` to locate commands, but in a different and more indirect way when +compared to `Get-Command`. -The first thing you need to know about the help system in PowerShell is how to use the `Get-Help` -cmdlet. The following command is used to display the help topic for `Get-Help`. +When using `Get-Help` to locate commands, it initially performs a wildcard search for command names +based on your input. If that doesn't find any matches, it conducts a comprehensive full-text search +across all PowerShell help articles on your system. If that also fails to find any results, it +returns an error. + +Here's how to use `Get-Help` to view the help content for the `Get-Help` cmdlet. ```powershell Get-Help -Name Get-Help ``` +Beginning with PowerShell version 3.0, the help content doesn't ship preinstalled with the operating +system. When you run `Get-Help` for the first time, a message asks if you want to download the +PowerShell help files to your computer. + +Answering **Yes** by pressing Y executes the `Update-Help` cmdlet, downloading the help +content. + ```Output Do you want to run Update-Help? -The Update-Help cmdlet downloads the most current Help files for Windows PowerShell -modules, and installs them on your computer. For more information about the Update-Help -cmdlet, see http://go.microsoft.com/fwlink/?LinkId=210614. +The Update-Help cmdlet downloads the most current Help files for Windows +PowerShell modules, and installs them on your computer. For more information +about the Update-Help cmdlet, see +https:/go.microsoft.com/fwlink/?LinkId=210614. [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): ``` -Beginning with PowerShell version 3, PowerShell help doesn't ship with the operating system. The -first time `Get-Help` is run for a command, the previous message is displayed. If the `help` -function or `man` alias is used instead of the `Get-Help` cmdlet, you don't receive this prompt. +You only receive this message if you run PowerShell elevated as an administrator. You also don't +receive it if you're using the `help` function or `man` alias. If you don't receive this message, +run `Update-Help` from an elevated PowerShell session running as an administrator. -Answering yes by pressing Y runs the `Update-Help` cmdlet, which requires internet access -by default. `Y` can be specified in either upper or lower case. +Once the update is complete, the help article is displayed. -Once the help is downloaded and the update is complete, the help topic is returned for the specified -command: - -```powershell -Get-Help -Name Get-Help -``` - -Take a moment to run that example on your computer, review the output, and take note of how the -information is grouped: +Take a moment to run the example on your computer, review the output, and observe how the help +system organizes the information. - NAME - SYNOPSIS @@ -95,25 +98,80 @@ information is grouped: - RELATED LINKS - REMARKS -As you can see, help topics can contain an enormous amount of information and this isn't even the -entire help topic. +As you review the output, keep in mind that help articles often contain a vast amount of +information, and what you see by default isn't the entire help article. + +### Parameters -While not specific to PowerShell, a parameter is a way to provide input to a command. `Get-Help` has -many parameters that can be specified in order to return the entire help topic or a subset of -it. +When you run a command in PowerShell, you might need to provide additional information or input to +the command. Parameters allow you to specify options and arguments that change the behavior of a +command. The **SYNTAX** section of each help article outlines the available parameters for the +command. -The syntax section of the help topic shown in the previous set of results lists all of the -parameters for `Get-Help`. At first glance, it appears the same parameters are listed six different -times. Each of those different blocks in the syntax section is a parameter set. This means the -`Get-Help` cmdlet has six different parameter sets. If you take a closer look, you'll notice that at -least one parameter is different in each of the parameter sets. +`Get-Help` has several parameters that you can specify to return the entire help article or a subset +for a command. To view all the available parameters for `Get-Help`, see the **SYNTAX** section of +its help article, as shown in the following example. -Parameter sets are mutually exclusive. Once a unique parameter that only exists in one of the -parameter sets is used, only parameters contained within that parameter set can be used. For -example, both the **Full** and **Detailed** parameters couldn't be specified at the same time -because they are in different parameter sets. +```Output +... +SYNTAX + Get-Help [[-Name] ] [-Category {Alias | Cmdlet | Provider + | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | + Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | + Class | Configuration}] [-Component ] [-Full] + [-Functionality ] [-Path ] [-Role + ] [] + + Get-Help [[-Name] ] [-Category {Alias | Cmdlet | Provider + | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | + Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | + Class | Configuration}] [-Component ] -Detailed + [-Functionality ] [-Path ] [-Role + ] [] + + Get-Help [[-Name] ] [-Category {Alias | Cmdlet | Provider + | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | + Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | + Class | Configuration}] [-Component ] -Examples + [-Functionality ] [-Path ] [-Role + ] [] + + Get-Help [[-Name] ] [-Category {Alias | Cmdlet | Provider + | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | + Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | + Class | Configuration}] [-Component ] [-Functionality + ] -Online [-Path ] [-Role + ] [] + + Get-Help [[-Name] ] [-Category {Alias | Cmdlet | Provider + | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | + Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | + Class | Configuration}] [-Component ] [-Functionality + ] -Parameter [-Path ] + [-Role ] [] + + Get-Help [[-Name] ] [-Category {Alias | Cmdlet | Provider + | General | FAQ | Glossary | HelpFile | ScriptCommand | Function | + Filter | ExternalScript | All | DefaultHelp | Workflow | DscResource | + Class | Configuration}] [-Component ] [-Functionality + ] [-Path ] [-Role ] + -ShowWindow [] +... +``` + +### Parameter sets -Each of the following parameters are in different parameter sets: +When you review the **SYNTAX** section for `Get-Help`, notice that the information appears to be +repeated six times. Each of those blocks is an individual parameter set, indicating the `Get-Help` +cmdlet features six distinct sets of parameters. A closer look reveals each parameter set contains +at least one unique parameter, making it different from the others. + +Parameter sets are mutually exclusive. Once you specify a unique parameter that only exists in one +parameter set, PowerShell limits you to using the parameters contained within that parameter set. +For instance, you can't use the **Full** and **Detailed** parameters of `Get-Help` together because +they belong to different parameter sets. + +Each of the following parameters belongs to a different parameter set for the `Get-Help` cmdlet. - Full - Detailed @@ -122,22 +180,99 @@ Each of the following parameters are in different parameter sets: - Parameter - ShowWindow -All of the cryptic syntax such as square and angle brackets in the syntax section means something -but will be covered in Appendix A of this book. While important, learning the cryptic syntax is -often difficult to retain for someone who is new to PowerShell and may not use it everyday. +### The help syntax + +If you're new to PowerShell, comprehending the cryptic help syntax —characterized by square and +angle brackets— in the **SYNTAX** section of the help articles might seem overwhelming. However, +learning these syntax elements is essential to becoming proficient with PowerShell. The more +frequently you use the PowerShell help system, the easier it becomes to remember all the nuances. + +View the syntax section of the help article for the `Get-EventLog` cmdlet. -For more information to better understand the cryptic syntax, see [Appendix A][Appendix A]. +```powershell +help Get-EventLog +``` + +The following output shows the relevant portion of the help article. + +```Output +... +SYNTAX + Get-EventLog [-LogName] [[-InstanceId] + ] [-After ] [-AsBaseObject] [-Before + ] [-ComputerName ] [-EntryType {Error + | Information | FailureAudit | SuccessAudit | Warning}] [-Index + ] [-Message ] [-Newest ] + [-Source ] [-UserName ] + [] + + Get-EventLog [-AsString] [-ComputerName ] [-List] + [] +... +``` -For beginners, there's an easier way to figure out the same information except in plain language. +The help syntax in the **SYNTAX** section of PowerShell help articles includes pairs of square +brackets `([ ])`. Depending on their usage, these square brackets serve two different purposes. -When the **Full** parameter of `Get-Help` is specified, the entire help topic is returned. +- Elements enclosed within square brackets are optional. +- When an empty set of square brackets follows a datatype, such as ``, it indicates the + parameter can accept multiple values as an array or a comma-separated list. + +### Positional parameters + +When developers create a PowerShell cmdlet or function, they can optionally designate one or more +parameters as positional. Positional parameters allow you to provide a value without specifying the +parameter's name. When using a parameter positionally, you must specify its value in the correct +position. You can find the positional information for a parameter in the **PARAMETERS** section of a +command's help article. When you explicitly specify parameter names, their order is irrelevant. + +For the `Get-EventLog` cmdlet, the first parameter in the first parameter set is **LogName**. +**LogName** is enclosed in square brackets, indicating it's a positional parameter. + +Since **LogName** is a positional parameter, you can specify it by either name or position. +According to the angle brackets following the parameter name, the value for **LogName** must be a +single string. The absence of square brackets enclosing both the parameter name and datatype +indicates that **LogName** is a required parameter within this particular parameter set. + +```powershell +Get-EventLog [-LogName] +``` + +The second parameter in that parameter set is **InstanceId**. Both the parameter name and datatype +are entirely enclosed in square brackets, signifying that **InstanceId** is an optional parameter. +Furthermore, **InstanceId** has its own pair of square brackets, indicating that it's a positional +parameter similar to the **LogName** parameter. Following the datatype, an empty set of square +brackets implies that **InstanceId** can accept multiple values. + +```powershell +[[-InstanceId] ] +``` + +### Switch parameters + +A parameter that doesn't require a value is called a switch parameter. You can easily identify +switch parameters because a datatype doesn't follow their parameter names. When you specify a switch +parameter, its value is `true`; when you don't specify a switch parameter, its value is `false`. + +The second parameter set includes a **List** parameter, which is a switch parameter. When you +specify the **List** parameter, it returns a list of event logs on the local computer. + +```powershell +[-List] +``` + +### A simplified approach to syntax + +There's a more user-friendly method to obtain the same information as the cryptic help syntax for +some commands, except in plain English. PowerShell returns the complete help article when using +`Get-Help` with the **Full** parameter, making it easier to understand a command's usage. ```powershell Get-Help -Name Get-Help -Full ``` -Take a moment to run that example on your computer, review the output, and take note of how the -information is grouped: +Take a moment to run the example on your computer, review the output, and observe how the help +system organizes the information. - NAME - SYNOPSIS @@ -150,30 +285,68 @@ information is grouped: - EXAMPLES - RELATED LINKS -Notice that using the **Full** parameter returned several additional sections, one of which is the -PARAMETERS section that provides more information than the cryptic SYNTAX section. +By specifying the **Full** parameter with the `Get-Help` cmdlet, notice the output includes several +extra sections. Among these sections, **PARAMETERS** often provides a detailed explanation for each +parameter. However, the extent of this information varies depending on the specific command you're +investigating. -The **Full** parameter is a switch parameter. A parameter that doesn't require a value is called a -switch parameter. When a switch parameter is specified, its value is true and when it's not, its -value is false. +```Output +... + -Detailed + Adds parameter descriptions and examples to the basic help display. + This parameter is effective only when the help files are installed + on the computer. It has no effect on displays of conceptual ( About_ + ) help. + + Required? true + Position? named + Default value False + Accept pipeline input? False + Accept wildcard characters? false + + -Examples + Displays only the name, synopsis, and examples. This parameter is + effective only when the help files are installed on the computer. It + has no effect on displays of conceptual ( About_ ) help. + + Required? true + Position? named + Default value False + Accept pipeline input? False + Accept wildcard characters? false + + -Full + Displays the entire help article for a cmdlet. Full includes + parameter descriptions and attributes, examples, input and output + object types, and additional notes. + + This parameter is effective only when the help files are installed + on the computer. It has no effect on displays of conceptual ( About_ + ) help. + + Required? false + Position? named + Default value False + Accept pipeline input? False + Accept wildcard characters? false +... +``` -If you've been working through this chapter in the PowerShell console, you noticed that the previous -command to display the full help topic for `Get-Help` flew by on the screen without giving you a -chance to read it. There's a better way. +When you ran the previous command to display the help article for `Get-Help`, you probably noticed +the output scrolled by too quickly to read it. -`Help` is a function that pipes `Get-Help` to a function named `more`, which is a wrapper for the -`more.com` executable file in Windows. In the PowerShell console, `help` provides one page of help -at a time. In the ISE, it works the same way as `Get-Help`. My recommendation is to use the `help` -function instead of the `Get-Help` cmdlet since it provides a better experience and it's less to -type. +If you're using the PowerShell console, Windows Terminal, or VS Code and need to view a help +article, the `help` function can be useful. It pipes `Get-Help` to `more.com`, displaying one page +of help content at a time. As for the ISE, running `help` works the same way as `Get-Help`. I +recommend using the `help` function instead of the `Get-Help` cmdlet because it provides a better +user experience and it's less to type. -Less typing isn't always a good thing, however. If you're going to save your commands as a script or -share them with someone else, be sure to use full cmdlet and parameter names. The full names are -self-documenting, which makes them easier to understand. Think about the next person that has to -read and understand your commands. It could be you. Your coworkers and future self will thank you. +While typing less might seem beneficial, it's not always the best practice or intuitive when saving +commands in a script or sharing code with others. Using full cmdlet and parameter names offers the +benefit of self-documenting, making the code more easily interpreted and understandable for anyone +who reviews it. -Try running the following commands in the PowerShell console on your Windows 10 lab environment -computer. +Run each of the following commands in PowerShell on your computer. ```powershell Get-Help -Name Get-Help -Full @@ -181,45 +354,57 @@ help -Name Get-Help -Full help Get-Help -Full ``` -Did you notice any differences in the output from the previously listed commands when you ran them -on your Windows 10 lab environment computer? +Did you observe any variations in the output when you ran the previous commands? -There aren't any differences other than the last two options return the results one page at a time. -The spacebar is used to display the next page of content when using the `Help` function -and Ctrl+C cancels commands that are running in the PowerShell console. +The only difference is the last two commands display their output one page at a time. When using the +`help` function, press the _Spacebar_ to navigate to the next page of content or `Q` to quit. If you +need to terminate any command running interactively in PowerShell, press +Ctrl+C. -The first example uses the `Get-Help` cmdlet, the second uses the `Help` function, and the third -omits the **Name** parameter when using the `Help` function. **Name** is a positional parameter and -it's being used positionally in that example. This means the value can be specified without -specifying the parameter name, as long as the value itself is specified in the correct position. How -did I know what position to specify the value in? By reading the help as shown in the following -example. +In the previous example, the first line uses the `Get-Help` cmdlet, the second uses the `help` +function, and the third line omits the **Name** parameter while using the `help` function. Since +**Name** is a positional parameter, the third example takes advantage of its placement instead of +explicitly stating the parameter's name. + +To quickly find information about a specific parameter, use the `help` function with the +**Parameter** parameter. This approach is more concise, containing only the parameter-specific help +content instead of manually scanning the entire help article for details about a parameter. + +In the following example, use the `help` function with the **Parameter** parameter to return +information from the help article for the **Name** parameter of `Get-Help`. ```powershell help Get-Help -Parameter Name ``` +Based on the following results, the **Name** parameter is positional and must be specified in +position zero when used positionally. + ```Output --Name - Gets help about the specified command or concept. Enter the name of a cmdlet, function, - provider, script, or workflow, such as Get-Member, a conceptual article name, such as - about_Objects, or an alias, such as ls. Wildcard characters are permitted in cmdlet and - provider names, but you can't use wildcard characters to find the names of function help and - script help articles. +-Name + Gets help about the specified command or concept. Enter the name of a + cmdlet, function, provider, script, or workflow, such as `Get-Member`, + a conceptual article name, such as `about_Objects`, or an alias, such + as `ls`. Wildcard characters are permitted in cmdlet and provider + names, but you can't use wildcard characters to find the names of + function help and script help articles. - To get help for a script that isn't located in a path that's listed in the $env:Path - environment variable, type the script's path and file name. + To get help for a script that isn't located in a path that's listed in + the `$env:Path` environment variable, type the script's path and file + name. - If you enter the exact name of a help article, Get-Help displays the article contents. + If you enter the exact name of a help article, `Get-Help` displays the + article contents. - If you enter a word or word pattern that appears in several help article titles, Get-Help - displays a list of the matching titles. + If you enter a word or word pattern that appears in several help + article titles, `Get-Help` displays a list of the matching titles. - If you enter a word that doesn't match any help article titles, Get-Help displays a list of - articles that include that word in their contents. + If you enter any text that doesn't match any help article titles, + `Get-Help` displays a list of articles that include that text in their + contents. - The names of conceptual articles, such as about_Objects, must be entered in English, even in - non-English versions of PowerShell. + The names of conceptual articles, such as `about_Objects`, must be + entered in English, even in non-English versions of PowerShell. Required? false Position? 0 @@ -228,21 +413,12 @@ help Get-Help -Parameter Name Accept wildcard characters? true ``` -Notice that in the previous example, the **Parameter** parameter was used with the Help function to -only return information from the help topic for the **Name** parameter. This is much more concise -than trying to manually sift through what sometimes seems like a hundred page help topic. - -Based on those results, you can see that the **Name** parameter is positional and must be specified -in position zero (the first position) when used positionally. The order that parameters are -specified in doesn't matter if the parameter name is specified. +The **Name** parameter expects the datatype for its value to be a single string as identified by +`` next to the parameter name. -One other important piece of information is that the **Name** parameter expects the datatype for its -value to be a single string, which is denoted by ``. If it accepted multiple strings, the -datatype would be listed as ``. - -Sometimes you simply don't want to display the entire help topic for a command. There are a number -of other parameters besides **Full** that can be specified with `Get-Help` or `Help`. Try running -the following commands on your Windows 10 lab environment computer: +There are several other parameters besides **Parameter** that you can specify with `Get-Help` to +return a subset of a help article. To see how they work, run the following commands on your +computer. ```powershell Get-Help -Name Get-Command -Full @@ -253,176 +429,189 @@ Get-Help -Name Get-Command -Parameter Noun Get-Help -Name Get-Command -ShowWindow ``` -I typically use `help ` with the **Full** or **Online** parameter. If I'm only -interested in the examples, I'll use the **Examples** parameter and if I'm only interested in a -specific parameter, I'll use the **Parameter** parameter. The **ShowWindow** parameter opens the -help topic in a separate searchable window that can be placed on a different monitor if you have -multiple monitors. I've avoided the **ShowWindow** parameter because there's a known bug where it -doesn't display the entire help topic. +I typically use `help ` with the **Full** or **Online** parameter. If you only have an +interest in the examples, use the **Examples** parameter; if you only have an interest in a specific +parameter, use the **Parameter** parameter. + +When the **ShowWindow** parameter is used, it opens the help article in a separate searchable window +that can be placed on a different monitor if you have multiple monitors. However, the **ShowWindow** +parameter has a known bug that might prevent it from displaying the entire help article. The +**ShowWindow** parameter also requires an operating system with a Graphical User Interface (GUI). It +returns an error if you attempt to use it on Windows Server installed with the server core +installation option. -If you want help in a separate window, my recommendation is to either use the **Online** parameter -or use the **Full** parameter and pipe the results to `Out-GridView`, as shown in the following -example. +If you want the help article in a separate window and have internet access, use the **Online** +parameter instead. The **Online** parameter opens the help article with the most up-to-date content +in your default web browser, allowing you to search it and navigate to other help articles. ```powershell -help Get-Command -Full | Out-GridView +help Get-Command -Online ``` -Both the `Out-GridView` cmdlet and the **ShowWindow** parameter of the `Get-Help` cmdlet require an -operating system with a GUI (Graphical User Interface). They will generate an error message if you -attempt to use either of them on Windows Server that's been installed using the server core (no-GUI) -installation option. +### Finding commands with Get-Help -To use `Get-Help` to find commands, use the asterisk (`*`) wildcard character with the **Name** -parameter. Specify a term that you're searching for commands on as the value for the **Name** -parameter as shown in the following example. +To find commands with `Get-Help`, specify a search term surrounded by asterisk (`*`) wildcard +characters for the value of the **Name** parameter. The following example uses the **Name** +parameter positionally. ```powershell help *process* ``` ```Output -Name Category Module Synopsis ----- -------- ------ -------- -Enter-PSHostProcess Cmdlet Microsoft.PowerShell.Core Connects to and ... -Exit-PSHostProcess Cmdlet Microsoft.PowerShell.Core Closes an intera... -Get-PSHostProcessInfo Cmdlet Microsoft.PowerShell.Core -Debug-Process Cmdlet Microsoft.PowerShell.M... Debugs one or mo... -Get-Process Cmdlet Microsoft.PowerShell.M... Gets the process... -Start-Process Cmdlet Microsoft.PowerShell.M... Starts one or mo... -Stop-Process Cmdlet Microsoft.PowerShell.M... Stops one or mor... -Wait-Process Cmdlet Microsoft.PowerShell.M... Waits for the pr... -Get-AppvVirtualProcess Function AppvClient ... -Start-AppvVirtualProcess Function AppvClient ... -``` - -In the previous example, the `*` wildcard characters are not required and omitting them produces the -same result. `Get-Help` automatically adds the wildcard characters behind the scenes. +Name Category Module Synops +---- -------- ------ ------ +Enter-PSHostProcess Cmdlet Microsoft.PowerShell.Core Con... +Exit-PSHostProcess Cmdlet Microsoft.PowerShell.Core Clo... +Get-PSHostProcessInfo Cmdlet Microsoft.PowerShell.Core Get... +Debug-Process Cmdlet Microsoft.PowerShell.M... Deb... +Get-Process Cmdlet Microsoft.PowerShell.M... Get... +Start-Process Cmdlet Microsoft.PowerShell.M... Sta... +Stop-Process Cmdlet Microsoft.PowerShell.M... Sto... +Wait-Process Cmdlet Microsoft.PowerShell.M... Wai... +Invoke-LapsPolicyProcessing Cmdlet LAPS Inv... +ConvertTo-ProcessMitigationPolicy Cmdlet ProcessMitigations Con... +Get-ProcessMitigation Cmdlet ProcessMitigations Get... +Set-ProcessMitigation Cmdlet ProcessMitigations Set... +``` + +In this scenario, you aren't required to add the `*` wildcard characters. When you omit the wildcard +characters, `Get-Help` automatically adds them behind the scenes. The following example produces the +same results as specifying the `*` wildcard character on each end of `process`. ```powershell help process ``` -The previous command produces the same results as specifying the `*` wildcard character on each end -of process. +However, you should always add them since that option works consistently. Otherwise, it requires you +to add them in certain scenarios and not in others. When you specify a wildcard character within the +value, they aren't appended automatically behind the scenes. -I prefer to add them since that's the option that always works consistently. Otherwise, they are -required in certain scenarios and not others. As soon as you add a wildcard character in the middle -of the value, they're no longer automatically added behind the scenes to the value you specified. +The following command doesn't return any results unless you add a `*` wildcard character to the +beginning, end, or both the beginning and end of `pr*cess`. ```powershell help pr*cess ``` -No results are returned by that command unless the `*` wildcard character is added to the beginning, -end, or both the beginning and end of `pr*cess`. - -If the value you specified begins with a dash, then an error is generated because PowerShell -interprets it as a parameter name and no such parameter name exists for the `Get-Help` cmdlet. +PowerShell generates an error if you specify a value that begins with a dash without enclosing it in +quotes because it interprets it as a parameter name. No such parameter name exists for the +`Get-Help` cmdlet. ```powershell help -process ``` -If what you're attempting to look for are commands that end with `-process`, you only need to add -the `*` wildcard character to the beginning of the value. +If you're attempting to search for commands that end with `-process`, you must add an `*` to the +beginning of the value. ```powershell help *-process ``` -When searching for PowerShell commands with `Get-Help`, you want to be a little more vague instead -of being too specific with what you're searching for. +When you search for PowerShell commands with `Get-Help`, it's better to be vague rather than too +specific. -Searching for `process` earlier found only commands that contained `process` in the name of the -command and returned only those results. When `Get-Help` is used to search for `processes`, it -doesn't find any matches for command names, so it performs a search of every help topic in -PowerShell on your system and returns any matches it finds. This causes it to return an enormous -number of results. +When you searched for `process` earlier, the results only returned commands that included `process` +in their name. But if you use `help` to search for `processes`, it doesn't find any matches for +command names. As previously stated, when help doesn't find any matches, it performs a comprehensive +full-text search of every help article on your system and returns those results. This type of search +often produces more results than expected, probably without the information you're trying to locate. ```powershell -Get-Help processes +help processes ``` ```Output -Name Category Module Synopsis ----- -------- ------ -------- -Disconnect-PSSession Cmdlet Microsoft.PowerShell.Core Disconnects from... -Enter-PSHostProcess Cmdlet Microsoft.PowerShell.Core Connects to and ... -ForEach-Object Cmdlet Microsoft.PowerShell.Core Performs an oper... -Get-PSSessionConfiguration Cmdlet Microsoft.PowerShell.Core Gets the registe... -New-PSTransportOption Cmdlet Microsoft.PowerShell.Core Creates an objec... -Out-Host Cmdlet Microsoft.PowerShell.Core Sends output to ... -Where-Object Cmdlet Microsoft.PowerShell.Core Selects objects ... -Clear-Variable Cmdlet Microsoft.PowerShell.U... Deletes the valu... -Compare-Object Cmdlet Microsoft.PowerShell.U... Compares two set... -Convert-String Cmdlet Microsoft.PowerShell.U... Formats a string... -ConvertFrom-Csv Cmdlet Microsoft.PowerShell.U... Converts object ... -ConvertTo-Html Cmdlet Microsoft.PowerShell.U... Converts Microso... -ConvertTo-Xml Cmdlet Microsoft.PowerShell.U... Creates an XML-b... -Debug-Runspace Cmdlet Microsoft.PowerShell.U... Starts an intera... -Export-Csv Cmdlet Microsoft.PowerShell.U... Converts objects... -Export-FormatData Cmdlet Microsoft.PowerShell.U... Saves formatting... -Format-List Cmdlet Microsoft.PowerShell.U... Formats the outp... -Format-Table Cmdlet Microsoft.PowerShell.U... Formats the outp... -Get-Random Cmdlet Microsoft.PowerShell.U... Gets a random nu... -Get-Unique Cmdlet Microsoft.PowerShell.U... Returns unique i... -Group-Object Cmdlet Microsoft.PowerShell.U... Groups objects t... -Import-Clixml Cmdlet Microsoft.PowerShell.U... Imports a CLIXML... -Import-Csv Cmdlet Microsoft.PowerShell.U... Creates table-li... -Measure-Object Cmdlet Microsoft.PowerShell.U... Calculates the n... -Out-File Cmdlet Microsoft.PowerShell.U... Sends output to ... -Out-GridView Cmdlet Microsoft.PowerShell.U... Sends output to ... -Select-Object Cmdlet Microsoft.PowerShell.U... Selects objects ... -Set-Variable Cmdlet Microsoft.PowerShell.U... Sets the value o... -Sort-Object Cmdlet Microsoft.PowerShell.U... Sorts objects by... -Tee-Object Cmdlet Microsoft.PowerShell.U... Saves command ou... -Trace-Command Cmdlet Microsoft.PowerShell.U... Configures and s... -Write-Output Cmdlet Microsoft.PowerShell.U... Sends the specif... -Debug-Process Cmdlet Microsoft.PowerShell.M... Debugs one or mo... -Get-Process Cmdlet Microsoft.PowerShell.M... Gets the process... -Get-WmiObject Cmdlet Microsoft.PowerShell.M... Gets instances o... -Start-Process Cmdlet Microsoft.PowerShell.M... Starts one or mo... -Stop-Process Cmdlet Microsoft.PowerShell.M... Stops one or mor... -Wait-Process Cmdlet Microsoft.PowerShell.M... Waits for the pr... -Get-Counter Cmdlet Microsoft.PowerShell.D... Gets performance... -Invoke-WSManAction Cmdlet Microsoft.WSMan.Manage... Invokes an actio... -Remove-WSManInstance Cmdlet Microsoft.WSMan.Manage... Deletes a manage... -Get-WSManInstance Cmdlet Microsoft.WSMan.Manage... Displays managem... -New-WSManInstance Cmdlet Microsoft.WSMan.Manage... Creates a new in... -Set-WSManInstance Cmdlet Microsoft.WSMan.Manage... Modifies the man... -about_Arithmetic_Operators HelpFile Describes the op... -about_Arrays HelpFile Describes arrays... -about_Debuggers HelpFile Describes the Wi... -about_Execution_Policies HelpFile Describes the Wi... -about_ForEach-Parallel HelpFile Describes the Fo... -about_Foreach HelpFile Describes a lang... -about_Functions HelpFile Describes how to... -about_Language_Keywords HelpFile Describes the ke... -about_Methods HelpFile Describes how to... -about_Objects HelpFile Provides essenti... -about_Parallel HelpFile Describes the Pa... -about_Pipelines HelpFile Combining comman... -about_Preference_Variables HelpFile Variables that c... -about_Remote HelpFile Describes how to... -about_Remote_Output HelpFile Describes how to... -about_Sequence HelpFile Describes the Se... -about_Session_Configuration_Files HelpFile Describes sessio... -about_Variables HelpFile Describes how va... -about_Windows_PowerShell_5.0 HelpFile Describes new fe... -about_WQL HelpFile Describes WMI Qu... -about_WS-Management_Cmdlets HelpFile Provides an over... -about_ForEach-Parallel HelpFile Describes the Fo... -about_Parallel HelpFile Describes the Pa... -about_Sequence HelpFile Describes the Se... -``` - -Using `Help` to search for `process` returned 10 results and using it to search for `processes` -returned 68 results. If only one result is found, the help topic itself will be displayed instead of -a list of commands. +Name Category Module Synops +---- -------- ------ ------ +Disconnect-PSSession Cmdlet Microsoft.PowerShell.Core Dis... +Enter-PSHostProcess Cmdlet Microsoft.PowerShell.Core Con... +ForEach-Object Cmdlet Microsoft.PowerShell.Core Per... +Get-PSHostProcessInfo Cmdlet Microsoft.PowerShell.Core Get... +Get-PSSessionConfiguration Cmdlet Microsoft.PowerShell.Core Get... +New-PSSessionOption Cmdlet Microsoft.PowerShell.Core Cre... +New-PSTransportOption Cmdlet Microsoft.PowerShell.Core Cre... +Out-Host Cmdlet Microsoft.PowerShell.Core Sen... +Start-Job Cmdlet Microsoft.PowerShell.Core Sta... +Where-Object Cmdlet Microsoft.PowerShell.Core Sel... +Debug-Process Cmdlet Microsoft.PowerShell.M... Deb... +Get-Process Cmdlet Microsoft.PowerShell.M... Get... +Get-WmiObject Cmdlet Microsoft.PowerShell.M... Get... +Start-Process Cmdlet Microsoft.PowerShell.M... Sta... +Stop-Process Cmdlet Microsoft.PowerShell.M... Sto... +Wait-Process Cmdlet Microsoft.PowerShell.M... Wai... +Clear-Variable Cmdlet Microsoft.PowerShell.U... Del... +Convert-String Cmdlet Microsoft.PowerShell.U... For... +ConvertFrom-Csv Cmdlet Microsoft.PowerShell.U... Con... +ConvertFrom-Json Cmdlet Microsoft.PowerShell.U... Con... +ConvertTo-Html Cmdlet Microsoft.PowerShell.U... Con... +ConvertTo-Xml Cmdlet Microsoft.PowerShell.U... Cre... +Debug-Runspace Cmdlet Microsoft.PowerShell.U... Sta... +Export-Csv Cmdlet Microsoft.PowerShell.U... Con... +Export-FormatData Cmdlet Microsoft.PowerShell.U... Sav... +Format-List Cmdlet Microsoft.PowerShell.U... For... +Format-Table Cmdlet Microsoft.PowerShell.U... For... +Get-Unique Cmdlet Microsoft.PowerShell.U... Ret... +Group-Object Cmdlet Microsoft.PowerShell.U... Gro... +Import-Clixml Cmdlet Microsoft.PowerShell.U... Imp... +Import-Csv Cmdlet Microsoft.PowerShell.U... Cre... +Measure-Object Cmdlet Microsoft.PowerShell.U... Cal... +Out-File Cmdlet Microsoft.PowerShell.U... Sen... +Out-GridView Cmdlet Microsoft.PowerShell.U... Sen... +Select-Object Cmdlet Microsoft.PowerShell.U... Sel... +Set-Variable Cmdlet Microsoft.PowerShell.U... Set... +Sort-Object Cmdlet Microsoft.PowerShell.U... Sor... +Tee-Object Cmdlet Microsoft.PowerShell.U... Sav... +Trace-Command Cmdlet Microsoft.PowerShell.U... Con... +Write-Information Cmdlet Microsoft.PowerShell.U... Spe... +Export-BinaryMiLog Cmdlet CimCmdlets Cre... +Get-CimAssociatedInstance Cmdlet CimCmdlets Ret... +Get-CimInstance Cmdlet CimCmdlets Get... +Import-BinaryMiLog Cmdlet CimCmdlets Use... +Invoke-CimMethod Cmdlet CimCmdlets Inv... +New-CimInstance Cmdlet CimCmdlets Cre... +Remove-CimInstance Cmdlet CimCmdlets Rem... +Set-CimInstance Cmdlet CimCmdlets Mod... +Compress-Archive Function Microsoft.PowerShell.A... Cre... +Get-Counter Cmdlet Microsoft.PowerShell.D... Get... +Invoke-WSManAction Cmdlet Microsoft.WSMan.Manage... Inv... +Remove-WSManInstance Cmdlet Microsoft.WSMan.Manage... Del... +Get-WSManInstance Cmdlet Microsoft.WSMan.Manage... Dis... +New-WSManInstance Cmdlet Microsoft.WSMan.Manage... Cre... +Set-WSManInstance Cmdlet Microsoft.WSMan.Manage... Mod... +about_Arithmetic_Operators HelpFile +about_Arrays HelpFile +about_Environment_Variables HelpFile +about_Execution_Policies HelpFile +about_Functions HelpFile +about_Jobs HelpFile +about_Logging HelpFile +about_Methods HelpFile +about_Objects HelpFile +about_Pipelines HelpFile +about_Preference_Variables HelpFile +about_Remote HelpFile +about_Remote_Jobs HelpFile +about_Session_Configuration_Files HelpFile +about_Simplified_Syntax HelpFile +about_Switch HelpFile +about_Variables HelpFile +about_Variable_Provider HelpFile +about_Windows_Powershell_5.1 HelpFile +about_WQL HelpFile +about_WS-Management_Cmdlets HelpFile +about_Foreach-Parallel HelpFile +about_Parallel HelpFile +about_Sequence HelpFile +``` + +When using the `help` function to search for `process`, it returned 12 results. However, when +searching for `processes`, it produced 78 results. If your search only finds one match, the help +article is displayed instead of listing the results. ```powershell -get-help *hotfix* +help *hotfix* ``` ```Output @@ -430,29 +619,34 @@ NAME Get-HotFix SYNOPSIS - Gets the hotfixes that have been applied to the local and remote computers. + Gets the hotfixes that are installed on local or remote computers. SYNTAX - Get-HotFix [-ComputerName ] [-Credential ] [-Description - ] [] + Get-HotFix [-ComputerName ] [-Credential + ] [-Description + ] [] - Get-HotFix [[-Id] ] [-ComputerName ] [-Credential - ] [] + Get-HotFix [[-Id] ] [-ComputerName ] + [-Credential ] + [] DESCRIPTION - The Get-Hotfix cmdlet gets hotfixes (also called updates) that have been installed - on either the local computer (or on specified remote computers) by Windows Update, - Microsoft Update, or Windows Server Update Services; the cmdlet also gets hotfixes - or updates that have been installed manually by users. + > This cmdlet is only available on the Windows platform. The + `Get-Hotfix` cmdlet uses the Win32_QuickFixEngineering WMI class to + list hotfixes that are installed on the local computer or specified + remote computers. RELATED LINKS - Online Version: http://go.microsoft.com/fwlink/?LinkId=821586 - Win32_QuickFixEngineering http://go.microsoft.com/fwlink/?LinkID=145071 - Get-ComputerRestorePoint + Online Version: https://learn.microsoft.com/powershell/module/microsoft. + powershell.management/get-hotfix?view=powershell-5.1&WT.mc_id=ps-gethelp + about_Arrays Add-Content + Get-ComputerRestorePoint + Get-Credential + Win32_QuickFixEngineering class REMARKS To see the examples, type: "get-help Get-HotFix -examples". @@ -461,12 +655,18 @@ REMARKS For online help, type: "get-help Get-HotFix -online" ``` -Now to debunk the myth that `Help` in PowerShell can only find commands that have help topics. +You can also find commands that lack help articles with `Get-Help`, although this capability isn't +commonly known. The `more` function is one of the commands that doesn't have a help article. To +confirm you can find commands with `Get-Help` that don't include help articles, use the `help` +function to find `more`. ```powershell help *more* ``` +The search only found one match, so it returned the basic syntax information you see when a command +doesn't have a help article. + ```Output NAME more @@ -474,194 +674,290 @@ NAME SYNTAX more [[-paths] ] - ALIASES None - REMARKS None ``` -Notice in the previous example that `more` doesn't have a help topic, yet the `Help` system in -PowerShell was able to find it. It only found one match and returned the basic syntax information -that you'll see when a command doesn't have a help topic. +The PowerShell help system also contains conceptual **About** help articles. You must update the +help content on your system for the **About** help articles to exist. If the initial update of the +help system fails, the **About** help articles aren't available until you run `Update-Help` and it +completes successfully. For more information, see the [Updating help](#updating-help) section of +this chapter. -PowerShell contains numerous conceptual (About) help topics. The following command can be used to -return a list of all **About** help topics on your system. +Use the following command to return a list of all **About** help articles on your system. ```powershell help About_* ``` -Limiting the results to one single About help topic displays the actual help topic instead of -returning a list. +When you limit the results to one **About** help article, the content of the help article is +displayed instead of returning a list of help articles. ```powershell help about_Updatable_Help ``` -The help system in PowerShell has to be updated in order for the **About** help topics to be -present. If for some reason the initial update of the help system failed on your computer, the files -will not be available until the `Update-Help` cmdlet has been run successfully. +## Updating help -## Get-Command +Earlier in this chapter, you updated the PowerShell help articles on your computer the first time +you ran the `Get-Help` cmdlet. You should periodically run the `Update-Help` cmdlet on your computer +to obtain any updates to the help content. `Update-Help` requires internet access by default. + +> [!IMPORTANT] +> When you run `Update-Help` in Windows PowerShell 5.1, it requires running PowerShell elevated as +> an administrator. -`Get-Command` is designed to help you locate commands. Running `Get-Command` without any parameters -returns a list of all the commands on your system. The following example demonstrates using the -`Get-Command` cmdlet to determine what commands exist for working with processes: +In the following example, use the `Update-Help` cmdlet to update the PowerShell help content on your +computer. ```powershell -Get-Command -Noun Process +Update-Help ``` +As shown in the following results, a module returned an error. Errors aren't uncommon and usually +occur when the module's author doesn't configure updatable help correctly. + ```Output -CommandType Name Version Source ------------ ---- ------- ------ -Cmdlet Debug-Process 3.1.0.0 Microsof... -Cmdlet Get-Process 3.1.0.0 Microsof... -Cmdlet Start-Process 3.1.0.0 Microsof... -Cmdlet Stop-Process 3.1.0.0 Microsof... -Cmdlet Wait-Process 3.1.0.0 Microsof... +Update-Help : Failed to update Help for the module(s) 'BitsTransfer' with UI +culture(s) {en-US} : Unable to retrieve the HelpInfo XML file for UI culture +en-US. Make sure the HelpInfoUri property in the module manifest is valid or +check your network connection and then try the command again. +At line:1 char:1 ++ Update-Help ++ ~~~~~~~~~~~ + + CategoryInfo : ResourceUnavailable: (:) [Update-Help], Except + ion + + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShe + ll.Commands.UpdateHelpCommand ``` -Notice in the previous example where `Get-Command` was run, the **Noun** parameter is used and -`Process` is specified as the value for the **Noun** parameter. What if you didn't know how to use -the `Get-Command` cmdlet? You could use `Get-Help` to display the help topic for `Get-Command`. +If your computer doesn't have internet access, use the `Save-Help` cmdlet on a computer with +internet access to download and save the updated help content. Then, use the **SourcePath** +parameter of `Update-Help` to specify the location of the saved updated help content. + +## Get-Command + +`Get-Command` is another multipurpose command that helps you locate commands. You can also use +`Get-Command` to learn how to use commands, but in a different and more indirect way when compared +to `Get-Help`. -The **Name**, **Noun**, and **Verb** parameters accept wildcards. The following example shows -wildcards being used with the **Name** parameter: +How do you determine the syntax for `Get-Command`? You could use `Get-Help` to display the help +article for `Get-Command`, as shown in the [Get-Help](#get-help) section of this chapter. You can +also use `Get-Command` with the **Syntax** parameter to view the syntax for any command. This +shortcut helps you quickly determine how to use a command without navigating through its help +content. ```powershell -Get-Command -Name *service* +Get-Command -Name Get-Command -Syntax ``` +Using `Get-Command` with its **Syntax** parameter offers a more programmatic view by showing the +parameters and their value types, without listing the specific allowable values. + ```Output -CommandType Name Version Source ------------ ---- ------- ------ -Function Get-NetFirewallServiceFilter 2.0.0.0 NetSecurity -Function Set-NetFirewallServiceFilter 2.0.0.0 NetSecurity -Cmdlet Get-Service 3.1.0.0 Microsof... -Cmdlet New-Service 3.1.0.0 Microsof... -Cmdlet New-WebServiceProxy 3.1.0.0 Microsof... -Cmdlet Restart-Service 3.1.0.0 Microsof... -Cmdlet Resume-Service 3.1.0.0 Microsof... -Cmdlet Set-Service 3.1.0.0 Microsof... -Cmdlet Start-Service 3.1.0.0 Microsof... -Cmdlet Stop-Service 3.1.0.0 Microsof... -Cmdlet Suspend-Service 3.1.0.0 Microsof... -Application AgentService.exe 10.0.14... C:\Windo... -Application SensorDataService.exe 10.0.14... C:\Windo... -Application services.exe 10.0.14... C:\Windo... -Application services.msc 0.0.0.0 C:\Windo... -Application TieringEngineService.exe 10.0.14... C:\Windo... -``` - -I'm not a fan of using wildcards with the **Name** parameter of `Get-Command` since it also returns -executable files that are not native PowerShell commands. - -If you are going to use wildcard characters with the **Name** parameter, I recommend limiting the -results with the **CommandType** parameter. +Get-Command [[-ArgumentList] ] [-Verb ] +[-Noun ] [-Module ] +[-FullyQualifiedModule ] [-TotalCount ] +[-Syntax] [-ShowCommandInfo] [-All] [-ListImported] +[-ParameterName ] [-ParameterType ] +[] + +Get-Command [[-Name] ] [[-ArgumentList] ] +[-Module ] [-FullyQualifiedModule ] +[-CommandType ] [-TotalCount ] [-Syntax] +[-ShowCommandInfo] [-All] [-ListImported] [-ParameterName ] +[-ParameterType ] [] +``` -```powershell -Get-Command -Name *service* -CommandType Cmdlet, Function, Alias +If you need more detailed information about how to use a command, revert to using `Get-Help`. + +```powwershell +help Get-Command -Full ``` -A better option is to use either the **Verb** or **Noun** parameter or both of them since only -PowerShell commands have both verbs and nouns. +The **SYNTAX** section of `Get-Help` provides a more user-friendly display by expanding enumerated +values for parameters. It shows you the actual values you can use, making it easier to understand +the available options. -Found something wrong with a help topic? The good news is the help topics for PowerShell have been -open-sourced and available in the [PowerShell-Docs][PowerShell-Docs] repository on GitHub. Pay it forward by not -only fixing the incorrect information for yourself, but everyone else as well. Simply fork the -PowerShell documentation repository on GitHub, update the help topic, and submit a pull request. -Once the pull request is accepted, the corrected documentation is available for everyone. +```Output +... + Get-Command [[-Name] ] [[-ArgumentList] + ] [-All] [-CommandType {Alias | Function | Filter | + Cmdlet | ExternalScript | Application | Script | Workflow | + Configuration | All}] [-FullyQualifiedModule + ] [-ListImported] + [-Module ] [-ParameterName ] + [-ParameterType ] + [-ShowCommandInfo] [-Syntax] [-TotalCount ] + [] + + Get-Command [[-ArgumentList] ] [-All] + [-FullyQualifiedModule + ] [-ListImported] + [-Module ] [-Noun ] [-ParameterName + ] [-ParameterType + ] [-ShowCommandInfo] + [-Syntax] [-TotalCount ] [-Verb ] + [] +... +``` + +The **PARAMETERS** section of the help article for `Get-Command` reveals the **Name**, **Noun**, and +**Verb** parameters accept wildcard characters. -## Updating Help +```Output +... + -Name + Specifies an array of names. This cmdlet gets only commands that + have the specified name. Enter a name or name pattern. Wildcard + characters are permitted. + + To get commands that have the same name, use the All parameter. When + two commands have the same name, by default, `Get-Command` gets the + command that runs when you type the command name. + + Required? false + Position? 0 + Default value None + Accept pipeline input? True (ByPropertyName, ByValue) + Accept wildcard characters? true + + -Noun + Specifies an array of command nouns. This cmdlet gets commands, + which include cmdlets, functions, and aliases, that have names that + include the specified noun. Enter one or more nouns or noun + patterns. Wildcard characters are permitted. + + Required? false + Position? named + Default value None + Accept pipeline input? True (ByPropertyName) + Accept wildcard characters? true + -Verb + Specifies an array of command verbs. This cmdlet gets commands, + which include cmdlets, functions, and aliases, that have names that + include the specified verb. Enter one or more verbs or verb + patterns. Wildcard characters are permitted. + + Required? false + Position? named + Default value None + Accept pipeline input? True (ByPropertyName) + Accept wildcard characters? true +... +``` -The local copy of the PowerShell help topics was previously updated the first-time help on a command -was requested. It's recommended to periodically update the help system because there can be updates -to the help content from time to time. The `Update-Help` cmdlet is used to update the help topics. -It requires internet access by default and for you to be running PowerShell elevated as an -administrator. +In the following example, use `*` wildcard characters with the value for the **Name** parameter of +`Get-Command`. ```powershell -Update-Help +Get-Command -Name *service* ``` +When you use wildcard characters with the **Name** parameter of `Get-Command`, it returns PowerShell +commands and native commands, as shown in the following results. + ```Output -Update-Help : Failed to update Help for the module(s) 'BitsTransfer' with UI culture(s) -{en-US} : Unable to retrieve the HelpInfo XML file for UI culture en-US. Make sure the HelpInfoUri -property in the module manifest is valid or check your network connection and then try the command again. -At line:1 char:1 -+ Update-Help -+ - + CategoryInfo : InvalidOperation: (:) [Update-Help], Exception - + FullyQualifiedErrorId : InvalidHelpInfoUri,Microsoft.PowerShell.Commands.UpdateHel - pCommand - -Update-Help : Failed to update Help for the module(s) 'NetworkControllerDiagnostics, -StorageReplica' with UI culture(s) {en-US} : Unable to retrieve the HelpInfo XML file -for UI culture en-US. Make sure the HelpInfoUri property in the module manifest is valid -or check your network connection and then try the command again. -At line:1 char:1 -+ Update-Help -+ - + CategoryInfo : ResourceUnavailable: (:) [Update-Help], Exception - + FullyQualifiedErrorId : UnableToRetrieveHelpInfoXml,Microsoft.PowerShell.Commands. - UpdateHelpCommand -``` -A couple of the modules returned errors, which is not uncommon. If the machine didn't have internet -access, you could use the `Save-Help` cmdlet on another machine that does have internet access to -first save the updated help information to a file share on your network and then use the -**SourcePath** parameter of `Update-Help` to specify this network location for the help topics. +CommandType Name Version +----------- ---- ------- +Function Get-NetFirewallServiceFilter 2.0.0.0 +Function Set-NetFirewallServiceFilter 2.0.0.0 +Cmdlet Get-Service 3.1.0.0 +Cmdlet New-Service 3.1.0.0 +Cmdlet New-WebServiceProxy 3.1.0.0 +Cmdlet Restart-Service 3.1.0.0 +Cmdlet Resume-Service 3.1.0.0 +Cmdlet Set-Service 3.1.0.0 +Cmdlet Start-Service 3.1.0.0 +Cmdlet Stop-Service 3.1.0.0 +Cmdlet Suspend-Service 3.1.0.0 +Application SecurityHealthService.exe 10.0.2... +Application SensorDataService.exe 10.0.2... +Application services.exe 10.0.2... +Application services.msc 0.0.0.0 +Application TieringEngineService.exe 10.0.2... +Application Windows.WARP.JITService.exe 10.0.2... +``` -Consider setting up a scheduled task or adding some logic to your profile script in PowerShell to -periodically update the help content on your computer. Profile scripts will be discussed in an -upcoming chapter. +If you use wildcard characters with the **Name** parameter of `Get-Command`, consider limiting the +results to PowerShell cmdlets, functions, and aliases with the **CommandType** parameter. -## Summary +```powershell +Get-Command -Name *service* -CommandType Cmdlet, Function, Alias +``` -In this chapter you've learned how to find commands with both `Get-Help` and `Get-Command`. You've -learned how to use the help system to figure out how to use commands once you find them. You've also -learned how to update the content of the help topics when updates are available. +A better option might be to use either the **Verb** or **Noun** parameter or both since only +PowerShell commands have verbs and nouns. -My challenge to you is to learn a PowerShell command a day. +In the following example, use `Get-Command` to determine what commands exist on your computer for +working with processes. Use the **Noun** parameter and specify `Process` as its value. ```powershell -Get-Command | Get-Random | Get-Help -Full +Get-Command -Noun Process ``` +```Output +CommandType Name Version +----------- ---- ------- +Cmdlet Debug-Process 3.1.0.0 +Cmdlet Get-Process 3.1.0.0 +Cmdlet Start-Process 3.1.0.0 +Cmdlet Stop-Process 3.1.0.0 +Cmdlet Wait-Process 3.1.0.0 +``` + +When you run `Get-Command` without any parameters, it returns a list of all the commands on your +system. + +## Contributing to the documentation + +The help content for PowerShell is open source and available in the [PowerShell-Docs][ps-docs] +repository on GitHub. For more information, see +[Contributing to PowerShell documentation][contribute-ps-docs]. + +## Summary + +In this chapter, you learned how to find commands with `Get-Help` and `Get-Command`. You also +learned how to use the help system to figure out how to use commands once you find them. In +addition, you learned how to update the help system on your computer when new help content is +available. + ## Review 1. Is the **DisplayName** parameter of `Get-Service` positional? 1. How many parameter sets does the `Get-Process` cmdlet have? 1. What PowerShell commands exist for working with event logs? -1. What is the PowerShell command for returning a list of PowerShell processes running on your +1. What's the PowerShell command for returning a list of PowerShell processes running on your computer? -1. How do you update the PowerShell help content that's stored on your computer? +1. How do you update the PowerShell help content stored on your computer? + +## References -## Recommended Reading +To learn more about the concepts covered in this chapter, read the following PowerShell help +articles. -If you want to know more information about the topics covered in this chapter, I recommend -reading the following PowerShell help topics. +- [Get-Help][help] +- [Get-Command][gcm] +- [Update-Help][update-help] +- [Save-Help][save-help] +- [about_Updatable_Help][updatable-help] +- [about_Command_Syntax][command-syntax] -- [Get-Help][Get-Help] -- [Get-Command][Get-Command] -- [Update-Help][Update-Help] -- [Save-Help][Save-Help] -- [about_Updatable_Help][about_Updatable_Help] -- [about_Command_Syntax][about_Command_Syntax] +## Next steps -In the next chapter, you'll learn about the `Get-Member` cmdlet as well as objects, properties, and -methods. +In the next chapter, you'll learn about objects, properties, methods, and the `Get-Member` cmdlet. -[Get-Help]: /powershell/module/microsoft.powershell.core/get-help -[Get-Command]: /powershell/module/microsoft.powershell.core/get-command -[Update-Help]: /powershell/module/microsoft.powershell.core/update-help -[Save-Help]: /powershell/module/microsoft.powershell.core/save-help -[about_Updatable_Help]: /powershell/module/microsoft.powershell.core/about/about_updatable_help -[about_Command_Syntax]: /powershell/module/microsoft.powershell.core/about/about_command_syntax -[PowerShell-Docs]: /~https://github.com/MicrosoftDocs/PowerShell-Docs -[Appendix A]: appendix-a.md + +[ps-docs]: /~https://github.com/MicrosoftDocs/PowerShell-Docs +[contribute-ps-docs]: /powershell/scripting/community/contributing/overview +[help]: /powershell/module/microsoft.powershell.core/get-help +[gcm]: /powershell/module/microsoft.powershell.core/get-command +[update-help]: /powershell/module/microsoft.powershell.core/update-help +[save-help]: /powershell/module/microsoft.powershell.core/save-help +[updatable-help]: /powershell/module/microsoft.powershell.core/about/about_updatable_help +[command-syntax]: /powershell/module/microsoft.powershell.core/about/about_command_syntax diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 7c2673c02aa..bbb7b3d24cd 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -50,7 +50,7 @@ items: href: learn/ps101/00-introduction.md - name: Getting started with PowerShell href: learn/ps101/01-getting-started.md - - name: The Help System + - name: The help system href: learn/ps101/02-help-system.md - name: Discovering objects, properties, and methods href: learn/ps101/03-discovering-objects.md From 3161a4c2d3d633a7b8776e7c10fff2085ee2a66e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 27 Jun 2024 10:45:15 -0500 Subject: [PATCH 2/3] Editorial changes --- .../learn/ps101/02-help-system.md | 259 +++++++++--------- reference/docs-conceptual/toc.yml | 2 +- 2 files changed, 123 insertions(+), 138 deletions(-) diff --git a/reference/docs-conceptual/learn/ps101/02-help-system.md b/reference/docs-conceptual/learn/ps101/02-help-system.md index ca852e15803..85db5271b62 100644 --- a/reference/docs-conceptual/learn/ps101/02-help-system.md +++ b/reference/docs-conceptual/learn/ps101/02-help-system.md @@ -1,15 +1,15 @@ --- -description: Becoming proficient with the help system is the key to success with PowerShell +description: Becoming proficient with the Help system is the key to success with PowerShell ms.custom: Contributor-mikefrobbins ms.date: 06/25/2024 ms.reviewer: mirobb -title: The Help System +title: The Help system --- -# Chapter 2 - The help system +# Chapter 2 - The Help system In an experiment designed to assess proficiency in PowerShell, two distinct groups of IT -professionals —beginners and experts— were first given a written examination without access to a +professionals — beginners and experts — were first given a written examination without access to a computer. Surprisingly, the test scores indicated comparable skills across both groups. A subsequent test was then administered, mirroring the first but with one key difference: participants had access to an offline computer equipped with PowerShell. The results revealed a significant skills gap @@ -20,10 +20,10 @@ What factors contributed to the outcomes observed between the two assessments? > Experts don't always know the answers, but they know how to figure out the answers. The outcomes observed in the results of the two tests were because experts don't memorize thousands -of PowerShell commands. Instead, they excel at using the help system within PowerShell, enabling +of PowerShell commands. Instead, they excel at using the Help system within PowerShell, enabling them to discover and learn how to use commands when necessary. -> Becoming proficient with the help system is the key to success with PowerShell. +> Becoming proficient with the Help system is the key to success with PowerShell. I heard Jeffrey Snover, the creator of PowerShell, share a similar story on multiple occasions. @@ -48,7 +48,7 @@ I'm often asked: _"How do you figure out what the commands are in PowerShell?"_. ## Get-Help -The first thing you need to know about the help system in PowerShell is how to use the `Get-Help` +The first thing you need to know about the Help system in PowerShell is how to use the `Get-Help` cmdlet. `Get-Help` is a multipurpose command that helps you learn how to use commands once you find them. @@ -82,9 +82,8 @@ https:/go.microsoft.com/fwlink/?LinkId=210614. [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): ``` -You only receive this message if you run PowerShell elevated as an administrator. You also don't -receive it if you're using the `help` function or `man` alias. If you don't receive this message, -run `Update-Help` from an elevated PowerShell session running as an administrator. +If you don't receive this message, run `Update-Help` from an elevated PowerShell session running as +an administrator. Once the update is complete, the help article is displayed. @@ -180,17 +179,17 @@ Each of the following parameters belongs to a different parameter set for the `G - Parameter - ShowWindow -### The help syntax +### The command syntax -If you're new to PowerShell, comprehending the cryptic help syntax —characterized by square and -angle brackets— in the **SYNTAX** section of the help articles might seem overwhelming. However, -learning these syntax elements is essential to becoming proficient with PowerShell. The more -frequently you use the PowerShell help system, the easier it becomes to remember all the nuances. +If you're new to PowerShell, comprehending the cryptic information — characterized by square and +angle brackets — in the **SYNTAX** section might seem overwhelming. However, learning these syntax +elements is essential to becoming proficient with PowerShell. The more frequently you use the +PowerShell Help system, the easier it becomes to remember all the nuances. -View the syntax section of the help article for the `Get-EventLog` cmdlet. +View the syntax of the `Get-EventLog` cmdlet. ```powershell -help Get-EventLog +Get-Help Get-EventLog ``` The following output shows the relevant portion of the help article. @@ -211,59 +210,61 @@ SYNTAX ... ``` -The help syntax in the **SYNTAX** section of PowerShell help articles includes pairs of square -brackets `([ ])`. Depending on their usage, these square brackets serve two different purposes. +The syntax information includes pairs of square brackets (`[]`). Depending on their usage, these +square brackets serve two different purposes. -- Elements enclosed within square brackets are optional. -- When an empty set of square brackets follows a datatype, such as ``, it indicates the - parameter can accept multiple values as an array or a comma-separated list. +- Elements enclosed in square brackets are optional. +- An empty set of square brackets following a datatype, such as ``, indicates that the + parameter can accept multiple values passed as an array or a collection object. ### Positional parameters -When developers create a PowerShell cmdlet or function, they can optionally designate one or more -parameters as positional. Positional parameters allow you to provide a value without specifying the -parameter's name. When using a parameter positionally, you must specify its value in the correct -position. You can find the positional information for a parameter in the **PARAMETERS** section of a -command's help article. When you explicitly specify parameter names, their order is irrelevant. +Some cmdlets are designed to accept positional parameters. Positional parameters allow you to +provide a value without specifying the name of the parameter. When using a parameter positionally, +you must specify its value in the correct position on the command line. You can find the positional +information for a parameter in the **PARAMETERS** section of a command's help article. When you +explicitly specify parameter names, you can use the parameters in any order. For the `Get-EventLog` cmdlet, the first parameter in the first parameter set is **LogName**. **LogName** is enclosed in square brackets, indicating it's a positional parameter. +```Syntax +Get-EventLog [-LogName] +``` + Since **LogName** is a positional parameter, you can specify it by either name or position. According to the angle brackets following the parameter name, the value for **LogName** must be a single string. The absence of square brackets enclosing both the parameter name and datatype indicates that **LogName** is a required parameter within this particular parameter set. -```powershell -Get-EventLog [-LogName] -``` - The second parameter in that parameter set is **InstanceId**. Both the parameter name and datatype are entirely enclosed in square brackets, signifying that **InstanceId** is an optional parameter. -Furthermore, **InstanceId** has its own pair of square brackets, indicating that it's a positional -parameter similar to the **LogName** parameter. Following the datatype, an empty set of square -brackets implies that **InstanceId** can accept multiple values. -```powershell +```Syntax [[-InstanceId] ] ``` +Furthermore, **InstanceId** has its own pair of square brackets, indicating that it's a positional +parameter similar to the **LogName** parameter. Following the datatype, an empty set of square +brackets implies that **InstanceId** can accept multiple values. + ### Switch parameters A parameter that doesn't require a value is called a switch parameter. You can easily identify -switch parameters because a datatype doesn't follow their parameter names. When you specify a switch -parameter, its value is `true`; when you don't specify a switch parameter, its value is `false`. +switch parameters because there's no datatype following the parameter name. When you specify a +switch parameter, its value is `true`. When you don't specify a switch parameter, its value is +`false`. The second parameter set includes a **List** parameter, which is a switch parameter. When you specify the **List** parameter, it returns a list of event logs on the local computer. -```powershell +```Syntax [-List] ``` ### A simplified approach to syntax -There's a more user-friendly method to obtain the same information as the cryptic help syntax for +There's a more user-friendly method to obtain the same information as the cryptic command syntax for some commands, except in plain English. PowerShell returns the complete help article when using `Get-Help` with the **Full** parameter, making it easier to understand a command's usage. @@ -285,8 +286,8 @@ system organizes the information. - EXAMPLES - RELATED LINKS -By specifying the **Full** parameter with the `Get-Help` cmdlet, notice the output includes several -extra sections. Among these sections, **PARAMETERS** often provides a detailed explanation for each +By specifying the **Full** parameter with the `Get-Help` cmdlet, the output includes several extra +sections. Among these sections, **PARAMETERS** often provides a detailed explanation for each parameter. However, the extent of this information varies depending on the specific command you're investigating. @@ -332,19 +333,16 @@ investigating. ... ``` -When you ran the previous command to display the help article for `Get-Help`, you probably noticed -the output scrolled by too quickly to read it. +When you ran the previous command to display the help for the `Get-Help` command, you probably +noticed the output scrolled by too quickly to read it. If you're using the PowerShell console, Windows Terminal, or VS Code and need to view a help -article, the `help` function can be useful. It pipes `Get-Help` to `more.com`, displaying one page -of help content at a time. As for the ISE, running `help` works the same way as `Get-Help`. I -recommend using the `help` function instead of the `Get-Help` cmdlet because it provides a better -user experience and it's less to type. +article, the `help` function can be useful. It pipes the output of `Get-Help` to `more.com`, +displaying one page of help content at a time. I recommend using the `help` function instead of the +`Get-Help` cmdlet because it provides a better user experience and it's less to type. -While typing less might seem beneficial, it's not always the best practice or intuitive when saving -commands in a script or sharing code with others. Using full cmdlet and parameter names offers the -benefit of self-documenting, making the code more easily interpreted and understandable for anyone -who reviews it. +> [!NOTE] +> The ISE doesn't support using `more.com`, so running `help` works the same way as `Get-Help`. Run each of the following commands in PowerShell on your computer. @@ -356,29 +354,29 @@ help Get-Help -Full Did you observe any variations in the output when you ran the previous commands? -The only difference is the last two commands display their output one page at a time. When using the -`help` function, press the _Spacebar_ to navigate to the next page of content or `Q` to quit. If you -need to terminate any command running interactively in PowerShell, press -Ctrl+C. - In the previous example, the first line uses the `Get-Help` cmdlet, the second uses the `help` function, and the third line omits the **Name** parameter while using the `help` function. Since -**Name** is a positional parameter, the third example takes advantage of its placement instead of +**Name** is a positional parameter, the third example takes advantage of its position instead of explicitly stating the parameter's name. -To quickly find information about a specific parameter, use the `help` function with the -**Parameter** parameter. This approach is more concise, containing only the parameter-specific help -content instead of manually scanning the entire help article for details about a parameter. +The difference is that the last two commands display their output one page at a time. When using the +`help` function, press the Spacebar to display to the next page of content or +Q to quit. If you need to terminate any command running interactively in PowerShell, +press Ctrl+C. + +To quickly find information about a specific parameter, use the **Parameter** parameter. This +approach returns content containing only the parameter-specific information, rather than the entire +help article. This is the easiest way to find information about a specific parameter. -In the following example, use the `help` function with the **Parameter** parameter to return +The following example uses the `help` function with the **Parameter** parameter to return information from the help article for the **Name** parameter of `Get-Help`. ```powershell help Get-Help -Parameter Name ``` -Based on the following results, the **Name** parameter is positional and must be specified in -position zero when used positionally. +The help information shows that the **Name** parameter is positional and must be specified in the +first position (position zero) when used positionally. ```Output -Name @@ -413,12 +411,11 @@ position zero when used positionally. Accept wildcard characters? true ``` -The **Name** parameter expects the datatype for its value to be a single string as identified by -`` next to the parameter name. +The **Name** parameter expects a string value as identified by the `` datatype next to the +parameter name. -There are several other parameters besides **Parameter** that you can specify with `Get-Help` to -return a subset of a help article. To see how they work, run the following commands on your -computer. +There are several other parameters you can specify with `Get-Help` to return a subset of a help +article. To see how they work, run the following commands on your computer. ```powershell Get-Help -Name Get-Command -Full @@ -430,19 +427,21 @@ Get-Help -Name Get-Command -ShowWindow ``` I typically use `help ` with the **Full** or **Online** parameter. If you only have an -interest in the examples, use the **Examples** parameter; if you only have an interest in a specific +interest in the examples, use the **Examples** parameter. If you only have an interest in a specific parameter, use the **Parameter** parameter. -When the **ShowWindow** parameter is used, it opens the help article in a separate searchable window -that can be placed on a different monitor if you have multiple monitors. However, the **ShowWindow** -parameter has a known bug that might prevent it from displaying the entire help article. The -**ShowWindow** parameter also requires an operating system with a Graphical User Interface (GUI). It -returns an error if you attempt to use it on Windows Server installed with the server core -installation option. +When you use the **ShowWindow** parameter, it displays the help content in a separate searchable +window. You can move that window to a different monitor if you have multiple monitors. However, the +**ShowWindow** parameter has a known bug that might prevent it from displaying the entire help +article. The **ShowWindow** parameter also requires an operating system with a Graphical User +Interface (GUI). It returns an error when you attempt to use it on Windows Server Core. -If you want the help article in a separate window and have internet access, use the **Online** -parameter instead. The **Online** parameter opens the help article with the most up-to-date content -in your default web browser, allowing you to search it and navigate to other help articles. +If you have internet access, you can use the **Online** parameter instead. The **Online** parameter +opens the help article in your default web browser. The online content is the most up-to-date +content. The browser allows you to search the help content and view other, related help articles. + +> [!NOTE] +> The **Online** parameter isn't supported for **About** articles. ```powershell help Get-Command -Online @@ -475,20 +474,17 @@ Get-ProcessMitigation Cmdlet ProcessMitigations Get... Set-ProcessMitigation Cmdlet ProcessMitigations Set... ``` -In this scenario, you aren't required to add the `*` wildcard characters. When you omit the wildcard -characters, `Get-Help` automatically adds them behind the scenes. The following example produces the -same results as specifying the `*` wildcard character on each end of `process`. +In this scenario, you aren't required to add the `*` wildcard characters. If `Get-Help` can't find a +command matching the value you provided, it does a full-text search for that value. The following +example produces the same results as specifying the `*` wildcard character on each end of `process`. ```powershell help process ``` -However, you should always add them since that option works consistently. Otherwise, it requires you -to add them in certain scenarios and not in others. When you specify a wildcard character within the -value, they aren't appended automatically behind the scenes. - -The following command doesn't return any results unless you add a `*` wildcard character to the -beginning, end, or both the beginning and end of `pr*cess`. +When you specify a wildcard character within the value, `Get-Help` only searches for commands that +match the pattern you provided. It doesn't perform a full-text search. The following command doesn't +return any results. ```powershell help pr*cess @@ -513,10 +509,10 @@ When you search for PowerShell commands with `Get-Help`, it's better to be vague specific. When you searched for `process` earlier, the results only returned commands that included `process` -in their name. But if you use `help` to search for `processes`, it doesn't find any matches for -command names. As previously stated, when help doesn't find any matches, it performs a comprehensive -full-text search of every help article on your system and returns those results. This type of search -often produces more results than expected, probably without the information you're trying to locate. +in their name. But if you search for `processes`, it doesn't find any matches for command names. As +previously stated, when help doesn't find any matches, it performs a comprehensive full-text search +of every help article on your system and returns those results. This type of search often produces +more results than expected, including information not relevant to you. ```powershell help processes @@ -606,9 +602,9 @@ about_Parallel HelpFile about_Sequence HelpFile ``` -When using the `help` function to search for `process`, it returned 12 results. However, when -searching for `processes`, it produced 78 results. If your search only finds one match, the help -article is displayed instead of listing the results. +When you searched for `process`, it returned 12 results. However, when searching for `processes`, it +produced 78 results. If your search only finds one match, `Get-Help` displays the help content +instead of listing the search results. ```powershell help *hotfix* @@ -657,7 +653,7 @@ REMARKS You can also find commands that lack help articles with `Get-Help`, although this capability isn't commonly known. The `more` function is one of the commands that doesn't have a help article. To -confirm you can find commands with `Get-Help` that don't include help articles, use the `help` +confirm that you can find commands with `Get-Help` that don't include help articles, use the `help` function to find `more`. ```powershell @@ -682,10 +678,8 @@ REMARKS ``` The PowerShell help system also contains conceptual **About** help articles. You must update the -help content on your system for the **About** help articles to exist. If the initial update of the -help system fails, the **About** help articles aren't available until you run `Update-Help` and it -completes successfully. For more information, see the [Updating help](#updating-help) section of -this chapter. +help content on your system to get the **About** articles. For more information, see the +[Updating help](#updating-help) section of this chapter. Use the following command to return a list of all **About** help articles on your system. @@ -693,8 +687,8 @@ Use the following command to return a list of all **About** help articles on you help About_* ``` -When you limit the results to one **About** help article, the content of the help article is -displayed instead of returning a list of help articles. +When you limit the results to one **About** help article, `Get-Help` displays the content that +article. ```powershell help about_Updatable_Help @@ -704,17 +698,18 @@ help about_Updatable_Help Earlier in this chapter, you updated the PowerShell help articles on your computer the first time you ran the `Get-Help` cmdlet. You should periodically run the `Update-Help` cmdlet on your computer -to obtain any updates to the help content. `Update-Help` requires internet access by default. +to obtain any updates to the help content. > [!IMPORTANT] -> When you run `Update-Help` in Windows PowerShell 5.1, it requires running PowerShell elevated as -> an administrator. +> In Windows PowerShell 5.1, you must run `Update-Help` as an administrator in an elevated +> PowerShell session. -In the following example, use the `Update-Help` cmdlet to update the PowerShell help content on your -computer. +In the following example, `Update-Help` downloads the PowerShell help content for all modules +installed on your computer. You should use the **Force** parameter to ensure that you download the +latest version the help content. ```powershell -Update-Help +Update-Help -Force ``` As shown in the following results, a module returned an error. Errors aren't uncommon and usually @@ -734,15 +729,16 @@ At line:1 char:1 ll.Commands.UpdateHelpCommand ``` -If your computer doesn't have internet access, use the `Save-Help` cmdlet on a computer with -internet access to download and save the updated help content. Then, use the **SourcePath** -parameter of `Update-Help` to specify the location of the saved updated help content. +`Update-Help` requires internet access to download the help content. If your computer doesn't have +internet access, use the `Save-Help` cmdlet on a computer with internet access to download and save +the updated help content. Then, use the **SourcePath** parameter of `Update-Help` to specify the +location of the saved updated help content. ## Get-Command -`Get-Command` is another multipurpose command that helps you locate commands. You can also use -`Get-Command` to learn how to use commands, but in a different and more indirect way when compared -to `Get-Help`. +`Get-Command` is another multipurpose command that helps you find commands. When you run +`Get-Command` without any parameters, it returns a list of all PowerShell commands on your system. +You can also use `Get-Command` to get command syntax similar to `Get-Help`. How do you determine the syntax for `Get-Command`? You could use `Get-Help` to display the help article for `Get-Command`, as shown in the [Get-Help](#get-help) section of this chapter. You can @@ -754,8 +750,9 @@ content. Get-Command -Name Get-Command -Syntax ``` -Using `Get-Command` with its **Syntax** parameter offers a more programmatic view by showing the -parameters and their value types, without listing the specific allowable values. +Using `Get-Command` with the **Syntax** parameter provides a more concise view of the syntax that +shows the parameters and their value types, without listing the specific allowable values like +`Get-Help` shows. ```Output Get-Command [[-ArgumentList] ] [-Verb ] @@ -772,9 +769,9 @@ Get-Command [[-Name] ] [[-ArgumentList] ] [-ParameterType ] [] ``` -If you need more detailed information about how to use a command, revert to using `Get-Help`. +If you need more detailed information about how to use a command, use `Get-Help`. -```powwershell +```powershell help Get-Command -Full ``` @@ -805,7 +802,7 @@ the available options. ... ``` -The **PARAMETERS** section of the help article for `Get-Command` reveals the **Name**, **Noun**, and +The **PARAMETERS** section of the help for `Get-Command` reveals that the **Name**, **Noun**, and **Verb** parameters accept wildcard characters. ```Output @@ -850,7 +847,7 @@ The **PARAMETERS** section of the help article for `Get-Command` reveals the **N ... ``` -In the following example, use `*` wildcard characters with the value for the **Name** parameter of +The following example uses the `*` wildcard character with the value for the **Name** parameter of `Get-Command`. ```powershell @@ -883,18 +880,17 @@ Application TieringEngineService.exe 10.0.2... Application Windows.WARP.JITService.exe 10.0.2... ``` -If you use wildcard characters with the **Name** parameter of `Get-Command`, consider limiting the -results to PowerShell cmdlets, functions, and aliases with the **CommandType** parameter. +You can limit the results `Get-Command` to PowerShell commands using the **CommandType** parameter. ```powershell -Get-Command -Name *service* -CommandType Cmdlet, Function, Alias +Get-Command -Name *service* -CommandType Cmdlet, Function, Alias, Script ``` -A better option might be to use either the **Verb** or **Noun** parameter or both since only +Another option might be to use either the **Verb** or **Noun** parameter or both since only PowerShell commands have verbs and nouns. -In the following example, use `Get-Command` to determine what commands exist on your computer for -working with processes. Use the **Noun** parameter and specify `Process` as its value. +The following example uses `Get-Command` to find commands on your computer that work with processes. +Use the **Noun** parameter and specify `Process` as its value. ```powershell Get-Command -Noun Process @@ -910,19 +906,10 @@ Cmdlet Stop-Process 3.1.0.0 Cmdlet Wait-Process 3.1.0.0 ``` -When you run `Get-Command` without any parameters, it returns a list of all the commands on your -system. - -## Contributing to the documentation - -The help content for PowerShell is open source and available in the [PowerShell-Docs][ps-docs] -repository on GitHub. For more information, see -[Contributing to PowerShell documentation][contribute-ps-docs]. - ## Summary In this chapter, you learned how to find commands with `Get-Help` and `Get-Command`. You also -learned how to use the help system to figure out how to use commands once you find them. In +learned how to use the help system to understand how to use commands once you find them. In addition, you learned how to update the help system on your computer when new help content is available. @@ -953,8 +940,6 @@ In the next chapter, you'll learn about objects, properties, methods, and the `G -[ps-docs]: /~https://github.com/MicrosoftDocs/PowerShell-Docs -[contribute-ps-docs]: /powershell/scripting/community/contributing/overview [help]: /powershell/module/microsoft.powershell.core/get-help [gcm]: /powershell/module/microsoft.powershell.core/get-command [update-help]: /powershell/module/microsoft.powershell.core/update-help diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index bbb7b3d24cd..6b337f7e621 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -50,7 +50,7 @@ items: href: learn/ps101/00-introduction.md - name: Getting started with PowerShell href: learn/ps101/01-getting-started.md - - name: The help system + - name: The Help system href: learn/ps101/02-help-system.md - name: Discovering objects, properties, and methods href: learn/ps101/03-discovering-objects.md From 740cb5b48b34d2087f376d7b46ecb3fc63138b2e Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" Date: Thu, 27 Jun 2024 15:00:14 -0500 Subject: [PATCH 3/3] Wordsmithing and updated based on peer review --- .../learn/ps101/02-help-system.md | 26 +++++++++++-------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/reference/docs-conceptual/learn/ps101/02-help-system.md b/reference/docs-conceptual/learn/ps101/02-help-system.md index 85db5271b62..866ba48e973 100644 --- a/reference/docs-conceptual/learn/ps101/02-help-system.md +++ b/reference/docs-conceptual/learn/ps101/02-help-system.md @@ -32,10 +32,13 @@ I heard Jeffrey Snover, the creator of PowerShell, share a similar story on mult Compiled commands in PowerShell are known as cmdlets, pronounced as _"command-let"_, not _"CMD-let"_. The naming convention for cmdlets follows a singular **Verb-Noun** format to make them easily discoverable. For instance, `Get-Process` is the cmdlet to determine what processes are -running, and `Get-Service` is the cmdlet to retrieve a list of services. Other types of commands in -PowerShell, such as aliases and functions, are discussed later in this book. The term _"PowerShell -command"_ describes any command in PowerShell, regardless of whether it's a cmdlet, function, or -alias. +running, and `Get-Service` is the cmdlet to retrieve a list of services. Functions, also known as +script cmdlets, and aliases are other types of PowerShell commands that are discussed later in this +book. The term _"PowerShell command"_ describes any command in PowerShell, regardless of whether +it's a cmdlet, function, or alias. + +You can also run operating system native commands from PowerShell, such as traditional command-line +programs like `ping.exe` and `ipconfig.exe`. ## The three core cmdlets in PowerShell @@ -360,9 +363,9 @@ function, and the third line omits the **Name** parameter while using the `help` explicitly stating the parameter's name. The difference is that the last two commands display their output one page at a time. When using the -`help` function, press the Spacebar to display to the next page of content or -Q to quit. If you need to terminate any command running interactively in PowerShell, -press Ctrl+C. +`help` function, press the Spacebar to display the next page of content or Q +to quit. If you need to terminate any command running interactively in PowerShell, press +Ctrl+C. To quickly find information about a specific parameter, use the **Parameter** parameter. This approach returns content containing only the parameter-specific information, rather than the entire @@ -438,7 +441,7 @@ Interface (GUI). It returns an error when you attempt to use it on Windows Serve If you have internet access, you can use the **Online** parameter instead. The **Online** parameter opens the help article in your default web browser. The online content is the most up-to-date -content. The browser allows you to search the help content and view other, related help articles. +content. The browser allows you to search the help content and view other related help articles. > [!NOTE] > The **Online** parameter isn't supported for **About** articles. @@ -687,7 +690,7 @@ Use the following command to return a list of all **About** help articles on you help About_* ``` -When you limit the results to one **About** help article, `Get-Help` displays the content that +When you limit the results to one **About** help article, `Get-Help` displays the content of that article. ```powershell @@ -706,7 +709,7 @@ to obtain any updates to the help content. In the following example, `Update-Help` downloads the PowerShell help content for all modules installed on your computer. You should use the **Force** parameter to ensure that you download the -latest version the help content. +latest version of the help content. ```powershell Update-Help -Force @@ -880,7 +883,8 @@ Application TieringEngineService.exe 10.0.2... Application Windows.WARP.JITService.exe 10.0.2... ``` -You can limit the results `Get-Command` to PowerShell commands using the **CommandType** parameter. +You can limit the results of `Get-Command` to PowerShell commands using the **CommandType** +parameter. ```powershell Get-Command -Name *service* -CommandType Cmdlet, Function, Alias, Script