home *** CD-ROM | disk | FTP | other *** search
/ Chip 2008 June / CHIP-2008-06.iso / software / PowerShell / PowerShell_Setup_x86.msi / product.cab / about_scriptcmdletmethods.help_EN.txt < prev    next >
Encoding:
Text File  |  2007-10-29  |  2.7 KB  |  78 lines
  1. TOPIC
  2. Script Cmdlet Methods and Properties
  3.  
  4. SHORT DESCRIPTION
  5. Methods and properties available to script cmdlets and Begin, Process, and 
  6. End methods.
  7.  
  8. LONG DESCRIPTION
  9. Script cmdlets can access a number of methods and properties through the 
  10. $cmdlet variable. These methods include the ShouldProcess met5hod used to 
  11. get user feedback, the ThrowTerminatingError method for generating error 
  12. records, several Write methods for emiting output from the cmdlet, and 
  13. more. All the methods and properties available to script cmdlets are 
  14. documented in the PSCmdlet class on MSDN.
  15.  
  16.  
  17. INPUT PROCESSING METHODS
  18.  
  19. The three methods described here are referred to as the input processing 
  20. methods of a cmdlet. In fact, this is the same for compiled and script 
  21. cmdlets. 
  22.  
  23. Each script cmdlet must overwrite one or more of the three input processing 
  24. methods. The Windows PowerShell runtime calls these methods when it is 
  25. running the commands of a pipeline. 
  26.  
  27. Begin{}
  28. This input processing method is used to provide optional one-time, pre-
  29. processing functionality for the cmdlet. The Windows PowerShell runtime 
  30. calls this method once for each instance of the cmdlet in the pipeline.
  31.  
  32. Process{}
  33. This input processing method is used to provide record-by-record processing 
  34. functionality for the cmdlet. This method might be called any number of 
  35. times, or not at all, depending on the input to the cmdlet. For example, if 
  36. the cmdlet is the first in the pipeline then it will get called once. Also, 
  37. if the cmdlet is not the first command of the pipeline then thew Process 
  38. method is called once for every input it receives from the pipeline. If 
  39. there is no pipeline input then the Process method is not called.
  40.  
  41. This method must be called if a cmdlet parameter is defined as accepting 
  42. ValueFromPipeline or ValueFromPipelineByPropertyName. If this method is 
  43. not overwritten, the cmdlet will miss the pipelined values passed to the 
  44. cmdlet. 
  45.  
  46. Also, when the cmdlet supports confirmation requests (when the 
  47. -SupportsSouldProcess attribute is declared), the call to the 
  48. ShouldProcess method must be made from within The Process{} method.
  49.  
  50. End{}
  51. This input processing method is used to provide optional one-time, post-
  52. processing functionality for the cmdlet.
  53.  
  54. The following example shows the outline of a script cmdlet with 
  55. a Begin{} method for one-time pre-processing, a Process{} method for 
  56. multiple record processing, and an End{} method for one-time post-
  57. processing.
  58.  
  59. Cmdlet Test-ScriptCmdlet
  60.   -SupportsShouldProcess
  61.   -ConfirmImpact low
  62.   -snapin MySnapIn
  63.  
  64.   {
  65.     Param ([Mandatory] $Parameter1)
  66.     Begin{}
  67.     Process{}
  68.     End{}
  69.   }
  70.  
  71.  
  72.  
  73.  
  74. SEE ALSO
  75.  
  76. About_ScriptCmdlets
  77. About_ScriptCmdletAttributes
  78. About_ScriptCmdletParameters