about_Methods

Applies To: Windows PowerShell 2.0

TOPIC
    about_methods

SHORT DESCRIPTION
    Describes how to use methods to perform actions on objects in Windows 
    PowerShell.
 

LONG DESCRIPTION
    Windows PowerShell uses structured collections of information, called 
    objects, to represent the items in data stores or the state of the 
    computer. For example, when you access a file in Windows PowerShell, you
    are not working with the actual file. Instead, you are working with a
    FileInfo object, a type of object that acts as the file's proxy.


    Most objects include methods. A method is a set of instructions that 
    specify a particular action you can take with that object. For instance,
    the FileInfo object includes a method called CopyTo, which allows you to
    copy the file represented by the object.


    To view a list of methods and method definitions associated with a 
    particular object, you can use the Get-Member cmdlet. However, to use 
    the cmdlet, the object must already exist in some form, either as 
    represented through a variable, as an object created when you specify a 
    command as an argument to the Get-Member command, or as an object 
    passed down a pipeline. For example, suppose that the $a variable has 
    been assigned a string value, which means that the variable is 
    associated with a string object. To view a list of the object's 
    methods, enter the following command at the Windows PowerShell command 
    prompt:


        Get-Member -inputobject $a -membertype method


    If you want to see which methods and method definitions are associated 
    with an object that is passed down the pipeline, you would use a 
    Get-Member command within the pipeline, as shown in the following example:


        Get-ChildItem c:\final.txt | Get-Member -membertype method


    The most common way to invoke a method is to specify the method name 
    after an object reference (such as a variable or expression). You must 
    separate the object reference and the method with a period. Additionally,
    you must use parentheses immediately following the method name to enclose
    any arguments that should be passed to the method. 


    If no arguments are being passed in a method signature, you must still 
    use a set of empty parentheses.


    For example, the following command uses the GetType method to return the 
    data type associated with the $a string object:


        $a.GetType()


    The GetType method will return the data type for any object, and a 
    variable always represents an object. The type of object depends on the 
    type of data stored within that variable.


    Every action you take in Windows PowerShell is associated with objects, 
    whether you are declaring a variable or combining commands into a pipeline.
    As a result, methods can be used in a variety of situations. For example, 
    you can use a method to take an action on a property value, as shown in 
    the following command:


        (Get-ChildItem c:\final.txt).name.ToUpper()


    In this case, the object on which the ToUpper method is being invoked is 
    the string object associated with the name property. (Note that the 
    Final.txt file must exist on the root of the C: drive for this example 
    to work.) The name property is actually a property of the FileInfo object
    returned by the Get-ChildItem command. This demonstrates not only the 
    object-oriented nature of Windows PowerShell, but shows how methods can be
    called on any accessible object.


    You can achieve the same results as the last example by using a 
    variable to store the Get-ChildItem command output, as shown in the 
    following example:


        $a = (Get-ChildItem c:\final.txt).name
        $a.ToUpper()


    The command again uses the ToUpper method of the string object 
    associated with the variable, which contains the file name returned by 
    the Get-ChildItem command.


    In some cases, a method requires an argument to direct the action of 
    that method. For example, the FileInfo object includes the MoveTo 
    method, which provides a way to move a file from one location to 
    another. The method requires an argument that specifies the target 
    location for the file. The following command demonstrates how to 
    include that argument:


        (Get-ChildItem c:\final.txt).MoveTo("c:\techdocs\final.txt")


    The Get-ChildItem command returns a FileInfo object for the Final.txt 
    file and then uses the MoveTo method of that object to initiate the 
    action and to specify the file's new location.


    To determine the arguments associated with a method, review the 
    corresponding method definition. A method definition contains one or 
    more method signatures (also known as overloads in the Microsoft 
    .NET Framework). A method signature contains the name of a method and zero
    or more parameters that you must supply when you call the method. Each 
    method signature is separated from the prior signature with a comma in the 
    Get-Member cmdlet display. For example, the CopyTo method of the 
    FileInfo class contains the following two method signatures:


        1. CopyTo(String destFileName)
        2. CopyTo(String destFileName, Boolean overwrite)


    The first method signature takes the destination file name (including 
    the path) in which to copy the source file. In the following example, 
    the first CopyTo method is used to copy Final.txt to the C:\Bin 
    directory:


        (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt")


    If the file already exists in the destination location, the CopyTo 
    method fails, and Windows PowerShell reports the following error:


        Exception calling "CopyTo" with "1" argument(s): "The file
        'c:\bin\final.txt' already exists.".


    In the second method signature, you pass the destination file name just 
    as you did in the first case, but you also pass a Boolean value to 
    specify whether you want an existing file of the same name in the 
    destination location to be overwritten, as the following example shows:


        (Get-ChildItem c:\final.txt).CopyTo("c:\bin\final.txt", $true)


    When you pass the Boolean value, you must use the $True variable, which 
    is created automatically by Windows PowerShell. The $True variable 
    contains the "true" Boolean value. (As you would expect, the $False 
    variable contains the "false" Boolean value.)


SEE ALSO
    about_Objects
    about_Properties
    Get-Member