Easy as can be. It’s not a rocket science to create your first PowerShell command in and save it as a module. Maybe your colleagues will get big eyes when you present them your own solution in form of a function and PowerShell Module. And it’s only the beginning of your PowerShell journey. Let’s do it.

What is a Function?

The official statement is:

A function is a list of Windows PowerShell statements that has a name that you assign. When you run a function, you type the function name. The statements in the list run as if you had typed them at the command prompt.

https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-5.1

I would say: Within a function you can place codes, statements, parameters and so on … This function has a name. And this name is used to start your function.

Here’s an example that can be found in the Microsoft Docs:

function Get-PowerShellProcess {Get-Process PowerShell}

After running the function a new command is available: Get-PowerShellProcess. And this command runs Get-Process PowerShell. Fantastic!

In this article we are going to create a funtion and then we’ll save this function as a PowerShell Module. First, let’s do a quick overview what a module is.

What is a PowerShell Module?

A module is a set of related Windows PowerShell functionalities, grouped together as a convenient unit (usually saved in a single directory). By defining a set of related script files, assemblies, and related resources as a module, you can reference, load, persist, and share your code much easier than you would otherwise.

https://msdn.microsoft.com/en-us/library/dd878324(v=vs.85).aspx

This means we can load a set of commands into our PowerShell Session. In older Versions of PowerShell you have to manually load modules into your session in order to use the commands of this module. For example – long time ago – you had to import the Module Active Directory to use Active Directory PowerShell commands.

When you run it in Verbose Mode PowerShell presents you all imported commands:

Import-Module ActiveDirectory -Verbose

Here’s another example. I have to explain this one in more detail. The goal is to test the reachability of the Default Gateway by using the command Test-Gateway. On the local compuer and on remote hosts. The difference to the first example is that I’m now using Parameters and an if – else condition.

function Test-Gateway {
param($Computer = $null,
 $Count = "1")
If ($Computer -eq $null)
{Test-Connection -Destination (Get-NetRoute -DestinationPrefix 0.0.0.0/0 | Select-Object -ExpandProperty Nexthop) -Count $Count}
 else
 {$Route=Invoke-Command -ComputerName $Computer {Get-NetRoute -DestinationPrefix 0.0.0.0/0 | Select-Object -ExpandProperty Nexthop}; Test-Connection -Source $Computer -Destination $Route -Count $Count}
 }

The function’s name is Test-Gateway. Pay attention to the param statement. I provide two parameters: Computer and Count. And I’ve specified standards for this parameters in case of that the user do not provide values for Computer and Count.

If the user doesn’t provide a value for Computer, then this values are $null, so Test-Connection is executed on the localhost. If the user does provide a computer name then the else statement is in action. Then the default gateway of a remote computer is tested. If the user do not provide a Count, then the ping is executed only once. (One ICMP Echo Request)

Why do I call the Default Gateway from Get-NetRoute? Well, the Default Route (0.0.0.0/0) read from the Routing Table always gives me the Default Gateway Address. If you have more than one network card on which can the Gateway Address be found?

Aaaand Action …

First, I do not provide a computername. I’m logged on computer DC01.

I now provide a computername. Note, that the remote computer has to reside in the same domain and you usually have to execute the command as a member of the Domain Admins. Client01 can reach it’s Default Gateway.

This second example should give you an overview how to create functions with parameters. Let’s go the final step. We want to create a module for this function.