Merge pull request #1 from keithbabinec/dev/keith/reorganizationUpdates

Module example updates, structure reorganization

Author: keithbabinec

README.md

@@ -1,16 +1,41 @@
 # PowerShellModuleStarterKit
-A starter kit for new PowerShell script modules including unit tests.
+A starter kit for new PowerShell script modules.
 
-Contains a basic .psd1 (manifest) and .psm1 (root module), class examples, function examples, and unit tests.
+This repository demonstrates how to organize a module and accomplish a few common tasks like public vs private functions, unit tests, working with classes, and more. 
 
-### Prerequisites
+## Features
+* Public and private functions.
+* Unit testing with the Pester framework.
+* PowerShell v5 classes (accessible inside and outside the module scope).
+* Module private data (for constants and caching).
+* Referencing static resource files.
+* Referencing external libraries.
 
-In order to run the unit tests, you need the Pester test framework (https://github.com/pester/Pester).
+## Setup
+1. Clone the repository to your local computer.
+2. Open PowerShell (as an administrator).
+3. Install the [Pester](https://github.com/pester/Pester) framework:
+``` powershell
+Install-Module -Name Pester -MinimumVersion 4.6.0 -Scope AllUsers -Force -SkipPublisherCheck
+```
+4. Add this starter kit module to the PSModule path.
+***Note: This assumes you have cloned the repository to C:\Source. Update the path if this isn't correct.***
+``` powershell
+$repoDirectory = 'C:\Source\PowerShellModuleStarterKit'
+$existingPaths = $ENV:PSModulePath
+$newPaths = "$repoDirectory;$existingPaths"
+$scope = [System.EnvironmentVariableTarget]::Machine
+[System.Environment]::SetEnvironmentVariable('PSModulePath',$newPaths,$scope)
+```
 
-Once Pester is installed and in your PSModule path, run the Invoke-Pester cmdlet (no args) from the root of the repository. It will find and run the tests for you.
+## Load the module
+``` powershell
+Import-Module -Name SampleModule
+```
 
-### Notes
-
-This module can be loaded by calling Import-Module on either the module manifest (.psd1), or the root module (.psm1) file.
-
-For the sake of easy unit testing, the .psm1 file is referenced for test imports. This is because the private functions and (non-exportable classes) are easily found and loaded.
+## Run the unit tests
+***Note: This assumes you have cloned the repository to C:\Source. Update the path if this isn't correct.***
+``` powershell
+cd 'C:\Source\PowerShellModuleStarterKit\SampleModule'
+Invoke-Pester
+```

Classes/AdvancedClass.ps1 renamed to SampleModule/Classes/AdvancedClass.ps1

@@ -5,16 +5,16 @@ function Get-RandomItemsCount
         Gets a random item count.
 
     .DESCRIPTION
-        Gets a random item count.
+        Gets a random item count, between the numbers 1 and 8.
 
     .EXAMPLE
-        Get-RandomItemsCount
+        PS C:\> Get-RandomItemsCount
+        Returns a random items count.
     #>
-
     [CmdletBinding()]
     Param
-    ()
-
+    (
+    )
     Process
     {
         # generate a random number and return it

Classes/SimpleClass.ps1 renamed to SampleModule/Classes/SimpleClass.ps1

@@ -0,0 +1,26 @@
+function Get-ModuleCacheItems
+{
+    <#
+    .SYNOPSIS
+        Returns some items from the writable module cache.
+
+    .DESCRIPTION
+        Returns some items from the writable module cache. If no items are in the cache, then nothing will be returned.
+
+    .EXAMPLE
+        PS C:\> Get-ModuleCacheItems
+        Returns the items saved in the cache, if they are found.
+    #>
+    [CmdletBinding()]
+    Param
+    (
+    )
+    Process
+    {
+        # example: read the first cache object, return it to the pipeline.
+        Write-Output $MyInvocation.MyCommand.Module.PrivateData.Cache['Example1Key']
+
+        # example: read the second cache object, return it to the pipeline.
+        Write-Output $MyInvocation.MyCommand.Module.PrivateData.Cache['Example2Key']
+    }
+}

Functions/Private/Get-RandomItemsCount.ps1 renamed to SampleModule/Functions/Private/Get-RandomItemsCount.ps1

@@ -0,0 +1,32 @@
+function Get-ModulePrivateDataConstant
+{
+    <#
+    .SYNOPSIS
+        Returns a constant setting from the module private data.
+
+    .DESCRIPTION
+        Returns a constant setting from the module private data. If the setting is not found, null will be returned.
+
+    .PARAMETER SettingName
+        The name of the constant setting to return.
+
+    .EXAMPLE
+        PS C:\> Get-ModulePrivateDataSetting -SettingName 'example'
+        Returns the module private data constant with key 'example'
+    #>
+    [CmdletBinding()]
+    Param
+    (
+        [Parameter(Mandatory=$true)]
+        [System.String]
+        $SettingName
+    )
+    Process
+    {
+        # capture the constant to a variable for use
+        $constant = $MyInvocation.MyCommand.Module.PrivateData.Constants[$SettingName]
+
+        # write it to the output pipeline.
+        Write-Output $constant
+    }
+} 

SampleModule/Functions/Public/Get-ModuleCacheItems.ps1

@@ -0,0 +1,26 @@
+function Get-ResourceFileContents
+{
+    <#
+    .SYNOPSIS
+        Returns the contents of a sample resource file packaged with the module.
+
+    .DESCRIPTION
+        Returns the contents of a sample resource file packaged with the module.
+
+    .EXAMPLE
+        PS C:\> Get-ResourceFileContents
+        Returns the contents of the sample resource file.
+    #>
+    [CmdletBinding()]
+    Param
+    (
+    )
+    Process
+    {
+        $moduleRoot = $MyInvocation.MyCommand.Module.ModuleBase
+        $filePath = Join-Path -Path $moduleRoot -ChildPath "Resources\Templates\TemplateResource.json"
+        $fileContents = Get-Content -Path $filePath -Raw
+        
+        Write-Output $fileContents
+    }
+} 

SampleModule/Functions/Public/Get-ModulePrivateDataConstant.ps1

@@ -0,0 +1,33 @@
+function Invoke-ReferencedLibrary
+{
+    <#
+    .SYNOPSIS
+        Invokes the external library referenced by the module manifest.
+
+    .DESCRIPTION
+        Invokes the external library referenced by the module manifest. The referenced library is Newtonsoft.JSON. 
+        The test will serialize an object to JSON and return the contents.
+
+    .EXAMPLE
+        PS C:\> Invoke-ReferencedLibrary
+        Tests the referenced library by serializing an object and returning the contents.
+    #>
+    [CmdletBinding()]
+    Param
+    (
+    )
+    Process
+    {
+        # the purpose of this function is to use the library that was referenced in the module manifest.
+        # the library is Newtonsoft.JSON, which is used for serializing and deserializing JSON data.
+        # in this example we just make a new class object and serialize it.
+
+        # NOTE: the library doesn't need to be loaded here with Add-Type, since it is already loaded automatically when the module was imported.
+
+        $item = New-AdvancedItem -Name 'Test'
+
+        $itemAsJson = [Newtonsoft.Json.JsonConvert]::SerializeObject($item)
+
+        Write-Output $itemAsJson
+    }
+}

SampleModule/Functions/Public/Get-ResourceFileContents.ps1

@@ -11,17 +11,16 @@ function New-AdvancedItem
         The name of the item.
 
     .EXAMPLE
-        New-AdvancedItem -Name 'Test'
+        PS C:\> New-AdvancedItem -Name 'Test'
+        Returns a new advanced item object.
     #>
-
     [CmdletBinding()]
     Param
     (
         [Parameter(Mandatory=$true)]
         [System.String]
         $Name
     )
-
     Process
     {
         # make the new item and return it

SampleModule/Functions/Public/Invoke-ReferencedLibrary.ps1

@@ -14,9 +14,9 @@ function New-SimpleItem
         The age of the item.
 
     .EXAMPLE
-        New-SimpleItem -Name 'Test' -Age 42
+        PS C:\> New-SimpleItem -Name 'Test' -Age 42
+        Returns a new simple item object.
     #>
-
     [CmdletBinding()]
     Param
     (
@@ -28,7 +28,6 @@ function New-SimpleItem
         [System.Int32]
         $Age
     )
-
     Process
     {
         # make the new item and return it

Functions/Public/New-AdvancedItem.ps1 renamed to SampleModule/Functions/Public/New-AdvancedItem.ps1

@@ -0,0 +1,27 @@
+function Set-ModuleCacheItems
+{
+    <#
+    .SYNOPSIS
+        Saves some items to the writable module cache.
+
+    .DESCRIPTION
+        Saves some items to the writable module cache.
+
+    .EXAMPLE
+        PS C:\> Set-ModuleCacheItems
+        Saves a simple type and a complex type to the cache.
+    #>
+    [CmdletBinding()]
+    Param
+    (
+    )
+    Process
+    {
+        # example: write to the cache, save a primitive type like string, or int.
+        $MyInvocation.MyCommand.Module.PrivateData.Cache['Example1Key'] = 'example1Value'
+
+        # example: write to the cache, save a complex type like a class object.
+        $advancedType = New-AdvancedItem -Name 'Test'
+        $MyInvocation.MyCommand.Module.PrivateData.Cache['Example2Key'] = $advancedType
+    }
+}

Functions/Public/New-SimpleItem.ps1 renamed to SampleModule/Functions/Public/New-SimpleItem.ps1

@@ -0,0 +1,5 @@
+{
+    "ID": 1,
+    "Name": "Sample document",
+    "Description": "This is a JSON blob that can be loaded as a module resource. See the module manifest to see how the file is referenced for packaging."
+}

SampleModule/Functions/Public/Set-ModuleCacheItems.ps1

@@ -0,0 +1,23 @@
+# load the module
+Import-Module SampleModule -Force
+
+# run tests
+# note: the Get-RandomItemsCount function is private (non-exported).
+# in order for Pester to test this function, use the 'InModuleScope' wrapper around the test.
+
+InModuleScope SampleModule {
+    Describe "Get-RandomItemsCount private function tests" {
+        Context "Basic functionality" {
+            It "Function can be loaded." {
+                { 
+                    Get-Help Get-RandomItemsCount -ErrorAction Stop
+                } | Should Not Throw
+            }
+            It "Returns a single integer output" {
+                $count = Get-RandomItemsCount
+                $count | Should Not Be $null
+                $count.GetType().FullName | Should Be 'System.Int32'
+            }
+        }
+    }
+}

SampleModule/Lib/Newtonsoft.Json.12.0.1.dll

@@ -0,0 +1,27 @@
+# load the module
+Import-Module SampleModule -Force
+
+# run tests
+Describe "Get-ModulePrivateDataConstant public function tests" {
+    Context "Basic functionality" {
+        It "Function can be loaded." {
+            { 
+                Get-Help Get-ModulePrivateDataConstant -ErrorAction Stop
+            } | Should Not Throw
+        }
+        It "Returns null for a non-existent module constant" {
+            $item = Get-ModulePrivateDataConstant -SettingName 'Not a real constant'
+            $item | Should Be $null
+        }
+        It "Returns the correct value for the string sample constant" {
+            $item = Get-ModulePrivateDataConstant -SettingName 'ExampleStringConst'
+            $item | Should Not Be $null
+            $item.GetType().FullName | Should Be 'System.String'
+        }
+        It "Returns the correct value for the int sample constant" {
+            $item = Get-ModulePrivateDataConstant -SettingName 'ExampleIntConst'
+            $item | Should Not Be $null
+            $item.GetType().FullName | Should Be 'System.Int32'
+        }
+    }
+}

SampleModule/Resources/Templates/TemplateResource.json

@@ -0,0 +1,20 @@
+# load the module
+Import-Module SampleModule -Force
+
+# run tests
+Describe "Get-ResourceFileContents public function tests" {
+    Context "Basic functionality" {
+        It "Function can be loaded." {
+            { 
+                Get-Help Get-ResourceFileContents -ErrorAction Stop
+            } | Should Not Throw
+        }
+        It "Returns a json document" {
+            $item = Get-ResourceFileContents
+            $item | Should Not Be $null
+            $item.GetType().FullName | Should Be 'System.String'
+            $item.StartsWith("{") | Should Be $true
+            $item.EndsWith("}") | Should Be $true
+        }
+    }
+}

ScriptModule.psd1 renamed to SampleModule/SampleModule.psd1

@@ -0,0 +1,20 @@
+# load the module
+Import-Module SampleModule -Force
+
+# run tests
+Describe "Invoke-ReferencedLibrary public function tests" {
+    Context "Basic functionality" {
+        It "Function can be loaded." {
+            { 
+                Get-Help Invoke-ReferencedLibrary -ErrorAction Stop
+            } | Should Not Throw
+        }
+        It "Returns a json document" {
+            $item = Invoke-ReferencedLibrary
+            $item | Should Not Be $null
+            $item.GetType().FullName | Should Be 'System.String'
+            $item.StartsWith("{") | Should Be $true
+            $item.EndsWith("}") | Should Be $true
+        }
+    }
+}

ScriptModule.psm1 renamed to SampleModule/SampleModule.psm1

@@ -1,5 +1,5 @@
 # load the module
-Import-Module .\ScriptModule.psm1
+Import-Module SampleModule -Force
 
 # run tests
 Describe "New-AdvancedItem public function tests" {
@@ -11,7 +11,7 @@ Describe "New-AdvancedItem public function tests" {
         }
         It "Returns the correct type" {
             $item = New-AdvancedItem -Name 'Cool'
-            $item -eq $null | Should Be $false
+            $item | Should Not Be $null
             $item.GetType().FullName | Should Be 'AdvancedClass'
         }
         It "Name property is set" {
@@ -24,7 +24,7 @@ Describe "New-AdvancedItem public function tests" {
         }
         It "Items collection is populated" {
             $item = New-AdvancedItem -Name 'Cool'
-            $item.Items -ne $null | Should Be $true
+            $item.Items | Should Not Be $null
             $item.Items.Count | Should BeGreaterThan 0
         }
     }