Monday, 18 September 2017

Create a PowerShell Module

Introduction

When you build up your own library of functions, it’s really useful to have them always available on your machine without you having to load script files etc. This is where creating your own PowerShell module comes in handy. You can have all your functions available in this module and just take it around wherever you go.

Today, I’m going to write a simple function and then create my own module which includes this function.

How to build a PowerShell module

So, this is really not as hard as it seems. The basic steps are below:

  1. Create your functions in a single .psm1 file
  2. Copy your .psm1 file into one of the PowerShell module folders
  3. Create a module manifest

1 - Create your functions and save the file as .psm1

I’ve created three simple functions below:

function Get-LoggedOnUser
    {
        ($env:USERDOMAIN).ToLower() + "\" + $env:USERNAME
    }

function List-Process 
    {
        Get-Process -IncludeUserName
    }

function List-MyProcesses
    {
        List-Process | ? {$_.UserName -eq (Get-LoggedOnUser)}
    }

Get-LoggedOnUser just gets the user name. List-Process gets a list of all processes and List-MyProcesses filters the processes using the logged on user details.

Save your functions in a .psm1 file.

2 - Copy your .psm1 file

You can store your psm1 file in one of three locations by default in Server 2016:

  • C:\Users\Administrator.contoso\Documents\WindowsPowerShell\Modules
  • C:\Program Files\WindowsPowerShell\Modules
  • C:\Windows\system32\WindowsPowerShell\v1.0\Modules

…..and you can confirm these are the locations by running the command below:

$env:PSModulePath -split ";"

image

We now need to make a folder for our module and give it a name. In this case, we will call our module ProcessTroubleshooting and we’ll save it in a module folder.

Make a new folder: C:\Program Files\WindowsPowerShell\Modules\ProcessTroubleshooting

Copy the .psm1 file your created to C:\Program Files\WindowsPowerShell\Modules\ProcessTroubleshooting\ProcessTroubleshooting.psm1

Note the psm1 extension. This is the convention for creating modules.

3 - Create a module manifest

We now need a module manifest so that our module can be loaded automatically and so that PowerShell knows which functions to provide to the user. To create a module manifest, you need to use the New-ModuleManifest cmdlet. The module manifest file is a .psd1 file.

New-ModuleManifest -Path 'C:\Program Files\WindowsPowerShell\Modules\ProcessTroubleshooting\ProcessTroubleshooting.psd1' `
-RootModule 'C:\Program Files\WindowsPowerShell\Modules\ProcessTroubleshooting\ProcessTroubleshooting.psm1' `
-Author "Mark Gossa" `
-FunctionsToExport List-MyProcesses

We now have a module manifest which includes information about our module and very importantly which functions to export and allow the user to access. The FunctionsToExport parameter lists which functions we want to provide to users, i.e. which functions we want to export (i.e. only the List-MyProcesses function). It’s all nice and simple really.

You should now be able to import your module and use all the functions you’ve exported. In Server 2012 and later, you don’t need to even import it - Windows Server just imports it as you call one of the functions. See below for our function in action:

image

So, there we have it - that's how you create PowerShell modules but manual steps I hear you say? Well, you can just write your own function that will package up your module for you and create the manifest and you can even save that function in another module.

Happy scripting!

No comments:

Post a Comment