Creating my own PowerShell Module

Since starting at my first Help Desk position, I’ve been slowly looking into PowerShell and how I can start to utilize it better instead of having to scroll through different web consoles to access the information that I need. After working on small scripts, I got tired of having to call each script by name and when opening up a new PowerShell window, having to follow the proper file path in order to call these scripts.

Then I found out about creating a custom PowerShell module. I could have all of my custom scripts typed out in this module and import it all at once. Then I can just call each script by their individual function names, and I even figured out how to style the documentation so you can call the Get-Help command to get the information about the given function.

The first step is to go to create a new file, call it whatever you want, but instead of a .ps1 file you want to save it as a .psm1 file. If you couldn’t guess, the “m” is for module GASP.

The way we want to format our scripts in this module is going to be as a function.

We’ll start off by calling our function:

function FUNCTION_NAME

In this example, I’m going to call an easy one I created called Get-DistroMembers, which will get all members of a given distribution list we give it.

function Get-DistroMembers(
    [Parameter(Mandatory)] $DistributionList) {
        Write-Host "Distribution List Members: `n"
        (Get-DistributionGroupMember -Identity $DistributionList).PrimarySmtpAddress
}

To break it down a little easier, we are naming the function Get-DistroMembers and it will take a mandatory parameter of DistributionList as an email address. Then, for purely asthetic purposes, we print out a title for our list of users and the [`n] is a callout in PowerShell meaning to add in an extra line. The last bit of this function is the real meats of the function. We call Get-DistributionGroupMember on our specified DistributionList, but we are only worried about the PrimarySmtpAddress values from the results and they get printed out as a list. So in the terminal, it should look a little something like this:

PS> Get-DistroMembers -DistributionList "test@testemail.com"
Distribution List Members:

user1@testemail.com
user2@testemail.com
user3@testemail.com

Now the last thing that we have to do before we can actually call this custom function is to actually import the module into our PowerShell environment. Luckily, it’s very easy to do, using the Import-Module command:

PS> Import-Module "Path\To\Module\module.psm1"

Once you run this, you should be able to call any of the custom functions in that module. One thing to remember, once you close your PowerShell window, you will have to re-import the module when you open a new PowerShell window. One way around this that I’ve been using, is to add that command to your PowerShell Profile. Any commands that are saved into the Profile document are run immediately when you open up a PowerShell terminal, every time.

If you call $PROFILE in your PowerShell terminal, it should return a directory to where the Profile should be stored.

To create a Profile, first we need to see if there is a current Profile created or not. We can use the Test-Path command to test this out:

PS> Test-Path $PROFILE

If this comes back True, then the Profile is already there and the system can see it. If it comes back False, then we need to create a new Profile, which can be done with the following command:

PS> New-Item -Path $PROFILE -Type File -Force

With this, the Profile has been created, but it’s empty. An easy way to edit the contents is to run:

PS> notepad $PROFILE

This should open a new Notepad window with the “contents” of your Profile. Go ahead and copy/paste the Import-Module command into this, save, and exit the Notepad window. Go ahead and close out of your current PowerShell terminal and open a new one, and boom! Now you have a custom function that is automatically imported whenever you open up PowerShell.

Another thing to mention is that if you make any changes to the Module file, you will have to close and re-open the PowerShell terminal in order for those changes to go into effect.