home *** CD-ROM | disk | FTP | other *** search
/ Chip 2008 June / CHIP-2008-06.iso / software / PowerShell / PowerShell_Setup_x86.msi / product.cab / about_Function.help_EN.txt < prev    next >
Encoding:
Text File  |  2007-10-29  |  9.8 KB  |  243 lines
  1. TOPIC
  2.     Functions
  3.  
  4. SHORT DESCRIPTION
  5.     Creating and using functions in the Windows PowerShell 
  6.  
  7. LONG DESCRIPTION
  8.     A function is a named block of code that you can reference within your 
  9.     Windows PowerShell commands. When you call the function name, the code
  10.     within the function runs as if you had typed the function's code block. 
  11.     A function can accept imported values that you specify as arguments when
  12.     you call the function or accept values that are passed to the function
  13.     through the current pipeline. The function returns values that can then
  14.     be assigned to variables or passed to other functions or cmdlets.
  15.  
  16.     Windows PowerShell supports two types of functions: regular functions and
  17.     filters. The primary difference between the two is how they are processed.
  18.     When you call a regular function, objects that are piped to the function
  19.     are bound to the $input automatic variable, and execution is blocked until
  20.     all input is received from the pipeline. This ensures that the function has
  21.     received all of the data that it needs before it begins processing the data.
  22.  
  23.     However, a filter processes data while it is being received (this 
  24.     allows the filtering action to occur). Filters are called for each 
  25.     incoming object in the pipeline, without waiting for all input. A 
  26.     filter receives each object from the pipeline through the $_ automatic 
  27.     variable, and the script block is processed for each object.
  28.  
  29.     To create a regular function or a filter, you must specify several 
  30.     required elements. You can also specify optional elements. The 
  31.     following syntax shows the various components that make up a function 
  32.     definition:
  33.  
  34.         function | filter
  35.         [<scope_type>:]<name>
  36.         { param(<param_list>) <script_block> }
  37.  
  38.     The following table describes each element in the function definition:
  39.  
  40.     Element           Description                                 Required?
  41.     ----------------- ------------------------------------------- ---------
  42.     function | filter One of two keywords that must be specified  Yes
  43.     scope_type:       A scope specification that overrides the    No
  44.                       default scope
  45.     name              Name of the function or filter              Yes
  46.     { }               Braces that enclose the parameter           Yes
  47.                       definitions and script block
  48.     param(param_list) The param keyword followed by parentheses   No
  49.                       that enclose the list of parameters. The 
  50.                       list includes the name of the parameters
  51.                       separated by commas. Optionally, parameter
  52.                       names can be preceded by data type names
  53.                       (in brackets).
  54.     script_block
  55.     The logic that supports the function or     Yes
  56.                       filter
  57.  
  58.     A basic function definition consists only of the initial keyword
  59.    (function or filter), the name of the function or filter, and the script
  60.     block (enclosed in braces. The following definition defines a regular
  61.     function that includes only the required elements:
  62.  
  63.         function small_files 
  64.         {
  65.             Get-ChildItem c:\ | where { $_.length -lt 100 
  66.                 -and !$_.PSIsContainer} 
  67.         }
  68.  
  69.     The definition creates a function named small_files. The script block 
  70.     (enclosed in the outer braces) is a command that calls the Get-ChildItem
  71.     cmdlet. The output from this cmdlet is then piped to the Where-Object
  72.     cmdlet, which selects objects with a file size (the length property) 
  73.     of be less than 100 bytes and that are not containers.
  74.  
  75.     After the function is created, you can run the function's script 
  76.     block by calling the function name in your Windows PowerShell commands, 
  77.     as shown in the following example:
  78.  
  79.         small_files
  80.  
  81.     When you run this command, it returns files with less than 100 bytes.
  82.  
  83.     You can create filters in much the same way as you create regular 
  84.     functions. The following example defines a filter named process_c.
  85.  
  86.         filter process_c
  87.         {
  88.             $_.processname -like "c*"
  89.         }
  90.  
  91.     In this definition, the script block provides the code that can be used 
  92.     within a Where-Object command to filter data. For example, the 
  93.     following command runs the Get-Process cmdlet and then pipes the process
  94.     objects to the Where-Object cmdlet.
  95.  
  96.         Get-Process | where { process_c }
  97.  
  98.     The data that the command returns includes all processes with names that
  99.     begin with the letter c.
  100.  
  101.     USING PARAMETERS
  102.     One of the most useful aspects of a function is the ability to pass 
  103.     data to and from the function when it is called. By default, all 
  104.     arguments passed to a function are bound to the $args automatic variable. 
  105.     You can reference the arguments within your function definition by
  106.     using the index keys that are associated with the $args values, starting
  107.     with 0.
  108.  
  109.     For example, the following function adds two numbers. The $args variable
  110.     in the script block specifies how the $args values are added.
  111.  
  112.         function add2
  113.         {
  114.             $args[0] + $args[1]
  115.         }
  116.  
  117.     When you call this function, you specify the numbers to be added. For 
  118.     example, to add 126 and 27, enter the following command at the Windows
  119.     PowerShell command prompt:
  120.  
  121.         add2 126 27
  122.  
  123.     The command returns 153.
  124.  
  125.     Windows PowerShell also allows you to define your own parameters in a
  126.     function definition. Add the parameter definitions within the braces and
  127.     just before the script block, as shown in the following example:
  128.  
  129.         function global:name_age
  130.         {
  131.             param([string]$first, [string]$last, [int]$age)
  132.             Write-Output "$last, $first : $age" 
  133.         }
  134.  
  135.     The function defines three parameters: $first, $last, and $age. The
  136.     parameter definitions follow the "param" keyword. They are enclosed in
  137.     parentheses and are separated by commas. In this example, a data type is
  138.     specified for each parameter. Although this is optional, it's 
  139.     generally recommended to prevent users from entering the wrong type of
  140.     data. You can also specify data types for the $args values.
  141.  
  142.     The function definition in the previous example also specifies a scope for 
  143.     the function. In this case, the scope is global, but you can assign any 
  144.     applicable scope. When you assign a scope, be sure to use a colon 
  145.     (but no spaces) to separate the scope name from the function name.
  146.  
  147.     When you call the name_age function, you should specify a first name, 
  148.     last name, and age, as shown in the following example:
  149.  
  150.         name_age Brad Sutton 45
  151.  
  152.     The command returns the following results:
  153.  
  154.         Sutton, Brad : 45
  155.  
  156.     You can also use the assignment operator (=) to specify default values
  157.     for the parameters. For example, the following function definition assigns
  158.     a default value of "unknown" to $first and $last and a value of 0 to $age.
  159.  
  160.         function name_age
  161.         {
  162.             param([string]$first = "unknown",
  163.             [string]$last = "unknown",
  164.             [int]$age = 0)
  165.             Write-Output "$last, $first : $age"
  166.         }
  167.  
  168.     If the function were called without all of the required data, three values
  169.     would still be returned. For example, the following command returns a 0
  170.     value for age:
  171.  
  172.         name_age Brad Sutton
  173.  
  174.         Sutton, Brad : 0
  175.  
  176.     There are two types of parameters, positional and named. When a parameter
  177.     is positional and you specify arguments without parameter names, the
  178.     parameter values must appear in the command in the order in which they are
  179.     defined. If you specify the parameter names, you can list the values in any
  180.     order. For example, the following command specifies only the last name and
  181.     age:
  182.  
  183.         name_age -age 45 -last Sutton
  184.  
  185.     The command returns an "unknown" value for the first name, as shown in 
  186.     the following results:
  187.  
  188.         Sutton, unknown : 45
  189.  
  190.     You can also define parameters in filters. For example, to create a filter
  191.     that returns a list of processes with a certain initial letter, use
  192.     a format such as the following:
  193.  
  194.         filter process_1
  195.         {
  196.             param([string]$first)
  197.             $_.processname -like "$first*"
  198.         }
  199.  
  200.     When you call the filter, you must specify the first letter as an 
  201.     argument, as shown in the following example:
  202.  
  203.         Get-Process | where { process_1 c }
  204.  
  205.     This command returns all system processes that begin with the 
  206.     letter "c."
  207.  
  208.     IMPLEMENTING FUNCTIONS AND FILTERS
  209.     You can define any function or filter at the Windows PowerShell command
  210.     prompt. However, that function or filter will not be available when you
  211.     restart Windows PowerShell. If you want your definition to be available
  212.     beyond the current session, you must add it to your a Windows Powershell
  213.     profile or create a script file.
  214.  
  215.     If you create a script file, use the name of the function or filter as
  216.     the file name and append the .ps1 extension. If you save the .ps1 file 
  217.     to the location specified in the $pshome variable, you do not have to 
  218.     specify a path to the file when you run it.
  219.  
  220. SEE ALSO    
  221.     For information about variables, type:
  222.  
  223.         help about_automatic_variables 
  224.  
  225.     and
  226.     help about_shell_variable
  227.  
  228.     For information about parameters, enter the following command:
  229.  
  230.         help about_parameter
  231.  
  232.     For information about script blocks, enter the following command:
  233.  
  234.         help about_script_block
  235.  
  236.     For information about scope, enter the following command:
  237.  
  238.         help about_scope
  239.  
  240.     For information about filtering, enter the following command:
  241.  
  242.         help about_filter
  243.