Using Functions

Functions are a type of command in Windows PowerShell. You run a function by typing its name, just like you run a cmdlet. Functions can have parameters just like cmdlets. Functions can take .NET objects as input and return .NET objects as output just like cmdlets. In fact, functions can do just about everything that cmdlets can do.

The best thing about functions is that they are really easy to write. Unlike cmdlets, which are written in C#, functions are just a named grouping of Windows PowerShell commands and expressions. If you can type commands in Windows PowerShell, you can write functions.

Functions are commands, so to find functions, use the Get-Command cmdlet.

For example, to find all functions in your session, type:

get-command -CommandType function

Windows PowerShell also comes with a Function: drive that contains all functions in your session. To navigate in the Function: drive, use the same methods that you use to navigate in the file system drives.

To enter the function drive, type:

cd function:

To display the functions in the function drive, type:

dir function:

To run a function, just type the function name. For example, to run the Clear-Host function, type:

clear-host

In the Windows PowerShell Console, the Clear-Host function deletes all of the text in the console window. It might behave differently or have no effect in other hosting programs.

To use the parameters of a function, type the parameter name preceded, by a hyphen and followed by a value, just as would do for the parameters of a cmdlet.

For example, the Help function, which displays Help topics one page at a time, has the same parameters as the Get-Help cmdlet. To use the Help function to get only the examples in the Help topic for the Get-Service cmdlet, type:

help -name get-service -examples

Functions can have Help topics. To find the Help topic for a function, use the Get-Help cmdlet. This is the same cmdlet that you use to get Help for cmdlets.

For example, to get Help for the Disable-PSRemoting function, type:

get-help Disable-PSRemoting

You can use all of the parameters of the Get-Help cmdlet to get Help for functions. For example, to get only the examples in the Help topic for the Disable-PSRemoting function, type:

get-help Disable-PSRemoting -example

A function is a named group of commands or expressions. To write a simple function, use the following format.

function <name> { <commands> }

Just type function, a name for the function, and enclose the commands in braces ({ }).

For example, if you repeatedly type a particular command, such as get-help get-member -examples, you can save time by writing a function that runs the command. The following function, called GMEX, runs the command.

function GMEX {get-help get-member -examples}

After you type the function at the Windows PowerShell prompt (or copy and paste it from this topic) and then press ENTER, you can use the function in your session. To run the function, type GMEX.

This is a simple function, but with just a few more lines, you can add parameters, make the parameters optional or mandatory, add user messages, and add a Help topic for your function. When you learn more about Windows PowerShell, you can write advanced functions that have all of the features of cmdlets.

For more information about writing functions, see about_Functions, about_Comment_Based_Help, and about_Functions_Advanced.

When you open Windows PowerShell, you are in a Windows PowerShell session. The session lasts until you close the Windows PowerShell window (or type Exit to end the session). Unless you save an item to a file on disk or save it in the registry, the items that you create in your session are deleted when your session ends.

To save the functions that you write so that they are available in future Windows PowerShell sessions, create a Windows PowerShell profile and save your functions in your profile.

For more information, see about_Profiles.