diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md index 7d549784ddb4..6a14dfe88f71 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 06/26/2024 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions @@ -16,10 +16,57 @@ Describes how to create and use functions in PowerShell. ## Long description A function is a list of PowerShell statements that has a name that you assign. -When you run a function, you type the function name. The statements in the list -run as if you had typed them at the command prompt. +When you run a function, you type the function name. -Functions can be as simple as: +PowerShell defines two kinds of functions: + +- A **function** is a block of code that can be called by name. It can take + input and return output. Functions are defined using the `function` keyword. +- A **filter** is a type of function designed to process data from the + pipeline. Filters are defined using the `filter` keyword. + +You can group the statements in a function into one of four different +predefined script blocks. These script blocks are named using the keywords +`begin`, `process`, and `end`. If you don't use these keywords, PowerShell puts +the statements in the appropriate code block. + +Functions can also act like cmdlets. You can create a function that works just +like a cmdlet without using `C#` programming. For more information, see +[about_Functions_Advanced][10]. + +> [!IMPORTANT] +> Within script files and script-based modules, functions must be defined +> before they can be called. + +## Function syntax + +Functions are defined using the following syntax: + +```Syntax +function [] { + param([type]$Parameter1 [,[type]$Parameter2]) + dynamicparam {} + begin {} + process {} + end {} +} +``` + +A function includes the following items: + +- A `function` keyword +- A scope (optional) +- A name that you select +- Any number of named parameters (optional), including dynamic parameters +- One or more PowerShell statements enclosed in braces `{}` + +If you don't use one of the keywords (`begin`, `process`, `end`) in a +`function` definition, PowerShell puts the statements in the `end` block. + +For more information about the `dynamicparam` keyword and dynamic parameters in +functions, see [about_Functions_Advanced_Parameters][09]. + +A function can be as simple as: ```powershell function Get-PowerShellProcess { Get-Process powershell } @@ -38,73 +85,51 @@ Get-PowerShellProcess 110 78.72 172.39 10.62 10936 1 powershell ``` -A function can also be as complex as a cmdlet or an application. - -Like cmdlets, functions can have parameters. The parameters can be named, -positional, switch, or dynamic parameters. Function parameters can be read from -the command line or from the pipeline. +A function can also be as complex as a cmdlet. Functions can return values that can be displayed, assigned to variables, or -passed to other functions or cmdlets. You can also specify a return value using -the `return` keyword. The `return` keyword doesn't affect or suppress other -output returned from your function. However, the `return` keyword exits the -function at that line. For more information, see [about_Return][16]. - -The function's statement list can contain different types of statement lists -with the keywords `begin`, `process`, and `end`. These statement lists handle -input from the pipeline differently. - -The [filter][04] keyword is used to create a type of function that runs on each -object in the pipeline. A filter resembles a function with all its statements -in a `process` block. - -Functions can also act like cmdlets. You can create a function that works just -like a cmdlet without using `C#` programming. For more information, see -[about_Functions_Advanced][11]. +passed to other functions or cmdlets. You can use the `return` keyword to +return output. The `return` keyword doesn't affect or suppress other output +returned from your function. However, the `return` keyword exits the function +at that line. For more information, see [about_Return][15]. -> [!IMPORTANT] -> Within script files and script-based modules, functions must be defined -> before they can be called. +## Filter syntax -## Syntax +The intent of the `filter` function is to provide a shorthand way of defining a +function that runs on each object in the pipeline. -The following are the syntax for a function: +The syntax of a filter is as follows: ```Syntax -function [] [([type]$Parameter1[,[type]$Parameter2])] -{ - begin {} - process {} - end {} -} +filter [] {} ``` -```Syntax -function [] -{ - param([type]$Parameter1 [,[type]$Parameter2]) - dynamicparam {} - begin {} - process {} - end {} +To simplify the syntax for `filter` functions, omit the script block keyword +(`begin`, `process`, `end`). PowerShell puts the statements in the `process` +block. You can use any of the other blocks in a filter function, but the intent +was to provide a shorthand way of defining a function that has the sole purpose +of processing each object in the pipeline. + +The following filter takes log entries from the pipeline and then displays +either the whole entry or only the message portion of the entry: + +```powershell +filter Get-EventMessage ([switch]$MessageOnly) { + if ($MessageOnly) { Out-Host -InputObject $_.Message } + else { $_ } } ``` -A function includes the following items: - -- A `function` keyword -- A scope (optional) -- A name that you select -- Any number of named parameters (optional) -- One or more PowerShell commands enclosed in braces `{}` +It can be used as follows: -For more information about the `dynamicparam` keyword and dynamic parameters in -functions, see [about_Functions_Advanced_Parameters][10]. +```powershell +Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly +``` ## Input processing methods The methods described in this section are referred to as the input processing -methods. For functions, these three methods are represented by the `begin`, +methods. For functions, these three methods named using the `begin`, `process`, and `end` blocks of the function. You aren't required to use any of these blocks in your functions. If you don't @@ -113,13 +138,12 @@ function. However, if you use any of these named blocks, or define a `dynamicparam` block, you must put all code in a named block. The following example shows the outline of a function that contains a `begin` -block for one-time preprocessing, a `process` block for multiple record -processing, and an `end` block for one-time post-processing. +block for one-time preprocessing, a `process` block data from the pipeline, and +an `end` block for one-time post-processing. ```powershell -Function Test-ScriptCmdlet -{ -[CmdletBinding(SupportsShouldProcess=$true)] +Function Test-ScriptCmdlet { + [CmdletBinding(SupportsShouldProcess=$true)] param ($Parameter1) begin{} process{} @@ -143,25 +167,25 @@ the function receives. The automatic variable `$_` or `$PSItem` contains the current object in the pipeline for use in the `process` block. The `$input` automatic variable contains an enumerator that's only available to functions and script blocks. -For more information, see [about_Automatic_Variables][05]. +For more information, see [about_Automatic_Variables][04]. -- Calling the function at the beginning, or outside of a pipeline, executes the - `process` block once. +- If the function is invoked without pipeline input, PowerShell executes the + `process` block only once. - Within a pipeline, the `process` block executes once for each input object that reaches the function. - If the pipeline input that reaches the function is empty, the `process` block - **does not** execute. + doesn't execute. - The `begin` and `end` blocks still execute. > [!IMPORTANT] -> If a function parameter is set to accept pipeline input, and a `process` -> block isn't defined, record-by-record processing will fail. In this case, -> your function will only execute once, regardless of the input. +> If a function parameter accepts pipeline input, and a `process` block isn't +> defined, record-by-record processing fails. In this case, your function only +> executes once, regardless of the input. ### `end` -This block is used to provide optional one-time post-processing for the -function. +Use this block to provide optional one-time post-processing for the function. + ## Simple functions @@ -169,27 +193,26 @@ Functions don't have to be complicated to be useful. The simplest functions have the following format: ```Syntax -function {statements} +function { statements } ``` For example, the following function starts PowerShell with the **Run as Administrator** option. ```powershell -function Start-PSAdmin {Start-Process PowerShell -Verb RunAs} +function Start-PSAdmin { Start-Process PowerShell -Verb RunAs } ``` To use the function, type: `Start-PSAdmin` To add statements to the function, type each statement on a separate line, or -use a semicolon `;` to separate the statements. +use a semicolon (`;`) to separate the statements. For example, the following function finds all `.jpg` files in the current user's directories that were changed after the start date. ```powershell -function Get-NewPicture -{ +function Get-NewPicture { $start = Get-Date -Month 1 -Day 1 -Year 2010 $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse $allPics | Where-Object {$_.LastWriteTime -gt $Start} @@ -197,37 +220,34 @@ function Get-NewPicture ``` You can create a toolbox of useful small functions. Add these functions to your -PowerShell profile, as described in [about_Profiles][15] and later in this -topic. - -## Function Names +PowerShell profile, as described in [about_Profiles][14] and later in this +article. -You can assign any name to a function, but functions that you share with others -should follow the naming rules that have been established for all PowerShell -commands. +## Function names -Functions names should consist of a verb-noun pair where the verb identifies -the action that the function performs and the noun identifies the item on which -the cmdlet performs its action. +You can assign any name to a function. However, for functions that you share +with others, you should follow the standard PowerShell naming rules. -Functions should use the standard verbs that have been approved for all -PowerShell commands. These verbs help us to keep our command names consistent -and easy for users to understand. +- Names should consist of a verb-noun pair where the verb identifies + the action that the function performs and the noun identifies the item on + which the cmdlet performs the action. +- Names should use the approved verbs for all PowerShell commands. Using + approved verbs creates consistency for users. For more information about the standard PowerShell verbs, see [Approved Verbs][02]. -## Functions with Parameters +## Functions with parameters You can use parameters with functions, including named parameters, positional parameters, switch parameters, and dynamic parameters. For more information about dynamic parameters in functions, see -[about_Functions_Advanced_Parameters][10]. +[about_Functions_Advanced_Parameters][09]. -### Named Parameters +### Named parameters You can define any number of named parameters. You can include a default value -for named parameters, as described later in this topic. +for named parameters, as described later in this article. You can define parameters inside the braces using the `param` keyword, as shown in the following sample syntax: @@ -248,7 +268,8 @@ function [([type]$Parameter1[,[type]$Parameter2])] { } ``` -Below is an example of this alternative syntax. +For example, the following function uses the alternative syntax to define two +parameters: ```powershell function Add-Numbers([int]$One, [int]$Two) { @@ -256,7 +277,7 @@ function Add-Numbers([int]$One, [int]$Two) { } ``` -While the first method is preferred, there is no difference between these two +While the first method is preferred, there's no difference between these two methods. When you run the function, the value you supply for a parameter is assigned to @@ -276,8 +297,8 @@ function Get-SmallFiles { } ``` -In the function, you can use the `$Size` variable, which is the name defined for -the parameter. +In the function, you can use the `$Size` variable, which is the name defined +for the parameter. To use this function, type the following command: @@ -330,7 +351,7 @@ function Get-SmallFiles { For more information about the **PSDefaultValue** attribute class, see [PSDefaultValue Attribute Members][01]. -### Positional Parameters +### Positional parameters A positional parameter is a parameter without a parameter name. PowerShell uses the parameter value order to associate each parameter value with a parameter in @@ -359,7 +380,7 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch Parameters +### Switch parameters A switch is a parameter that doesn't require a value. Instead, you type the function name followed by the name of the switch parameter. @@ -413,7 +434,7 @@ Switch-Item -On:$false Switch off ``` -## Using Splatting to Represent Command Parameters +## Use splatting to pass parameter values You can use splatting to represent the parameters of a command. This feature is introduced in Windows PowerShell 3.0. @@ -446,12 +467,12 @@ Cmdlet Get-ChildItem Microsoft.PowerShell.Management The `@args` feature uses the `$args` automatic parameter, which represents undeclared cmdlet parameters and values from remaining arguments. -For more information, see [about_Splatting][19]. +For more information, see [about_Splatting][18]. -## Piping Objects to Functions +## Piping objects to functions Any function can take input from the pipeline. You can control how a function -processes input from the pipeline using `begin`, `process`, and `end` +processes input from the pipeline using `begin`, `process`, `end`, and `clean` keywords. The following sample syntax shows these keywords: The `process` statement list runs one time for each object in the pipeline. @@ -508,12 +529,12 @@ PS> Get-SumOfNumbers 1, 2, 3, 4 When you use a function in a pipeline, the objects piped to the function are assigned to the `$input` automatic variable. The function runs statements with -the `begin` keyword before any objects come from the pipeline. The function -runs statements with the `end` keyword after all the objects have been received -from the pipeline. +the `begin` script block before any objects come from the pipeline. The +function runs statements with the `end` script block when there are no more +objects in the pipeline. -The following example shows the `$input` automatic variable with `begin` and -`end` keywords. +The following example shows the `$input` automatic variable used int the +`begin` and `end` script blocks. ```powershell function Get-PipelineBeginEnd { @@ -522,7 +543,7 @@ function Get-PipelineBeginEnd { } ``` -If this function is run using the pipeline, it displays the following +When you run the function with pipeline input, it displays the following results: ```powershell @@ -549,10 +570,10 @@ function Get-PipelineInput } ``` -In this example, each object that's piped to the function is sent to the -`process` statement list. The `process` statements run on each object, one -object at a time. The `$input` automatic variable is empty when the function -reaches the `end` keyword. +In this example, each object piped to the function is sent to the `process` +statement list. The `process` statements run on each object, one object at a +time. The `$input` automatic variable is empty when the function reaches the +`end` keyword. ```powershell 1, 2, 4 | Get-PipelineInput @@ -565,39 +586,11 @@ Processing: 4 End: The input is: ``` -For more information, see [Using Enumerators][06] +For more information, see [Using Enumerators][05] -## Filters +## Function scope -A filter is a type of function that runs on each object in the pipeline. A -filter resembles a function with all its statements in a `process` block. - -The syntax of a filter is as follows: - -``` -filter [] {} -``` - -The following filter takes log entries from the pipeline and then displays -either the whole entry or only the message portion of the entry: - -```powershell -filter Get-ErrorLog ([switch]$Message) -{ - if ($Message) { Out-Host -InputObject $_.Message } - else { $_ } -} -``` - -It can be used as follows: - -```powershell -Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message -``` - -## Function Scope - -A function exists in the scope in which it's created. +A function exists in the scope in which you create it. If a function is part of a script, the function is available to statements within that script. By default, a function in a script isn't available outside @@ -618,9 +611,9 @@ in functions, and at the command line. Functions create a new scope. The items created in a function, such as variables, exist only in the function scope. -For more information, see [about_Scopes][17]. +For more information, see [about_Scopes][16]. -## Finding and Managing Functions Using the Function: Drive +## Find and manage functions using the `Function:` drive All the functions and filters in PowerShell are automatically stored in the `Function:` drive. This drive is exposed by the PowerShell **Function** @@ -650,26 +643,25 @@ You can also use the following syntax. $Function:help ``` -For more information about the `Function:` drive, see the help topic for the -**Function** provider. Type `Get-Help Function`. +For more information, see +[about_Function_Provider][07]. -## Reusing Functions in New Sessions +## Reuse functions in new sessions When you type a function at the PowerShell command prompt, the function becomes part of the current session. The function is available until the session ends. To use your function in all PowerShell sessions, add the function to your PowerShell profile. For more information about profiles, see -[about_Profiles][15]. +[about_Profiles][14]. You can also save your function in a PowerShell script file. Type your function in a text file, and then save the file with the `.ps1` filename extension. -## Writing Help for Functions +## Create Help for functions -The `Get-Help` cmdlet gets help for functions, as well as for cmdlets, -providers, and scripts. To get help for a function, type `Get-Help` followed by -the function name. +The `Get-Help` cmdlet gets help for functions, cmdlets, providers, and scripts. +To get help for a function, type `Get-Help` followed by the function name. For example, to get help for the `Get-MyDisks` function, type: @@ -681,59 +673,53 @@ You can write help for a function using either of the two following methods: - Comment-Based Help for Functions - Create a help topic using special keywords in the comments. To create - comment-based help for a function, the comments must be placed at the - beginning or end of the function body or on the lines preceding the function - keyword. For more information about comment-based help, see - [about_Comment_Based_Help][07]. + Create help using special keywords in the comments. To create comment-based + help for a function, the comments must be placed at the beginning, end, or + within the body of the function. For more information about comment-based + help, see [about_Comment_Based_Help][06]. - XML-Based Help for Functions - Create an XML-based help topic, such as the type that's typically created for - cmdlets. XML-based help is required if you are localizing help topics into - multiple languages. - - To associate the function with the XML-based help topic, use the + XML-based help is required if you need to localize help content into multiple + languages. To associate the function with the XML-based help file, use the `.EXTERNALHELP` comment-based help keyword. Without this keyword, `Get-Help` - can't find the function help topic and calls to `Get-Help` for the function - return only autogenerated help. + can't find the function help file and only returns the autogenerated help. For more information about the `.EXTERNALHELP` keyword, see - [about_Comment_Based_Help][07]. For more information about XML-based help, + [about_Comment_Based_Help][06]. For more information about XML-based help, see [How to Write Cmdlet Help][03]. ## See also -- [about_Automatic_Variables][05] -- [about_Comment_Based_Help][07] -- [about_Function_Provider][08] -- [about_Functions_Advanced][11] -- [about_Functions_Advanced_Methods][09] -- [about_Functions_Advanced_Parameters][10] -- [about_Functions_CmdletBindingAttribute][12] -- [about_Functions_OutputTypeAttribute][13] -- [about_Parameters][14] -- [about_Profiles][15] -- [about_Scopes][17] -- [about_Script_Blocks][18] +- [about_Automatic_Variables][04] +- [about_Comment_Based_Help][06] +- [about_Function_Provider][07] +- [about_Functions_Advanced][10] +- [about_Functions_Advanced_Methods][08] +- [about_Functions_Advanced_Parameters][09] +- [about_Functions_CmdletBindingAttribute][11] +- [about_Functions_OutputTypeAttribute][12] +- [about_Parameters][13] +- [about_Profiles][14] +- [about_Scopes][16] +- [about_Script_Blocks][17] [01]: /dotnet/api/system.management.automation.psdefaultvalueattribute [02]: /powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands [03]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets -[04]: #filters -[05]: about_Automatic_Variables.md -[06]: about_Automatic_Variables.md#using-enumerators -[07]: about_Comment_Based_Help.md -[08]: about_Function_Provider.md -[09]: about_Functions_Advanced_Methods.md -[10]: about_Functions_Advanced_Parameters.md -[11]: about_Functions_Advanced.md -[12]: about_Functions_CmdletBindingAttribute.md -[13]: about_Functions_OutputTypeAttribute.md -[14]: about_Parameters.md -[15]: about_Profiles.md -[16]: about_Return.md -[17]: about_Scopes.md -[18]: about_Script_Blocks.md -[19]: about_Splatting.md +[04]: about_Automatic_Variables.md +[05]: about_Automatic_Variables.md#using-enumerators +[06]: about_Comment_Based_Help.md +[07]: about_Function_Provider.md +[08]: about_Functions_Advanced_Methods.md +[09]: about_Functions_Advanced_Parameters.md +[10]: about_Functions_Advanced.md +[11]: about_Functions_CmdletBindingAttribute.md +[12]: about_Functions_OutputTypeAttribute.md +[13]: about_Parameters.md +[14]: about_Profiles.md +[15]: about_Return.md +[16]: about_Scopes.md +[17]: about_Script_Blocks.md +[18]: about_Splatting.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSItem.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSItem.md index 33f87a436c8c..69ed80749c46 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_PSItem.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_PSItem.md @@ -1,7 +1,7 @@ --- description: The automatic variable that contains the current object in the pipeline object. Locale: en-US -ms.date: 01/31/2025 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_psitem?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_PSItem @@ -400,7 +400,7 @@ For more examples, see the _Accessing exception information_ section in [07]: about_Functions_Advanced_Parameters.md#validatescript-validation-attribute [08]: about_Functions_Advanced.md [09]: about_Functions.md -[10]: about_Functions.md#filters +[10]: about_Functions.md#filter-syntax [11]: about_Script_Blocks.md [12]: about_Script_Blocks.md#using-delay-bind-script-blocks-with-parameters [13]: about_Switch.md diff --git a/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md b/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md index a06c58887e26..5e43fece28e4 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Out-Default.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 02/07/2023 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-default?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Default @@ -20,24 +20,9 @@ Out-Default [-Transcript] [-InputObject ] [] ## DESCRIPTION -PowerShell automatically adds `Out-Default` to the end of every pipeline. `Out-Default` decides how -to format and output the object stream. If the object stream is a stream of strings, `Out-Default` -pipes these directly to `Out-Host` which calls the appropriate APIs provided by the host. If the -object stream does not contain strings, `Out-Default` inspects the object to determine what to do. -First it looks at the object type and determines whether there is a registered _view_ for this -object type. - -PowerShell defines an XML schema and a mechanism (the `Update-FormatData` cmdlet) where anyone can -register views for an object type. You can specify **wide**, **list**, **table**, or **custom** -views for any object type. The views specify which properties to display and how they should be -displayed. If a view is registered, it defines which formatter to use. So if the registered view is -a **table** view, `Out-Default` streams the objects to `Format-Table | Out-Host`. `Format-Table` -transforms the objects into a stream of Formatting records (driven by the data in the view -definition) and `Out-Host` transforms the formatting records into calls on the Host interface. - -This cmdlet isn't intended to be used by the end user. Other cmdlets are recommended for controlling -output like [Out-Host](Out-Host.md) or using `Format-*` cmdlets and the [Format.ps1xml](About/about_format.ps1xml.md) -file to control formatting. +PowerShell automatically adds `Out-Default` to the end of every top-level interactive pipeline. +`Out-Default` passes the objects it receives to the PowerShell format system. Then, it writes the +formatted output to the console. This cmdlet isn't intended to be used by the end user. ## EXAMPLES @@ -82,7 +67,7 @@ Accept wildcard characters: False ### -Transcript -Determines whether the output should be sent to PowerShell's transcription services. +When you use this parameter, the output is only sent to the PowerShell transcript. ```yaml Type: System.Management.Automation.SwitchParameter @@ -100,7 +85,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/5.1/Microsoft.PowerShell.Core/Out-Host.md b/reference/5.1/Microsoft.PowerShell.Core/Out-Host.md index 43746478c472..1416a7be6404 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Out-Host.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Out-Host.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/31/2022 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-host?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Host @@ -27,10 +27,9 @@ The `Out-Host` cmdlet sends output to the PowerShell host for display. The host at the command line. Because `Out-Host` is the default, you don't have to specify it unless you want to use its parameters. -`Out-Host` is automatically appended to every command that is executed. It passes the output of the -pipeline to the host executing the command. `Out-Host` ignores ANSI escape sequences. The escape -sequences are handled by the host. `Out-Host` passes ANSI escape sequences to the host without -trying to interpret or change them. +`Out-Host` passes the output of the pipeline to the host executing the command. `Out-Host` ignores +ANSI escape sequences. The escape sequences are handled by the host. `Out-Host` passes ANSI escape +sequences to the host without trying to interpret or change them. ## EXAMPLES @@ -89,14 +88,14 @@ Accept wildcard characters: False ### -Paging -Indicates that `Out-Host` displays one page of output at a time, and waits for user input before the -remaining pages are displayed. By default, all the output is displayed on a single page. The page -size is determined by the characteristics of the host. +Indicates that `Out-Host` displays one page of output at a time. The page size is determined by the +characteristics of the host. -Press the Space bar to display the next page of output or the Enter key to -view the next line of output. Press Q to quit. +After outputting the first page, the command waits for user input before the remaining pages are +displayed. Press the Spacebar to display the next page of output or the Enter +key to view the next line of output. Press Q to quit. -**Paging** is similar to the **more** command. +Using **Paging** is similar to using the **more** command. > [!NOTE] > The **Paging** parameter isn't supported by the PowerShell ISE host. @@ -117,7 +116,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -137,20 +137,22 @@ Windows PowerShell includes the following aliases for `Out-Host`: - `oh` -The **Paging** parameter isn't supported by all PowerShell hosts. For example, if you use the -**Paging** parameter in the PowerShell ISE, the following error is displayed: -`out-lineoutput : The method or operation is not implemented.` +Not all PowerShell hosts support the **Paging** parameter. For example, if you use the **Paging** +parameter in the Windows PowerShell ISE, the following error is displayed: + +> out-lineoutput : The method or operation is not implemented. The cmdlets that contain the **Out** verb, `Out-`, don't format objects. They render objects and send them to the specified display destination. If you send an unformatted object to an `Out-` cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. -The `Out-` cmdlets don't have parameters for names or file paths. To send data to an `Out-` cmdlet, -use the pipeline to send a PowerShell command's output to the cmdlet. Or, you can store data in a -variable and use the **InputObject** parameter to pass the data to the cmdlet. +The `Out-` cmdlets don't read input from files. To send data to an `Out-` cmdlet, use the pipeline +to send data to the cmdlet. Or, you can store data in a variable and use the **InputObject** +parameter to pass the data to the cmdlet. -`Out-Host` sends data, but it doesn't produce any output objects. If you pipeline the output of -`Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects have been specified. +`Out-Host` sends data to the host only. Tt doesn't produce output objects to the pipeline. If you +pipeline the output of `Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects +have been specified. ## RELATED LINKS diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md index 0198cb5f7bde..6525ccda9f58 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 06/26/2024 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions @@ -16,10 +16,58 @@ Describes how to create and use functions in PowerShell. ## Long description A function is a list of PowerShell statements that has a name that you assign. -When you run a function, you type the function name. The statements in the list -run as if you had typed them at the command prompt. +When you run a function, you type the function name. -Functions can be as simple as: +PowerShell defines two kinds of functions: + +- A **function** is a block of code that can be called by name. It can take + input and return output. Functions are defined using the `function` keyword. +- A **filter** is a type of function designed to process data from the + pipeline. Filters are defined using the `filter` keyword. + +You can group the statements in a function into one of four different +predefined script blocks. These script blocks are named using the keywords +`begin`, `process`, `end`, and `clean`. If you don't use these keywords, +PowerShell puts the statements in the appropriate code block. + +Functions can also act like cmdlets. You can create a function that works just +like a cmdlet without using `C#` programming. For more information, see +[about_Functions_Advanced][10]. + +> [!IMPORTANT] +> Within script files and script-based modules, functions must be defined +> before they can be called. + +## Function syntax + +Functions are defined using the following syntax: + +```Syntax +function [] { + param([type]$Parameter1 [,[type]$Parameter2]) + dynamicparam {} + begin {} + process {} + end {} + clean {} +} +``` + +A function includes the following items: + +- A `function` keyword +- A scope (optional) +- A name that you select +- Any number of named parameters (optional), including dynamic parameters +- One or more PowerShell statements enclosed in braces `{}` + +If you don't use one of the keywords (`begin`, `process`, `end`, `clean`) in a +`function` definition, PowerShell puts the statements in the `end` block. + +For more information about the `dynamicparam` keyword and dynamic parameters in +functions, see [about_Functions_Advanced_Parameters][09]. + +A function can be as simple as: ```powershell function Get-PowerShellProcess { Get-Process pwsh } @@ -38,75 +86,51 @@ Get-PowerShellProcess 110 78.72 172.39 10.62 10936 1 pwsh ``` -A function can also be as complex as a cmdlet or an application. - -Like cmdlets, functions can have parameters. The parameters can be named, -positional, switch, or dynamic parameters. Function parameters can be read from -the command line or from the pipeline. +A function can also be as complex as a cmdlet. Functions can return values that can be displayed, assigned to variables, or -passed to other functions or cmdlets. You can also specify a return value using -the `return` keyword. The `return` keyword doesn't affect or suppress other -output returned from your function. However, the `return` keyword exits the -function at that line. For more information, see [about_Return][16]. +passed to other functions or cmdlets. You can use the `return` keyword to +return output. The `return` keyword doesn't affect or suppress other output +returned from your function. However, the `return` keyword exits the function +at that line. For more information, see [about_Return][15]. -The function's statement list can contain different types of statement lists -with the keywords `begin`, `process`, `end`, and `clean`. These statement lists -handle input from the pipeline differently. +## Filter syntax -The [filter][04] keyword is used to create a type of function that runs on each -object in the pipeline. A filter resembles a function with all its statements -in a `process` block. +The intent of the `filter` function is to provide a shorthand way of defining a +function that runs on each object in the pipeline. -Functions can also act like cmdlets. You can create a function that works just -like a cmdlet without using `C#` programming. For more information, see -[about_Functions_Advanced][11]. - -> [!IMPORTANT] -> Within script files and script-based modules, functions must be defined -> before they can be called. - -## Syntax - -The following are the syntax for a function: +The syntax of a filter is as follows: ```Syntax -function [] [([type]$Parameter1[,[type]$Parameter2])] -{ - begin {} - process {} - end {} - clean {} -} +filter [] {} ``` -```Syntax -function [] -{ - param([type]$Parameter1 [,[type]$Parameter2]) - dynamicparam {} - begin {} - process {} - end {} - clean {} +To simplify the syntax for `filter` functions, omit the script block keyword +(`begin`, `process`, `end`, `clean`). PowerShell puts the statements in the +`process` block. You can use any of the other blocks in a filter function, but +the intent was to provide a shorthand way of defining a function that has the +sole purpose of processing each object in the pipeline. + +The following filter takes log entries from the pipeline and then displays +either the whole entry or only the message portion of the entry: + +```powershell +filter Get-EventMessage ([switch]$MessageOnly) { + if ($MessageOnly) { Out-Host -InputObject $_.Message } + else { $_ } } ``` -A function includes the following items: - -- A `function` keyword -- A scope (optional) -- A name that you select -- Any number of named parameters (optional) -- One or more PowerShell commands enclosed in braces `{}` +It can be used as follows: -For more information about the `dynamicparam` keyword and dynamic parameters in -functions, see [about_Functions_Advanced_Parameters][10]. +```powershell +Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly +``` ## Input processing methods The methods described in this section are referred to as the input processing -methods. For functions, these three methods are represented by the `begin`, +methods. For functions, these three methods named using the `begin`, `process`, and `end` blocks of the function. PowerShell 7.3 adds a `clean` block process method. @@ -116,13 +140,12 @@ function. However, if you use any of these named blocks, or define a `dynamicparam` block, you must put all code in a named block. The following example shows the outline of a function that contains a `begin` -block for one-time preprocessing, a `process` block for multiple record -processing, and an `end` block for one-time post-processing. +block for one-time preprocessing, a `process` block data from the pipeline, and +an `end` block for one-time post-processing. ```powershell -Function Test-ScriptCmdlet -{ -[CmdletBinding(SupportsShouldProcess=$true)] +Function Test-ScriptCmdlet { + [CmdletBinding(SupportsShouldProcess=$true)] param ($Parameter1) begin{} process{} @@ -146,25 +169,24 @@ the function receives. The automatic variable `$_` or `$PSItem` contains the current object in the pipeline for use in the `process` block. The `$input` automatic variable contains an enumerator that's only available to functions and script blocks. -For more information, see [about_Automatic_Variables][05]. +For more information, see [about_Automatic_Variables][04]. -- Calling the function at the beginning, or outside of a pipeline, executes the - `process` block once. +- If the function is invoked without pipeline input, PowerShell executes the + `process` block only once. - Within a pipeline, the `process` block executes once for each input object that reaches the function. - If the pipeline input that reaches the function is empty, the `process` block - **does not** execute. + doesn't execute. - The `begin`, `end`, and `clean` blocks still execute. > [!IMPORTANT] -> If a function parameter is set to accept pipeline input, and a `process` -> block isn't defined, record-by-record processing will fail. In this case, -> your function will only execute once, regardless of the input. +> If a function parameter accepts pipeline input, and a `process` block isn't +> defined, record-by-record processing fails. In this case, your function only +> executes once, regardless of the input. ### `end` -This block is used to provide optional one-time post-processing for the -function. +Use this block to provide optional one-time post-processing for the function. ### `clean` @@ -175,19 +197,18 @@ across the `begin`, `process`, and `end` blocks. It's semantically similar to a `finally` block that covers all other named blocks of a script function or a script cmdlet. Resource cleanup is enforced for the following scenarios: -1. when the pipeline execution finishes normally without terminating error +1. when the pipeline execution finishes without terminating error 1. when the pipeline execution is interrupted due to terminating error -1. when the pipeline is halted by `Select-Object -First` -1. when the pipeline is being stopped by Ctrl+c or - `StopProcessing()` +1. when the pipeline is truncated, for example: `Select-Object -First` +1. when the pipeline is stopped by Ctrl+c or `StopProcessing()` -The clean block discards any output that's written to the **Success** stream. +The clean block discards any output written to the **Success** stream. > [!CAUTION] > Adding the `clean` block is a breaking change. Because `clean` is parsed as a > keyword, it prevents users from directly calling a command named `clean` as > the first statement in a script block. However, it's not likely to be a -> problem. The command can still be invoked using the call operator +> problem. You can still invoke the command using the call operator > (`& clean`). ## Simple functions @@ -196,27 +217,26 @@ Functions don't have to be complicated to be useful. The simplest functions have the following format: ```Syntax -function {statements} +function { statements } ``` For example, the following function starts PowerShell with the **Run as Administrator** option. ```powershell -function Start-PSAdmin {Start-Process PowerShell -Verb RunAs} +function Start-PSAdmin { Start-Process PowerShell -Verb RunAs } ``` To use the function, type: `Start-PSAdmin` To add statements to the function, type each statement on a separate line, or -use a semicolon `;` to separate the statements. +use a semicolon (`;`) to separate the statements. For example, the following function finds all `.jpg` files in the current user's directories that were changed after the start date. ```powershell -function Get-NewPicture -{ +function Get-NewPicture { $start = Get-Date -Month 1 -Day 1 -Year 2010 $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse $allPics | Where-Object {$_.LastWriteTime -gt $Start} @@ -224,37 +244,34 @@ function Get-NewPicture ``` You can create a toolbox of useful small functions. Add these functions to your -PowerShell profile, as described in [about_Profiles][15] and later in this -topic. +PowerShell profile, as described in [about_Profiles][14] and later in this +article. -## Function Names +## Function names -You can assign any name to a function, but functions that you share with others -should follow the naming rules that have been established for all PowerShell -commands. +You can assign any name to a function. However, for functions that you share +with others, you should follow the standard PowerShell naming rules. -Functions names should consist of a verb-noun pair where the verb identifies -the action that the function performs and the noun identifies the item on which -the cmdlet performs its action. - -Functions should use the standard verbs that have been approved for all -PowerShell commands. These verbs help us to keep our command names consistent -and easy for users to understand. +- Names should consist of a verb-noun pair where the verb identifies + the action that the function performs and the noun identifies the item on + which the cmdlet performs the action. +- Names should use the approved verbs for all PowerShell commands. Using + approved verbs creates consistency for users. For more information about the standard PowerShell verbs, see [Approved Verbs][02]. -## Functions with Parameters +## Functions with parameters You can use parameters with functions, including named parameters, positional parameters, switch parameters, and dynamic parameters. For more information about dynamic parameters in functions, see -[about_Functions_Advanced_Parameters][10]. +[about_Functions_Advanced_Parameters][09]. -### Named Parameters +### Named parameters You can define any number of named parameters. You can include a default value -for named parameters, as described later in this topic. +for named parameters, as described later in this article. You can define parameters inside the braces using the `param` keyword, as shown in the following sample syntax: @@ -275,7 +292,8 @@ function [([type]$Parameter1[,[type]$Parameter2])] { } ``` -Below is an example of this alternative syntax. +For example, the following function uses the alternative syntax to define two +parameters: ```powershell function Add-Numbers([int]$One, [int]$Two) { @@ -283,7 +301,7 @@ function Add-Numbers([int]$One, [int]$Two) { } ``` -While the first method is preferred, there is no difference between these two +While the first method is preferred, there's no difference between these two methods. When you run the function, the value you supply for a parameter is assigned to @@ -357,7 +375,7 @@ function Get-SmallFiles { For more information about the **PSDefaultValue** attribute class, see [PSDefaultValue Attribute Members][01]. -### Positional Parameters +### Positional parameters A positional parameter is a parameter without a parameter name. PowerShell uses the parameter value order to associate each parameter value with a parameter in @@ -386,7 +404,7 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch Parameters +### Switch parameters A switch is a parameter that doesn't require a value. Instead, you type the function name followed by the name of the switch parameter. @@ -440,7 +458,7 @@ Switch-Item -On:$false Switch off ``` -## Using Splatting to Represent Command Parameters +## Use splatting to pass parameter values You can use splatting to represent the parameters of a command. This feature is introduced in Windows PowerShell 3.0. @@ -473,9 +491,9 @@ Cmdlet Get-ChildItem Microsoft.PowerShell.Management The `@args` feature uses the `$args` automatic parameter, which represents undeclared cmdlet parameters and values from remaining arguments. -For more information, see [about_Splatting][19]. +For more information, see [about_Splatting][18]. -## Piping Objects to Functions +## Piping objects to functions Any function can take input from the pipeline. You can control how a function processes input from the pipeline using `begin`, `process`, `end`, and `clean` @@ -535,12 +553,12 @@ PS> Get-SumOfNumbers 1, 2, 3, 4 When you use a function in a pipeline, the objects piped to the function are assigned to the `$input` automatic variable. The function runs statements with -the `begin` keyword before any objects come from the pipeline. The function -runs statements with the `end` keyword after all the objects have been received -from the pipeline. +the `begin` script block before any objects come from the pipeline. The +function runs statements with the `end` script block when there are no more +objects in the pipeline. -The following example shows the `$input` automatic variable with `begin` and -`end` keywords. +The following example shows the `$input` automatic variable used int the +`begin` and `end` script blocks. ```powershell function Get-PipelineBeginEnd { @@ -549,7 +567,7 @@ function Get-PipelineBeginEnd { } ``` -If this function is run using the pipeline, it displays the following +When you run the function with pipeline input, it displays the following results: ```powershell @@ -576,10 +594,10 @@ function Get-PipelineInput } ``` -In this example, each object that's piped to the function is sent to the -`process` statement list. The `process` statements run on each object, one -object at a time. The `$input` automatic variable is empty when the function -reaches the `end` keyword. +In this example, each object piped to the function is sent to the `process` +statement list. The `process` statements run on each object, one object at a +time. The `$input` automatic variable is empty when the function reaches the +`end` keyword. ```powershell 1, 2, 4 | Get-PipelineInput @@ -592,7 +610,7 @@ Processing: 4 End: The input is: ``` -For more information, see [Using Enumerators][06] +For more information, see [Using Enumerators][05] PowerShell 7.3 added the `clean` block. The `clean` block is a convenient way for users to clean up resources created and used in the `begin`, `process`, and @@ -602,9 +620,8 @@ enforced for the following scenarios: 1. when the pipeline execution finishes normally without terminating error 1. when the pipeline execution is interrupted due to terminating error -1. when the pipeline is halted by `Select-Object -First` -1. when the pipeline is being stopped by Ctrl+C or - `StopProcessing()` +1. when the pipeline is truncated, for example: `Select-Object -First` +1. when the pipeline is stopped by Ctrl+C or `StopProcessing()` > [!CAUTION] > Adding the `clean` block is a breaking change. Because `clean` is parsed as a @@ -613,37 +630,9 @@ enforced for the following scenarios: > problem. The command can still be invoked using the call operator > (`& clean`). -## Filters - -A filter is a type of function that runs on each object in the pipeline. A -filter resembles a function with all its statements in a `process` block. - -The syntax of a filter is as follows: - -``` -filter [] {} -``` - -The following filter takes log entries from the pipeline and then displays -either the whole entry or only the message portion of the entry: - -```powershell -filter Get-ErrorLog ([switch]$Message) -{ - if ($Message) { Out-Host -InputObject $_.Message } - else { $_ } -} -``` - -It can be used as follows: - -```powershell -Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message -``` - -## Function Scope +## Function scope -A function exists in the scope in which it's created. +A function exists in the scope in which you create it. If a function is part of a script, the function is available to statements within that script. By default, a function in a script isn't available outside @@ -664,9 +653,9 @@ in functions, and at the command line. Functions create a new scope. The items created in a function, such as variables, exist only in the function scope. -For more information, see [about_Scopes][17]. +For more information, see [about_Scopes][16]. -## Finding and Managing Functions Using the Function: Drive +## Find and manage functions using the `Function:` drive All the functions and filters in PowerShell are automatically stored in the `Function:` drive. This drive is exposed by the PowerShell **Function** @@ -696,26 +685,25 @@ You can also use the following syntax. $Function:help ``` -For more information about the `Function:` drive, see the help topic for the -**Function** provider. Type `Get-Help Function`. +For more information, see +[about_Function_Provider][07]. -## Reusing Functions in New Sessions +## Reuse functions in new sessions When you type a function at the PowerShell command prompt, the function becomes part of the current session. The function is available until the session ends. To use your function in all PowerShell sessions, add the function to your PowerShell profile. For more information about profiles, see -[about_Profiles][15]. +[about_Profiles][14]. You can also save your function in a PowerShell script file. Type your function in a text file, and then save the file with the `.ps1` filename extension. -## Writing Help for Functions +## Create Help for functions -The `Get-Help` cmdlet gets help for functions, as well as for cmdlets, -providers, and scripts. To get help for a function, type `Get-Help` followed by -the function name. +The `Get-Help` cmdlet gets help for functions, cmdlets, providers, and scripts. +To get help for a function, type `Get-Help` followed by the function name. For example, to get help for the `Get-MyDisks` function, type: @@ -727,59 +715,53 @@ You can write help for a function using either of the two following methods: - Comment-Based Help for Functions - Create a help topic using special keywords in the comments. To create - comment-based help for a function, the comments must be placed at the - beginning or end of the function body or on the lines preceding the function - keyword. For more information about comment-based help, see - [about_Comment_Based_Help][07]. + Create help using special keywords in the comments. To create comment-based + help for a function, the comments must be placed at the beginning, end, or + within the body of the function. For more information about comment-based + help, see [about_Comment_Based_Help][06]. - XML-Based Help for Functions - Create an XML-based help topic, such as the type that's typically created for - cmdlets. XML-based help is required if you are localizing help topics into - multiple languages. - - To associate the function with the XML-based help topic, use the + XML-based help is required if you need to localize help content into multiple + languages. To associate the function with the XML-based help file, use the `.EXTERNALHELP` comment-based help keyword. Without this keyword, `Get-Help` - can't find the function help topic and calls to `Get-Help` for the function - return only autogenerated help. + can't find the function help file and only returns the autogenerated help. For more information about the `.EXTERNALHELP` keyword, see - [about_Comment_Based_Help][07]. For more information about XML-based help, + [about_Comment_Based_Help][06]. For more information about XML-based help, see [How to Write Cmdlet Help][03]. ## See also -- [about_Automatic_Variables][05] -- [about_Comment_Based_Help][07] -- [about_Function_Provider][08] -- [about_Functions_Advanced][11] -- [about_Functions_Advanced_Methods][09] -- [about_Functions_Advanced_Parameters][10] -- [about_Functions_CmdletBindingAttribute][12] -- [about_Functions_OutputTypeAttribute][13] -- [about_Parameters][14] -- [about_Profiles][15] -- [about_Scopes][17] -- [about_Script_Blocks][18] +- [about_Automatic_Variables][04] +- [about_Comment_Based_Help][06] +- [about_Function_Provider][07] +- [about_Functions_Advanced][10] +- [about_Functions_Advanced_Methods][08] +- [about_Functions_Advanced_Parameters][09] +- [about_Functions_CmdletBindingAttribute][11] +- [about_Functions_OutputTypeAttribute][12] +- [about_Parameters][13] +- [about_Profiles][14] +- [about_Scopes][16] +- [about_Script_Blocks][17] [01]: /dotnet/api/system.management.automation.psdefaultvalueattribute [02]: /powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands [03]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets -[04]: #filters -[05]: about_Automatic_Variables.md -[06]: about_Automatic_Variables.md#using-enumerators -[07]: about_Comment_Based_Help.md -[08]: about_Function_Provider.md -[09]: about_Functions_Advanced_Methods.md -[10]: about_Functions_Advanced_Parameters.md -[11]: about_Functions_Advanced.md -[12]: about_Functions_CmdletBindingAttribute.md -[13]: about_Functions_OutputTypeAttribute.md -[14]: about_Parameters.md -[15]: about_Profiles.md -[16]: about_Return.md -[17]: about_Scopes.md -[18]: about_Script_Blocks.md -[19]: about_Splatting.md +[04]: about_Automatic_Variables.md +[05]: about_Automatic_Variables.md#using-enumerators +[06]: about_Comment_Based_Help.md +[07]: about_Function_Provider.md +[08]: about_Functions_Advanced_Methods.md +[09]: about_Functions_Advanced_Parameters.md +[10]: about_Functions_Advanced.md +[11]: about_Functions_CmdletBindingAttribute.md +[12]: about_Functions_OutputTypeAttribute.md +[13]: about_Parameters.md +[14]: about_Profiles.md +[15]: about_Return.md +[16]: about_Scopes.md +[17]: about_Script_Blocks.md +[18]: about_Splatting.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSItem.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSItem.md index cd347bb5ba5d..359c779c3361 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_PSItem.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_PSItem.md @@ -418,7 +418,7 @@ with the default format for the current culture by casting the value to [07]: about_Functions_Advanced_Parameters.md#validatescript-validation-attribute [08]: about_Functions_Advanced.md [09]: about_Functions.md -[10]: about_Functions.md#filters +[10]: about_Functions.md#filter-syntax [11]: about_Script_Blocks.md [12]: about_Script_Blocks.md#using-delay-bind-script-blocks-with-parameters [13]: about_Switch.md diff --git a/reference/7.4/Microsoft.PowerShell.Core/Out-Default.md b/reference/7.4/Microsoft.PowerShell.Core/Out-Default.md index 5d691b3bfbe8..f3408d4a7ad5 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Out-Default.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 02/07/2023 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-default?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Default @@ -20,24 +20,9 @@ Out-Default [-Transcript] [-InputObject ] [] ## DESCRIPTION -PowerShell automatically adds `Out-Default` to the end of every pipeline. `Out-Default` decides how -to format and output the object stream. If the object stream is a stream of strings, `Out-Default` -pipes these directly to `Out-Host` which calls the appropriate APIs provided by the host. If the -object stream does not contain strings, `Out-Default` inspects the object to determine what to do. -First it looks at the object type and determines whether there is a registered _view_ for this -object type. - -PowerShell defines an XML schema and a mechanism (the `Update-FormatData` cmdlet) where anyone can -register views for an object type. You can specify **wide**, **list**, **table**, or **custom** -views for any object type. The views specify which properties to display and how they should be -displayed. If a view is registered, it defines which formatter to use. So if the registered view is -a **table** view, `Out-Default` streams the objects to `Format-Table | Out-Host`. `Format-Table` -transforms the objects into a stream of Formatting records (driven by the data in the view -definition) and `Out-Host` transforms the formatting records into calls on the Host interface. - -This cmdlet isn't intended to be used by the end user. Other cmdlets are recommended for controlling -output like [Out-Host](Out-Host.md) or using `Format-*` cmdlets and the [Format.ps1xml](About/about_format.ps1xml.md) -file to control formatting. +PowerShell automatically adds `Out-Default` to the end of every top-level interactive pipeline. +`Out-Default` passes the objects it receives to the PowerShell format system. Then, it writes the +formatted output to the console. This cmdlet isn't intended to be used by the end user. ## EXAMPLES @@ -82,7 +67,7 @@ Accept wildcard characters: False ### -Transcript -Determines whether the output should be sent to PowerShell's transcription services. +When you use this parameter, the output is only sent to the PowerShell transcript. ```yaml Type: System.Management.Automation.SwitchParameter @@ -100,7 +85,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.4/Microsoft.PowerShell.Core/Out-Host.md b/reference/7.4/Microsoft.PowerShell.Core/Out-Host.md index 3ce6bdce8735..c07c2d017470 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/Out-Host.md +++ b/reference/7.4/Microsoft.PowerShell.Core/Out-Host.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/31/2022 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-host?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Host @@ -27,10 +27,9 @@ The `Out-Host` cmdlet sends output to the PowerShell host for display. The host at the command line. Because `Out-Host` is the default, you don't have to specify it unless you want to use its parameters. -`Out-Host` is automatically appended to every command that is executed. It passes the output of the -pipeline to the host executing the command. `Out-Host` ignores ANSI escape sequences. The escape -sequences are handled by the host. `Out-Host` passes ANSI escape sequences to the host without -trying to interpret or change them. +`Out-Host` passes the output of the pipeline to the host executing the command. `Out-Host` ignores +ANSI escape sequences. The escape sequences are handled by the host. `Out-Host` passes ANSI escape +sequences to the host without trying to interpret or change them. ## EXAMPLES @@ -89,14 +88,14 @@ Accept wildcard characters: False ### -Paging -Indicates that `Out-Host` displays one page of output at a time, and waits for user input before the -remaining pages are displayed. By default, all the output is displayed on a single page. The page -size is determined by the characteristics of the host. +Indicates that `Out-Host` displays one page of output at a time. The page size is determined by the +characteristics of the host. -Press the Space bar to display the next page of output or the Enter key to -view the next line of output. Press Q to quit. +After outputting the first page, the command waits for user input before the remaining pages are +displayed. Press the Spacebar to display the next page of output or the Enter +key to view the next line of output. Press Q to quit. -**Paging** is similar to the **more** command. +Using **Paging** is similar to using the **more** command. > [!NOTE] > The **Paging** parameter isn't supported by the PowerShell ISE host. @@ -117,7 +116,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -138,20 +138,22 @@ PowerShell includes the following aliases for `Out-Host`: - All platforms: - `oh` -The **Paging** parameter isn't supported by all PowerShell hosts. For example, if you use the -**Paging** parameter in the PowerShell ISE, the following error is displayed: -`out-lineoutput : The method or operation is not implemented.` +Not all PowerShell hosts support the **Paging** parameter. For example, if you use the **Paging** +parameter in the Windows PowerShell ISE, the following error is displayed: + +> out-lineoutput : The method or operation is not implemented. The cmdlets that contain the **Out** verb, `Out-`, don't format objects. They render objects and send them to the specified display destination. If you send an unformatted object to an `Out-` cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. -The `Out-` cmdlets don't have parameters for names or file paths. To send data to an `Out-` cmdlet, -use the pipeline to send a PowerShell command's output to the cmdlet. Or, you can store data in a -variable and use the **InputObject** parameter to pass the data to the cmdlet. +The `Out-` cmdlets don't read input from files. To send data to an `Out-` cmdlet, use the pipeline +to send data to the cmdlet. Or, you can store data in a variable and use the **InputObject** +parameter to pass the data to the cmdlet. -`Out-Host` sends data, but it doesn't produce any output objects. If you pipeline the output of -`Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects have been specified. +`Out-Host` sends data to the host only. Tt doesn't produce output objects to the pipeline. If you +pipeline the output of `Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects +have been specified. ## RELATED LINKS diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md index e351e85cf15e..fe15587f72df 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 06/26/2024 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions @@ -16,10 +16,58 @@ Describes how to create and use functions in PowerShell. ## Long description A function is a list of PowerShell statements that has a name that you assign. -When you run a function, you type the function name. The statements in the list -run as if you had typed them at the command prompt. +When you run a function, you type the function name. -Functions can be as simple as: +PowerShell defines two kinds of functions: + +- A **function** is a block of code that can be called by name. It can take + input and return output. Functions are defined using the `function` keyword. +- A **filter** is a type of function designed to process data from the + pipeline. Filters are defined using the `filter` keyword. + +You can group the statements in a function into one of four different +predefined script blocks. These script blocks are named using the keywords +`begin`, `process`, `end`, and `clean`. If you don't use these keywords, +PowerShell puts the statements in the appropriate code block. + +Functions can also act like cmdlets. You can create a function that works just +like a cmdlet without using `C#` programming. For more information, see +[about_Functions_Advanced][10]. + +> [!IMPORTANT] +> Within script files and script-based modules, functions must be defined +> before they can be called. + +## Function syntax + +Functions are defined using the following syntax: + +```Syntax +function [] { + param([type]$Parameter1 [,[type]$Parameter2]) + dynamicparam {} + begin {} + process {} + end {} + clean {} +} +``` + +A function includes the following items: + +- A `function` keyword +- A scope (optional) +- A name that you select +- Any number of named parameters (optional), including dynamic parameters +- One or more PowerShell statements enclosed in braces `{}` + +If you don't use one of the keywords (`begin`, `process`, `end`, `clean`) in a +`function` definition, PowerShell puts the statements in the `end` block. + +For more information about the `dynamicparam` keyword and dynamic parameters in +functions, see [about_Functions_Advanced_Parameters][09]. + +A function can be as simple as: ```powershell function Get-PowerShellProcess { Get-Process pwsh } @@ -38,75 +86,51 @@ Get-PowerShellProcess 110 78.72 172.39 10.62 10936 1 pwsh ``` -A function can also be as complex as a cmdlet or an application. - -Like cmdlets, functions can have parameters. The parameters can be named, -positional, switch, or dynamic parameters. Function parameters can be read from -the command line or from the pipeline. +A function can also be as complex as a cmdlet. Functions can return values that can be displayed, assigned to variables, or -passed to other functions or cmdlets. You can also specify a return value using -the `return` keyword. The `return` keyword doesn't affect or suppress other -output returned from your function. However, the `return` keyword exits the -function at that line. For more information, see [about_Return][16]. +passed to other functions or cmdlets. You can use the `return` keyword to +return output. The `return` keyword doesn't affect or suppress other output +returned from your function. However, the `return` keyword exits the function +at that line. For more information, see [about_Return][15]. -The function's statement list can contain different types of statement lists -with the keywords `begin`, `process`, `end`, and `clean`. These statement lists -handle input from the pipeline differently. +## Filter syntax -The [filter][04] keyword is used to create a type of function that runs on each -object in the pipeline. A filter resembles a function with all its statements -in a `process` block. +The intent of the `filter` function is to provide a shorthand way of defining a +function that runs on each object in the pipeline. -Functions can also act like cmdlets. You can create a function that works just -like a cmdlet without using `C#` programming. For more information, see -[about_Functions_Advanced][11]. - -> [!IMPORTANT] -> Within script files and script-based modules, functions must be defined -> before they can be called. - -## Syntax - -The following are the syntax for a function: +The syntax of a filter is as follows: ```Syntax -function [] [([type]$Parameter1[,[type]$Parameter2])] -{ - begin {} - process {} - end {} - clean {} -} +filter [] {} ``` -```Syntax -function [] -{ - param([type]$Parameter1 [,[type]$Parameter2]) - dynamicparam {} - begin {} - process {} - end {} - clean {} +To simplify the syntax for `filter` functions, omit the script block keyword +(`begin`, `process`, `end`, `clean`). PowerShell puts the statements in the +`process` block. You can use any of the other blocks in a filter function, but +the intent was to provide a shorthand way of defining a function that has the +sole purpose of processing each object in the pipeline. + +The following filter takes log entries from the pipeline and then displays +either the whole entry or only the message portion of the entry: + +```powershell +filter Get-EventMessage ([switch]$MessageOnly) { + if ($MessageOnly) { Out-Host -InputObject $_.Message } + else { $_ } } ``` -A function includes the following items: - -- A `function` keyword -- A scope (optional) -- A name that you select -- Any number of named parameters (optional) -- One or more PowerShell commands enclosed in braces `{}` +It can be used as follows: -For more information about the `dynamicparam` keyword and dynamic parameters in -functions, see [about_Functions_Advanced_Parameters][10]. +```powershell +Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly +``` ## Input processing methods The methods described in this section are referred to as the input processing -methods. For functions, these three methods are represented by the `begin`, +methods. For functions, these three methods named using the `begin`, `process`, and `end` blocks of the function. PowerShell 7.3 adds a `clean` block process method. @@ -116,13 +140,12 @@ function. However, if you use any of these named blocks, or define a `dynamicparam` block, you must put all code in a named block. The following example shows the outline of a function that contains a `begin` -block for one-time preprocessing, a `process` block for multiple record -processing, and an `end` block for one-time post-processing. +block for one-time preprocessing, a `process` block data from the pipeline, and +an `end` block for one-time post-processing. ```powershell -Function Test-ScriptCmdlet -{ -[CmdletBinding(SupportsShouldProcess=$true)] +Function Test-ScriptCmdlet { + [CmdletBinding(SupportsShouldProcess=$true)] param ($Parameter1) begin{} process{} @@ -146,25 +169,24 @@ the function receives. The automatic variable `$_` or `$PSItem` contains the current object in the pipeline for use in the `process` block. The `$input` automatic variable contains an enumerator that's only available to functions and script blocks. -For more information, see [about_Automatic_Variables][05]. +For more information, see [about_Automatic_Variables][04]. -- Calling the function at the beginning, or outside of a pipeline, executes the - `process` block once. +- If the function is invoked without pipeline input, PowerShell executes the + `process` block only once. - Within a pipeline, the `process` block executes once for each input object that reaches the function. - If the pipeline input that reaches the function is empty, the `process` block - **does not** execute. + doesn't execute. - The `begin`, `end`, and `clean` blocks still execute. > [!IMPORTANT] -> If a function parameter is set to accept pipeline input, and a `process` -> block isn't defined, record-by-record processing will fail. In this case, -> your function will only execute once, regardless of the input. +> If a function parameter accepts pipeline input, and a `process` block isn't +> defined, record-by-record processing fails. In this case, your function only +> executes once, regardless of the input. ### `end` -This block is used to provide optional one-time post-processing for the -function. +Use this block to provide optional one-time post-processing for the function. ### `clean` @@ -175,19 +197,18 @@ across the `begin`, `process`, and `end` blocks. It's semantically similar to a `finally` block that covers all other named blocks of a script function or a script cmdlet. Resource cleanup is enforced for the following scenarios: -1. when the pipeline execution finishes normally without terminating error +1. when the pipeline execution finishes without terminating error 1. when the pipeline execution is interrupted due to terminating error -1. when the pipeline is halted by `Select-Object -First` -1. when the pipeline is being stopped by Ctrl+c or - `StopProcessing()` +1. when the pipeline is truncated, for example: `Select-Object -First` +1. when the pipeline is stopped by Ctrl+c or `StopProcessing()` -The clean block discards any output that's written to the **Success** stream. +The clean block discards any output written to the **Success** stream. > [!CAUTION] > Adding the `clean` block is a breaking change. Because `clean` is parsed as a > keyword, it prevents users from directly calling a command named `clean` as > the first statement in a script block. However, it's not likely to be a -> problem. The command can still be invoked using the call operator +> problem. You can still invoke the command using the call operator > (`& clean`). ## Simple functions @@ -196,27 +217,26 @@ Functions don't have to be complicated to be useful. The simplest functions have the following format: ```Syntax -function {statements} +function { statements } ``` For example, the following function starts PowerShell with the **Run as Administrator** option. ```powershell -function Start-PSAdmin {Start-Process PowerShell -Verb RunAs} +function Start-PSAdmin { Start-Process PowerShell -Verb RunAs } ``` To use the function, type: `Start-PSAdmin` To add statements to the function, type each statement on a separate line, or -use a semicolon `;` to separate the statements. +use a semicolon (`;`) to separate the statements. For example, the following function finds all `.jpg` files in the current user's directories that were changed after the start date. ```powershell -function Get-NewPicture -{ +function Get-NewPicture { $start = Get-Date -Month 1 -Day 1 -Year 2010 $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse $allPics | Where-Object {$_.LastWriteTime -gt $Start} @@ -224,37 +244,34 @@ function Get-NewPicture ``` You can create a toolbox of useful small functions. Add these functions to your -PowerShell profile, as described in [about_Profiles][15] and later in this -topic. +PowerShell profile, as described in [about_Profiles][14] and later in this +article. -## Function Names +## Function names -You can assign any name to a function, but functions that you share with others -should follow the naming rules that have been established for all PowerShell -commands. +You can assign any name to a function. However, for functions that you share +with others, you should follow the standard PowerShell naming rules. -Functions names should consist of a verb-noun pair where the verb identifies -the action that the function performs and the noun identifies the item on which -the cmdlet performs its action. - -Functions should use the standard verbs that have been approved for all -PowerShell commands. These verbs help us to keep our command names consistent -and easy for users to understand. +- Names should consist of a verb-noun pair where the verb identifies + the action that the function performs and the noun identifies the item on + which the cmdlet performs the action. +- Names should use the approved verbs for all PowerShell commands. Using + approved verbs creates consistency for users. For more information about the standard PowerShell verbs, see [Approved Verbs][02]. -## Functions with Parameters +## Functions with parameters You can use parameters with functions, including named parameters, positional parameters, switch parameters, and dynamic parameters. For more information about dynamic parameters in functions, see -[about_Functions_Advanced_Parameters][10]. +[about_Functions_Advanced_Parameters][09]. -### Named Parameters +### Named parameters You can define any number of named parameters. You can include a default value -for named parameters, as described later in this topic. +for named parameters, as described later in this article. You can define parameters inside the braces using the `param` keyword, as shown in the following sample syntax: @@ -275,7 +292,8 @@ function [([type]$Parameter1[,[type]$Parameter2])] { } ``` -Below is an example of this alternative syntax. +For example, the following function uses the alternative syntax to define two +parameters: ```powershell function Add-Numbers([int]$One, [int]$Two) { @@ -283,7 +301,7 @@ function Add-Numbers([int]$One, [int]$Two) { } ``` -While the first method is preferred, there is no difference between these two +While the first method is preferred, there's no difference between these two methods. When you run the function, the value you supply for a parameter is assigned to @@ -357,7 +375,7 @@ function Get-SmallFiles { For more information about the **PSDefaultValue** attribute class, see [PSDefaultValue Attribute Members][01]. -### Positional Parameters +### Positional parameters A positional parameter is a parameter without a parameter name. PowerShell uses the parameter value order to associate each parameter value with a parameter in @@ -386,7 +404,7 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch Parameters +### Switch parameters A switch is a parameter that doesn't require a value. Instead, you type the function name followed by the name of the switch parameter. @@ -440,7 +458,7 @@ Switch-Item -On:$false Switch off ``` -## Using Splatting to Represent Command Parameters +## Use splatting to pass parameter values You can use splatting to represent the parameters of a command. This feature is introduced in Windows PowerShell 3.0. @@ -473,9 +491,9 @@ Cmdlet Get-ChildItem Microsoft.PowerShell.Management The `@args` feature uses the `$args` automatic parameter, which represents undeclared cmdlet parameters and values from remaining arguments. -For more information, see [about_Splatting][19]. +For more information, see [about_Splatting][18]. -## Piping Objects to Functions +## Piping objects to functions Any function can take input from the pipeline. You can control how a function processes input from the pipeline using `begin`, `process`, `end`, and `clean` @@ -535,12 +553,12 @@ PS> Get-SumOfNumbers 1, 2, 3, 4 When you use a function in a pipeline, the objects piped to the function are assigned to the `$input` automatic variable. The function runs statements with -the `begin` keyword before any objects come from the pipeline. The function -runs statements with the `end` keyword after all the objects have been received -from the pipeline. +the `begin` script block before any objects come from the pipeline. The +function runs statements with the `end` script block when there are no more +objects in the pipeline. -The following example shows the `$input` automatic variable with `begin` and -`end` keywords. +The following example shows the `$input` automatic variable used int the +`begin` and `end` script blocks. ```powershell function Get-PipelineBeginEnd { @@ -549,7 +567,7 @@ function Get-PipelineBeginEnd { } ``` -If this function is run using the pipeline, it displays the following +When you run the function with pipeline input, it displays the following results: ```powershell @@ -576,10 +594,10 @@ function Get-PipelineInput } ``` -In this example, each object that's piped to the function is sent to the -`process` statement list. The `process` statements run on each object, one -object at a time. The `$input` automatic variable is empty when the function -reaches the `end` keyword. +In this example, each object piped to the function is sent to the `process` +statement list. The `process` statements run on each object, one object at a +time. The `$input` automatic variable is empty when the function reaches the +`end` keyword. ```powershell 1, 2, 4 | Get-PipelineInput @@ -592,7 +610,7 @@ Processing: 4 End: The input is: ``` -For more information, see [Using Enumerators][06] +For more information, see [Using Enumerators][05] PowerShell 7.3 added the `clean` block. The `clean` block is a convenient way for users to clean up resources created and used in the `begin`, `process`, and @@ -602,9 +620,8 @@ enforced for the following scenarios: 1. when the pipeline execution finishes normally without terminating error 1. when the pipeline execution is interrupted due to terminating error -1. when the pipeline is halted by `Select-Object -First` -1. when the pipeline is being stopped by Ctrl+C or - `StopProcessing()` +1. when the pipeline is truncated, for example: `Select-Object -First` +1. when the pipeline is stopped by Ctrl+C or `StopProcessing()` > [!CAUTION] > Adding the `clean` block is a breaking change. Because `clean` is parsed as a @@ -613,37 +630,9 @@ enforced for the following scenarios: > problem. The command can still be invoked using the call operator > (`& clean`). -## Filters - -A filter is a type of function that runs on each object in the pipeline. A -filter resembles a function with all its statements in a `process` block. - -The syntax of a filter is as follows: - -``` -filter [] {} -``` - -The following filter takes log entries from the pipeline and then displays -either the whole entry or only the message portion of the entry: - -```powershell -filter Get-ErrorLog ([switch]$Message) -{ - if ($Message) { Out-Host -InputObject $_.Message } - else { $_ } -} -``` - -It can be used as follows: - -```powershell -Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message -``` - -## Function Scope +## Function scope -A function exists in the scope in which it's created. +A function exists in the scope in which you create it. If a function is part of a script, the function is available to statements within that script. By default, a function in a script isn't available outside @@ -664,9 +653,9 @@ in functions, and at the command line. Functions create a new scope. The items created in a function, such as variables, exist only in the function scope. -For more information, see [about_Scopes][17]. +For more information, see [about_Scopes][16]. -## Finding and Managing Functions Using the Function: Drive +## Find and manage functions using the `Function:` drive All the functions and filters in PowerShell are automatically stored in the `Function:` drive. This drive is exposed by the PowerShell **Function** @@ -696,26 +685,25 @@ You can also use the following syntax. $Function:help ``` -For more information about the `Function:` drive, see the help topic for the -**Function** provider. Type `Get-Help Function`. +For more information, see +[about_Function_Provider][07]. -## Reusing Functions in New Sessions +## Reuse functions in new sessions When you type a function at the PowerShell command prompt, the function becomes part of the current session. The function is available until the session ends. To use your function in all PowerShell sessions, add the function to your PowerShell profile. For more information about profiles, see -[about_Profiles][15]. +[about_Profiles][14]. You can also save your function in a PowerShell script file. Type your function in a text file, and then save the file with the `.ps1` filename extension. -## Writing Help for Functions +## Create Help for functions -The `Get-Help` cmdlet gets help for functions, as well as for cmdlets, -providers, and scripts. To get help for a function, type `Get-Help` followed by -the function name. +The `Get-Help` cmdlet gets help for functions, cmdlets, providers, and scripts. +To get help for a function, type `Get-Help` followed by the function name. For example, to get help for the `Get-MyDisks` function, type: @@ -727,59 +715,53 @@ You can write help for a function using either of the two following methods: - Comment-Based Help for Functions - Create a help topic using special keywords in the comments. To create - comment-based help for a function, the comments must be placed at the - beginning or end of the function body or on the lines preceding the function - keyword. For more information about comment-based help, see - [about_Comment_Based_Help][07]. + Create help using special keywords in the comments. To create comment-based + help for a function, the comments must be placed at the beginning, end, or + within the body of the function. For more information about comment-based + help, see [about_Comment_Based_Help][06]. - XML-Based Help for Functions - Create an XML-based help topic, such as the type that's typically created for - cmdlets. XML-based help is required if you are localizing help topics into - multiple languages. - - To associate the function with the XML-based help topic, use the + XML-based help is required if you need to localize help content into multiple + languages. To associate the function with the XML-based help file, use the `.EXTERNALHELP` comment-based help keyword. Without this keyword, `Get-Help` - can't find the function help topic and calls to `Get-Help` for the function - return only autogenerated help. + can't find the function help file and only returns the autogenerated help. For more information about the `.EXTERNALHELP` keyword, see - [about_Comment_Based_Help][07]. For more information about XML-based help, + [about_Comment_Based_Help][06]. For more information about XML-based help, see [How to Write Cmdlet Help][03]. ## See also -- [about_Automatic_Variables][05] -- [about_Comment_Based_Help][07] -- [about_Function_Provider][08] -- [about_Functions_Advanced][11] -- [about_Functions_Advanced_Methods][09] -- [about_Functions_Advanced_Parameters][10] -- [about_Functions_CmdletBindingAttribute][12] -- [about_Functions_OutputTypeAttribute][13] -- [about_Parameters][14] -- [about_Profiles][15] -- [about_Scopes][17] -- [about_Script_Blocks][18] +- [about_Automatic_Variables][04] +- [about_Comment_Based_Help][06] +- [about_Function_Provider][07] +- [about_Functions_Advanced][10] +- [about_Functions_Advanced_Methods][08] +- [about_Functions_Advanced_Parameters][09] +- [about_Functions_CmdletBindingAttribute][11] +- [about_Functions_OutputTypeAttribute][12] +- [about_Parameters][13] +- [about_Profiles][14] +- [about_Scopes][16] +- [about_Script_Blocks][17] [01]: /dotnet/api/system.management.automation.psdefaultvalueattribute [02]: /powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands [03]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets -[04]: #filters -[05]: about_Automatic_Variables.md -[06]: about_Automatic_Variables.md#using-enumerators -[07]: about_Comment_Based_Help.md -[08]: about_Function_Provider.md -[09]: about_Functions_Advanced_Methods.md -[10]: about_Functions_Advanced_Parameters.md -[11]: about_Functions_Advanced.md -[12]: about_Functions_CmdletBindingAttribute.md -[13]: about_Functions_OutputTypeAttribute.md -[14]: about_Parameters.md -[15]: about_Profiles.md -[16]: about_Return.md -[17]: about_Scopes.md -[18]: about_Script_Blocks.md -[19]: about_Splatting.md +[04]: about_Automatic_Variables.md +[05]: about_Automatic_Variables.md#using-enumerators +[06]: about_Comment_Based_Help.md +[07]: about_Function_Provider.md +[08]: about_Functions_Advanced_Methods.md +[09]: about_Functions_Advanced_Parameters.md +[10]: about_Functions_Advanced.md +[11]: about_Functions_CmdletBindingAttribute.md +[12]: about_Functions_OutputTypeAttribute.md +[13]: about_Parameters.md +[14]: about_Profiles.md +[15]: about_Return.md +[16]: about_Scopes.md +[17]: about_Script_Blocks.md +[18]: about_Splatting.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSItem.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSItem.md index 2cc44eef41e5..859ac6025ccd 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_PSItem.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_PSItem.md @@ -418,7 +418,7 @@ with the default format for the current culture by casting the value to [07]: about_Functions_Advanced_Parameters.md#validatescript-validation-attribute [08]: about_Functions_Advanced.md [09]: about_Functions.md -[10]: about_Functions.md#filters +[10]: about_Functions.md#filter-syntax [11]: about_Script_Blocks.md [12]: about_Script_Blocks.md#using-delay-bind-script-blocks-with-parameters [13]: about_Switch.md diff --git a/reference/7.5/Microsoft.PowerShell.Core/Out-Default.md b/reference/7.5/Microsoft.PowerShell.Core/Out-Default.md index d1dbaa5af16a..bb89ca4b5072 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Out-Default.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 02/07/2023 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-default?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Default @@ -20,24 +20,9 @@ Out-Default [-Transcript] [-InputObject ] [] ## DESCRIPTION -PowerShell automatically adds `Out-Default` to the end of every pipeline. `Out-Default` decides how -to format and output the object stream. If the object stream is a stream of strings, `Out-Default` -pipes these directly to `Out-Host` which calls the appropriate APIs provided by the host. If the -object stream does not contain strings, `Out-Default` inspects the object to determine what to do. -First it looks at the object type and determines whether there is a registered _view_ for this -object type. - -PowerShell defines an XML schema and a mechanism (the `Update-FormatData` cmdlet) where anyone can -register views for an object type. You can specify **wide**, **list**, **table**, or **custom** -views for any object type. The views specify which properties to display and how they should be -displayed. If a view is registered, it defines which formatter to use. So if the registered view is -a **table** view, `Out-Default` streams the objects to `Format-Table | Out-Host`. `Format-Table` -transforms the objects into a stream of Formatting records (driven by the data in the view -definition) and `Out-Host` transforms the formatting records into calls on the Host interface. - -This cmdlet isn't intended to be used by the end user. Other cmdlets are recommended for controlling -output like [Out-Host](Out-Host.md) or using `Format-*` cmdlets and the -[Format.ps1xml](About/about_Format.ps1xml.md) file to control formatting. +PowerShell automatically adds `Out-Default` to the end of every top-level interactive pipeline. +`Out-Default` passes the objects it receives to the PowerShell format system. Then, it writes the +formatted output to the console. This cmdlet isn't intended to be used by the end user. ## EXAMPLES @@ -82,7 +67,7 @@ Accept wildcard characters: False ### -Transcript -Determines whether the output should be sent to PowerShell's transcription services. +When you use this parameter, the output is only sent to the PowerShell transcript. ```yaml Type: System.Management.Automation.SwitchParameter diff --git a/reference/7.5/Microsoft.PowerShell.Core/Out-Host.md b/reference/7.5/Microsoft.PowerShell.Core/Out-Host.md index 87f05c93b095..7a209ff119a1 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/Out-Host.md +++ b/reference/7.5/Microsoft.PowerShell.Core/Out-Host.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/31/2022 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-host?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Host @@ -27,10 +27,9 @@ The `Out-Host` cmdlet sends output to the PowerShell host for display. The host at the command line. Because `Out-Host` is the default, you don't have to specify it unless you want to use its parameters. -`Out-Host` is automatically appended to every command that is executed. It passes the output of the -pipeline to the host executing the command. `Out-Host` ignores ANSI escape sequences. The escape -sequences are handled by the host. `Out-Host` passes ANSI escape sequences to the host without -trying to interpret or change them. +`Out-Host` passes the output of the pipeline to the host executing the command. `Out-Host` ignores +ANSI escape sequences. The escape sequences are handled by the host. `Out-Host` passes ANSI escape +sequences to the host without trying to interpret or change them. ## EXAMPLES @@ -89,14 +88,14 @@ Accept wildcard characters: False ### -Paging -Indicates that `Out-Host` displays one page of output at a time, and waits for user input before the -remaining pages are displayed. By default, all the output is displayed on a single page. The page -size is determined by the characteristics of the host. +Indicates that `Out-Host` displays one page of output at a time. The page size is determined by the +characteristics of the host. -Press the Space bar to display the next page of output or the Enter key to -view the next line of output. Press Q to quit. +After outputting the first page, the command waits for user input before the remaining pages are +displayed. Press the Spacebar to display the next page of output or the Enter +key to view the next line of output. Press Q to quit. -**Paging** is similar to the **more** command. +Using **Paging** is similar to using the **more** command. > [!NOTE] > The **Paging** parameter isn't supported by the PowerShell ISE host. @@ -139,20 +138,22 @@ PowerShell includes the following aliases for `Out-Host`: - All platforms: - `oh` -The **Paging** parameter isn't supported by all PowerShell hosts. For example, if you use the -**Paging** parameter in the PowerShell ISE, the following error is displayed: -`out-lineoutput : The method or operation is not implemented.` +Not all PowerShell hosts support the **Paging** parameter. For example, if you use the **Paging** +parameter in the Windows PowerShell ISE, the following error is displayed: + +> out-lineoutput : The method or operation is not implemented. The cmdlets that contain the **Out** verb, `Out-`, don't format objects. They render objects and send them to the specified display destination. If you send an unformatted object to an `Out-` cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. -The `Out-` cmdlets don't have parameters for names or file paths. To send data to an `Out-` cmdlet, -use the pipeline to send a PowerShell command's output to the cmdlet. Or, you can store data in a -variable and use the **InputObject** parameter to pass the data to the cmdlet. +The `Out-` cmdlets don't read input from files. To send data to an `Out-` cmdlet, use the pipeline +to send data to the cmdlet. Or, you can store data in a variable and use the **InputObject** +parameter to pass the data to the cmdlet. -`Out-Host` sends data, but it doesn't produce any output objects. If you pipeline the output of -`Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects have been specified. +`Out-Host` sends data to the host only. Tt doesn't produce output objects to the pipeline. If you +pipeline the output of `Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects +have been specified. ## RELATED LINKS diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md index cdf5aadfba98..26d85605329d 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 06/26/2024 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: about_Functions @@ -16,10 +16,58 @@ Describes how to create and use functions in PowerShell. ## Long description A function is a list of PowerShell statements that has a name that you assign. -When you run a function, you type the function name. The statements in the list -run as if you had typed them at the command prompt. +When you run a function, you type the function name. -Functions can be as simple as: +PowerShell defines two kinds of functions: + +- A **function** is a block of code that can be called by name. It can take + input and return output. Functions are defined using the `function` keyword. +- A **filter** is a type of function designed to process data from the + pipeline. Filters are defined using the `filter` keyword. + +You can group the statements in a function into one of four different +predefined script blocks. These script blocks are named using the keywords +`begin`, `process`, `end`, and `clean`. If you don't use these keywords, +PowerShell puts the statements in the appropriate code block. + +Functions can also act like cmdlets. You can create a function that works just +like a cmdlet without using `C#` programming. For more information, see +[about_Functions_Advanced][10]. + +> [!IMPORTANT] +> Within script files and script-based modules, functions must be defined +> before they can be called. + +## Function syntax + +Functions are defined using the following syntax: + +```Syntax +function [] { + param([type]$Parameter1 [,[type]$Parameter2]) + dynamicparam {} + begin {} + process {} + end {} + clean {} +} +``` + +A function includes the following items: + +- A `function` keyword +- A scope (optional) +- A name that you select +- Any number of named parameters (optional), including dynamic parameters +- One or more PowerShell statements enclosed in braces `{}` + +If you don't use one of the keywords (`begin`, `process`, `end`, `clean`) in a +`function` definition, PowerShell puts the statements in the `end` block. + +For more information about the `dynamicparam` keyword and dynamic parameters in +functions, see [about_Functions_Advanced_Parameters][09]. + +A function can be as simple as: ```powershell function Get-PowerShellProcess { Get-Process pwsh } @@ -38,75 +86,51 @@ Get-PowerShellProcess 110 78.72 172.39 10.62 10936 1 pwsh ``` -A function can also be as complex as a cmdlet or an application. - -Like cmdlets, functions can have parameters. The parameters can be named, -positional, switch, or dynamic parameters. Function parameters can be read from -the command line or from the pipeline. +A function can also be as complex as a cmdlet. Functions can return values that can be displayed, assigned to variables, or -passed to other functions or cmdlets. You can also specify a return value using -the `return` keyword. The `return` keyword doesn't affect or suppress other -output returned from your function. However, the `return` keyword exits the -function at that line. For more information, see [about_Return][16]. +passed to other functions or cmdlets. You can use the `return` keyword to +return output. The `return` keyword doesn't affect or suppress other output +returned from your function. However, the `return` keyword exits the function +at that line. For more information, see [about_Return][15]. -The function's statement list can contain different types of statement lists -with the keywords `begin`, `process`, `end`, and `clean`. These statement lists -handle input from the pipeline differently. +## Filter syntax -The [filter][04] keyword is used to create a type of function that runs on each -object in the pipeline. A filter resembles a function with all its statements -in a `process` block. +The intent of the `filter` function is to provide a shorthand way of defining a +function that runs on each object in the pipeline. -Functions can also act like cmdlets. You can create a function that works just -like a cmdlet without using `C#` programming. For more information, see -[about_Functions_Advanced][11]. - -> [!IMPORTANT] -> Within script files and script-based modules, functions must be defined -> before they can be called. - -## Syntax - -The following are the syntax for a function: +The syntax of a filter is as follows: ```Syntax -function [] [([type]$Parameter1[,[type]$Parameter2])] -{ - begin {} - process {} - end {} - clean {} -} +filter [] {} ``` -```Syntax -function [] -{ - param([type]$Parameter1 [,[type]$Parameter2]) - dynamicparam {} - begin {} - process {} - end {} - clean {} +To simplify the syntax for `filter` functions, omit the script block keyword +(`begin`, `process`, `end`, `clean`). PowerShell puts the statements in the +`process` block. You can use any of the other blocks in a filter function, but +the intent was to provide a shorthand way of defining a function that has the +sole purpose of processing each object in the pipeline. + +The following filter takes log entries from the pipeline and then displays +either the whole entry or only the message portion of the entry: + +```powershell +filter Get-EventMessage ([switch]$MessageOnly) { + if ($MessageOnly) { Out-Host -InputObject $_.Message } + else { $_ } } ``` -A function includes the following items: - -- A `function` keyword -- A scope (optional) -- A name that you select -- Any number of named parameters (optional) -- One or more PowerShell commands enclosed in braces `{}` +It can be used as follows: -For more information about the `dynamicparam` keyword and dynamic parameters in -functions, see [about_Functions_Advanced_Parameters][10]. +```powershell +Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly +``` ## Input processing methods The methods described in this section are referred to as the input processing -methods. For functions, these three methods are represented by the `begin`, +methods. For functions, these three methods named using the `begin`, `process`, and `end` blocks of the function. PowerShell 7.3 adds a `clean` block process method. @@ -116,13 +140,12 @@ function. However, if you use any of these named blocks, or define a `dynamicparam` block, you must put all code in a named block. The following example shows the outline of a function that contains a `begin` -block for one-time preprocessing, a `process` block for multiple record -processing, and an `end` block for one-time post-processing. +block for one-time preprocessing, a `process` block data from the pipeline, and +an `end` block for one-time post-processing. ```powershell -Function Test-ScriptCmdlet -{ -[CmdletBinding(SupportsShouldProcess=$true)] +Function Test-ScriptCmdlet { + [CmdletBinding(SupportsShouldProcess=$true)] param ($Parameter1) begin{} process{} @@ -146,25 +169,24 @@ the function receives. The automatic variable `$_` or `$PSItem` contains the current object in the pipeline for use in the `process` block. The `$input` automatic variable contains an enumerator that's only available to functions and script blocks. -For more information, see [about_Automatic_Variables][05]. +For more information, see [about_Automatic_Variables][04]. -- Calling the function at the beginning, or outside of a pipeline, executes the - `process` block once. +- If the function is invoked without pipeline input, PowerShell executes the + `process` block only once. - Within a pipeline, the `process` block executes once for each input object that reaches the function. - If the pipeline input that reaches the function is empty, the `process` block - **does not** execute. + doesn't execute. - The `begin`, `end`, and `clean` blocks still execute. > [!IMPORTANT] -> If a function parameter is set to accept pipeline input, and a `process` -> block isn't defined, record-by-record processing will fail. In this case, -> your function will only execute once, regardless of the input. +> If a function parameter accepts pipeline input, and a `process` block isn't +> defined, record-by-record processing fails. In this case, your function only +> executes once, regardless of the input. ### `end` -This block is used to provide optional one-time post-processing for the -function. +Use this block to provide optional one-time post-processing for the function. ### `clean` @@ -175,19 +197,18 @@ across the `begin`, `process`, and `end` blocks. It's semantically similar to a `finally` block that covers all other named blocks of a script function or a script cmdlet. Resource cleanup is enforced for the following scenarios: -1. when the pipeline execution finishes normally without terminating error +1. when the pipeline execution finishes without terminating error 1. when the pipeline execution is interrupted due to terminating error -1. when the pipeline is halted by `Select-Object -First` -1. when the pipeline is being stopped by Ctrl+c or - `StopProcessing()` +1. when the pipeline is truncated, for example: `Select-Object -First` +1. when the pipeline is stopped by Ctrl+c or `StopProcessing()` -The clean block discards any output that's written to the **Success** stream. +The clean block discards any output written to the **Success** stream. > [!CAUTION] > Adding the `clean` block is a breaking change. Because `clean` is parsed as a > keyword, it prevents users from directly calling a command named `clean` as > the first statement in a script block. However, it's not likely to be a -> problem. The command can still be invoked using the call operator +> problem. You can still invoke the command using the call operator > (`& clean`). ## Simple functions @@ -196,27 +217,26 @@ Functions don't have to be complicated to be useful. The simplest functions have the following format: ```Syntax -function {statements} +function { statements } ``` For example, the following function starts PowerShell with the **Run as Administrator** option. ```powershell -function Start-PSAdmin {Start-Process PowerShell -Verb RunAs} +function Start-PSAdmin { Start-Process PowerShell -Verb RunAs } ``` To use the function, type: `Start-PSAdmin` To add statements to the function, type each statement on a separate line, or -use a semicolon `;` to separate the statements. +use a semicolon (`;`) to separate the statements. For example, the following function finds all `.jpg` files in the current user's directories that were changed after the start date. ```powershell -function Get-NewPicture -{ +function Get-NewPicture { $start = Get-Date -Month 1 -Day 1 -Year 2010 $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse $allPics | Where-Object {$_.LastWriteTime -gt $Start} @@ -224,37 +244,34 @@ function Get-NewPicture ``` You can create a toolbox of useful small functions. Add these functions to your -PowerShell profile, as described in [about_Profiles][15] and later in this -topic. +PowerShell profile, as described in [about_Profiles][14] and later in this +article. -## Function Names +## Function names -You can assign any name to a function, but functions that you share with others -should follow the naming rules that have been established for all PowerShell -commands. +You can assign any name to a function. However, for functions that you share +with others, you should follow the standard PowerShell naming rules. -Functions names should consist of a verb-noun pair where the verb identifies -the action that the function performs and the noun identifies the item on which -the cmdlet performs its action. - -Functions should use the standard verbs that have been approved for all -PowerShell commands. These verbs help us to keep our command names consistent -and easy for users to understand. +- Names should consist of a verb-noun pair where the verb identifies + the action that the function performs and the noun identifies the item on + which the cmdlet performs the action. +- Names should use the approved verbs for all PowerShell commands. Using + approved verbs creates consistency for users. For more information about the standard PowerShell verbs, see [Approved Verbs][02]. -## Functions with Parameters +## Functions with parameters You can use parameters with functions, including named parameters, positional parameters, switch parameters, and dynamic parameters. For more information about dynamic parameters in functions, see -[about_Functions_Advanced_Parameters][10]. +[about_Functions_Advanced_Parameters][09]. -### Named Parameters +### Named parameters You can define any number of named parameters. You can include a default value -for named parameters, as described later in this topic. +for named parameters, as described later in this article. You can define parameters inside the braces using the `param` keyword, as shown in the following sample syntax: @@ -275,7 +292,8 @@ function [([type]$Parameter1[,[type]$Parameter2])] { } ``` -Below is an example of this alternative syntax. +For example, the following function uses the alternative syntax to define two +parameters: ```powershell function Add-Numbers([int]$One, [int]$Two) { @@ -283,7 +301,7 @@ function Add-Numbers([int]$One, [int]$Two) { } ``` -While the first method is preferred, there is no difference between these two +While the first method is preferred, there's no difference between these two methods. When you run the function, the value you supply for a parameter is assigned to @@ -357,7 +375,7 @@ function Get-SmallFiles { For more information about the **PSDefaultValue** attribute class, see [PSDefaultValue Attribute Members][01]. -### Positional Parameters +### Positional parameters A positional parameter is a parameter without a parameter name. PowerShell uses the parameter value order to associate each parameter value with a parameter in @@ -386,7 +404,7 @@ Get-Extension myTextFile myTextFile.txt ``` -### Switch Parameters +### Switch parameters A switch is a parameter that doesn't require a value. Instead, you type the function name followed by the name of the switch parameter. @@ -440,7 +458,7 @@ Switch-Item -On:$false Switch off ``` -## Using Splatting to Represent Command Parameters +## Use splatting to pass parameter values You can use splatting to represent the parameters of a command. This feature is introduced in Windows PowerShell 3.0. @@ -473,9 +491,9 @@ Cmdlet Get-ChildItem Microsoft.PowerShell.Management The `@args` feature uses the `$args` automatic parameter, which represents undeclared cmdlet parameters and values from remaining arguments. -For more information, see [about_Splatting][19]. +For more information, see [about_Splatting][18]. -## Piping Objects to Functions +## Piping objects to functions Any function can take input from the pipeline. You can control how a function processes input from the pipeline using `begin`, `process`, `end`, and `clean` @@ -535,12 +553,12 @@ PS> Get-SumOfNumbers 1, 2, 3, 4 When you use a function in a pipeline, the objects piped to the function are assigned to the `$input` automatic variable. The function runs statements with -the `begin` keyword before any objects come from the pipeline. The function -runs statements with the `end` keyword after all the objects have been received -from the pipeline. +the `begin` script block before any objects come from the pipeline. The +function runs statements with the `end` script block when there are no more +objects in the pipeline. -The following example shows the `$input` automatic variable with `begin` and -`end` keywords. +The following example shows the `$input` automatic variable used int the +`begin` and `end` script blocks. ```powershell function Get-PipelineBeginEnd { @@ -549,7 +567,7 @@ function Get-PipelineBeginEnd { } ``` -If this function is run using the pipeline, it displays the following +When you run the function with pipeline input, it displays the following results: ```powershell @@ -576,10 +594,10 @@ function Get-PipelineInput } ``` -In this example, each object that's piped to the function is sent to the -`process` statement list. The `process` statements run on each object, one -object at a time. The `$input` automatic variable is empty when the function -reaches the `end` keyword. +In this example, each object piped to the function is sent to the `process` +statement list. The `process` statements run on each object, one object at a +time. The `$input` automatic variable is empty when the function reaches the +`end` keyword. ```powershell 1, 2, 4 | Get-PipelineInput @@ -592,7 +610,7 @@ Processing: 4 End: The input is: ``` -For more information, see [Using Enumerators][06] +For more information, see [Using Enumerators][05] PowerShell 7.3 added the `clean` block. The `clean` block is a convenient way for users to clean up resources created and used in the `begin`, `process`, and @@ -602,9 +620,8 @@ enforced for the following scenarios: 1. when the pipeline execution finishes normally without terminating error 1. when the pipeline execution is interrupted due to terminating error -1. when the pipeline is halted by `Select-Object -First` -1. when the pipeline is being stopped by Ctrl+C or - `StopProcessing()` +1. when the pipeline is truncated, for example: `Select-Object -First` +1. when the pipeline is stopped by Ctrl+C or `StopProcessing()` > [!CAUTION] > Adding the `clean` block is a breaking change. Because `clean` is parsed as a @@ -613,37 +630,9 @@ enforced for the following scenarios: > problem. The command can still be invoked using the call operator > (`& clean`). -## Filters - -A filter is a type of function that runs on each object in the pipeline. A -filter resembles a function with all its statements in a `process` block. - -The syntax of a filter is as follows: - -``` -filter [] {} -``` - -The following filter takes log entries from the pipeline and then displays -either the whole entry or only the message portion of the entry: - -```powershell -filter Get-ErrorLog ([switch]$Message) -{ - if ($Message) { Out-Host -InputObject $_.Message } - else { $_ } -} -``` - -It can be used as follows: - -```powershell -Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message -``` - -## Function Scope +## Function scope -A function exists in the scope in which it's created. +A function exists in the scope in which you create it. If a function is part of a script, the function is available to statements within that script. By default, a function in a script isn't available outside @@ -664,9 +653,9 @@ in functions, and at the command line. Functions create a new scope. The items created in a function, such as variables, exist only in the function scope. -For more information, see [about_Scopes][17]. +For more information, see [about_Scopes][16]. -## Finding and Managing Functions Using the Function: Drive +## Find and manage functions using the `Function:` drive All the functions and filters in PowerShell are automatically stored in the `Function:` drive. This drive is exposed by the PowerShell **Function** @@ -696,26 +685,25 @@ You can also use the following syntax. $Function:help ``` -For more information about the `Function:` drive, see the help topic for the -**Function** provider. Type `Get-Help Function`. +For more information, see +[about_Function_Provider][07]. -## Reusing Functions in New Sessions +## Reuse functions in new sessions When you type a function at the PowerShell command prompt, the function becomes part of the current session. The function is available until the session ends. To use your function in all PowerShell sessions, add the function to your PowerShell profile. For more information about profiles, see -[about_Profiles][15]. +[about_Profiles][14]. You can also save your function in a PowerShell script file. Type your function in a text file, and then save the file with the `.ps1` filename extension. -## Writing Help for Functions +## Create Help for functions -The `Get-Help` cmdlet gets help for functions, as well as for cmdlets, -providers, and scripts. To get help for a function, type `Get-Help` followed by -the function name. +The `Get-Help` cmdlet gets help for functions, cmdlets, providers, and scripts. +To get help for a function, type `Get-Help` followed by the function name. For example, to get help for the `Get-MyDisks` function, type: @@ -727,59 +715,53 @@ You can write help for a function using either of the two following methods: - Comment-Based Help for Functions - Create a help topic using special keywords in the comments. To create - comment-based help for a function, the comments must be placed at the - beginning or end of the function body or on the lines preceding the function - keyword. For more information about comment-based help, see - [about_Comment_Based_Help][07]. + Create help using special keywords in the comments. To create comment-based + help for a function, the comments must be placed at the beginning, end, or + within the body of the function. For more information about comment-based + help, see [about_Comment_Based_Help][06]. - XML-Based Help for Functions - Create an XML-based help topic, such as the type that's typically created for - cmdlets. XML-based help is required if you are localizing help topics into - multiple languages. - - To associate the function with the XML-based help topic, use the + XML-based help is required if you need to localize help content into multiple + languages. To associate the function with the XML-based help file, use the `.EXTERNALHELP` comment-based help keyword. Without this keyword, `Get-Help` - can't find the function help topic and calls to `Get-Help` for the function - return only autogenerated help. + can't find the function help file and only returns the autogenerated help. For more information about the `.EXTERNALHELP` keyword, see - [about_Comment_Based_Help][07]. For more information about XML-based help, + [about_Comment_Based_Help][06]. For more information about XML-based help, see [How to Write Cmdlet Help][03]. ## See also -- [about_Automatic_Variables][05] -- [about_Comment_Based_Help][07] -- [about_Function_Provider][08] -- [about_Functions_Advanced][11] -- [about_Functions_Advanced_Methods][09] -- [about_Functions_Advanced_Parameters][10] -- [about_Functions_CmdletBindingAttribute][12] -- [about_Functions_OutputTypeAttribute][13] -- [about_Parameters][14] -- [about_Profiles][15] -- [about_Scopes][17] -- [about_Script_Blocks][18] +- [about_Automatic_Variables][04] +- [about_Comment_Based_Help][06] +- [about_Function_Provider][07] +- [about_Functions_Advanced][10] +- [about_Functions_Advanced_Methods][08] +- [about_Functions_Advanced_Parameters][09] +- [about_Functions_CmdletBindingAttribute][11] +- [about_Functions_OutputTypeAttribute][12] +- [about_Parameters][13] +- [about_Profiles][14] +- [about_Scopes][16] +- [about_Script_Blocks][17] [01]: /dotnet/api/system.management.automation.psdefaultvalueattribute [02]: /powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands [03]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-cmdlets -[04]: #filters -[05]: about_Automatic_Variables.md -[06]: about_Automatic_Variables.md#using-enumerators -[07]: about_Comment_Based_Help.md -[08]: about_Function_Provider.md -[09]: about_Functions_Advanced_Methods.md -[10]: about_Functions_Advanced_Parameters.md -[11]: about_Functions_Advanced.md -[12]: about_Functions_CmdletBindingAttribute.md -[13]: about_Functions_OutputTypeAttribute.md -[14]: about_Parameters.md -[15]: about_Profiles.md -[16]: about_Return.md -[17]: about_Scopes.md -[18]: about_Script_Blocks.md -[19]: about_Splatting.md +[04]: about_Automatic_Variables.md +[05]: about_Automatic_Variables.md#using-enumerators +[06]: about_Comment_Based_Help.md +[07]: about_Function_Provider.md +[08]: about_Functions_Advanced_Methods.md +[09]: about_Functions_Advanced_Parameters.md +[10]: about_Functions_Advanced.md +[11]: about_Functions_CmdletBindingAttribute.md +[12]: about_Functions_OutputTypeAttribute.md +[13]: about_Parameters.md +[14]: about_Profiles.md +[15]: about_Return.md +[16]: about_Scopes.md +[17]: about_Script_Blocks.md +[18]: about_Splatting.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/About/about_PSItem.md b/reference/7.6/Microsoft.PowerShell.Core/About/about_PSItem.md index ed05725cd446..6652d41b1695 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/About/about_PSItem.md +++ b/reference/7.6/Microsoft.PowerShell.Core/About/about_PSItem.md @@ -418,7 +418,7 @@ with the default format for the current culture by casting the value to [07]: about_Functions_Advanced_Parameters.md#validatescript-validation-attribute [08]: about_Functions_Advanced.md [09]: about_Functions.md -[10]: about_Functions.md#filters +[10]: about_Functions.md#filter-syntax [11]: about_Script_Blocks.md [12]: about_Script_Blocks.md#using-delay-bind-script-blocks-with-parameters [13]: about_Switch.md diff --git a/reference/7.6/Microsoft.PowerShell.Core/Out-Default.md b/reference/7.6/Microsoft.PowerShell.Core/Out-Default.md index 52a215682028..c6c9a4c12717 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/Out-Default.md +++ b/reference/7.6/Microsoft.PowerShell.Core/Out-Default.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 02/07/2023 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-default?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Default @@ -20,24 +20,9 @@ Out-Default [-Transcript] [-InputObject ] [] ## DESCRIPTION -PowerShell automatically adds `Out-Default` to the end of every pipeline. `Out-Default` decides how -to format and output the object stream. If the object stream is a stream of strings, `Out-Default` -pipes these directly to `Out-Host` which calls the appropriate APIs provided by the host. If the -object stream does not contain strings, `Out-Default` inspects the object to determine what to do. -First it looks at the object type and determines whether there is a registered _view_ for this -object type. - -PowerShell defines an XML schema and a mechanism (the `Update-FormatData` cmdlet) where anyone can -register views for an object type. You can specify **wide**, **list**, **table**, or **custom** -views for any object type. The views specify which properties to display and how they should be -displayed. If a view is registered, it defines which formatter to use. So if the registered view is -a **table** view, `Out-Default` streams the objects to `Format-Table | Out-Host`. `Format-Table` -transforms the objects into a stream of Formatting records (driven by the data in the view -definition) and `Out-Host` transforms the formatting records into calls on the Host interface. - -This cmdlet isn't intended to be used by the end user. Other cmdlets are recommended for controlling -output like [Out-Host](Out-Host.md) or using `Format-*` cmdlets and the [Format.ps1xml](About/about_format.ps1xml.md) -file to control formatting. +PowerShell automatically adds `Out-Default` to the end of every top-level interactive pipeline. +`Out-Default` passes the objects it receives to the PowerShell format system. Then, it writes the +formatted output to the console. This cmdlet isn't intended to be used by the end user. ## EXAMPLES @@ -82,7 +67,7 @@ Accept wildcard characters: False ### -Transcript -Determines whether the output should be sent to PowerShell's transcription services. +When you use this parameter, the output is only sent to the PowerShell transcript. ```yaml Type: System.Management.Automation.SwitchParameter @@ -100,7 +85,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS diff --git a/reference/7.6/Microsoft.PowerShell.Core/Out-Host.md b/reference/7.6/Microsoft.PowerShell.Core/Out-Host.md index e80ccdc9ba13..e9c710d4e147 100644 --- a/reference/7.6/Microsoft.PowerShell.Core/Out-Host.md +++ b/reference/7.6/Microsoft.PowerShell.Core/Out-Host.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 12/31/2022 +ms.date: 04/17/2025 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/out-host?view=powershell-7.6&WT.mc_id=ps-gethelp schema: 2.0.0 title: Out-Host @@ -27,10 +27,9 @@ The `Out-Host` cmdlet sends output to the PowerShell host for display. The host at the command line. Because `Out-Host` is the default, you don't have to specify it unless you want to use its parameters. -`Out-Host` is automatically appended to every command that is executed. It passes the output of the -pipeline to the host executing the command. `Out-Host` ignores ANSI escape sequences. The escape -sequences are handled by the host. `Out-Host` passes ANSI escape sequences to the host without -trying to interpret or change them. +`Out-Host` passes the output of the pipeline to the host executing the command. `Out-Host` ignores +ANSI escape sequences. The escape sequences are handled by the host. `Out-Host` passes ANSI escape +sequences to the host without trying to interpret or change them. ## EXAMPLES @@ -89,14 +88,14 @@ Accept wildcard characters: False ### -Paging -Indicates that `Out-Host` displays one page of output at a time, and waits for user input before the -remaining pages are displayed. By default, all the output is displayed on a single page. The page -size is determined by the characteristics of the host. +Indicates that `Out-Host` displays one page of output at a time. The page size is determined by the +characteristics of the host. -Press the Space bar to display the next page of output or the Enter key to -view the next line of output. Press Q to quit. +After outputting the first page, the command waits for user input before the remaining pages are +displayed. Press the Spacebar to display the next page of output or the Enter +key to view the next line of output. Press Q to quit. -**Paging** is similar to the **more** command. +Using **Paging** is similar to using the **more** command. > [!NOTE] > The **Paging** parameter isn't supported by the PowerShell ISE host. @@ -117,7 +116,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -138,20 +138,22 @@ PowerShell includes the following aliases for `Out-Host`: - All platforms: - `oh` -The **Paging** parameter isn't supported by all PowerShell hosts. For example, if you use the -**Paging** parameter in the PowerShell ISE, the following error is displayed: -`out-lineoutput : The method or operation is not implemented.` +Not all PowerShell hosts support the **Paging** parameter. For example, if you use the **Paging** +parameter in the Windows PowerShell ISE, the following error is displayed: + +> out-lineoutput : The method or operation is not implemented. The cmdlets that contain the **Out** verb, `Out-`, don't format objects. They render objects and send them to the specified display destination. If you send an unformatted object to an `Out-` cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it. -The `Out-` cmdlets don't have parameters for names or file paths. To send data to an `Out-` cmdlet, -use the pipeline to send a PowerShell command's output to the cmdlet. Or, you can store data in a -variable and use the **InputObject** parameter to pass the data to the cmdlet. +The `Out-` cmdlets don't read input from files. To send data to an `Out-` cmdlet, use the pipeline +to send data to the cmdlet. Or, you can store data in a variable and use the **InputObject** +parameter to pass the data to the cmdlet. -`Out-Host` sends data, but it doesn't produce any output objects. If you pipeline the output of -`Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects have been specified. +`Out-Host` sends data to the host only. Tt doesn't produce output objects to the pipeline. If you +pipeline the output of `Out-Host` to the `Get-Member` cmdlet, `Get-Member` reports that no objects +have been specified. ## RELATED LINKS