Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Reformatting v5.1 About_ topics missed in first pass #2009

Merged
merged 1 commit into from
Jan 4, 2018
Merged

Reformatting v5.1 About_ topics missed in first pass #2009

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion reference/5.0/Microsoft.PowerShell.Core/About/about_For.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ all the values in an array, consider using a Foreach statement.
The following shows the For statement syntax.

```powershell
for (>init>; <condition>; <repeat>)
for (<init>; <condition>; <repeat>)
{<statement list>}
```

Expand Down
661 changes: 357 additions & 304 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Debuggers.md
View file
Open in desktop

Large diffs are not rendered by default.

270 changes: 135 additions & 135 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Methods.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,83 +1,78 @@
---
ms.date: 2017-06-09
ms.date: 2018-01-03
schema: 2.0.0
locale: en-us
keywords: powershell,cmdlet
title: about_Functions_Advanced_Methods
---

# About Functions Advanced Methods
## about_Functions_Advanced_Methods

## SHORT DESCRIPTION

# SHORT DESCRIPTION

Describes how functions that specify the `CmdletBinding` attribute can use
the methods and properties that are available to compiled cmdlets.
Describes how functions that specify the `CmdletBinding` attribute can use the
methods and properties that are available to compiled cmdlets.

# LONG DESCRIPTION

Functions that specify the `CmdletBinding` attribute can access a number of
methods and properties through the `$pscmdlet` variable. These methods
include the following methods:
methods and properties through the `$pscmdlet` variable. These methods include
the following methods:

- Input-processing methods that compiled cmdlets use to do their work.

- The `ShouldProcess` and `ShouldContinue` methods that are used to get
user feedback before an action is performed.

user feedback before an action is performed.
- The `ThrowTerminatingError` method for generating error records.

- Several Write methods that return different types of output.

All the methods and properties of the `PSCmdlet` class are available to
advanced functions. For more information about these methods and
properties, see `System.Management.Automation.PSCmdlet` in the MSDN
(Microsoft Developer Network) library at
http://go.microsoft.com/fwlink/?LinkId=142139.

# 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`, `Process`, and `End` blocks of the function. Each function
must include one or more of these blocks. The Windows PowerShell runtime
uses the code within these blocks when it is running a function. (These
blocks are also available to functions that do not use the `CmdletBinding`
attribute.)

## Begin
advanced functions. For more information about these methods and properties,
see `System.Management.Automation.PSCmdlet` in the MSDN (Microsoft Developer
Network) library at http://go.microsoft.com/fwlink/?LinkId=142139.

### 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`,
`Process`, and `End` blocks of the function. Each function must include one or
more of these blocks. The Windows PowerShell runtime uses the code within
these blocks when it is running a function. (These blocks are also available
to functions that do not use the `CmdletBinding` attribute.)

#### Begin

This block is used to provide optional one-time preprocessing for the
function. The Windows PowerShell runtime uses the code in this block one
time for each instance of the function in the pipeline.

## Process
This block is used to provide record-by-record processing for the
function. This block might be used any number of times, or not at all,
depending on the input to the function. For example, if the function is
the first command in the pipeline, the `Process` block will be used one
time. If the function is not the first command in the pipeline, the
`Process` block is used one time for every input that the function
receives from the pipeline. If there is no pipeline input, the `Process`
block is not used.

This block must be defined if a function parameter is set to accept
pipeline input. If this block is not defined and the parameter accepts
input from the pipeline, the function will miss the values that are
passed to the function through the pipeline.
function. The Windows PowerShell runtime uses the code in this block one time
for each instance of the function in the pipeline.

#### Process

This block is used to provide record-by-record processing for the function.
This block might be used any number of times, or not at all, depending on the
input to the function. For example, if the function is the first command in
the pipeline, the `Process` block will be used one time. If the function is
not the first command in the pipeline, the `Process` block is used one time
for every input that the function receives from the pipeline. If there is no
pipeline input, the `Process` block is not used.

This block must be defined if a function parameter is set to accept pipeline
input. If this block is not defined and the parameter accepts input from the
pipeline, the function will miss the values that are passed to the function
through the pipeline.

Also, when the function supports confirmation requests (when the
`SupportsShouldProcess` parameter of the Parameter attribute is set to
`$True`), the call to the `ShouldProcess` method must be made from within
the Process block.
`$True`), the call to the `ShouldProcess` method must be made from within the
Process block.

#### End

## End
This block is used to provide optional one-time post-processing for
the function.
This block is used to provide optional one-time post-processing for the
function.

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.
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.

```powershell
Function Test-ScriptCmdlet
Expand All @@ -90,119 +85,125 @@ Function Test-ScriptCmdlet
}
```

# Confirmation Methods
### Confirmation Methods

#### ShouldProcess

## ShouldProcess
This method is called to request confirmation from the user before the
function performs an action that would change the system. The function
can continue based on the Boolean value returned by the method. This
method can be called only from within the `Process{}` block of the
function. And, the `CmdletBinding` attribute must declare that the
function supports `ShouldProcess` (as shown in the previous example).
function performs an action that would change the system. The function can
continue based on the Boolean value returned by the method. This method can be
called only from within the `Process{}` block of the function. And, the
`CmdletBinding` attribute must declare that the function supports
`ShouldProcess` (as shown in the previous example).

For more information about this method, see
`System.Management.Automation.Cmdlet.ShouldProcess` in the MSDN library at
http://go.microsoft.com/fwlink/?LinkId=142142.
[`System.Management.Automation.Cmdlet.ShouldProcess`](http://go.microsoft.com/fwlink/?LinkId=142142)
in the MSDN library.

For more information about how to request confirmation, see
"Requesting Confirmation" in the MSDN library at
http://go.microsoft.com/fwlink/?LinkID=136658.
[Requesting Confirmation](http://go.microsoft.com/fwlink/?LinkID=136658)
in the MSDN library.

#### ShouldContinue

## ShouldContinue
This method is called to request a second confirmation message. It
should be called when the `ShouldProcess` method returns `$true`. For more
information about this method, see
`System.Management.Automation.Cmdlet.ShouldContinue` in the MSDN library
at http://go.microsoft.com/fwlink/?LinkId=142143.
This method is called to request a second confirmation message. It should be
called when the `ShouldProcess` method returns `$true`. For more information
about this method, see `System.Management.Automation.Cmdlet.ShouldContinue` in
the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142143.

# Error Methods
### Error Methods

Functions can call two different methods when errors occur. When a
nonterminating error occurs, the function should call the `WriteError`
method, which is described in the "Write Methods" section. When a
terminating error occurs and the function cannot continue, it should call
the `ThrowTerminatingError` method. You can also use the `Throw` statement for
nonterminating error occurs, the function should call the `WriteError` method,
which is described in the "Write Methods" section. When a terminating error
occurs and the function cannot continue, it should call the
`ThrowTerminatingError` method. You can also use the `Throw` statement for
terminating errors and the `Write-Error` cmdlet for nonterminating errors.

For more information, see `System.Management.Automation.Cmdlet.ThrowTerminatingError`
in the MSDN libray at
http://go.microsoft.com/fwlink/?LinkId=142144.
For more information, see
[`System.Management.Automation.Cmdlet.ThrowTerminatingError`](http://go.microsoft.com/fwlink/?LinkId=142144)
in the MSDN libray.

# Write Methods
### Write Methods

A function can call the following methods to return different types of
output. Notice that not all the output goes to the next command in the
pipeline. You can also use the various Write cmdlets, such as
Write-Error.
A function can call the following methods to return different types of output.
Notice that not all the output goes to the next command in the pipeline. You
can also use the various Write cmdlets, such as Write-Error.

#### WriteCommandDetail

## WriteCommandDetail
For information about the `WriteCommandDetails` method, see
`System.Management.Automation.Cmdlet.WriteCommandDetail` in the MSDN
library at http://go.microsoft.com/fwlink/?LinkId=142155.

## WriteDebug
To provide information that can be used to troubleshoot a function,
make the function call the `WriteDebug` method. This displays debug
messages to the user. For more information, see
`System.Management.Automation.Cmdlet.WriteDebug` in the MSDN library
at http://go.microsoft.com/fwlink/?LinkId=142156.

## WriteError
Functions should call this method when nonterminating errors occur and
the function is designed to continue processing records. For more
information, see `System.Management.Automation.Cmdlet.WriteError` in the
MSDN library at http://go.microsoft.com/fwlink/?LinkId=142157.
[`System.Management.Automation.Cmdlet.WriteCommandDetail`](http://go.microsoft.com/fwlink/?LinkId=142155)
in the MSDN library.

#### WriteDebug

To provide information that can be used to troubleshoot a function, make the
function call the `WriteDebug` method. This displays debug messages to the
user. For more information, see
[`System.Management.Automation.Cmdlet.WriteDebug`](http://go.microsoft.com/fwlink/?LinkId=142156)
in the MSDN library.

#### WriteError

Functions should call this method when nonterminating errors occur and the
function is designed to continue processing records. For more information, see
[`System.Management.Automation.Cmdlet.WriteError`](http://go.microsoft.com/fwlink/?LinkId=142157)
in the MSDN library.

Note: If a terminating error occurs, the function should call the
`ThrowTerminatingError` method.

## WriteObject
This method allows the function to send an object to the next command in
the pipeline. In most cases, this is the method to use when the function
returns data. For more information, see
`System.Management.Automation.PSCmdlet.WriteObject` in the MSDN library at
http://go.microsoft.com/fwlink/?LinkId=142158.

## WriteProgress
For functions whose actions take a long time to complete, this method
allows the function to call the `WriteProgress` method so that progress
information is displayed. For example, you can display the percent
completed. For more information, see
`System.Management.Automation.PSCmdlet.WriteProgress` in the MSDN library
at http://go.microsoft.com/fwlink/?LinkId=142160.

## WriteVerbose
To provide detailed information about what the function is doing, make
the function call the `WriteVerbose` method to display verbose messages to
the user. By default, verbose messages are not displayed. For more
information, see `System.Management.Automation.PSCmdlet.WriteVerbose`
in the MSDN library at http://go.microsoft.com/fwlink/?LinkId=142162.

## WriteWarning
To provide information about conditions that may cause unexpected
results, make the function call the WriteWarning method to display
warning messages to the user. By default, warning messages are displayed.
For more information, see
`System.Management.Automation.PSCmdlet.WriteWarning` in the MSDN library
at http://go.microsoft.com/fwlink/?LinkId=142164.
#### WriteObject

This method allows the function to send an object to the next command in the
pipeline. In most cases, this is the method to use when the function returns
data. For more information, see
[`System.Management.Automation.PSCmdlet.WriteObject`](http://go.microsoft.com/fwlink/?LinkId=142158)
in the MSDN library.

#### WriteProgress

For functions whose actions take a long time to complete, this method allows
the function to call the `WriteProgress` method so that progress information
is displayed. For example, you can display the percent completed. For more
information, see [`System.Management.Automation.PSCmdlet.WriteProgress`](http://go.microsoft.com/fwlink/?LinkId=142160)
in the MSDN library.

#### WriteVerbose

To provide detailed information about what the function is doing, make the
function call the `WriteVerbose` method to display verbose messages to the
user. By default, verbose messages are not displayed. For more information,
see
[`System.Management.Automation.PSCmdlet.WriteVerbose`](http://go.microsoft.com/fwlink/?LinkId=142162)
in the MSDN library.

#### WriteWarning

To provide information about conditions that may cause unexpected results,
make the function call the WriteWarning method to display warning messages to
the user. By default, warning messages are displayed. For more information,
see [`System.Management.Automation.PSCmdlet.WriteWarning`](http://go.microsoft.com/fwlink/?LinkId=142164)
in the MSDN library.

Note: You can also display warning messages by configuring the
`WarningPreference` variable or by using the `Verbose` and `Debug`
command-line options.

# Other Methods and Properties
### Other Methods and Properties

For information about the other methods and properties that can be
accessed through the `$PSCmdlet` variable, see
`System.Management.Automation.PSCmdlet` in the MSDN library at
http://go.microsoft.com/fwlink/?LinkId=142139.
[`System.Management.Automation.PSCmdlet`](http://go.microsoft.com/fwlink/?LinkId=142139)
in the MSDN library.

For example, the `ParameterSetName` property allows you to see the parameter
set that is being used. Parameter sets allow you to create a function that
performs different tasks based on the parameters that are specified when
the function is run.
performs different tasks based on the parameters that are specified when the
function is run.

# SEE ALSO
## SEE ALSO

[about_Functions](about_Functions.md)

Expand All @@ -213,4 +214,3 @@ the function is run.
[about_Functions_CmdletBindingAttribute](about_Functions_CmdletBindingAttribute.md)

[about_Functions_OutputTypeAttribute](about_Functions_OutputTypeAttribute.md)

Loading