Modules, Scripts and Functions All Versions

Examples

• 1

  Function
  1

  A function is a named block of code which is used to define reusable code that should be easy to use. It is usually included inside a script to help reuse code (to avoid duplicate code) or distributed as part of a module to make it useful for others in multiple scripts.

  Scenarios where a function might be useful:

  • Calculate the average of a group of numbers
  • Generate a report for running processes
  • Write a function that tests is a computer is "healthy" by pinging the computer and accessing the c$-share

  Functions are created using the function keyword, followed by a single-word name and a script block containing the code to executed when the function name is called.

  function NameOfFunction {
      Your code
  }
  

  Demo

  function HelloWorld {
      Write-Host "Greetings from PowerShell!"
  }
  

  Usage:

  > HelloWorld
  Greetings from PowerShell!
  

  created Sep 1 '16 at 20:21

  
  discuss
• 1

  Module
  1

  A module is a collection of related reusable functions (or cmdlets) that can easily be distributed to other PowerShell users and used in multiple scripts or directly in the console. A module is usually saved in it's own directory and consists of:

  • One or more code files with the .psm1 file extension containing functions or binary assemblies (.dll) containing cmdlets
  • A module manifest .psd1 describing the modules name, version, author, description, which functions/cmdlets it provides etc.
  • Other requirements for it to work incl. dependencies, scripts etc.

  Examples of modules:

  • A module containing functions/cmdlets that perform statistics on a dataset
  • A module for querying and configuring databases

  To make it easy for PowerShell to find and import a module, it is often placed in one of the known PowerShell module-locations defined in $env:PSModulePath.

  Demo

  List modules that are installed to one of the known module-locations:

  Get-Module -ListAvailable
  

  Import a module, ex. Hyper-V module:

  Import-Module Hyper-V
  

  List available commands in a module, ex. the Microsoft.PowerShell.Archive-module

  > Import-Module Microsoft.PowerShell.Archive
  > Get-Command -Module Microsoft.PowerShell.Archive
  
  CommandType Name             Version Source                      
  ----------- ----             ------- ------                      
  Function    Compress-Archive 1.0.1.0 Microsoft.PowerShell.Archive
  Function    Expand-Archive   1.0.1.0 Microsoft.PowerShell.Archive
  

  created Sep 1 '16 at 20:21

  
  discuss
• 1

  Script
  1

  A script is a text file with the file extension .ps1 that contains PowerShell commands that will be executed when the script is called. Because scripts are saved files, they are easy to transfer between computers.

  Scripts are often written to solve a specific problem, ex.:

  • Run a weekly maintenance task
  • To install and configure a solution/application on a computer

  Demo

  MyFirstScript.ps1:

  Write-Host "Hello World!"
  2+2
  

  You can run a script by entering the path to the file using an:

  • Absolute path, ex. c:\MyFirstScript.ps1
  • Relative path, ex .\MyFirstScript.ps1 if the current directory of your PowerShell console was C:\

  Usage:

  > .\MyFirstScript.ps1
  Hello World!
  4
  

  A script can also import modules, define it's own functions etc.

  MySecondScript.ps1:

  function HelloWorld {
      Write-Host "Greetings from PowerShell!"
  }
  
  HelloWorld
  Write-Host "Let's get started!"
  2+2
  HelloWorld
  

  Usage:

  > .\MySecondScript.ps1
  Greetings from PowerShell!
  Let's get started!
  4
  Greetings from PowerShell!
  

  created Sep 1 '16 at 20:21

  
  discuss
• 0

  Advanced Functions
  0

  Advanced functions behave the in the same way as cmdlets. The PowerShell ISE includes two skeletons of advanced functions. Access these via the menu, edit, code snippets, or by Ctrl+J. (As of PS 3.0, later versions may differ)

  Key things that advanced functions include are,

  • built-in, customized help for the function, accessible via Get-Help
  • can use [CmdletBinding()] which makes the function act like a cmdlet
  • extensive parameter options

  Simple version:

  <#
  .Synopsis
     Short description
  .DESCRIPTION
     Long description
  .EXAMPLE
     Example of how to use this cmdlet
  .EXAMPLE
     Another example of how to use this cmdlet
  #>
  function Verb-Noun
  {
      [CmdletBinding()]
      [OutputType([int])]
      Param
      (
          # Param1 help description
          [Parameter(Mandatory=$true,
                     ValueFromPipelineByPropertyName=$true,
                     Position=0)]
          $Param1,
  
          # Param2 help description
          [int]
          $Param2
      )
  
      Begin
      {
      }
      Process
      {
      }
      End
      {
      }
  }
  

  Complete version:

  <#
  .Synopsis
     Short description
  .DESCRIPTION
     Long description
  .EXAMPLE
     Example of how to use this cmdlet
  .EXAMPLE
     Another example of how to use this cmdlet
  .INPUTS
     Inputs to this cmdlet (if any)
  .OUTPUTS
     Output from this cmdlet (if any)
  .NOTES
     General notes
  .COMPONENT
     The component this cmdlet belongs to
  .ROLE
     The role this cmdlet belongs to
  .FUNCTIONALITY
     The functionality that best describes this cmdlet
  #>
  function Verb-Noun
  {
      [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                    SupportsShouldProcess=$true, 
                    PositionalBinding=$false,
                    HelpUri = 'http://www.microsoft.com/',
                    ConfirmImpact='Medium')]
      [OutputType([String])]
      Param
      (
          # Param1 help description
          [Parameter(Mandatory=$true, 
                     ValueFromPipeline=$true,
                     ValueFromPipelineByPropertyName=$true, 
                     ValueFromRemainingArguments=$false, 
                     Position=0,
                     ParameterSetName='Parameter Set 1')]
          [ValidateNotNull()]
          [ValidateNotNullOrEmpty()]
          [ValidateCount(0,5)]
          [ValidateSet("sun", "moon", "earth")]
          [Alias("p1")] 
          $Param1,
  
          # Param2 help description
          [Parameter(ParameterSetName='Parameter Set 1')]
          [AllowNull()]
          [AllowEmptyCollection()]
          [AllowEmptyString()]
          [ValidateScript({$true})]
          [ValidateRange(0,5)]
          [int]
          $Param2,
  
          # Param3 help description
          [Parameter(ParameterSetName='Another Parameter Set')]
          [ValidatePattern("[a-z]*")]
          [ValidateLength(0,15)]
          [String]
          $Param3
      )
  
      Begin
      {
      }
      Process
      {
          if ($pscmdlet.ShouldProcess("Target", "Operation"))
          {
          }
      }
      End
      {
      }
  }
  

  created Oct 7 '16 at 15:09

  
  discuss