Powershell to the people
Commenting and modules — Part 2
Please share this tutorial, that inspires me to continue doing this tutorial series.
Previous parts
You read part 1, and that is great, that means that you are interested in Powershell and would like to continue learning. There are a few things that are that you need to know when you are developing, so let’s get to this.
Commenting
When you are developing, it is good to have comments in the script, that would help you in the future to understand the script and also help others who read the script. It is pretty awkward when you created a script, and you did not write any comment, and you are trying to explain the script to someone and you can’t because you don’t know what is happening, so you have to spend the time to reread the code and try to understand this. Believe me that this is more common than you think. Comments are just like documenting the script; the person who is reading the script is like reading a book. So how do you comment, well it is important to know that even if you are commenting the code that you should have some structure for the comments and of course that you should also have some structure for the code and it is important to keep in mind that when you comment that you are not commenting something that is self explanatory, such as if you had a variable named my age, that is really self explanatory and should not necessary be commented. Below is an example of how to comment in Powershell.
# This is a comment and is marked with this hash character in front<#
This is a multiline comment block
Here is the second line in the comment block
#>
The structure of the commenting should have some specific details. To begin with, on top of the document, it should contain some accurate information, such as what is the minimum Powershell version required. As seen in the code block below, it would help the reader to know what the Powershell version is needed to run this script.
# REQUIRES -Version 6.4Next, it would be good to have some necessary details of the script, such as examples, etc. You should set the comment into a comment block, as seen in the case below.
<#
.SYNOPSIS
Some very short information about the script, like small intro.
.DESCRIPTION
More detailed information about the script
.NOTES
Author : Gisli
File Name : myfirstapp.ps1
Licensing Notes : What kind of licensing is used
.OTHER
GIT : repo for the git
.EXAMPLE1
Have some example on how the script is used
#>If you are creating functions in the script, it would be good to have some comments on the function. In future parts, I will explain better what functions are, but in simple terms, it is something you create to do one thing, and you can call it as often as you like. Anyhow, as seen in the code block below, this function prints out some text. But keep in mind that the comment is what we are trying to learn.
<#
The function takes in a parameter and displays it into console.
#>
function Set-MyAge($yourage){
write-host "Your age is $yourage years old"
}# This runs the function, and we can call this function as often as # we like
Set-MyAge -yourage 42
Set-MyAge -yourage 43
As you can see in the code block above, this commenting helps one to understand the code, this is not the best example, but in the sense that you are just beginning to learn Powershell, this should be enough for you for now.
Powershell scripts and modules
There is, in fact, two commonly known types of file extensions that Powershell supports and are Powershell scripts that end with the file extension .ps1 and Powershell modules that end with the file extension .psm1.
Powershell scripts, as was explained in the first part, a collection of actions to do some specific tasks.
Powershell modules are the same but cannot be run in the sense like Powershell scripts but are used to import into Powershell scripts. Parts of the module are used to extend the scripts. This helps the script to be more modular, and you can split the script into multiple files and even reuse specific modules in other projects.
There are modules that you can create and also the operating systems, services and software modules that are already imported and can be imported when you need those specific modules. For example, the modules that are included in the operating system do not be imported manually but are included by default when starting Powershell. These modules are commonly called cmdlets. In the code block below you can get all cmdlets available in the operating system.
# With this command you cent all the modules that are available
Get-Command -ListImported
These cmdlets can be used to do different things such as if you know what the command prompt line “dir” does then you have another cmdlet in Powershell named “Get-Item”. In future parts, I will do a more in-depth how-to for psm1 modules.
Filtering
It is very hard to use Powershell without having filtering. Powershell is based on a pipe and filter framework where you pipe data from one point to another as seen in the screenshot.