Skip to content

Commit

Permalink
Fix typo: Non-terminating and built-in (#10424)
Browse files Browse the repository at this point in the history
* Fix typo: Non-terminating and built-in

* URL fix
  • Loading branch information
skycommand authored Sep 15, 2023
1 parent 65f080e commit 8d15908
Show file tree
Hide file tree
Showing 35 changed files with 508 additions and 369 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
Because neither **RelativePathWidth** nor **VersionWidth** were passed to the cmdlet, it
calculates the required column withs dynamically.
The final command displays the string built in the third command.
The final command displays the string the third command has built.
#>
function Add-VersionedContentTable {
[CmdletBinding()]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ title: about Aliases
# about_Aliases

## Short description

Describes how to use alternate names for cmdlets and commands in PowerShell.

## Long description
Expand Down Expand Up @@ -46,7 +47,7 @@ If you create `word` as the alias for Microsoft Office Word, you can type
"C:\Program Files\Microsoft Office\Office11\Winword.exe"
```

## Built in aliases
## Built-in aliases

PowerShell includes a set of built-in aliases, including `cd` and `chdir` for
the `Set-Location` cmdlet, and `ls` and `dir` for the `Get-ChildItem` cmdlet.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ title: about Execution Policies
# about_Execution_Policies

## Short description

Describes the PowerShell execution policies and explains how to manage them.

## Long description
Expand Down Expand Up @@ -51,7 +52,7 @@ The PowerShell execution policies are as follows:

- Nothing is blocked and there are no warnings or prompts.
- This execution policy is designed for configurations in which a PowerShell
script is built in to a larger application or for configurations in which
script is built into a larger application or for configurations in which
PowerShell is the foundation for a program that has its own security model.

### Default
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ get-help use-transaction -detailed
## TRANSACTION-ENABLED ELEMENTS

To participate in a transaction, both the cmdlet and the provider must support
transactions. This feature is built in to the objects that are affected by the
transactions. This feature is built into the objects that are affected by the
transaction.

The PowerShell Registry provider supports transactions in Windows Vista. The
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ title: about Aliases
# about_Aliases

## Short description

Describes how to use alternate names for cmdlets and commands in PowerShell.

## Long description
Expand Down Expand Up @@ -46,7 +47,7 @@ If you create `word` as the alias for Microsoft Office Word, you can type
"C:\Program Files\Microsoft Office\Office11\Winword.exe"
```

## Built in aliases
## Built-in aliases

PowerShell includes a set of built-in aliases, including `cd` and `chdir` for
the `Set-Location` cmdlet, `ls` and `dir` on Windows and `dir` on Linux and
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ title: about Execution Policies
# about_Execution_Policies

## Short description

Describes the PowerShell execution policies and explains how to manage them.

## Long description
Expand Down Expand Up @@ -59,7 +60,7 @@ execution policies are as follows:

- Nothing is blocked and there are no warnings or prompts.
- This execution policy is designed for configurations in which a PowerShell
script is built in to a larger application or for configurations in which
script is built into a larger application or for configurations in which
PowerShell is the foundation for a program that has its own security model.

### Default
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ title: about Aliases
# about_Aliases

## Short description

Describes how to use alternate names for cmdlets and commands in PowerShell.

## Long description
Expand Down Expand Up @@ -46,7 +47,7 @@ If you create `word` as the alias for Microsoft Office Word, you can type
"C:\Program Files\Microsoft Office\Office11\Winword.exe"
```

## Built in aliases
## Built-in aliases

PowerShell includes a set of built-in aliases, including `cd` and `chdir` for
the `Set-Location` cmdlet, `ls` and `dir` on Windows and `dir` on Linux and
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ title: about Execution Policies
# about_Execution_Policies

## Short description

Describes the PowerShell execution policies and explains how to manage them.

## Long description
Expand Down Expand Up @@ -59,7 +60,7 @@ execution policies are as follows:

- Nothing is blocked and there are no warnings or prompts.
- This execution policy is designed for configurations in which a PowerShell
script is built in to a larger application or for configurations in which
script is built into a larger application or for configurations in which
PowerShell is the foundation for a program that has its own security model.

### Default
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ title: about Aliases
# about_Aliases

## Short description

Describes how to use alternate names for cmdlets and commands in PowerShell.

## Long description
Expand Down Expand Up @@ -46,7 +47,7 @@ If you create `word` as the alias for Microsoft Office Word, you can type
"C:\Program Files\Microsoft Office\Office11\Winword.exe"
```

## Built in aliases
## Built-in aliases

PowerShell includes a set of built-in aliases, including `cd` and `chdir` for
the `Set-Location` cmdlet, `ls` and `dir` on Windows and `dir` on Linux and
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ title: about Execution Policies
# about_Execution_Policies

## Short description

Describes the PowerShell execution policies and explains how to manage them.

## Long description
Expand Down Expand Up @@ -59,7 +60,7 @@ execution policies are as follows:

- Nothing is blocked and there are no warnings or prompts.
- This execution policy is designed for configurations in which a PowerShell
script is built in to a larger application or for configurations in which
script is built into a larger application or for configurations in which
PowerShell is the foundation for a program that has its own security model.

### Default
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ title: Adding Non-Terminating Error Reporting to Your Cmdlet
---
# Adding Non-Terminating Error Reporting to Your Cmdlet

Cmdlets can report nonterminating errors by calling the
Cmdlets can report non-terminating errors by calling the
[System.Management.Automation.Cmdlet.WriteError][WriteError] method and still continue to operate on
the current input object or on further incoming pipeline objects. This section explains how to
create a cmdlet that reports nonterminating errors from its input processing methods.
create a cmdlet that reports non-terminating errors from its input processing methods.

For nonterminating errors (as well as terminating errors), the cmdlet must pass an
For non-terminating errors (as well as terminating errors), the cmdlet must pass an
[System.Management.Automation.ErrorRecord][ErrorRecord] object identifying the error. Each error
record is identified by a unique string called the "error identifier". In addition to the
identifier, the category of each error is specified by constants defined by a
Expand Down Expand Up @@ -140,9 +140,9 @@ Unhandled exceptions are not caught by PowerShell in the following conditions:
- If an object has code in its destructor or Dispose methods that causes an unhandled exception,
PowerShell will not catch the error and will terminate the process.

## Reporting Nonterminating Errors
## Reporting Non-terminating Errors

Any one of the input processing methods can report a nonterminating error to the output stream using
Any one of the input processing methods can report a non-terminating error to the output stream using
the [System.Management.Automation.Cmdlet.WriteError][WriteError] method.

Here is a code example from this Get-Proc cmdlet that illustrates the call to
Expand All @@ -162,7 +162,7 @@ protected override void ProcessRecord()
{
// If a name parameter is passed to cmdlet, get and write
// the associated processes.
// Write a nonterminating error for failure to retrieve
// Write a non-terminating error for failure to retrieve
// a process.
foreach (string name in processNames)
{
Expand All @@ -188,18 +188,18 @@ protected override void ProcessRecord()
}
```

### Things to Remember About Writing Nonterminating Errors
### Things to Remember About Writing Non-terminating Errors

For a nonterminating error, the cmdlet must generate a specific error identifier for each specific
For a non-terminating error, the cmdlet must generate a specific error identifier for each specific
input object.

A cmdlet frequently needs to modify the PowerShell action produced by a nonterminating error. It can
A cmdlet frequently needs to modify the PowerShell action produced by a non-terminating error. It can
do this by defining the `ErrorAction` and `ErrorVariable` parameters. If defining the `ErrorAction`
parameter, the cmdlet presents the user options
[System.Management.Automation.ActionPreference][ActionPreference], you can also directly influence
the action by setting the `$ErrorActionPreference` variable.

The cmdlet can save nonterminating errors to a variable using the `ErrorVariable` parameter, which
The cmdlet can save non-terminating errors to a variable using the `ErrorVariable` parameter, which
is not affected by the setting of `ErrorAction`. Failures can be appended to an existing error
variable by adding a plus sign (+) to the front of the variable name.

Expand Down Expand Up @@ -241,19 +241,19 @@ line. Let's test the sample Get-Proc cmdlet to see whether it reports an error:

## See Also

[Adding Parameters that Process Pipeline Input](./adding-parameters-that-process-pipeline-input.md)
- [Adding Parameters that Process Pipeline Input](./adding-parameters-that-process-pipeline-input.md)

[Adding Parameters that Process Command-Line Input](./adding-parameters-that-process-command-line-input.md)
- [Adding Parameters that Process Command-Line Input](./adding-parameters-that-process-command-line-input.md)

[Creating Your First Cmdlet](./creating-a-cmdlet-without-parameters.md)
- [Creating Your First Cmdlet](./creating-a-cmdlet-without-parameters.md)

[Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85))
- [Extending Object Types and Formatting](/previous-versions/ms714665(v=vs.85))

[How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85))
- [How to Register Cmdlets, Providers, and Host Applications](/previous-versions/ms714644(v=vs.85))

[Windows PowerShell Reference](../windows-powershell-reference.md)
- [Windows PowerShell Reference](../windows-powershell-reference.md)

[Cmdlet Samples](./cmdlet-samples.md)
- [Cmdlet Samples](./cmdlet-samples.md)

[Exception]: /dotnet/api/System.Exception
[ActionPreference]: /dotnet/api/System.Management.Automation.ActionPreference
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,28 +8,31 @@ title: Cmdlet Error Reporting
# Cmdlet error reporting

Cmdlets should report errors differently depending on whether the errors are terminating errors or
nonterminating errors. Terminating errors are errors that cause the pipeline to be terminated
immediately, or errors that occur when there's no reason to continue processing. Nonterminating
non-terminating errors. Terminating errors are errors that cause the pipeline to be terminated
immediately, or errors that occur when there's no reason to continue processing. Non-terminating
errors are those errors that report a current error condition, but the cmdlet can continue to
process input objects. With nonterminating errors, the user is typically notified of the problem,
process input objects. With non-terminating errors, the user is typically notified of the problem,
but the cmdlet continues to process the next input object.

## Terminating and nonterminating errors
Unless specified otherwise, all classes and methods mentioned in this document come from the
[System.Management.Automation](/dotnet/api/system.management.automation) namespace.

## Terminating and non-terminating errors

The following guidelines can be used to determine if an error condition is a terminating error or a
nonterminating error.
non-terminating error.

- Does the error condition prevent your cmdlet from successfully processing any further input
objects? If so, this is a terminating error.

- Is the error condition related to a specific input object or a subset of input objects? If so,
this is a nonterminating error.
this is a non-terminating error.

- Does the cmdlet accept multiple input objects, such that processing may succeed on another input
object? If so, this is a nonterminating error.
object? If so, this is a non-terminating error.

- Cmdlets that can accept multiple input objects should decide between what are terminating and
nonterminating errors, even when a particular situation applies to only a single input object.
non-terminating errors, even when a particular situation applies to only a single input object.

- Cmdlets can receive any number of input objects and send any number of success or error objects
before throwing a terminating exception. There's no relationship between the number of input
Expand All @@ -38,35 +41,33 @@ nonterminating error.
- Cmdlets that can accept only 0-1 input objects and generate only 0-1 output objects should treat
errors as terminating errors and generate terminating exceptions.

## Reporting nonterminating errors
## Reporting non-terminating errors

The reporting of a non-terminating error should always be done within the cmdlet's implementation of
the following methods:

The reporting of a nonterminating error should always be done within the cmdlet's implementation of
the
[System.Management.Automation.Cmdlet.BeginProcessing](/dotnet/api/System.Management.Automation.Cmdlet.BeginProcessing)
method, the
[System.Management.Automation.Cmdlet.ProcessRecord](/dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord)
method, or the
[System.Management.Automation.Cmdlet.EndProcessing](/dotnet/api/System.Management.Automation.Cmdlet.EndProcessing)
method. These types of errors are reported by calling the
[System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError)
method that in turn sends an error record to the error stream.
- [Cmdlet.BeginProcessing][1]
- [Cmdlet.ProcessRecord][2]
- [Cmdlet.EndProcessing][3]

These types of errors are reported by calling the [Cmdlet.WriteError][4] method that in turn sends
an error record to the error stream.

## Reporting terminating errors

Terminating errors are reported by throwing exceptions or by calling the
[System.Management.Automation.Cmdlet.ThrowTerminatingError](/dotnet/api/System.Management.Automation.Cmdlet.ThrowTerminatingError)
method. Be aware that cmdlets can also catch and rethrow exceptions such as **OutOfMemory**,
however, they aren't required to rethrow exceptions as the PowerShell runtime will catch them as
well.
[Cmdlet.ThrowTerminatingError][5] method. Be aware that cmdlets can also catch and rethrow
exceptions such as **OutOfMemory**, however, they aren't required to rethrow exceptions as the
PowerShell runtime will catch them as well.

You can also define your own exceptions for issues specific to your situation, or add additional
information to an existing exception using its error record.

## Error records

PowerShell describes a nonterminating error condition with [System.Management.Automation.ErrorRecord](/dotnet/api/System.Management.Automation.ErrorRecord)
objects. Each object provides error category information, an optional target object, and details
about the error condition.
PowerShell describes a non-terminating error condition with [ErrorRecord][6] objects. Each object
provides error category information, an optional target object, and details about the error
condition.

### Error identifiers

Expand All @@ -78,14 +79,11 @@ specific errors, or with other user-specific activities.
The following guidelines should be followed when specifying error identifiers:

- Assign different, highly specific, error identifiers to different code paths. Each code path that
calls
[System.Management.Automation.Cmdlet.WriteError](/dotnet/api/System.Management.Automation.Cmdlet.WriteError)
or
[System.Management.Automation.Cmdlet.ThrowTerminatingError](/dotnet/api/System.Management.Automation.Cmdlet.ThrowTerminatingError)
should have its own error identifier.
calls [Cmdlet.WriteError][4] or [Cmdlet.ThrowTerminatingError][5] should have its own error
identifier.

- Error identifiers should be unique to Common Language Runtime (CLR) exception types for both
terminating and nonterminating errors.
terminating and non-terminating errors.

- Don't change the semantics of an error identifier between versions of your cmdlet or PowerShell
provider. After the semantics of an error identifier is established, it should remain constant
Expand All @@ -94,7 +92,7 @@ The following guidelines should be followed when specifying error identifiers:
- For terminating errors, use a unique error identifier for a particular CLR exception type. If the
exception type changes, use a new error identifier.

- For nonterminating errors, use a specific error identifier for a specific input object.
- For non-terminating errors, use a specific error identifier for a specific input object.

- Choose text for the identifier that tersely corresponds to the error being reported. Don't use
white space or punctuation.
Expand All @@ -108,16 +106,24 @@ The following guidelines should be followed when specifying error identifiers:
Error categories are used to group errors for the user. PowerShell defines these categories and
cmdlets and PowerShell providers must choose between them when generating the error record.

For a description of the error categories that are available, see the [System.Management.Automation.ErrorCategory](/dotnet/api/System.Management.Automation.ErrorCategory)
For a description of the error categories that are available, see the [ErrorCategory][7]
enumeration. In general, you should avoid using **NoError**, **UndefinedError**, and
**GenericError** whenever possible.

Users can view errors based on category when they set `$ErrorView` to **CategoryView**.

## See also

[Cmdlet Overview](./cmdlet-overview.md)
- [Cmdlet Overview](./cmdlet-overview.md)

- [Types of Cmdlet Output](./types-of-cmdlet-output.md)

[Types of Cmdlet Output](./types-of-cmdlet-output.md)
- [Windows PowerShell Reference](../windows-powershell-reference.md)

[Windows PowerShell Reference](../windows-powershell-reference.md)
[1]: /dotnet/api/System.Management.Automation.Cmdlet.BeginProcessing
[2]: /dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord
[3]: /dotnet/api/System.Management.Automation.Cmdlet.EndProcessing
[4]: /dotnet/api/System.Management.Automation.Cmdlet.WriteError
[5]: /dotnet/api/System.Management.Automation.Cmdlet.ThrowTerminatingError
[6]: /dotnet/api/System.Management.Automation.ErrorRecord
[7]: /dotnet/api/System.Management.Automation.ErrorCategory
Loading

0 comments on commit 8d15908

Please sign in to comment.