DAY-2 : PowerShell Help and Parameter Set

                                                                                                 Author - Ankit Sharma

Exploring PowerShell Help Files

We work in an industry that doesn’t place a lot of emphasis on reading. Most of the administrators tend to dive right in, relying on things like tooltips, context menus, inbuild instruction, and so forth those GUI discoverability tools—to figure out how to do something. But let’s be clear about one thing:

If you aren’t willing to read PowerShell’s help files, you won’t be effective with it. 

Updating PowerShell Help

On regular basis, Microsoft keeps updating the help files for PowerShell on the internet. By Running a simple command we can update the Help files on our system. Updating help files should be your first task. These files are stored in the System32 directory, which means your shell must be running under elevated privileges

Demo video: How to Update Help Files 

USING POWERSHELL HELP SYSTEM

PoweShell provides us with the cmdlet( in PowerShell one line commands are called as cmdlets ), Get-Help, that access the help system. The help system has two main goals: to help you find commands to perform specific tasks and to help you learn how to use those commands once you have found them.

Like most commands, Get-Help has several parameters. One of those perhaps the most important one is -Name. This specifies the name of the help topic you’d like to access and it is positional parameter so you don’t have to type –Name. It also accepts wildcards which make the help system useful for discovering commands. For example, suppose you want to do something with services. You don’t know what command might be available, and you decided to search for help topics that cover service. You need to run below-listed commands- 

Get-Help –Name *service*

You can also use wildcards—mainly the * wildcard, which stand in for zero or more characters—with help. If PowerShell only finds one match to whatever you’ve typed, it won’t display a list of topics with that one item. Instead, it’ll display the contents of that item.

In below video, I have shown how to run Help command for listing related commands and how to use the help.

PowerShell Parameters

Run the below-mentioned command in console

Get-help get-service

In the syntax column, you will see 3 different syntaxes are given for one single cmdlets. It means that we can run this command with 3 different ways using different parameter sets. For each cmdlet, the number of syntaxes is different.

SYNTAX

Get-Service [[-Name] <String[]>] [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-RequiredServices] [<CommonParameters>]

Get-Service [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-RequiredServices] -DisplayName <String[]> [<CommonParameters>]

Get-Service [-ComputerName <String[]>] [-DependentServices] [-Exclude <String[]>] [-Include <String[]>] [-InputObject <ServiceController[]>] [-RequiredServices] [<CommonParameters>]

You might have noticed that the parameters in above syntaxes have enclosed in brackets but in different styles. 

Parameters Values

Help file gives you clue about what kind of input each parameter accept.

[[-Name] <String[]>] 

This simply means that the value accepted by the -Name parameter is String type. You cannot pass an integer value to this parameter. 

Some common types of input:

1. String - A series of Letters and numbers. But remember, the numbers in the string will be considered as a string, not an integer.

2. int, int32, or int64 - An integer number.

3. DateTime - A string that can be interpreted as a date based on your computer's regional settings.

Now we will discuss, types of parameters we have in Powershell.

1. Optional and Mandatory Parameters - You don't need every single parameter in order to make a cmdlet run. Parameters completely enclosed in square brackets are optional, means we don't have to use it at all. Mandatory parameters are those for which we have to provide the value before executing the cmdlet. Take a look at the help for the Get-Eventlog, and you'll see that the -Logname parameter is mandatory, as the parameter isn't enclosed in square brackets. Try running Get-Eventlog without specifying a logName.

     [[-Name] <String[]>]                   Optional parameter

    -DisplayName <String[]>            Mandatory parameter

2. Positional Parameters - For few parameters, you can provide the value without typing the parameter's name, provide you type the value at the correct place. There are 2 ways to identify positional parameters: via syntax or through the full help. 

The parameter name-only the name will be surrounded by the square brackets for positional parameters in syntax. For example, look at the first 2 parameters set of Get-EventLog:

Get-EventLog [-LogName] <String> [[-InstanceId] <Int64[]>]

You will see both the parameters names are enclosed in square brackets. Here you can also see, that the -LogName parameter as a whole ( [-LogName] <String> ) is not enclosed in square brackets, this makes it a Mandatory as well as a positional parameter.

3. Switch Parameters - Some parameters, referred to as switches, don't require any input value at all.

    Get-EventLog [-AsString] [-ComputerName <String[]>] [-List] [<CommonParameters>]

As you can see for -AsString parameter, a value type is not defined. It means that this parameter doesn't require any value to pass to the cmdlet. 

4. Common Parameters - You'll notice that every parameter set for every PowerShell cmdlet ends with [<CommonParameters>].

  Get-EventLog [-AsString] [-ComputerName <String[]>] [-List] [<CommonParameters>]

This refers to a set of eight default parameters that are available on every single cmdlet. We will discuss more on this topic in our upcoming blogs.

5. Multiple-Valued Parameters - Parameters that can accept more than one value in a single cmdlet. In syntax, you'll notice that some values that have more square brackets:

[-ComputerName <String[]>] - This bracket after the value type ( string ) indicates that the parameter can accept multiple values (array), a collection or a list of strings.

Eg. Get-Eventlog -LogName System -Computername server1,server2

In my next blog, we will be covering below listed topics:

1. Running Commands
2. Alias
3.Dealing with Errors