Creating a PowerShell Module from a DBA’s Perspective

Problem

The last T-SQL Tuesday a lot of data professionals shared their favorite PowerShell scripts including functions, but some DBAs are new to PowerShell and don’t know how to use the functions.  So this post will cover how to create a PowerShell module so you can store the functions you just found that are useful to you as a DBA for future use, as I couldn’t find a DBA friendly blog post out there to explain how to do this for a reader of my blog.

Description of a Design of PowerShell Module components

This module is based on how I’ve seen DBATools do their setup, of course, theirs is a bit more complicated.  This is will simply allow you to collect different functions for future use.

First, you can find where your PowerShell module will be created using this command by running this command to see where your PowerShell Module will be stored at:

$Env:PsModulePath

My first path is listed as C:\Program Files\WindowsPowerShell\Modules and recommend you use this path to create your module files in the commands in later steps.  In this folder will be creating two files, a manifest file .psd1 and .psm1 file.

Creating a Manifest file

The first file you need to create is a manifest file.  This file tells who wrote the module what version PowerShell should be used and module version.  You will need to open either PowerShell ISE or PowerShell under Run as administrator to run this command. You change the path to match the name you want the name you want your module to have along with the name of the module and author.  You may have to create the folder in your Modules folder (DBAFunctions) first depending on the security on your machine.

New-ModuleManifest -Path 'C:\Program Files\WindowsPowerShell\Modules\DBAFunctions\DBAFunctions.psd1' -RootModule 'DBAFunctions' -CmdletsToExport '*' -FunctionsToExport '*' -VariablesToExport '*' -AliasesToExport '*'

Creating your MODULE(PSM1) FILE

When we first created our module we used at work we put all our functions in our module file but it soon became very large and hard to find things. Then we noticed how DBATools did create their solution.  So in your folder, you created your manifest files (PSD1), create your module (PSM1) file and copy and paste the code the below.

foreach ($function in (Get-ChildItem "$PSScriptRoot\Functions\*.ps1"))
{
	$ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText($function))), $null, $null)
}

Create a Folder to hold our Collection

Now in the folder, you created your files, create a Functions folder and save the .PS1 files you have gotten.  As an example, my reader was pulling the function I wrote from my post here.  So save the function into a file with a .ps1 extension and place into your Functions folder.  The following code will load the module and show the help if any for the function you specify:

Import-Module DBAFunctions
Get-Help Get-AvailabiliytGroupStatus

I would also say if the author has put a header at the top, I would add and maybe edit the one they have to add the URL of where you got it from for your reference back to easily.  For example:

function Get-AvailabiliytGroupStatus {
  <#
    .SYNOPSIS
      Add text

    .DESCRIPTION
      Add description

    .PARAMETER ComputerName
      Add one for each parameter and description to help you out
      
    .NOTES
      Website: http://tracyboggiano.com

    .EXAMPLE
      Add any examples they gave on their website

      Describe the example

    .EXAMPLE
      Add any examples they gave on their website
#>
{
Code goes here
}

Using your new module

Now you are ready to use your new module and function(s).  In your favorite PowerShell IDE run the following command when you want to use one of the functions you have saved in this folder.

Import-Module DBAFunctions
Get-AvailabiliytGroupStatus -ServerInstanceList "Servername"