home *** CD-ROM | disk | FTP | other *** search
/ Chip 2008 June / CHIP-2008-06.iso / software / PowerShell / PowerShell_Setup_x86.msi / product.cab / about_Parameter.help_EN.txt < prev    next >
Encoding:
Text File  |  2007-10-29  |  10.1 KB  |  211 lines
  1. TOPIC
  2.     Cmdlet parameters
  3.  
  4. SHORT DESCRIPTION
  5.     Working with Cmdlet parameters in the Windows PowerShell 
  6.  
  7. LONG DESCRIPTION
  8.     Most PowerShell Cmdlets rely on parameters. Parameters are Cmdlet elements 
  9.     that provide information to the Cmdlet. The information either 
  10.     identifies the items to be acted upon by the command or controls how 
  11.     the Cmdlet carries out its job.
  12.  
  13.     When creating a command that include Cmdlet parameters, the parameters 
  14.     follow the Cmdlet name and usually take the following form:
  15.  
  16.         -<parameter_name> <parameter_value>
  17.  
  18.     The name of the parameter is preceded by a hyphen (-), which signals to 
  19.     PowerShell that the word following the hyphen is a parameter and not a 
  20.     value being passed to the Cmdlet. Not all parameters require a value, and 
  21.     not all parameter names must be specified. In some cases, the parameter 
  22.     name is implied and does not need to be explicitly included.
  23.  
  24.     The type of parameters and the requirements for those parameters vary 
  25.     from Cmdlet to Cmdlet. To find information on a Cmdlet's parameters, 
  26.     use the Get-Help Cmdlet to retrieve information about the specific 
  27.     Cmdlet. For example, to find information about the parameters supported 
  28.     by the Get-ChildItem Cmdlet, enter the following command at the PowerShell 
  29.     command prompt:
  30.  
  31.         help Get-ChildItem
  32.  
  33.     The command returns various details about the Cmdlet, including a 
  34.     description of the Cmdlet, the command syntax, and information about 
  35.     the parameters. From this information, you'll find the sections on the 
  36.     syntax and the parameters the most helpful in determining how to use 
  37.     the parameters for that Cmdlet. For example, the Help information on 
  38.     the Get-ChildItem Cmdlet includes the following syntax:
  39.  
  40.         Get-ChildItem [-Path] path [-Include includeFilter] 
  41.         [-Exclude excludeFilter] 
  42.         [-Filter providerSpecificFilter] [-Force []]
  43.  
  44.     The syntax shows the Cmdlet name (Get-ChildItem), followed by a list of 
  45.     parameters. Elements that are optional are shown in brackets. If a 
  46.     value is required for a parameter, a placeholder follows the parameter 
  47.     name. For example, the first elements after the Cmdlet name are "[-
  48.     Path] path." [-Path] is the name of the parameter. Because it is 
  49.     bracketed, you do not have to specify -Path when providing a directory 
  50.     path. However, notice that the second "path" is not bracketed. This is 
  51.     a placeholder for the actual value, and it is required. All other 
  52.     elements in the syntax are optional.
  53.  
  54.     In addition to the command syntax, the Get-Help command returns 
  55.     parameter information. This information includes the details you need 
  56.     about all the individual parameters. For example, the Help information 
  57.     for the Get-ChildItem Cmdlet includes the following details about the -
  58.     Path parameter:
  59.  
  60.         -Path pathname
  61.             The path to the file that will become the output file.
  62.         Wildcards are allowed but they must resolve to a single name.
  63.  
  64.             Parameter required?      true
  65.             Parameter position?      1
  66.             Parameter type        String
  67.             Default value         
  68.             Accept multiple values?    false
  69.             Accepts pipeline input?    true
  70.             Accepts wildcard characters? true
  71.  
  72.     Notice that the information includes details about seven settings. 
  73.     These settings are common to most parameters. The following sections 
  74.     describe each of these settings:
  75.  
  76.     PARAMETER REQUIRED?
  77.     This setting indicates whether the command will run if you do not 
  78.     supply this parameter. When set to "true, you must provide the 
  79.     parameter when running this Cmdlet. If you do not supply the parameter, 
  80.     the command prompts you for a value.
  81.  
  82.     PARAMETER POSITION?
  83.     This setting indicates whether you can supply a parameter's value 
  84.     without preceding it with the parameter name. If set to "0" or "named," 
  85.     a parameter is required. This type of parameter is referred to as a 
  86.     "named" parameter. A named parameter can be listed in any position 
  87.     after the Cmdlet name.
  88.  
  89.     If the Parameter position? setting is set to an integer other than 0, 
  90.     the parameter name is not required. This type of parameter is referred 
  91.     to as a "positional" parameter, and the number indicates the position 
  92.     that the parameter must appear in relation to other positional 
  93.     parameters. If you include the parameter name for a positional 
  94.     parameter, the parameter can be listed in any position after the Cmdlet 
  95.     name.
  96.  
  97.     For example, the Get-ChildItem includes the -Path parameter and the -
  98.     Exclude parameter. The Parameter position? setting for -Path is 1, 
  99.     which means that it's a positional parameter. The Parameter position? 
  100.     setting for -Exclude is 0, which means that it's a named parameter. 
  101.     This means that -Path does not require the parameter name; however, the 
  102.     parameter value must be the first of the positional parameter values 
  103.     listed, if those other parameter values are listed without a name. On 
  104.     the other hand, because the -Exclude parameter is a named parameter, 
  105.     you can place it in any position.
  106.  
  107.     As a result of the Parameter position? settings for these two 
  108.     parameters, you can use any of the following commands:
  109.  
  110.         Get-ChildItem -path c:\techdocs -exclude *.ppt
  111.         Get-ChildItem c:\techdocs -exclude *.ppt
  112.         Get-ChildItem -exclude *.ppt -path c:\techdocs
  113.         Get-ChildItem -exclude *.ppt c:\techdocs
  114.  
  115.     If you were to include another positional parameter without including 
  116.     the parameter name, that parameter would have to be placed in the order 
  117.     specified by the Parameter position? setting, relative to the -Path 
  118.     positional parameter.
  119.  
  120.     PARAMETER TYPE
  121.     This setting specifies the form that the parameter's value should take. 
  122.     This refers to the .NET type that determines the kind of value that is 
  123.     permitted as a parameter argument. For example, if the type is set to 
  124.     int32, the parameter argument must be an integer, such as 0, 5, or 100. 
  125.     If the type is set to string, the argument must be in the form of a 
  126.     character string. If the string contains spaces, the value must be 
  127.     enclosed in quotation marks or the spaces must be preceded by the 
  128.     escape character (`).
  129.  
  130.     DEFAULT VALUE
  131.     This setting provides a default value that the parameter will assume if 
  132.     no other value is provided. Required parameters never have a default 
  133.     value, nor do many optional parameters. For example, many commands that 
  134.     accept a -Path parameter use the current working location as the value 
  135.     if you do not supply the parameter.
  136.  
  137.     ACCEPTS MULTIPLE VALUES?
  138.     This setting indicates whether a parameter will accept multiple values 
  139.     in a single argument. If a command accepts multiple values, you can 
  140.     supply more than one value on the command line, or you can construct an 
  141.     array and supply the array as the parameter value. If you supply more 
  142.     than one value on the command line, you must separate each value with a 
  143.     comma (,).
  144.  
  145.     For instance, the Get-Service Cmdlet includes the -ServiceName 
  146.     parameter, which accepts multiple values. You can include those values 
  147.     as one argument, as shown in the following command:
  148.  
  149.         Get-Service -servicename b*, c*
  150.  
  151.     Note that, if a string value contains a comma, the value must be 
  152.     enclosed in quotation marks so the string will not be treated as two 
  153.     separate values.
  154.  
  155.     ACCEPTS PIPELINE INPUT?
  156.     This setting indicates whether the parameter can receive its value as 
  157.     input from a pipeline object. In order to use a command in a pipeline, 
  158.     the applicable parameter must have this option set to True to receive 
  159.     the pipeline input.
  160.  
  161.     ACCEPTS WILDCARD CHARACTERS?
  162.     This setting indicates whether the parameter's value can contain 
  163.     wildcard characters so that the parameter value can be matched to more 
  164.     than one existing item in the target container.
  165.  
  166.     UBIQUITOUS PARAMETERS
  167.     Cmdlets are created by subclassing the base Cmdlet object. The base 
  168.     object includes a number of parameters to ensure that each Cmdlet 
  169.     shares a level of consistency. The following table provides a list of 
  170.     the ubiquitous parameters:
  171.  
  172.     Parameter     Type    Description
  173.     ------------- ------- -------------------------------------------------
  174.     Confirm       boolean Prompts user before taking any action that 
  175.                           modifies the system
  176.     Debug         boolean Provides programming-level information about the 
  177.                           operation
  178.     ErrorAction   enum    Controls command behavior when error occurs
  179.     ErrorVariable string  Name of variable (in addition to $error) in which 
  180.                           to place objects to which an error has occurred
  181.     OutputBuffer  int32   Controls the number of objects to be buffered 
  182.                           between this command and the next (useful for
  183.                           tweaking performance)
  184.     OutVariable   string  Name of variable in which to place output objects
  185.                           (equivalent to piping the command 
  186.                           Set-Variable <name> -passthru true)
  187.     Verbose       boolean Provides detailed information about the operation
  188.     WhatIf        boolean Provides information about the changes that would 
  189.                           occur, but does not make those changes
  190.  
  191. SEE ALSO
  192.     For information about any of a Cmdlet's parameters, use the help alias 
  193.     (for the Get-Help Cmdlet) plus the Cmdlet name. For example, to view 
  194.     parameter information about the Set-Alias Cmdlet, enter the following 
  195.     command:
  196.  
  197.         help Set-Alias
  198.  
  199.     For information about command syntax, enter the following command:
  200.  
  201.         help about_command_syntax
  202.  
  203.     For information about pipelines, enter the following command:
  204.  
  205.         help about_pipeline
  206.  
  207.     For information about wildcards, enter the following command:
  208.  
  209.         help about_wildcard
  210.  
  211.