PowerShell Functions All Versions

Examples

• Improvements requested:

  • This example does not sufficiently illustrate the point and needs to be edited to provide more details. –  TravisEz13 Dec 2 at 23:11

    Advanced Functions should be used over functions, this topic does not make this clear.

  Edit Example Delete Example
  7

  Functions with parameters

  edit move example delete share 1

  7

  A function can be defined with parameters using the param block:

  function Get-Greeting {
      param
      (
          $name,
          $age
      )
      "Hello $name, age $age"
  }
  

  Or using the simple function syntax (more C# style syntax):

  function Get-Greeting($name, $age) {
      "Hello $name, age $age"
  }
  

  Note: This format is as good as the advanced format, but has very limited capabilities.
  Try using a parameter set, parameter validation, ...
  Because of this and because I like uniformity I prefer to use the advanced format for every function.

  This function can then be invoked with ordered parameters where the order of the parameters on the invocation is matched to the order of the declaration in the function header

  $greeting = Get-Greeting "Jim" 82
  

  Alternatively, this function can be invoked with named parameters

  $greeting = Get-Greeting -name "Bob" -age 82
  

  Note: PowerShell functions are never called with the syntax Get-Greeting("Jim", 82), doing this will pass one array in as the first parameter and leave the second parameter empty.

  edited Dec 28 '16 at 14:48

  

  

  

  

  
• 6

  Advanced Function

  edit move example delete share

  6

  <#
  .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')]
      [Alias()]
      [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 Jul 26 '16 at 6:19

  
• 4

  Mandatory Parameters

  edit move example delete share

  4

  Parameters to a function can be marked as mandatory

  function Get-Greeting{
      param
      (
          [Parameter(Mandatory=$true)]$name
      )
      "Hello World $name"
  }
  

  If the function is invoked without a value, the command line will prompt for the value:

  $greeting = Get-Greeting 
  
  cmdlet Get-Greeting at command pipeline position 1
  Supply values for the following parameters:
  name: 
  

  edited Jul 22 '16 at 1:00

  

  

• Improvements requested:

  • This example does not sufficiently illustrate the point and needs to be edited to provide more details. –  Liam Oct 5 at 13:19

    Needs some explanation. As it stands it's just a lump of code. Examples are good, examples with no context, less useful

  Edit Example Delete Example
  0

  Simple Function with No Parameters

  edit move example delete share 1

  0

  This is an example of a function which returns a string. In the example, the function is called in a statement assigning a value to a variable. The value in this case is the return value of the function.

  function Get-Greeting{
      "Hello World"
  }
  
  # Invoking the function
  $greeting = Get-Greeting
  
  # demonstrate output
  $greeting
  Get-Greeting
  

  function declares the following code to be a function.

  Get-Greeting is the name of the function. Any time that function needs to be used in the script, the function can be called by means of invoking it by name.

  { ... } is the script block that is executed by the function.

  If the above code is executed in the ISE, the results would be something like:

  Hello World
  Hello World
  

  edited Oct 7 '16 at 15:30