about_Methods

Article
09/19/2022

Short description

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

Long description

PowerShell uses objects to represent the items in data stores or the state of the computer. For example, FileInfo objects represent the files in file system drives and ProcessInfo objects represent the processes on the computer.

Objects have properties, which store data about the object, and methods that let you change the object.

A "method" is a set of instructions that specify an action you can perform on the object. For example, the FileInfo object includes the CopyTo method that copies the file that the FileInfo object represents.

To get the methods of any object, use the Get-Member cmdlet. Use its MemberType property with a value of "Method". The following command gets the methods of process objects.

Get-Process | Get-Member -MemberType Method

TypeName: System.Diagnostics.Process

Name                      MemberType Definition
----                      ---------- ----------
BeginErrorReadLine        Method     System.Void BeginErrorReadLine()
BeginOutputReadLine       Method     System.Void BeginOutputReadLine()
...
Kill                      Method     System.Void Kill()
Refresh                   Method     System.Void Refresh()
Start                     Method     bool Start()
ToString                  Method     string ToString()
WaitForExit               Method     bool WaitForExit(int milliseconds), ...
WaitForInputIdle          Method     bool WaitForInputIdle(int millisecon...

To perform or "invoke" a method of an object, type a dot (.), the method name, and a set of parentheses "()". If the method has arguments, place the argument values inside the parentheses. The parentheses are required for every method call, even when there are no arguments. If the method takes multiple arguments, they should be separated by commas.

For example, the following command invokes the Kill method of processes to end the Notepad process on the computer.

$notepad = Get-Process notepad
$notepad.Kill()

This example can be shortened by combining the above statements.

(Get-Process Notepad).Kill()

The Get-Process command is enclosed in parentheses to ensure that it runs before the Kill method is invoked. The Kill method is then invoked on the returned Process object.

Another very useful method is the Replace method of strings. The Replace method, replaces text within a string. In the example below, the dot (.) can be placed immediately after the end quote of the string.

'this is rocket science'.Replace('rocket', 'rock')

this is rock science

As shown in the previous examples, you can invoke a method on an object that you get by using a command, an object in a variable, or anything that results in an object (like a string in quotes).

Starting in PowerShell 4.0, method invocation by using dynamic method names is supported.

Learning about methods

To find definitions of the methods of an object, go to help topic for the object type and look for its methods page. For example, the following page describes the methods of process objects System.Diagnostics.Process.

To determine the arguments of a method, review the method definition, which is like the syntax diagram of a PowerShell cmdlet.

A method definition might have one or more method signatures, which are like the parameter sets of PowerShell cmdlets. The signatures show all of the valid formats of commands to invoke the method.

For example, the CopyTo method of the FileInfo class contains the following two method signatures:

    CopyTo(String destFileName)
    CopyTo(String destFileName, Boolean overwrite)

The first method signature takes the destination file name (and a path). The following example uses the first CopyTo method to copy the Final.txt file to the C:\Bin directory.

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

Note

Unlike PowerShell's argument mode, object methods execute in expression mode, which is a pass-through to the .NET framework that PowerShell is built on. In expression mode bareword arguments (unquoted strings) are not allowed. You can see this difference when using the path as a parameter, versus the path as an argument. You can read more about parsing modes in about_Parsing

The second method signature takes a destination file name and a Boolean value that determines whether the destination file should be overwritten, if it already exists.

The following example uses the second CopyTo method to copy the Final.txt file to the C:\Bin directory, and to overwrite existing files.

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

Member-access enumeration

Starting in PowerShell 3.0, when you use the member-access operator (.) to access a method that does not exist on a list collection, PowerShell automatically enumerates the items in the collection and invokes the method on each item. For more information, see about_Member-Access_Enumeration.

Examples

The following example runs the Kill method of individual process objects in a collection of objects.

The first command starts three instances of the Notepad process. Get-Process gets all three instance of the Notepad process and saves them in the $p variable.

Notepad; Notepad; Notepad
$p = Get-Process Notepad
$p.Count

The next command runs the Kill method on all three processes in the $p variable. This command works even though a collection of processes does not have a Kill method.

$p.Kill()
Get-Process Notepad

The Get-Process command confirms that the Kill method worked.

Get-Process : Cannot find a process with the name "notepad". Verify the proc
ess name and call the cmdlet again.
At line:1 char:12
+ Get-Process <<<<  notepad
    + CategoryInfo          : ObjectNotFound: (notepad:String) [Get-Process]
, ProcessCommandException
    + FullyQualifiedErrorId : NoProcessFoundForGivenName,Microsoft.PowerShel
l.Commands.GetProcessCommand

This example is functionally equivalent to using the Foreach-Object cmdlet to run the method on each object in the collection.

$p | ForEach-Object {$_.Kill()}

ForEach and Where methods

Beginning in PowerShell 4.0, collection filtering using a method syntax is supported. This allows use of two new methods when dealing with collections ForEach and Where.

You can read more about these methods in about_arrays

Calling a specific method when multiple overloads exist

Consider the following scenario when calling .NET methods. If a method takes an object but has an overload via an interface taking a more specific type, PowerShell chooses the method that accepts the object unless you explicitly cast it to that interface.

Add-Type -TypeDefinition @'

   // Interface
   public interface IFoo {
     string Bar(int p);
   }

   // Type that implements the interface
   public class Foo : IFoo {

   // Direct member method named 'Bar'
   public string Bar(object p) { return $"object: {p}"; }

   // *Explicit* implementation of IFoo's 'Bar' method().
   string IFoo.Bar(int p) {
       return $"int: {p}";
   }

}
'@

In this example the less specific object overload of the Bar method was chosen.

[Foo]::new().Bar(1)

object: 1

In this example we cast the method to the interface IFoo to select the more specific overload of the Bar method.

([IFoo] [Foo]::new()).Bar(1)

int: 1

Using .NET methods that take filesystem paths

PowerShell supports multiple runspaces per process. Each runspace has its own current directory. This is not the same as the working directory of the current process: [System.Environment]::CurrentDirectory.

.NET methods use the process working directory. PowerShell cmdlets use the Runspace location. Also, .NET methods only work with native filesystem paths, not PowerShell Path objects. To use PowerShell paths with .NET methods, you must resolve the path to a filesystem-native path before passing it to the .NET method.

Share via