Software: Apache. PHP/5.5.15 

uname -a: Windows NT SVR-DMZ 6.1 build 7600 (Windows Server 2008 R2 Enterprise Edition) i586 

SYSTEM 

Safe-mode: OFF (not secure)

C:\Windows\System32\WindowsPowerShell\v1.0\en-US\   drwxrwxrwx
Free 4.1 GB of 39.52 GB (10.37%)
Detected drives: [ a ] [ c ] [ d ] [ e ] [ f ]
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     about_functions.help.txt (15.26 KB)      -rw-rw-rw-

TOPIC
    about_Functions

SHORT DESCRIPTION
    Describes how to create and use functions in Windows PowerShell. 


LONG DESCRIPTION
    A function is a list of statements that has a name that you assign. When 
    you run a function, you type the function name. The statements in the list 
    run as if you had typed them at the command prompt. 

    Like cmdlets, functions can have parameters. The parameters can be named, 
    positional, switch, or dynamic parameters. Function parameters can be read 
    from the command line or from the pipeline. 

    Functions can return values that can be displayed, assigned to variables, 
    or passed to other functions or cmdlets. 

    The function's statement list can contain different types of statement 
    lists with the keywords Begin, Process, and End. These statement lists 
    handle input from the pipeline differently.

    A filter is a special kind of function that uses the Filter keyword. 

    Functions can also act like cmdlets. You can create a function that works 
    just like a cmdlet without using C# programming. For more information, 
    see about_Functions_Advanced.


  Syntax
      The following is the syntax for a function:

          function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]  
          {
              param([type]$parameter1 [,[type]$parameter2])

              dynamicparam {<statement list>}
  
              begin {<statement list>}
              process {<statement list>}
              end {<statement list>}
          }


      A function includes the following items:

          - A Function keyword
          - A scope (optional)
          - A name that you select
          - Any number of named parameters (optional)
          - One or more Windows PowerShell commands enclosed in braces ({}) 


      For more information about the Dynamicparam keyword and dynamic 
      parameters in functions, see about_Functions_Advanced_Parameters.


  Simple Functions
      Functions do not have to be complicated to be useful. The following 
      function gets the environment variables that do not belong to the System 
      account of the current system: 

          function other_env 
          { 
             get-wmiObject win32_environment | 
                where {$_.username -ne "<System>"}
          }

      To run the function, type "other_env". 

      You can create a toolbox of useful small functions. Add these functions 
      to your Windows PowerShell profile, as described in about_Profiles and 
      later in this topic.


  Functions with Parameters
      You can use parameters with functions, including named parameters, 
      positional parameters, switch parameters, and dynamic parameters. For 
      more information about dynamic parameters in functions, 
      see about_Functions_Advanced_Parameters.


  Named Parameters
      You can define any number of named parameters. You can include a default 
      value for named parameters, as described later in this topic.

      You can define parameters inside the braces using the Param keyword, as 
      shown in the following sample syntax:
    
          function <name> { 
               param ([type]$parameter1[,[type]$parameter2])
               <statement list> 
          }


      You can also define parameters outside the braces without the Param 
      keyword, as shown in the following sample syntax:

          function <name> [([type]$parameter1[,[type]$parameter2])] { 
              <statement list> 
          }


      There is no difference between these two methods. Use the method that 
      you prefer.

      When you run the function, the value you supply for a parameter is 
      assigned to a variable that contains the parameter name. The value of 
      that variable can be used in the function. 

      The following example is a function called Small_files. This function 
      has a $size parameter. The function displays all the files that are 
      smaller than the value of the $size parameter, and it excludes 
      directories:

          function small_files {
              param ($size)
              Get-ChildItem c:\ | where {
                  $_.length -lt $size -and !$_.PSIsContainer} 
          }


      In the function, you can use the $size variable, which is the name 
      defined for the parameter.

      To use this function, type the following command:
 
          C:\PS> function small_files –size 50


      You can also enter a value for a named parameter without the parameter 
      name. For example, the following command gives the same result as a 
      command that names the Size parameter:

          C:\PS> function small_files 50


      To define a default value for a parameter, type an equal sign and the 
      value after the parameter name, as shown in the following variation of 
      the Small_files example:

          function small_files ($size = 100) {
              Get-ChildItem c:\ | where {
                  $_.length -lt $size -and !$_.PSIsContainer} 
          }


      If you type "small_files" without a value, the function assigns 100 to 
      $size. If you provide a value, the function uses that value.


  Positional Parameters
      A positional parameter is a parameter without a parameter name. Windows 
      PowerShell uses the parameter value order to associate each parameter 
      value with a parameter in the function. 

      When you use positional parameters, type one or more values after the 
      function name. Positional parameter values are assigned to the $args 
      array variable. The value that follows the function name is assigned to 
      the first position in the $args array, $args[0]. 

      The following Extension function adds the .txt file name extension to a 
      file name that you supply:

          function extension {
              $name = $args[0] + ".txt"
              $name
          }

          C:\PS> extension myTextFile
          myTextFile.txt
   
      Functions can take more than one positional parameter. The following 
      example displays any values entered with the function name.

          function repeat { foreach ($arg in $args) { "The input is $arg" } }

          C:\PS>repeat one 
          The input is one

          C:\PS> repeat one two three
          The input is one
          The input is two 
          The input is three


      This function can be used with any number of values. The function 
      assigns each value to a position in the $args array.


  Switch Parameters
      A switch is a parameter that does not require a value. Instead, you type 
      the function name followed by the name of the switch parameter.

      To define a switch parameter, specify the type [switch] before the 
      parameter name, as shown in the following example:

          function switchExample {
              param ([switch]$on)
              if ($on) { "Switch on" }
              else { "Switch off" }
          }


      When you type the On switch parameter after the function name, the 
      function displays "Switch on". Without the switch parameter, it displays 
      "Switch off".

          C:\PS> SwitchExample -on
          Switch on

          C:\PS> SwitchExample
          Switch off

      You can also assign a Boolean value to a switch when you run the 
      function, as shown in the following example:

          C:\PS> SwitchExample -on:$true
          Switch on

          C:\PS> SwitchExample -on:$false
          Switch off


  Piping Objects to Functions
      Any function can take input from the pipeline. You can control how a 
      function processes input from the pipeline using Begin, Process, and End 
      keywords. The following sample syntax shows the three keywords:

          function <name> { 
              begin {<statement list>}
              process {<statement list>}
              end {<statement list>}
          }

      The Begin statement list runs one time only, at the beginning of 
      the function.  

      The Process statement list runs one time for each object in the pipeline.
      While the Process block is running, each pipeline object is assigned to 
      the $_ automatic variable, one pipeline object at a time. 

      After the function receives all the objects in the pipeline, the End 
      statement list runs one time. If no Begin, Process, or End keywords are 
      used, all the statements are treated like an End statement list.

      The following function uses the Process keyword. The function displays 
      examples from the pipeline:

          function pipelineFunction 
          { 
              process {"The value is: $_"} 
          }


      To demonstrate this function, enter an array of numbers created with 
      commas, as shown in the following example:

          C:\PS> 1,2,4 | pipelineFunction
          The value is: 1
          The value is: 2
          The value is: 4


      When you use a function in a pipeline, the objects piped to the function 
      are assigned to the $input automatic variable. The function runs 
      statements with the Begin keyword before any objects come from the 
      pipeline. The function runs statements with the End keyword after all 
      the objects have been received from the pipeline.

      The following example shows the $input automatic variable with Begin and 
      End keywords.

          function PipelineBeginEnd 
          {
              begin {"Begin: The input is $input"}
              end {"End:   The input is $input" }
          }


      If this function is run by using the pipeline, it displays the following 
      results:

          C:\PS> 1,2,4 | PipelineBeginEnd
          Begin: The input is 
          End:   The input is 1 2 4


      When the Begin statement runs, the function does not have the input from 
      the pipeline. The End statement runs after the function has the values.

      If the function has a Process keyword, the function reads the data in 
      $input. The following example has a Process statement list:

          function PipelineInput
          {
              process {"Processing:  $_ " }
              end {"End:   The input is: $input" }
          }  

      In this example, each object that is piped to the function is sent to the
      Process statement list. The Process statements run on each object, one 
      object at a time. The $input automatic variable is empty when the 
      function reaches the End keyword.

          C:\PS> 1,2,4 | PipelineInput
          Processing:  1 
          Processing:  2 
          Processing:  4 
          End:   The input is:


  Filters
      A filter is a type of function that runs on each object in the pipeline. 
      A filter resembles a function with all its statements in a Process block.

      The syntax of a filter is as follows: 

          filter [<scope:>]<name> {<statement list>}

      The following filter takes log entries from the pipeline and then 
      displays either the whole entry or only the message portion of the entry:

          filter ErrorLog ([switch]$message)
          {
              if ($message) { out-host -inputobject $_.Message }
              else { $_ }   
          }


  Function Scope
      A function exists in the scope in which it was created. 

      If a function is part of a script, the function is available to 
      statements within that script. By default, a function in a script is not 
      available at the command prompt. 

      You can specify the scope of a function. For example, the function is 
      added to the global scope in the following example: 

 
          function global:get-dependentsvs { get-service |
             where {$_.dependentservices} }


      When a function is in the global scope, you can use the function in 
      scripts, in functions, and at the command line.

      Functions normally create a scope. The items created in a function, such 
      as variables, exist only in the function scope.

      For more information about scope in Windows PowerShell, see about_Scope.

        
  Finding and Managing Functions Using the Function: Drive
      All the functions and filters in Windows PowerShell are automatically 
      stored in the Function: drive. This drive is exposed by the Windows 
      PowerShell Function provider.

      When referring to the Function: drive, type a colon after Function, just 
      as you would do when referencing the C or D drive of a computer.

      The following command displays all the functions in the current session 
      of Windows PowerShell:

          C:\PS>    dir function:


      The commands in the function are stored as a script block in the 
      definition property of the function. For example, to display the 
      commands in the Help function that comes with Windows PowerShell, type:

          (dir function:help).definition

      For more information about the Function: drive, see Function.


  Reusing Functions in New Sessions
      When you type a function at the Windows PowerShell command prompt, the 
      function becomes part of the current session. It is available until the 
      session ends. 

      To use your function in all Windows PowerShell sessions, add the function
      to your Windows PowerShell profile. For more information about profiles, 
      see about_Profiles.

      You can also save your function in a Windows PowerShell script file. 
      Type your function in a text file, and then save the file with the .ps1 
      file name extension.


  Writing Help for Functions
    The Get-Help cmdlet gets help for functions, as well as for cmdlets,
    providers, and scripts. To get help for a function, type Get-Help followed
    by the function name.

    For example, to get help for the MyDisks function, type:

        get-help MyDisks

    You can write help for a function by using either of the two following methods:

    --  Comment-Based Help  for Functions

        Create a help topic by using special keywords in the comments. To create
        comment-based help for a function, the comments must be placed at the
        beginning or end of the function body or on the lines preceding the function
        keyword. For more information about comment-based help, see
        about_Comment_Based_Help.

    --  XML-Based Help  for Functions

        Create an XML-based help topic, such as the type that is typically
        created for cmdlets. XML-based help is required if you are localizing
        help topics into multiple languages.  

        To associate the function with the XML-based help topic, use the
        .ExternalHelp help comment keyword. For more information about the
        ExternalHelp keyword, see about_Comment_Based_Help. For more information
        about XML-based help, see "How to Write Cmdlet Help" in MSDN.



SEE ALSO 
    about_Automatic_Variables 
    about_Comment_Based_Help
    about_Functions_Advanced  
    about_Functions_CmdletBindingAttribute
    about_Parameters
    about_Profiles
    about_Scopes
    about_Script_Blocks
    Function (provider)