home *** CD-ROM | disk | FTP | other *** search
/ Chip 2008 June / CHIP-2008-06.iso / software / PowerShell / PowerShell_Setup_x86.msi / product.cab / about_Method.help_EN.txt < prev    next >
Encoding:
Text File  |  2007-10-29  |  6.6 KB  |  142 lines
  1. TOPIC
  2.     Methods
  3.  
  4. SHORT DESCRIPTION
  5.     Using methods to perform actions on objects in the Windows PowerShell 
  6.  
  7. LONG DESCRIPTION
  8.     PowerShell uses structured collections of information, called objects, to 
  9.     represent items in data stores or the state of the computer. For 
  10.     example, when you access a file in PowerShell, you're not working with the 
  11.     actual file, but instead you're working with a FileInfo object, a type 
  12.     of object that acts as the file's proxy.
  13.  
  14.     Most objects include methods. A method is a set of instructions that 
  15.     specify a particular action you can take with that object. For 
  16.     instance, the FileInfo object includes a method called CopyTo, which 
  17.     allows you to copy the file represented by the object.
  18.  
  19.     To view a list of methods and method definitions associated with a 
  20.     particular object, you can use the Get-Member Cmdlet. However, to use 
  21.     the Cmdlet, the object must already exist in some form, either as 
  22.     represented through a variable, as an object created when you specify a 
  23.     command as an argument to the Get-Member command, or as an object 
  24.     passed down a pipeline. For example, suppose that the $a variable has 
  25.     been assigned a string value, which means that the variable is 
  26.     associated with a string object. To view a list of the object's 
  27.     methods, enter the following command at the PowerShell command prompt:
  28.  
  29.         Get-Member -inputobject $a -membertype method
  30.  
  31.     If you want to see what methods and method definitions are associated 
  32.     with an object that is passed down the pipeline, you would use a Get-
  33.     Member command within the pipeline, as shown in the following example:
  34.  
  35.         Get-ChildItem c:\final.txt | Get-Member -membertype method
  36.  
  37.     The most common way to invoke a method is to specify the method name 
  38.     after an object reference (such as a variable or expression). You must 
  39.     separate the object reference and the method with a period. In 
  40.     addition, you must use parentheses immediately following the method 
  41.     name to enclose any arguments that should be passed to the method. 
  42.  
  43.     If no arguments are being passed in a method signature, you must still 
  44.     use a set of empty parentheses.
  45.  
  46.     For example, the following command uses the GetType() method to return 
  47.     the data type associated with the $a string object:
  48.  
  49.         $a.GetType()
  50.  
  51.     The GetType() method will return the data type for any object, and a 
  52.     variable always represents an object. The type of object depends on the 
  53.     type of data stored within that variable.
  54.  
  55.     Every action you take in PowerShell is associated with objects, whether 
  56.     you're declaring a variable or combining commands into a pipeline. As a 
  57.     result, methods can be used in a variety of situations. For example, 
  58.     you can use a method to take an action on a property value, as shown in 
  59.     the following command:
  60.  
  61.         (Get-ChildItem c:\final.txt).name.ToUpper()
  62.  
  63.     In this case, the object on which the ToUpper method is being invoked 
  64.     is the string object associated with the name property. (Note that the 
  65.     final.txt file must exist on the root of the c: drive for this example 
  66.     to work.) The name property is actually a property of the FileInfo 
  67.     object returned by the Get-ChildItem command. This demonstrates not 
  68.     only the object-oriented nature of PowerShell, but shows how methods 
  69.     can be called on any accessible object.
  70.  
  71.     You can achieve the same results as the last example by using a 
  72.     variable to store the Get-ChildItem command output, as shown in the 
  73.     following example:
  74.  
  75.         $a = (Get-ChildItem c:\final.txt).name
  76.         $a.ToUpper()
  77.  
  78.     The command again uses the ToUpper() method of the string object 
  79.     associated with the variable, which contains the filename returned by 
  80.     the Get-ChildItem command.
  81.  
  82.     In some cases, a method requires an argument to direct the action of 
  83.     that method. For example, the FileInfo object includes the MoveTo() 
  84.     method, which provides a way to move a file from one location to 
  85.     another. The method requires an argument that specifies the target 
  86.     location for the file. The following command demonstrates how to 
  87.     include that argument:
  88.  
  89.         (Get-ChildItem c:\final.txt).MoveTo("c:\techdocs\final.txt")
  90.  
  91.     The Get-ChildItem command returns a FileInfo object for the final.txt 
  92.     file and then uses the MoveTo method of that object to initiate the 
  93.     action and to specify the file's new location.
  94.  
  95.     To determine the arguments associated with a method, review the 
  96.     corresponding method definition. A method definition contains one or 
  97.     more method signatures (also known as overloads in the .NET Framework). 
  98.     A method signature contains the name of a method and zero or more 
  99.     parameters that you must supply when you call the method. Each method 
  100.     signature is separated from the prior signature with a comma in the 
  101.     Get-Member Cmdlet display. For example, the CopyTo method of the 
  102.     FileInfo class contains the following two method signatures:
  103.  
  104.         1. CopyTo(String destFileName)
  105.         2. CopyTo(String destFileName, Boolean overwrite)
  106.  
  107.     The first method signature takes the destination filename (including 
  108.     the path) in which to copy the source file. In the following example, 
  109.     the first CopyTo method is used to copy final.txt to the c:\bin 
  110.     directory:
  111.  
  112.         (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt")
  113.  
  114.     If the file already exists in the destination location, the CopyTo 
  115.     method will fail and PowerShell will report the following error:
  116.  
  117.         Exception calling "CopyTo" with "1" argument(s): "The file
  118.         'c:\bin\final.txt' already exists.".
  119.  
  120.     In the second method signature, you pass the destination filename just 
  121.     as you did in the first case, but you also pass a boolean value to 
  122.     specify whether you want an existing file of the same name in the 
  123.     destination location to be overwritten, as the following example shows:
  124.  
  125.         (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true)
  126.  
  127.     When you pass the boolean value, you must use the $true variable, which 
  128.     is created automatically by PowerShell. The $true variable contains the 
  129.     "true" boolean value. (As you would expect, the $false variable contains 
  130.     the "false" boolean value.)
  131.  
  132. SEE ALSO
  133.     For information about objects, enter the following command:
  134.  
  135.         help about_object
  136.  
  137.     For information about the Get-Member Cmdlet, enter the following 
  138.     command:
  139.  
  140.         help Get-Member
  141.  
  142.