Updates from: 07/30/2021 03:18:16
Service Microsoft Docs article Related commit history on GitHub Change details
Microsoft.PowerShell.Core About Logging (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Logging.md
---
-description: PowerShell logs internal operations from the engine, providers, and cmdlets.
+description: PowerShell logs internal operations from the engine, providers, and cmdlets.
keywords: powershell Locale: en-US Last updated 12/14/2018
more information about Public Key Cryptography, see
To enable a Protected Event Logging policy, deploy a public key to all machines that have event log data to protect. The corresponding private key is used to post-process the event logs at a more secure location such as a central event
-log collector, or [SIEM][] aggregator. You can set up SIEM in Azure. For more
+log collector, or [SIEM][SIEM] aggregator. You can set up SIEM in Azure. For more
information, see [Generic SIEM integration](/cloud-app-security/siem). ### Enabling Protected Event Logging via Group Policy
Microsoft.PowerShell.Core About Operator Precedence (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md
The Operator column lists the operators. The Reference column lists the
PowerShell Help topic in which the operator is described. To display the topic, type `get-help <topic-name>`.
-| OPERATOR | REFERENCE |
-| ------------------------ | ------------------------------ |
-| `$() @() () @{}` | [about_Operators][] |
-| `.` (member access) | [about_Operators][] |
-| `::` (static) | [about_Operators][] |
-| `[0]` (index operator) | [about_Operators][] |
-| `[int]` (cast operators) | [about_Operators][] |
-| `-split` (unary) | [about_Split][] |
-| `-join` (unary) | [about_Join][] |
-| `,` (comma operator) | [about_Operators][] |
-| `++ --` | [about_Assignment_Operators][] |
-| `! -not` | [about_Logical_Operators][] |
-| `..` (range operator) | [about_Operators][] |
-| `-f` (format operator) | [about_Operators][] |
-| `-` (unary/negative) | [about_Arithmetic_Operators][] |
-| `* / %` | [about_Arithmetic_Operators][] |
-| `+ -` | [about_Arithmetic_Operators][] |
+| OPERATOR | REFERENCE |
+| --------------------------- | ------------------------------------ |
+| `$() @() () @{}` | [about_Operators][ops] |
+| `. ?.` (member access) | [about_Operators][ops] |
+| `::` (static) | [about_Operators][ops] |
+| `[0] ?[0]` (index operator) | [about_Operators][ops] |
+| `[int]` (cast operators) | [about_Operators][ops] |
+| `-split` (unary) | [about_Split][split] |
+| `-join` (unary) | [about_Join][join] |
+| `,` (comma operator) | [about_Operators][ops] |
+| `++ --` | [about_Assignment_Operators][assign] |
+| `! -not` | [about_Logical_Operators][logic] |
+| `..` (range operator) | [about_Operators][ops] |
+| `-f` (format operator) | [about_Operators][ops] |
+| `-` (unary/negative) | [about_Arithmetic_Operators][math] |
+| `* / %` | [about_Arithmetic_Operators][math] |
+| `+ -` | [about_Arithmetic_Operators][math] |
The following group of operators have equal precedence. Their case-sensitive and explicitly case-insensitive variants have the same precedence.
-| OPERATOR | REFERENCE |
-| ------------------------- | ------------------------------ |
-| `-split` (binary) | [about_Split][] |
-| `-join` (binary) | [about_Join][] |
-| `-is -isnot -as` | [about_Type_Operators][] |
-| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][] |
-| `-like -notlike` | [about_Comparison_Operators][] |
-| `-match -notmatch` | [about_Comparison_Operators][] |
-| `-in -notIn` | [about_Comparison_Operators][] |
-| `-contains -notContains` | [about_Comparison_Operators][] |
-| `-replace` | [about_Comparison_Operators][] |
+| OPERATOR | REFERENCE |
+| ------------------------- | ------------------------------------- |
+| `-split` (binary) | [about_Split][split] |
+| `-join` (binary) | [about_Join][join] |
+| `-is -isnot -as` | [about_Type_Operators][type] |
+| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][compare] |
+| `-like -notlike` | [about_Comparison_Operators][compare] |
+| `-match -notmatch` | [about_Comparison_Operators][compare] |
+| `-in -notIn` | [about_Comparison_Operators][compare] |
+| `-contains -notContains` | [about_Comparison_Operators][compare] |
+| `-replace` | [about_Comparison_Operators][compare] |
The list resumes here with the following operators in precedence order:
-| OPERATOR | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][] |
-| `-and -or -xor` | [about_Logical_Operators][] |
+| OPERATOR | REFERENCE |
+| ---------------------------------- | ---------------------------------- |
+| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][math] |
+| `-and -or -xor` | [about_Logical_Operators][logic] |
The following items are not true operators. They are part of PowerShell's command syntax, not expression syntax. Assignment is always the last action that happens.
-| SYNTAX | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `.` (dot-source) | [about_Operators][] |
-| `&` (call) | [about_Operators][] |
-| <code>&#124;</code> (pipeline operator) | [about_Operators][] |
-| `> >> 2> 2>> 2>&1` | [about_Redirection][] |
-| `= += -= *= /= %=` | [about_Assignment_Operators][] |
+| SYNTAX | REFERENCE |
+| ------------------------------------------------------- | ------------------------------------ |
+| `.` (dot-source) | [about_Operators][ops] |
+| `&` (call) | [about_Operators][ops] |
+| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][ops] |
+| `??` (null-coalese operator) | [about_Operators][ops] |
+| <code>&#124;</code> (pipeline operator) | [about_Operators][ops] |
+| `> >> 2> 2>> 2>&1` | [about_Redirection][redir] |
+| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][ops] |
+| `= += -= *= /= %= ??=` | [about_Assignment_Operators][assign] |
## EXAMPLES
are reading and maintaining your scripts.
## SEE ALSO
-[about_Operators][]
+[about_Operators][ops]
-[about_Assignment_Operators][]
+[about_Assignment_Operators][assign]
-[about_Comparison_Operators][]
+[about_Comparison_Operators][compare]
-[about_Arithmetic_Operators][]
+[about_Arithmetic_Operators][math]
-[about_Join][]
+[about_Join][join]
-[about_Redirection][]
+[about_Redirection][redir]
-[about_Scopes][]
+[about_Scopes][scopes]
-[about_Split][]
+[about_Split][split]
-[about_Type_Operators][]
+[about_Type_Operators][type]
<!-- reference links -->
-[about_Arithmetic_Operators]: about_Arithmetic_Operators.md
-[about_Assignment_Operators]: about_Assignment_Operators.md
-[about_Comparison_Operators]: about_Comparison_Operators.md
-[about_Join]: about_Join.md
-[about_Logical_Operators]: about_logical_operators.md
-[about_Operators]: about_Operators.md
-[about_Redirection]: about_Redirection.md
-[about_Scopes]: about_Scopes.md
-[about_Split]: about_Split.md
-[about_Type_Operators]: about_Type_Operators.md
+[math]: about_Arithmetic_Operators.md
+[assign]: about_Assignment_Operators.md
+[compare]: about_Comparison_Operators.md
+[join]: about_Join.md
+[logic]: about_logical_operators.md
+[ops]: about_Operators.md
+[redir]: about_Redirection.md
+[scopes]: about_Scopes.md
+[split]: about_Split.md
+[type]: about_Type_Operators.md
Microsoft.PowerShell.Core New Pssessionoption (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/New-PSSessionOption.md
external help file: System.Management.Automation.dll-Help.xml
keywords: powershell,cmdlet Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 02/07/2019 Last updated : 07/29/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/new-pssessionoption?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-PSSessionOption --- # New-PSSessionOption
-## SYNOPSIS
+## Synopsis
Creates an object that contains advanced options for a PSSession.
-## SYNTAX
+## Syntax
``` New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachineProfile] [-Culture <CultureInfo>]
New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachinePr
[-OperationTimeout <Int32>] [-NoEncryption] [-UseUTF16] [-IncludePortInSPN] [<CommonParameters>] ```
-## DESCRIPTION
+## Description
The `New-PSSessionOption` cmdlet creates an object that contains advanced options for a user-managed session (**PSSession**). You can use the object as the value of the **SessionOption**
in the session configuration. However, they do not take precedence over maximum
limits set in the session configuration. For more information about session configurations, see [about_Session_Configurations](About/about_Session_Configurations.md).
-## EXAMPLES
+## Examples
### Example 1: Create a default session option
commands in the remote session. The data appears in the **ApplicationArguments**
The final `Invoke-Command` shows how the data might be used.
-## PARAMETERS
+## Parameters
### -ApplicationArguments
Accept wildcard characters: False
### -OperationTimeout
-Determines the maximum time that any operation in the session can run. When the interval expires,
-the operation fails. Enter a value in milliseconds.
+Determines the maximum time **WinRM** waits for positive connection tests from a live connection
+before initiating a connection time-out. For more information on WinRM, see the [Windows Remote Management Documentation](/windows/win32/winrm/portal)
-The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the operation
-continues indefinitely.
+**OperationTimeout** does _not_ impose a time limit on commands or processes running in a remote
+session.
+
+The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out.
```yaml Type: System.Int32
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
-## INPUTS
+## Inputs
### None You cannot pipe input to this cmdlet.
-## OUTPUTS
+## Outputs
### System.Management.Automation.Remoting.PSSessionOption
-## NOTES
+## Notes
If the **SessionOption** parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the `$PSSessionOption` preference variable, if it
The properties of a session configuration object vary with the options set for t
configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties.
-## RELATED LINKS
+## Related links
[Enter-PSSession](Enter-PSSession.md)
Microsoft.PowerShell.Core About Logging Non Windows (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md
---
-description: PowerShell logs internal operations from the engine, providers, and cmdlets.
-keywords: powershell
+description: PowerShell logs internal operations from the engine, providers, and cmdlets.
Locale: en-US Last updated 03/30/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_non-windows?view=powershell-7&WT.mc_id=ps-gethelp
You can get help for `log` by running `log show --help` for additional details.
> predicate string. You may also want to consider saving the event logs to a more secure location
-such as a central event log collector, or [SIEM][] aggregator. You can set up
+such as a central event log collector, or [SIEM][SIEM] aggregator. You can set up
SIEM in Azure. For more information, see [Generic SIEM integration](/cloud-app-security/siem).
Microsoft.PowerShell.Core About Logging Windows (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Logging_Windows.md
---
-description: PowerShell logs internal operations from the engine, providers, and cmdlets to the Windows event log.
-keywords: powershell
+description: PowerShell logs internal operations from the engine, providers, and cmdlets to the Windows event log.
Locale: en-US Last updated 03/30/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_windows?view=powershell-7&WT.mc_id=ps-gethelp
more information about Public Key Cryptography, see
To enable a Protected Event Logging policy, deploy a public key to all machines that have event log data to protect. The corresponding private key is used to post-process the event logs at a more secure location such as a central event
-log collector, or [SIEM][] aggregator. You can set up SIEM in Azure. For more
+log collector, or [SIEM][SIEM] aggregator. You can set up SIEM in Azure. For more
information, see [Generic SIEM integration](/cloud-app-security/siem). ### Enabling Protected Event Logging via Group Policy
Microsoft.PowerShell.Core About Operator Precedence (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md
The Operator column lists the operators. The Reference column lists the
PowerShell Help topic in which the operator is described. To display the topic, type `get-help <topic-name>`.
-| OPERATOR | REFERENCE |
-| ------------------------ | ------------------------------ |
-| `$() @() () @{}` | [about_Operators][] |
-| `. ?.` (member access) | [about_Operators][] |
-| `::` (static) | [about_Operators][] |
-| `[0] ?[0]` (index operator) | [about_Operators][] |
-| `[int]` (cast operators) | [about_Operators][] |
-| `-split` (unary) | [about_Split][] |
-| `-join` (unary) | [about_Join][] |
-| `,` (comma operator) | [about_Operators][] |
-| `++ --` | [about_Assignment_Operators][] |
-| `! -not` | [about_Logical_Operators][] |
-| `..` (range operator) | [about_Operators][] |
-| `-f` (format operator) | [about_Operators][] |
-| `-` (unary/negative) | [about_Arithmetic_Operators][] |
-| `* / %` | [about_Arithmetic_Operators][] |
-| `+ -` | [about_Arithmetic_Operators][] |
+| OPERATOR | REFERENCE |
+| --------------------------- | ------------------------------------ |
+| `$() @() () @{}` | [about_Operators][ops] |
+| `. ?.` (member access) | [about_Operators][ops] |
+| `::` (static) | [about_Operators][ops] |
+| `[0] ?[0]` (index operator) | [about_Operators][ops] |
+| `[int]` (cast operators) | [about_Operators][ops] |
+| `-split` (unary) | [about_Split][split] |
+| `-join` (unary) | [about_Join][join] |
+| `,` (comma operator) | [about_Operators][ops] |
+| `++ --` | [about_Assignment_Operators][assign] |
+| `! -not` | [about_Logical_Operators][logic] |
+| `..` (range operator) | [about_Operators][ops] |
+| `-f` (format operator) | [about_Operators][ops] |
+| `-` (unary/negative) | [about_Arithmetic_Operators][math] |
+| `* / %` | [about_Arithmetic_Operators][math] |
+| `+ -` | [about_Arithmetic_Operators][math] |
The following group of operators have equal precedence. Their case-sensitive and explicitly case-insensitive variants have the same precedence.
-| OPERATOR | REFERENCE |
-| ------------------------- | ------------------------------ |
-| `-split` (binary) | [about_Split][] |
-| `-join` (binary) | [about_Join][] |
-| `-is -isnot -as` | [about_Type_Operators][] |
-| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][] |
-| `-like -notlike` | [about_Comparison_Operators][] |
-| `-match -notmatch` | [about_Comparison_Operators][] |
-| `-in -notIn` | [about_Comparison_Operators][] |
-| `-contains -notContains` | [about_Comparison_Operators][] |
-| `-replace` | [about_Comparison_Operators][] |
+| OPERATOR | REFERENCE |
+| ------------------------- | ------------------------------------- |
+| `-split` (binary) | [about_Split][split] |
+| `-join` (binary) | [about_Join][join] |
+| `-is -isnot -as` | [about_Type_Operators][type] |
+| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][compare] |
+| `-like -notlike` | [about_Comparison_Operators][compare] |
+| `-match -notmatch` | [about_Comparison_Operators][compare] |
+| `-in -notIn` | [about_Comparison_Operators][compare] |
+| `-contains -notContains` | [about_Comparison_Operators][compare] |
+| `-replace` | [about_Comparison_Operators][compare] |
The list resumes here with the following operators in precedence order:
-| OPERATOR | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][] |
-| `-and -or -xor` | [about_Logical_Operators][] |
+| OPERATOR | REFERENCE |
+| ---------------------------------- | ---------------------------------- |
+| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][math] |
+| `-and -or -xor` | [about_Logical_Operators][logic] |
The following items are not true operators. They are part of PowerShell's command syntax, not expression syntax. Assignment is always the last action that happens.
-| SYNTAX | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `.` (dot-source) | [about_Operators][] |
-| `&` (call) | [about_Operators][] |
-| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][] |
-| `??` (null-coalese operator) | [about_Operators][] |
-| <code>&#124;</code> (pipeline operator) | [about_Operators][] |
-| `> >> 2> 2>> 2>&1` | [about_Redirection][] |
-| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][] |
-| `= += -= *= /= %= ??=` | [about_Assignment_Operators][] |
+| SYNTAX | REFERENCE |
+| ------------------------------------------------------- | ------------------------------------ |
+| `.` (dot-source) | [about_Operators][ops] |
+| `&` (call) | [about_Operators][ops] |
+| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][ops] |
+| `??` (null-coalese operator) | [about_Operators][ops] |
+| <code>&#124;</code> (pipeline operator) | [about_Operators][ops] |
+| `> >> 2> 2>> 2>&1` | [about_Redirection][redir] |
+| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][ops] |
+| `= += -= *= /= %= ??=` | [about_Assignment_Operators][assign] |
## EXAMPLES
are reading and maintaining your scripts.
## SEE ALSO
-[about_Operators][]
+[about_Operators][ops]
-[about_Assignment_Operators][]
+[about_Assignment_Operators][assign]
-[about_Comparison_Operators][]
+[about_Comparison_Operators][compare]
-[about_Arithmetic_Operators][]
+[about_Arithmetic_Operators][math]
-[about_Join][]
+[about_Join][join]
-[about_Redirection][]
+[about_Redirection][redir]
-[about_Scopes][]
+[about_Scopes][scopes]
-[about_Split][]
+[about_Split][split]
-[about_Type_Operators][]
+[about_Type_Operators][type]
<!-- reference links -->
-[about_Arithmetic_Operators]: about_Arithmetic_Operators.md
-[about_Assignment_Operators]: about_Assignment_Operators.md
-[about_Comparison_Operators]: about_Comparison_Operators.md
-[about_Join]: about_Join.md
-[about_Logical_Operators]: about_logical_operators.md
-[about_Operators]: about_Operators.md
-[about_Redirection]: about_Redirection.md
-[about_Scopes]: about_Scopes.md
-[about_Split]: about_Split.md
-[about_Type_Operators]: about_Type_Operators.md
+[math]: about_Arithmetic_Operators.md
+[assign]: about_Assignment_Operators.md
+[compare]: about_Comparison_Operators.md
+[join]: about_Join.md
+[logic]: about_logical_operators.md
+[ops]: about_Operators.md
+[redir]: about_Redirection.md
+[scopes]: about_Scopes.md
+[split]: about_Split.md
+[type]: about_Type_Operators.md
Microsoft.PowerShell.Core About Powershell Editions (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md
---
-description: Different editions of PowerShell run on different underlying runtimes.
+description: Different editions of PowerShell run on different underlying runtimes.
Locale: en-US Last updated 03/28/2019 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_powershell_editions?view=powershell-7&WT.mc_id=ps-gethelp
there are things you can do to ensure cross-edition compatibility.
The only true way to confirm and continually validate compatibility however is to write tests for your script or module and run them on all versions and editions of PowerShell you need compatibility
-with. A recommended testing framework for this is [Pester][].
+with. A recommended testing framework for this is [Pester][Pester].
### PowerShell script
you use that are affected by edition compatibility.
Generally, scripts that work in PowerShell 6.1 and above will work with Windows PowerShell 5.1, but there are some exceptions.
-Version 1.18.0 [PSScriptAnalyzer][] module has rules like [`PSUseCompatibleCommands`][] and
-[`PSUseCompatibleTypes`][] that are able to detect possibly incompatible usage of commands
+Version 1.18.0 [PSScriptAnalyzer][pssa] module has rules like [PSUseCompatibleCommands][psucc] and
+[PSUseCompatibleTypes][psuct] that are able to detect possibly incompatible usage of commands
and .NET APIs in PowerShell scripts. ### .NET assemblies If you are writing a binary module or a module that incorporates .NET assemblies (DLLs) generated
-from source code, you should compile against [.NET Standard][] and [PowerShell Standard][]
+from source code, you should compile against [.NET Standard][netstd] and [PowerShell Standard][psstd]
for compile-time compatibility validation of .NET and PowerShell API compatibility. Although these libraries are able to check some compatibility at compile time, they won't be able
to catch possible behavioral differences between editions. For this you must sti
- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support) [Pester]: https://github.com/pester/Pester/wiki/Pester
-[PSScriptAnalyzer]: https://github.com/PowerShell/PSScriptAnalyzer
-[`PSUseCompatibleCommands`]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleCommands.md
-[`PSUseCompatibleTypes`]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleTypes.md
-[.NET Standard]: /dotnet/standard/net-standard
-[PowerShell Standard]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
+[pssa]: https://github.com/PowerShell/PSScriptAnalyzer
+[psucc]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleCommands.md
+[psuct]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleTypes.md
+[netstd]: /dotnet/standard/net-standard
+[psstd]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
Microsoft.PowerShell.Core New Pssessionoption (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/New-PSSessionOption.md
external help file: System.Management.Automation.dll-Help.xml
keywords: powershell,cmdlet Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 02/07/2019 Last updated : 07/29/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/new-pssessionoption?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-PSSessionOption --- # New-PSSessionOption
-## SYNOPSIS
+## Synopsis
Creates an object that contains advanced options for a PSSession.
-## SYNTAX
+## Syntax
``` New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachineProfile] [-Culture <CultureInfo>]
New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachinePr
[-OperationTimeout <Int32>] [-NoEncryption] [-UseUTF16] [-IncludePortInSPN] [<CommonParameters>] ```
-## DESCRIPTION
+## Description
The `New-PSSessionOption` cmdlet creates an object that contains advanced options for a user-managed session (**PSSession**). You can use the object as the value of the **SessionOption**
in the session configuration. However, they do not take precedence over maximum
limits set in the session configuration. For more information about session configurations, see [about_Session_Configurations](About/about_Session_Configurations.md).
-## EXAMPLES
+## Examples
### Example 1: Create a default session option
commands in the remote session. The data appears in the **ApplicationArguments**
The final `Invoke-Command` shows how the data might be used.
-## PARAMETERS
+## Parameters
### -ApplicationArguments
Accept wildcard characters: False
### -OperationTimeout
-Determines the maximum time that any operation in the session can run. When the interval expires,
-the operation fails. Enter a value in milliseconds.
+Determines the maximum time **WinRM** waits for positive connection tests from a live connection
+before initiating a connection time-out. For more information on WinRM, see the [Windows Remote Management Documentation](/windows/win32/winrm/portal)
-The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the operation
-continues indefinitely.
+**OperationTimeout** does _not_ impose a time limit on commands or processes running in a remote
+session and does _not_ affect other remoting protocols like SSH.
+
+The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out.
```yaml Type: System.Int32
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
-## INPUTS
+## Inputs
### None You cannot pipe input to this cmdlet.
-## OUTPUTS
+## Outputs
### System.Management.Automation.Remoting.PSSessionOption
-## NOTES
+## Notes
If the **SessionOption** parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the `$PSSessionOption` preference variable, if it
The properties of a session configuration object vary with the options set for t
configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties.
-## RELATED LINKS
+## Related links
[Enter-PSSession](Enter-PSSession.md)
Microsoft.PowerShell.Core About Logging Non Windows (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md
---
-description: PowerShell logs internal operations from the engine, providers, and cmdlets.
-keywords: powershell
+description: PowerShell logs internal operations from the engine, providers, and cmdlets.
Locale: en-US Last updated 03/30/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_non-windows?view=powershell-7.1&WT.mc_id=ps-gethelp
You can get help for `log` by running `log show --help` for additional details.
> predicate string. You may also want to consider saving the event logs to a more secure location
-such as a central event log collector, or [SIEM][] aggregator. You can set up
+such as a central event log collector, or [SIEM][SIEM] aggregator. You can set up
SIEM in Azure. For more information, see [Generic SIEM integration](/cloud-app-security/siem).
Microsoft.PowerShell.Core About Logging Windows (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Logging_Windows.md
---
-description: PowerShell logs internal operations from the engine, providers, and cmdlets to the Windows event log.
-keywords: powershell
+description: PowerShell logs internal operations from the engine, providers, and cmdlets to the Windows event log.
Locale: en-US Last updated 03/30/2020 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_windows?view=powershell-7.1&WT.mc_id=ps-gethelp
more information about Public Key Cryptography, see
To enable a Protected Event Logging policy, deploy a public key to all machines that have event log data to protect. The corresponding private key is used to post-process the event logs at a more secure location such as a central event
-log collector, or [SIEM][] aggregator. You can set up SIEM in Azure. For more
+log collector, or [SIEM][SIEM] aggregator. You can set up SIEM in Azure. For more
information, see [Generic SIEM integration](/cloud-app-security/siem). ### Enabling Protected Event Logging via Group Policy
Microsoft.PowerShell.Core About Operator Precedence (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md
The Operator column lists the operators. The Reference column lists the
PowerShell Help topic in which the operator is described. To display the topic, type `get-help <topic-name>`.
-| OPERATOR | REFERENCE |
-| ------------------------ | ------------------------------ |
-| `$() @() () @{}` | [about_Operators][] |
-| `. ?.` (member access) | [about_Operators][] |
-| `::` (static) | [about_Operators][] |
-| `[0] ?[0]` (index operator) | [about_Operators][] |
-| `[int]` (cast operators) | [about_Operators][] |
-| `-split` (unary) | [about_Split][] |
-| `-join` (unary) | [about_Join][] |
-| `,` (comma operator) | [about_Operators][] |
-| `++ --` | [about_Assignment_Operators][] |
-| `! -not` | [about_Logical_Operators][] |
-| `..` (range operator) | [about_Operators][] |
-| `-f` (format operator) | [about_Operators][] |
-| `-` (unary/negative) | [about_Arithmetic_Operators][] |
-| `* / %` | [about_Arithmetic_Operators][] |
-| `+ -` | [about_Arithmetic_Operators][] |
+| OPERATOR | REFERENCE |
+| --------------------------- | ------------------------------------ |
+| `$() @() () @{}` | [about_Operators][ops] |
+| `. ?.` (member access) | [about_Operators][ops] |
+| `::` (static) | [about_Operators][ops] |
+| `[0] ?[0]` (index operator) | [about_Operators][ops] |
+| `[int]` (cast operators) | [about_Operators][ops] |
+| `-split` (unary) | [about_Split][split] |
+| `-join` (unary) | [about_Join][join] |
+| `,` (comma operator) | [about_Operators][ops] |
+| `++ --` | [about_Assignment_Operators][assign] |
+| `! -not` | [about_Logical_Operators][logic] |
+| `..` (range operator) | [about_Operators][ops] |
+| `-f` (format operator) | [about_Operators][ops] |
+| `-` (unary/negative) | [about_Arithmetic_Operators][math] |
+| `* / %` | [about_Arithmetic_Operators][math] |
+| `+ -` | [about_Arithmetic_Operators][math] |
The following group of operators have equal precedence. Their case-sensitive and explicitly case-insensitive variants have the same precedence.
-| OPERATOR | REFERENCE |
-| ------------------------- | ------------------------------ |
-| `-split` (binary) | [about_Split][] |
-| `-join` (binary) | [about_Join][] |
-| `-is -isnot -as` | [about_Type_Operators][] |
-| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][] |
-| `-like -notlike` | [about_Comparison_Operators][] |
-| `-match -notmatch` | [about_Comparison_Operators][] |
-| `-in -notIn` | [about_Comparison_Operators][] |
-| `-contains -notContains` | [about_Comparison_Operators][] |
-| `-replace` | [about_Comparison_Operators][] |
+| OPERATOR | REFERENCE |
+| ------------------------- | ------------------------------------- |
+| `-split` (binary) | [about_Split][split] |
+| `-join` (binary) | [about_Join][join] |
+| `-is -isnot -as` | [about_Type_Operators][type] |
+| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][compare] |
+| `-like -notlike` | [about_Comparison_Operators][compare] |
+| `-match -notmatch` | [about_Comparison_Operators][compare] |
+| `-in -notIn` | [about_Comparison_Operators][compare] |
+| `-contains -notContains` | [about_Comparison_Operators][compare] |
+| `-replace` | [about_Comparison_Operators][compare] |
The list resumes here with the following operators in precedence order:
-| OPERATOR | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][] |
-| `-and -or -xor` | [about_Logical_Operators][] |
+| OPERATOR | REFERENCE |
+| ---------------------------------- | ---------------------------------- |
+| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][math] |
+| `-and -or -xor` | [about_Logical_Operators][logic] |
The following items are not true operators. They are part of PowerShell's command syntax, not expression syntax. Assignment is always the last action that happens.
-| SYNTAX | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `.` (dot-source) | [about_Operators][] |
-| `&` (call) | [about_Operators][] |
-| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][] |
-| `??` (null-coalese operator) | [about_Operators][] |
-| <code>&#124;</code> (pipeline operator) | [about_Operators][] |
-| `> >> 2> 2>> 2>&1` | [about_Redirection][] |
-| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][] |
-| `= += -= *= /= %= ??=` | [about_Assignment_Operators][] |
+| SYNTAX | REFERENCE |
+| ------------------------------------------------------- | ------------------------------------ |
+| `.` (dot-source) | [about_Operators][ops] |
+| `&` (call) | [about_Operators][ops] |
+| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][ops] |
+| `??` (null-coalese operator) | [about_Operators][ops] |
+| <code>&#124;</code> (pipeline operator) | [about_Operators][ops] |
+| `> >> 2> 2>> 2>&1` | [about_Redirection][redir] |
+| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][ops] |
+| `= += -= *= /= %= ??=` | [about_Assignment_Operators][assign] |
## EXAMPLES
are reading and maintaining your scripts.
## SEE ALSO
-[about_Operators][]
+[about_Operators][ops]
-[about_Assignment_Operators][]
+[about_Assignment_Operators][assign]
-[about_Comparison_Operators][]
+[about_Comparison_Operators][compare]
-[about_Arithmetic_Operators][]
+[about_Arithmetic_Operators][math]
-[about_Join][]
+[about_Join][join]
-[about_Redirection][]
+[about_Redirection][redir]
-[about_Scopes][]
+[about_Scopes][scopes]
-[about_Split][]
+[about_Split][split]
-[about_Type_Operators][]
+[about_Type_Operators][type]
<!-- reference links -->
-[about_Arithmetic_Operators]: about_Arithmetic_Operators.md
-[about_Assignment_Operators]: about_Assignment_Operators.md
-[about_Comparison_Operators]: about_Comparison_Operators.md
-[about_Join]: about_Join.md
-[about_Logical_Operators]: about_logical_operators.md
-[about_Operators]: about_Operators.md
-[about_Redirection]: about_Redirection.md
-[about_Scopes]: about_Scopes.md
-[about_Split]: about_Split.md
-[about_Type_Operators]: about_Type_Operators.md
+[math]: about_Arithmetic_Operators.md
+[assign]: about_Assignment_Operators.md
+[compare]: about_Comparison_Operators.md
+[join]: about_Join.md
+[logic]: about_logical_operators.md
+[ops]: about_Operators.md
+[redir]: about_Redirection.md
+[scopes]: about_Scopes.md
+[split]: about_Split.md
+[type]: about_Type_Operators.md
Microsoft.PowerShell.Core About Powershell Editions (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md
---
-description: Different editions of PowerShell run on different underlying runtimes.
+description: Different editions of PowerShell run on different underlying runtimes.
Locale: en-US Last updated 03/28/2019 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_powershell_editions?view=powershell-7.1&WT.mc_id=ps-gethelp
there are things you can do to ensure cross-edition compatibility.
The only true way to confirm and continually validate compatibility however is to write tests for your script or module and run them on all versions and editions of PowerShell you need compatibility
-with. A recommended testing framework for this is [Pester][].
+with. A recommended testing framework for this is [Pester][Pester].
### PowerShell script
you use that are affected by edition compatibility.
Generally, scripts that work in PowerShell 6.1 and above will work with Windows PowerShell 5.1, but there are some exceptions.
-Version 1.18.0 [PSScriptAnalyzer][] module has rules like [`PSUseCompatibleCommands`][] and
-[`PSUseCompatibleTypes`][] that are able to detect possibly incompatible usage of commands
+Version 1.18.0 [PSScriptAnalyzer][pssa] module has rules like [PSUseCompatibleCommands][psucc] and
+[PSUseCompatibleTypes][psuct] that are able to detect possibly incompatible usage of commands
and .NET APIs in PowerShell scripts. ### .NET assemblies If you are writing a binary module or a module that incorporates .NET assemblies (DLLs) generated
-from source code, you should compile against [.NET Standard][] and [PowerShell Standard][]
+from source code, you should compile against [.NET Standard][netstd] and [PowerShell Standard][psstd]
for compile-time compatibility validation of .NET and PowerShell API compatibility. Although these libraries are able to check some compatibility at compile time, they won't be able
to catch possible behavioral differences between editions. For this you must sti
- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support) [Pester]: https://github.com/pester/Pester/wiki/Pester
-[PSScriptAnalyzer]: https://github.com/PowerShell/PSScriptAnalyzer
-[`PSUseCompatibleCommands`]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleCommands.md
-[`PSUseCompatibleTypes`]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleTypes.md
-[.NET Standard]: /dotnet/standard/net-standard
-[PowerShell Standard]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
+[pssa]: https://github.com/PowerShell/PSScriptAnalyzer
+[psucc]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleCommands.md
+[psuct]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleTypes.md
+[netstd]: /dotnet/standard/net-standard
+[psstd]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
Microsoft.PowerShell.Core New Pssessionoption (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/New-PSSessionOption.md
external help file: System.Management.Automation.dll-Help.xml
keywords: powershell,cmdlet Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 02/07/2019 Last updated : 07/29/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/new-pssessionoption?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-PSSessionOption --- # New-PSSessionOption
-## SYNOPSIS
+## Synopsis
Creates an object that contains advanced options for a PSSession.
-## SYNTAX
+## Syntax
``` New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachineProfile] [-Culture <CultureInfo>]
New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachinePr
[-OperationTimeout <Int32>] [-NoEncryption] [-UseUTF16] [-IncludePortInSPN] [<CommonParameters>] ```
-## DESCRIPTION
+## Description
The `New-PSSessionOption` cmdlet creates an object that contains advanced options for a user-managed session (**PSSession**). You can use the object as the value of the **SessionOption**
in the session configuration. However, they do not take precedence over maximum
limits set in the session configuration. For more information about session configurations, see [about_Session_Configurations](About/about_Session_Configurations.md).
-## EXAMPLES
+## Examples
### Example 1: Create a default session option
commands in the remote session. The data appears in the **ApplicationArguments**
The final `Invoke-Command` shows how the data might be used.
-## PARAMETERS
+## Parameters
### -ApplicationArguments
Accept wildcard characters: False
### -OperationTimeout
-Determines the maximum time that any operation in the session can run. When the interval expires,
-the operation fails. Enter a value in milliseconds.
+Determines the maximum time **WinRM** waits for positive connection tests from a live connection
+before initiating a connection time-out. For more information on WinRM, see the [Windows Remote Management Documentation](/windows/win32/winrm/portal)
-The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the operation
-continues indefinitely.
+**OperationTimeout** does _not_ impose a time limit on commands or processes running in a remote
+session and does _not_ affect other remoting protocols like SSH.
+
+The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out.
```yaml Type: System.Int32
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
-## INPUTS
+## Inputs
### None You cannot pipe input to this cmdlet.
-## OUTPUTS
+## Outputs
### System.Management.Automation.Remoting.PSSessionOption
-## NOTES
+## Notes
If the **SessionOption** parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the `$PSSessionOption` preference variable, if it
The properties of a session configuration object vary with the options set for t
configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties.
-## RELATED LINKS
+## Related links
[Enter-PSSession](Enter-PSSession.md)
Microsoft.PowerShell.Core About Logging Non Windows (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md
You can get help for `log` by running `log show --help` for additional details.
> predicate string. You may also want to consider saving the event logs to a more secure location
-such as a central event log collector, or [SIEM][] aggregator. You can set up
+such as a central event log collector, or [SIEM][SIEM] aggregator. You can set up
SIEM in Azure. For more information, see [Generic SIEM integration](/cloud-app-security/siem).
Microsoft.PowerShell.Core About Logging Windows (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Logging_Windows.md
more information about Public Key Cryptography, see
To enable a Protected Event Logging policy, deploy a public key to all machines that have event log data to protect. The corresponding private key is used to post-process the event logs at a more secure location such as a central event
-log collector, or [SIEM][] aggregator. You can set up SIEM in Azure. For more
+log collector, or [SIEM][SIEM] aggregator. You can set up SIEM in Azure. For more
information, see [Generic SIEM integration](/cloud-app-security/siem). ### Enabling Protected Event Logging via Group Policy
Microsoft.PowerShell.Core About Operator Precedence (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Operator_Precedence.md
The Operator column lists the operators. The Reference column lists the
PowerShell Help topic in which the operator is described. To display the topic, type `get-help <topic-name>`.
-| OPERATOR | REFERENCE |
-| ------------------------ | ------------------------------ |
-| `$() @() () @{}` | [about_Operators][] |
-| `. ?.` (member access) | [about_Operators][] |
-| `::` (static) | [about_Operators][] |
-| `[0] ?[0]` (index operator) | [about_Operators][] |
-| `[int]` (cast operators) | [about_Operators][] |
-| `-split` (unary) | [about_Split][] |
-| `-join` (unary) | [about_Join][] |
-| `,` (comma operator) | [about_Operators][] |
-| `++ --` | [about_Assignment_Operators][] |
-| `! -not` | [about_Logical_Operators][] |
-| `..` (range operator) | [about_Operators][] |
-| `-f` (format operator) | [about_Operators][] |
-| `-` (unary/negative) | [about_Arithmetic_Operators][] |
-| `* / %` | [about_Arithmetic_Operators][] |
-| `+ -` | [about_Arithmetic_Operators][] |
+| OPERATOR | REFERENCE |
+| --------------------------- | ------------------------------------ |
+| `$() @() () @{}` | [about_Operators][ops] |
+| `. ?.` (member access) | [about_Operators][ops] |
+| `::` (static) | [about_Operators][ops] |
+| `[0] ?[0]` (index operator) | [about_Operators][ops] |
+| `[int]` (cast operators) | [about_Operators][ops] |
+| `-split` (unary) | [about_Split][split] |
+| `-join` (unary) | [about_Join][join] |
+| `,` (comma operator) | [about_Operators][ops] |
+| `++ --` | [about_Assignment_Operators][assign] |
+| `! -not` | [about_Logical_Operators][logic] |
+| `..` (range operator) | [about_Operators][ops] |
+| `-f` (format operator) | [about_Operators][ops] |
+| `-` (unary/negative) | [about_Arithmetic_Operators][math] |
+| `* / %` | [about_Arithmetic_Operators][math] |
+| `+ -` | [about_Arithmetic_Operators][math] |
The following group of operators have equal precedence. Their case-sensitive and explicitly case-insensitive variants have the same precedence.
-| OPERATOR | REFERENCE |
-| ------------------------- | ------------------------------ |
-| `-split` (binary) | [about_Split][] |
-| `-join` (binary) | [about_Join][] |
-| `-is -isnot -as` | [about_Type_Operators][] |
-| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][] |
-| `-like -notlike` | [about_Comparison_Operators][] |
-| `-match -notmatch` | [about_Comparison_Operators][] |
-| `-in -notIn` | [about_Comparison_Operators][] |
-| `-contains -notContains` | [about_Comparison_Operators][] |
-| `-replace` | [about_Comparison_Operators][] |
+| OPERATOR | REFERENCE |
+| ------------------------- | ------------------------------------- |
+| `-split` (binary) | [about_Split][split] |
+| `-join` (binary) | [about_Join][join] |
+| `-is -isnot -as` | [about_Type_Operators][type] |
+| `-eq -ne -gt -ge -lt -le` | [about_Comparison_Operators][compare] |
+| `-like -notlike` | [about_Comparison_Operators][compare] |
+| `-match -notmatch` | [about_Comparison_Operators][compare] |
+| `-in -notIn` | [about_Comparison_Operators][compare] |
+| `-contains -notContains` | [about_Comparison_Operators][compare] |
+| `-replace` | [about_Comparison_Operators][compare] |
The list resumes here with the following operators in precedence order:
-| OPERATOR | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][] |
-| `-and -or -xor` | [about_Logical_Operators][] |
+| OPERATOR | REFERENCE |
+| ---------------------------------- | ---------------------------------- |
+| `-band -bnot -bor -bxor -shr -shl` | [about_Arithmetic_Operators][math] |
+| `-and -or -xor` | [about_Logical_Operators][logic] |
The following items are not true operators. They are part of PowerShell's command syntax, not expression syntax. Assignment is always the last action that happens.
-| SYNTAX | REFERENCE |
-| --------------------------------------- | ------------------------------ |
-| `.` (dot-source) | [about_Operators][] |
-| `&` (call) | [about_Operators][] |
-| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][] |
-| `??` (null-coalese operator) | [about_Operators][] |
-| <code>&#124;</code> (pipeline operator) | [about_Operators][] |
-| `> >> 2> 2>> 2>&1` | [about_Redirection][] |
-| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][] |
-| `= += -= *= /= %= ??=` | [about_Assignment_Operators][] |
+| SYNTAX | REFERENCE |
+| ------------------------------------------------------- | ------------------------------------ |
+| `.` (dot-source) | [about_Operators][ops] |
+| `&` (call) | [about_Operators][ops] |
+| `? <if-true> : <if-false>` (Ternary operator) | [about_Operators][ops] |
+| `??` (null-coalese operator) | [about_Operators][ops] |
+| <code>&#124;</code> (pipeline operator) | [about_Operators][ops] |
+| `> >> 2> 2>> 2>&1` | [about_Redirection][redir] |
+| <code>&& &#124;&#124;</code> (pipeline chain operators) | [about_Operators][ops] |
+| `= += -= *= /= %= ??=` | [about_Assignment_Operators][assign] |
## EXAMPLES
are reading and maintaining your scripts.
## SEE ALSO
-[about_Operators][]
+[about_Operators][ops]
-[about_Assignment_Operators][]
+[about_Assignment_Operators][assign]
-[about_Comparison_Operators][]
+[about_Comparison_Operators][compare]
-[about_Arithmetic_Operators][]
+[about_Arithmetic_Operators][math]
-[about_Join][]
+[about_Join][join]
-[about_Redirection][]
+[about_Redirection][redir]
-[about_Scopes][]
+[about_Scopes][scopes]
-[about_Split][]
+[about_Split][split]
-[about_Type_Operators][]
+[about_Type_Operators][type]
<!-- reference links -->
-[about_Arithmetic_Operators]: about_Arithmetic_Operators.md
-[about_Assignment_Operators]: about_Assignment_Operators.md
-[about_Comparison_Operators]: about_Comparison_Operators.md
-[about_Join]: about_Join.md
-[about_Logical_Operators]: about_logical_operators.md
-[about_Operators]: about_Operators.md
-[about_Redirection]: about_Redirection.md
-[about_Scopes]: about_Scopes.md
-[about_Split]: about_Split.md
-[about_Type_Operators]: about_Type_Operators.md
+[math]: about_Arithmetic_Operators.md
+[assign]: about_Assignment_Operators.md
+[compare]: about_Comparison_Operators.md
+[join]: about_Join.md
+[logic]: about_logical_operators.md
+[ops]: about_Operators.md
+[redir]: about_Redirection.md
+[scopes]: about_Scopes.md
+[split]: about_Split.md
+[type]: about_Type_Operators.md
Microsoft.PowerShell.Core About Powershell Editions (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_PowerShell_Editions.md
there are things you can do to ensure cross-edition compatibility.
The only true way to confirm and continually validate compatibility however is to write tests for your script or module and run them on all versions and editions of PowerShell you need compatibility
-with. A recommended testing framework for this is [Pester][].
+with. A recommended testing framework for this is [Pester][Pester].
### PowerShell script
you use that are affected by edition compatibility.
Generally, scripts that work in PowerShell 6.1 and above will work with Windows PowerShell 5.1, but there are some exceptions.
-Version 1.18.0 [PSScriptAnalyzer][] module has rules like [`PSUseCompatibleCommands`][] and
-[`PSUseCompatibleTypes`][] that are able to detect possibly incompatible usage of commands
+Version 1.18.0 [PSScriptAnalyzer][pssa] module has rules like [PSUseCompatibleCommands][psucc] and
+[PSUseCompatibleTypes][psuct] that are able to detect possibly incompatible usage of commands
and .NET APIs in PowerShell scripts. ### .NET assemblies If you are writing a binary module or a module that incorporates .NET assemblies (DLLs) generated
-from source code, you should compile against [.NET Standard][] and [PowerShell Standard][]
+from source code, you should compile against [.NET Standard][netstd] and [PowerShell Standard][psstd]
for compile-time compatibility validation of .NET and PowerShell API compatibility. Although these libraries are able to check some compatibility at compile time, they won't be able
to catch possible behavioral differences between editions. For this you must sti
- [Modules with compatible PowerShell Editions](/powershell/scripting/gallery/concepts/module-psedition-support) [Pester]: https://github.com/pester/Pester/wiki/Pester
-[PSScriptAnalyzer]: https://github.com/PowerShell/PSScriptAnalyzer
-[`PSUseCompatibleCommands`]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleCommands.md
-[`PSUseCompatibleTypes`]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleTypes.md
-[.NET Standard]: /dotnet/standard/net-standard
-[PowerShell Standard]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
+[pssa]: https://github.com/PowerShell/PSScriptAnalyzer
+[psucc]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleCommands.md
+[psuct]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/RuleDocumentation/UseCompatibleTypes.md
+[netstd]: /dotnet/standard/net-standard
+[psstd]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
Microsoft.PowerShell.Core New Pssessionoption (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/New-PSSessionOption.md
external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core Previously updated : 02/07/2019 Last updated : 07/29/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/new-pssessionoption?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: New-PSSessionOption --- # New-PSSessionOption
-## SYNOPSIS
+## Synopsis
Creates an object that contains advanced options for a PSSession.
-## SYNTAX
+## Syntax
``` New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachineProfile] [-Culture <CultureInfo>]
New-PSSessionOption [-MaximumRedirection <Int32>] [-NoCompression] [-NoMachinePr
[-OperationTimeout <Int32>] [-NoEncryption] [-UseUTF16] [-IncludePortInSPN] [<CommonParameters>] ```
-## DESCRIPTION
+## Description
The `New-PSSessionOption` cmdlet creates an object that contains advanced options for a user-managed session (**PSSession**). You can use the object as the value of the **SessionOption**
in the session configuration. However, they do not take precedence over maximum
limits set in the session configuration. For more information about session configurations, see [about_Session_Configurations](About/about_Session_Configurations.md).
-## EXAMPLES
+## Examples
### Example 1: Create a default session option
commands in the remote session. The data appears in the **ApplicationArguments**
The final `Invoke-Command` shows how the data might be used.
-## PARAMETERS
+## Parameters
### -ApplicationArguments
Accept wildcard characters: False
### -OperationTimeout
-Determines the maximum time that any operation in the session can run. When the interval expires,
-the operation fails. Enter a value in milliseconds.
+Determines the maximum time **WinRM** waits for positive connection tests from a live connection
+before initiating a connection time-out. For more information on WinRM, see the [Windows Remote Management Documentation](/windows/win32/winrm/portal)
-The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out; the operation
-continues indefinitely.
+**OperationTimeout** does _not_ impose a time limit on commands or processes running in a remote
+session and does _not_ affect other remoting protocols like SSH.
+
+The default value is 180000 (3 minutes). A value of 0 (zero) means no time-out.
```yaml Type: System.Int32
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
-## INPUTS
+## Inputs
### None You cannot pipe input to this cmdlet.
-## OUTPUTS
+## Outputs
### System.Management.Automation.Remoting.PSSessionOption
-## NOTES
+## Notes
If the **SessionOption** parameter is not used in a command to create a **PSSession**, the session options are determined by the property values of the `$PSSessionOption` preference variable, if it
The properties of a session configuration object vary with the options set for t
configuration and the values of those options. Also, session configurations that use a session configuration file have additional properties.
-## RELATED LINKS
+## Related links
[Enter-PSSession](Enter-PSSession.md)
PowerShell-Support-Lifecycle Powershell Support Lifecycle https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/PowerShell-Support-Lifecycle.md
PowerShell is a distinct set of tools and components that is shipped, installed,
separately from Windows PowerShell. PowerShell isn't included in the Windows licensing agreements.
-PowerShell is supported under traditional Microsoft support agreements, including [paid support][],
-[Microsoft Enterprise Agreements][enterprise-agreement], and
-[Microsoft Software Assurance][assurance]. You can also pay for [assisted support][] for PowerShell
-by filing a support request for your problem.
+PowerShell is supported under traditional Microsoft support agreements, including
+[paid support][paid], [Microsoft Enterprise Agreements][enterprise-agreement], and
+[Microsoft Software Assurance][assurance]. You can also pay for [assisted support][assisted] for
+PowerShell by filing a support request for your problem.
## Community Support
-We also offer [community support][] on GitHub where you can file an issue, bug, or feature request.
-Also, you may find help from other members of the community in the Microsoft
-[PowerShell Tech Community][] or any of the forums listed in the community section of
+We also offer [community support][community] on GitHub where you can file an issue, bug, or feature
+request. Also, you may find help from other members of the community in the Microsoft
+[PowerShell Tech Community][pscommunity] or any of the forums listed in the community section of
[PowerShell][pshub] hub page. We offer no guarantee there that the community will address or resolve your issue in a timely manner. If you have a problem that requires immediate attention, you should use the traditional, paid support options.
supported. These packages are marked as `Community` in the table.
Platforms listed as `Experimental` aren't officially supported, but are available for experimentation and feedback.
-<!-- TODO: update OS list -->
-
-| Platform | 7.0 | 7.1 |
-| ------------------------------------------------- | :-----------: | :-----------: |
-| Windows 8.1, and 10 | Supported | Supported |
-| Windows Server 2012 R2, 2016, 2019 | Supported | Supported |
-| [Windows Server Semi-Annual Channel][semi-annual] | Supported | Supported |
-| Ubuntu 16.04, 18.04 | Supported | Supported |
-| Ubuntu 20.04 | Not Supported | Supported |
-| Ubuntu 19.10, 20.10 (via Snap Package) | Community | Supported |
-| Debian 9 | Supported | Supported |
-| Debian 10 | Supported | Supported |
-| CentOS 7 | Supported | Supported |
-| CentOS 8 | Supported | Supported |
-| Red Hat Enterprise Linux 7 | Supported | Supported |
-| Red Hat Enterprise Linux 8 | Supported | Supported |
-| Fedora 31+ | Supported | Not Supported |
-| Alpine 3.10 | See Note 1 | Not Supported |
-| Alpine 3.11+ | See Note 1 | See Note 1 |
-| macOS 10.13+ | Supported | Supported |
-| Arch | Community | Community |
-| Raspbian | Community | Community |
-| Kali | Community | Community |
-| AppImage (works on multiple Linux platforms) | Community | Community |
-| [Snap Package](https://snapcraft.io/powershell) | See note 2 | See note |
+| Platform | 7.0 | 7.1 | 7.2 |
+| ------------------------------------------------- | :-----------: | :-----------: | :-----------: |
+| Windows 8.1, and 10 | Supported | Supported | Supported |
+| Windows Server 2012 R2, 2016, 2019, 2022 | Supported | Supported | Supported |
+| [Windows Server Semi-Annual Channel][semi-annual] | Supported | Supported | Supported |
+| Ubuntu 16.04 LTS, 18.04 LTS | Supported | Supported | Supported |
+| Ubuntu 20.04 LTS | Not Supported | Supported | Supported |
+| Ubuntu 21.04 | Not Supported | Not Supported | Supported |
+| Debian 9 | Supported | Supported | Supported |
+| Debian 10 | Supported | Supported | Supported |
+| CentOS 7 | Supported | Supported | Supported |
+| CentOS 8 | Supported | Supported | Supported |
+| Red Hat Enterprise Linux 7 | Supported | Supported | Supported |
+| Red Hat Enterprise Linux 8 | Supported | Supported | Supported |
+| Fedora 31+ | Supported | Not Supported | Not Supported |
+| Alpine 3.10 | See Note 1 | Not Supported | Not Supported |
+| Alpine 3.11+ | See Note 1 | See Note 1 | See Note 1 |
+| macOS 10.13+ | Supported | Supported | Supported |
+| Arch | Community | Community | Community |
+| Raspbian | Community | Community | Community |
+| Kali | Community | Community | Community |
+| AppImage (works on multiple Linux platforms) | Community | Community | Community |
+| [Snap Package](https://snapcraft.io/powershell) | See note 2 | See note | See note |
> [!NOTE] > - 1 - CIM, PowerShell Remoting, and DSC are not supported on Alpine.
customers needing access but formal support and updates of any kind will no long
So, the distribution owners ended support for the following versions and aren't supported.
-<!-- TODO: Update this table Jason-->
- | Platform | Version | End of Life | | -------------- | :-----: | ---------------------------------------------------------------------------------------------------------------------------- | | Debian | 8 | [June 2018](https://lists.debian.org/debian-security-announce/2018/msg00132.html) |
So, the distribution owners ended support for the following versions and aren't
| Ubuntu | 16.10 | [July 2017](https://lists.ubuntu.com/archives/ubuntu-announce/2017-July/000223.html) | | Ubuntu | 17.04 | [January 2018](https://lists.ubuntu.com/archives/ubuntu-announce/2018-January.txt) | | Ubuntu | 17.10 | [July 2018](https://lists.ubuntu.com/archives/ubuntu-announce/2018-July/000232.html) |
+| Ubuntu | 18.10 | [July 2018](https://lists.ubuntu.com/archives/ubuntu-announce/2019-July/000246.html) |
+| Ubuntu | 19.10 | [July 2020](https://lists.ubuntu.com/archives/ubuntu-announce/2020-July/000258.html) |
+| Ubuntu | 20.10 | [July 2021](https://lists.ubuntu.com/archives/ubuntu-announce/2021-July/000270.html) |
| Windows | 7 | [January 2020](https://support.microsoft.com/help/4057281/windows-7-support-ended-on-january-14-2020) | | Windows Server | 2008 R2 | [January 2020](https://support.microsoft.com/help/4456235/end-of-support-for-windows-server-2008-and-windows-server-2008-r2) | ## Notes on licensing
-PowerShell Core is released under the [MIT license][]. Under this license, and without a paid
-support agreement, users are limited to [community support][]. With community support, Microsoft
-makes no guarantees of responsiveness or fixes.
+PowerShell Core is released under the [MIT license][mit]. Under this license, and without a paid
+support agreement, users are limited to [community support][community]. With community support,
+Microsoft makes no guarantees of responsiveness or fixes.
## Windows PowerShell Compatibility The support lifecycle for PowerShell doesn't cover modules that ship outside of the PowerShell 7 release package. For example, using the `ActiveDirectory` module that ships as part of Windows
-Server is supported under the [Windows Support Lifecycle][].
+Server is supported under the [Windows Support Lifecycle][lifecycle].
PowerShell 7 improves compatibility with existing PowerShell modules written for Windows PowerShell.
-For more information, see the [about_Windows_Compatibility][] article and the
-[module compatibility list][].
+For more information, see the [about_Windows_Compatibility][about_Windows_Compatibility] article and
+the [module compatibility list][compatlist].
> [!NOTE]
-> The [**WindowsPSModulePath**](https://www.powershellgallery.com/packages/WindowsPSModulePath)
-> module is no longer necessary in PowerShell 7 and is not supported.
+> The [WindowsPSModulePath][WindowsPSModulePath] module is no longer necessary in PowerShell 7 and
+> is not supported.
## Experimental features
-[Experimental features][] are limited to [community support](#community-support).
+[Experimental features][exp] are limited to [community support](#community-support).
## Security Servicing Criteria
-PowerShell follows the [Microsoft Security Servicing Criteria for Windows][].
+PowerShell follows the [Microsoft Security Servicing Criteria for Windows][mssec].
The table below outlines the features that meet the servicing criteria and those that do not. | Feature | Type |
The table below outlines the features that meet the servicing criteria and those
> precedence over a `Set-ExecutionPolicy -ExecutionPolicy Bypass` command. For more information about AppLocker and Windows Defender Application Control (WDAC), see
-[Application Controls for Windows](/windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control).
+[Application Controls for Windows][WDAC].
## Release history
for historical reference. It is not intended for use to determine the support li
| PowerShell 1.0 | Nov-2006 | Installable on Windows XP SP2, Windows Server 2003 SP1 and Windows Vista. Optional component of Windows Server 2008. | <!-- hyperlink references -->
-[paid support]: https://support.microsoft.com/hub/4343728/support-for-business
+
+[paid]: https://support.microsoft.com/hub/4343728/support-for-business
[enterprise-agreement]: https://www.microsoft.com/licensing/licensing-programs/enterprise.aspx [assurance]: https://www.microsoft.com/licensing/licensing-programs/software-assurance-default.aspx
-[community support]: /powershell/scripting/community/community-support
+[community]: /powershell/scripting/community/community-support
[pshub]: /powershell
-[PowerShell Tech Community]: https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell
-[assisted support]: https://support.microsoft.com/assistedsupportproducts
+[pscommunity]: https://techcommunity.microsoft.com/t5/PowerShell/ct-p/WindowsPowerShell
+[assisted]: https://support.microsoft.com/assistedsupportproducts
[modern]: https://support.microsoft.com/help/30881/modern-lifecycle-policy [Long-Term]: https://dotnet.microsoft.com/platform/support/policy/dotnet-core [lifecycle-chart]: ./images/modern-lifecycle.png [semi-annual]: /windows-server/get-started/semi-annual-channel-overview
-[MIT license]: https://github.com/PowerShell/PowerShell/blob/master/LICENSE.txt
+[mit]: https://github.com/PowerShell/PowerShell/blob/master/LICENSE.txt
[about_Windows_Compatibility]: /powershell/module/microsoft.powershell.core/about/about_windows_powershell_compatibility
-[Windows Support Lifecycle]: https://support.microsoft.com/help/13853/windows-lifecycle-fact-sheet
-[module compatibility list]: /powershell/scripting/whats-new/module-compatibility
+[lifecycle]: https://support.microsoft.com/help/13853/windows-lifecycle-fact-sheet
+[compatlist]: /powershell/scripting/whats-new/module-compatibility
[WindowsPSModulePath]: https://www.powershellgallery.com/packages/WindowsPSModulePath/
-[Experimental features]: /powershell/module/microsoft.powershell.core/about/about_powershell_config#experimentalfeatures
+[exp]: /powershell/module/microsoft.powershell.core/about/about_powershell_config#experimentalfeatures
[Microsoft Security Servicing Criteria for Windows]: https://www.microsoft.com/msrc/windows-security-servicing-criteria
+[WDAC]: /windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control
community Powershell Style Guide https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/community/contributing/powershell-style-guide.md
Related products
## Markdown specifics
-The Microsoft Open Publishing System (OPS) that builds our documentation uses [markdig][] to process
-the Markdown documents. Markdig parses the documents based on the rules of the latest [CommonMark][]
-specification.
+The Microsoft Open Publishing System (OPS) that builds our documentation uses [markdig][markdig] to
+process the Markdown documents. Markdig parses the documents based on the rules of the latest
+[CommonMark][CommonMark] specification.
The new CommonMark spec is much stricter about the construction of some Markdown elements. Pay close attention to the details provided in this document.
GameConfigStore GameDVR_Enabled : 1
### Don't use aliases in examples Use the full name of all cmdlets and parameters unless you're specifically documenting the alias.
-Cmdlet and parameter names must use the proper [Pascal-cased][] names.
+Cmdlet and parameter names must use the proper [Pascal-cased][Pascal-cased] names.
### Using parameters in examples
example, even if the parameter is positional. This reduces the chance of confusi
## Formatting cmdlet reference articles
-Cmdlet reference articles have a specific structure. This structure is defined by [PlatyPS][].
-PlatyPS generates the cmdlet help for PowerShell modules in Markdown. After editing the Markdown
-files, PlatyPS is used create the MAML help files used by the `Get-Help` cmdlet.
+Cmdlet reference articles have a specific structure. This structure is defined by
+[PlatyPS][PlatyPS]. PlatyPS generates the cmdlet help for PowerShell modules in Markdown. After
+editing the Markdown files, PlatyPS is used create the MAML help files used by the `Get-Help`
+cmdlet.
PlatyPS has a hard-coded schema for cmdlet reference that is written into the code. The
-[platyPS.schema.md][] document attempts to describe this structure. Schema violations cause build
-errors that must be fixed before we can accept your contribution.
+[platyPS.schema.md][platyPS.schema.md] document attempts to describe this structure. Schema
+violations cause build errors that must be fixed before we can accept your contribution.
- Don't remove any of the ATX header structures. PlatyPS expects a specific set of headers. - The **Input type** and **Output type** headers must have a type. If the cmdlet doesn't take input
Get-Command -ListImported
## Formatting About_ files
-`About_*` files are written in Markdown but are shipped as plain text files. We use [Pandoc][] to
-convert the Markdown to plain text. `About_*` files are formatted for the best compatibility across
-all versions of PowerShell and with the publishing tools.
+`About_*` files are written in Markdown but are shipped as plain text files. We use
+[Pandoc][Pandoc] to convert the Markdown to plain text. `About_*` files are formatted for the best
+compatibility across all versions of PowerShell and with the publishing tools.
Basic formatting guidelines:
dev-cross-plat Writing Portable Modules https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/Writing-Portable-Modules.md
description: This article explains how to create modules new modules or update e
# Portable Modules
-Windows PowerShell is written for [.NET Framework][] while PowerShell Core is written for
-[.NET Core][]. Portable modules are modules that work in both Windows PowerShell and PowerShell
+Windows PowerShell is written for [.NET Framework][netframe] while PowerShell Core is written for
+[.NET Core][netcore]. Portable modules are modules that work in both Windows PowerShell and PowerShell
Core. While .NET Framework and .NET Core are highly compatible, there are differences in the available APIs between the two. There are also differences in the APIs available in Windows PowerShell and PowerShell Core. Modules intended to be used in both environments need to be aware of
these differences.
PowerShell [SnapIns](/powershell/scripting/developer/cmdlet/modules-and-snap-ins) aren't supported in PowerShell Core. However, it's trivial to convert a PSSnapIn to a PowerShell module. Typically, the PSSnapIn registration code is in a single source file of a class that derives from
-[PSSnapIn][]. Remove this source file from the build; it's no longer needed.
+[PSSnapIn][PSSnapIn]. Remove this source file from the build; it's no longer needed.
-Use [New-ModuleManifest][] to create a new module manifest that replaces the need for the PSSnapIn
-registration code. Some of the values from the **PSSnapIn** (such as **Description**) can be reused
-within the module manifest.
+Use [New-ModuleManifest][New-ModuleManifest] to create a new module manifest that replaces the need
+for the PSSnapIn registration code. Some of the values from the **PSSnapIn** (such as
+**Description**) can be reused within the module manifest.
The **RootModule** property in the module manifest should be set to the name of the assembly (dll) implementing the cmdlets.
implementing the cmdlets.
### The .NET Portability Analyzer (aka APIPort) To port modules written for Windows PowerShell to work with PowerShell Core, start with the
-[.NET Portability Analyzer][]. Run this tool against your compiled assembly to determine if the .NET
+[.NET Portability Analyzer][portability]. Run this tool against your compiled assembly to determine if the .NET
APIs used in the module are compatible with .NET Framework, .NET Core, and other .NET runtimes. The
-tool suggests alternate APIs if they exist. Otherwise, you may need to add [runtime checks][] and
-restrict capabilities not available in specific runtimes.
+tool suggests alternate APIs if they exist. Otherwise, you may need to add [runtime checks][checks]
+and restrict capabilities not available in specific runtimes.
## Creating a new module
-If creating a new module, the recommendation is to use the [.NET CLI][].
+If creating a new module, the recommendation is to use the [.NET CLI][netcli].
### Installing the PowerShell Standard module template
FavoriteNumber FavoritePet
### Debugging the module For a guide on setting up Visual Studio Code to debug the module, see
-[Using Visual Studio Code for debugging compiled cmdlets][].
+[Using Visual Studio Code for debugging compiled cmdlets][using-vscode].
## Supporting technologies
The following sections describe in detail some of the technologies used by this
### .NET Standard Library
-[.NET Standard][] is a formal specification of .NET APIs that are available in all .NET
+[.NET Standard][netstd] is a formal specification of .NET APIs that are available in all .NET
implementations. Managed code targeting .NET Standard works with the .NET Framework and .NET Core versions that are compatible with that version of the .NET Standard.
works with PowerShell Core 6 without recompilation.
### PowerShell Standard Library
-The [PowerShell Standard][] library is a formal specification of PowerShell APIs available in all
+The [PowerShell Standard][psstd] library is a formal specification of PowerShell APIs available in all
PowerShell versions greater than or equal to the version of that standard.
-For example, [PowerShell Standard 5.1][] is compatible with both Windows PowerShell 5.1 and
+For example, [PowerShell Standard 5.1][psstd51] is compatible with both Windows PowerShell 5.1 and
PowerShell Core 6.0 or newer. We recommend you compile your module using PowerShell Standard Library. The library ensures
Standard Library 5.1 will always be compatible with future versions of PowerShel
#### Indicating Compatibility With Windows PowerShell and PowerShell Core
-After validating that your module works with both Windows PowerShell and PowerShell Core, the
-module manifest should explicitly indicate compatibility by using the [CompatiblePSEditions][]
-property. A value of `Desktop` means that the module is compatible with Windows PowerShell, while a
-value of `Core` means that the module is compatible with PowerShell Core. Including both `Desktop`
-and `Core` means that the module is compatible with both Windows PowerShell and PowerShell Core.
+After validating that your module works with both Windows PowerShell and PowerShell Core, the module
+manifest should explicitly indicate compatibility by using the
+[CompatiblePSEditions][CompatiblePSEditions] property. A value of `Desktop` means that the module is
+compatible with Windows PowerShell, while a value of `Core` means that the module is compatible with
+PowerShell Core. Including both `Desktop` and `Core` means that the module is compatible with both
+Windows PowerShell and PowerShell Core.
> [!NOTE] > `Core` does not automatically mean that the module is compatible with Windows, Linux, and macOS.
and `Core` means that the module is compatible with both Windows PowerShell and
First, validate that your module works on Linux and macOS. Next, indicate compatibility with those operating systems in the module manifest. This makes it easier for users to find your module for
-their operating system when published to the [PowerShell Gallery][].
+their operating system when published to the [PowerShell Gallery][gallery].
Within the module manifest, the `PrivateData` property has a `PSData` sub-property. The optional `Tags` property of `PSData` takes an array of values that show up in PowerShell Gallery. The
Prior to PowerShell 7, one would have to have custom code to load the appropriat
dll so that the managed library can find it correctly. With PowerShell 7, native binaries to load are searched in sub-folders within the managed
-library's location following a subset of the [.NET RID Catalog][] notation.
+library's location following a subset of the [.NET RID Catalog][rids] notation.
``` managed.dll folder
managed.dll folder
``` <!-- reference links -->
-[.NET Framework]: /dotnet/framework/
-[.NET Core]: /dotnet/core/
+[netframe]: /dotnet/framework/
+[netcore]: /dotnet/core/
[PSSnapIn]: /dotnet/api/system.management.automation.pssnapin [New-ModuleManifest]: /powershell/module/microsoft.powershell.core/new-modulemanifest
-[runtime checks]: /dotnet/api/system.runtime.interopservices.runtimeinformation.frameworkdescription#System_Runtime_InteropServices_RuntimeInformation_FrameworkDescription
-[.NET CLI]: /dotnet/core/tools/?tabs=netcore2x
-[Using Visual Studio Code for debugging compiled cmdlets]: vscode/using-vscode-for-debugging-compiled-cmdlets.md
-[.NET Standard]: /dotnet/standard/net-standard
-[PowerShell Standard]: https://github.com/PowerShell/PowerShellStandard
-[PowerShell Standard 5.1]: https://www.nuget.org/packages/PowerShellStandard.Library/5.1.0
-[PowerShell Gallery]: https://www.powershellgallery.com
-[.NET Portability Analyzer]: https://github.com/Microsoft/dotnet-apiport
+[checks]: /dotnet/api/system.runtime.interopservices.runtimeinformation.frameworkdescription#System_Runtime_InteropServices_RuntimeInformation_FrameworkDescription
+[netcli]: /dotnet/core/tools/?tabs=netcore2x
+[using-vscode]: vscode/using-vscode-for-debugging-compiled-cmdlets.md
+[netstd]: /dotnet/standard/net-standard
+[psstd]: https://github.com/PowerShell/PowerShellStandard
+[psstd51]: https://www.nuget.org/packages/PowerShellStandard.Library/5.1.0
+[gallery]: https://www.powershellgallery.com
+[portability]: https://github.com/Microsoft/dotnet-apiport
[CompatiblePSEditions]: /powershell/scripting/gallery/concepts/module-psedition-support
-[.NET RID Catalog]: /dotnet/core/rid-catalog
+[rids]: /dotnet/core/rid-catalog
dev-cross-plat Choosing The Right Nuget Package https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/choosing-the-right-nuget-package.md
# Choosing the right PowerShell NuGet package for your .NET project Alongside the `pwsh` executable packages published with each PowerShell release, the PowerShell team
-also maintains several packages available on [NuGet][]. These packages allow targeting PowerShell as
+also maintains several packages available on [NuGet][NuGet]. These packages allow targeting PowerShell as
an API platform in .NET. As a .NET application that provides APIs and expects to load .NET libraries implementing its own
PowerShell in their own applications.
- **Referencing** is for when a project, usually a module, is intended to be loaded into PowerShell. It must be compiled against the APIs that PowerShell provides in order to interact with it, but the PowerShell implementation is supplied by the PowerShell process loading it in. For
- referencing, a project can use [reference assemblies][] or the actual runtime assemblies as a
- compilation target, but must ensure that it does not publish any of these with its build.
+ referencing, a project can use [reference assemblies][refasm] or the actual runtime assemblies as
+ a compilation target, but must ensure that it does not publish any of these with its build.
- **Hosting** is when a project needs its own implementation of PowerShell, usually because it is a standalone application that needs to run PowerShell. In this case, pure reference assemblies cannot be used. Instead, a concrete PowerShell implementation must be depended upon. Because a
PowerShell in their own applications.
> runtime. In order to prevent publishing project dependencies that are just being used as compilation
-reference targets, it is recommended to set the [PrivateAssets attribute][]:
+reference targets, it is recommended to set the [PrivateAssets][PrivateAssets] attribute:
```xml <PackageReference Include="PowerShellStandard.Library" Version="5.1.0.0" PrivateAssets="all" />
PowerShell APIs:
- **Implementing a PowerShell binary module** PowerShell binary modules are .NET libraries loaded by PowerShell that must implement PowerShell
- APIs like the [PSCmdlet][] or [CmdletProvider][] types in order to expose cmdlets or providers
- respectively. Because they are loaded in, modules seek to compile against references to PowerShell
- without publishing it in their build. It's also common for modules to want to support multiple
- PowerShell versions and platforms, ideally with a minimum of overhead of disk space, complexity,
- or repeated implementation. See [about_Modules][] for more information about modules.
+ APIs like the [PSCmdlet][PSCmdlet] or [CmdletProvider][CmdletProvider] types in order to expose
+ cmdlets or providers respectively. Because they are loaded in, modules seek to compile against
+ references to PowerShell without publishing it in their build. It's also common for modules to
+ want to support multiple PowerShell versions and platforms, ideally with a minimum of overhead of
+ disk space, complexity, or repeated implementation. See [about_Modules][about_Modules] for more
+ information about modules.
- **Implementing a PowerShell Host** A PowerShell Host provides an interaction layer for the PowerShell runtime. It is a specific form
- of _hosting_, where a [PSHost][] is implemented as a new user interface to PowerShell. For
+ of _hosting_, where a [PSHost][PSHost] is implemented as a new user interface to PowerShell. For
example, the PowerShell ConsoleHost provides a terminal user interface for PowerShell executables, while the PowerShell Editor Services Host and the ISE Host both provide an editor-integrated partially graphical user interface around PowerShell. While it's possible to load a host onto an
PowerShell APIs:
- **Unit testing PowerShell modules from .NET** While modules and other libraries designed to expose functionality to PowerShell should be
- primarily tested from PowerShell (we recommend [Pester][]), sometimes it's necessary to unit test
+ primarily tested from PowerShell (we recommend [Pester][Pester]), sometimes it's necessary to unit test
APIs written for a PowerShell module from .NET. This situation involves the module code trying to target a number of PowerShell versions, while testing should run it on specific, concrete implementations.
PowerShell APIs:
In this article, we'll cover the following NuGet packages that expose PowerShell APIs: -- [PowerShellStandard.Library][], a reference assembly that enables building a single assembly
- that can be loaded by multiple PowerShell runtimes.
-- [Microsoft.PowerShell.SDK][], the way to target and rehost the whole PowerShell SDK-- The [System.Management.Automation][] package, the core PowerShell runtime and engine
+- [PowerShellStandard.Library][psstdlib], a reference assembly that enables building a single
+ assembly that can be loaded by multiple PowerShell runtimes.
+- [Microsoft.PowerShell.SDK][pssdk], the way to target and rehost the whole PowerShell SDK
+- The [System.Management.Automation][sma] package, the core PowerShell runtime and engine
implementation, that can be useful in minimal hosted implementations and for version-specific targeting scenarios. - The **Windows PowerShell reference assemblies**, the way to target and effectively rehost Windows PowerShell (PowerShell versions 5.1 and below). > [!NOTE]
-> The [PowerShell NuGet][] package is not a .NET library package at all, but instead provides the
-> PowerShell dotnet global tool implementation. This should not be used by any projects, since it
-> only provides an executable.
+> The [PowerShell NuGet][psnuget] package is not a .NET library package at all, but instead provides
+> the PowerShell dotnet global tool implementation. This should not be used by any projects, since
+> it only provides an executable.
## PowerShellStandard.Library
applications.
### Using PowerShell Standard with different .NET runtimes
-PowerShell Standard targets the [.NET Standard 2.0][] target runtime, which is a façade runtime
-designed to provide a common surface area shared by .NET Framework and .NET Core. This allows
-targeting a single runtime to produce a single assembly that will work with multiple PowerShell
-versions, but has the following consequences:
+PowerShell Standard targets the [.NET Standard 2.0][netstd20] target runtime, which is a façade
+runtime designed to provide a common surface area shared by .NET Framework and .NET Core. This
+allows targeting a single runtime to produce a single assembly that will work with multiple
+PowerShell versions, but has the following consequences:
- The PowerShell loading the module or library must be running a minimum of .NET 4.6.1; .NET 4.6 and .NET 4.5.2 do not support .NET Standard. Note that a newer Windows PowerShell version does not mean a newer .NET Framework version; Windows PowerShell 5.1 may run on .NET 4.5.2. - In order to work with a PowerShell running .NET Framework 4.7.1 or below, the .NET 4.6.1
- [NETStandard.Library][] implementation is required to provide the netstandard.dll and other shim
- assemblies in older .NET Framework versions.
+ [NETStandard.Library][netstdlib] implementation is required to provide the netstandard.dll and
+ other shim assemblies in older .NET Framework versions.
PowerShell 6+ provides its own shim assemblies for type forwarding from .NET Framework 4.6.1 (and above) to .NET Core. This means that as long as a module uses only APIs that exist in .NET Core,
a testing dependency with .NET Core (with the version set to match the desired P
and the appropriate Windows PowerShell reference assemblies with .NET Framework. For more information on PowerShell Standard and using it to write a binary module that works in
-multiple PowerShell versions, see [this blog post][]. Also see the
-[PowerShell Standard repository][] on GitHub.
+multiple PowerShell versions, see [this blog post][blog]. Also see the
+[PowerShell Standard repository][psstdrepo] on GitHub.
## Microsoft.PowerShell.SDK
of the PowerShell application; version 7.0 contains the implementation of PowerS
commands or scripts with it will largely behave like running them in PowerShell 7.0. Running PowerShell commands from the SDK is mostly, but not totally, the same as running them from
-`pwsh`. For example, [Start-Job][] currently depends on the `pwsh` executable being available, and
-so will not work with `Microsoft.Powershell.SDK` by default.
+`pwsh`. For example, [Start-Job][Start-Job] currently depends on the `pwsh` executable being
+available, and so will not work with `Microsoft.Powershell.SDK` by default.
Targeting `Microsoft.Powershell.SDK` from a .NET application allows you to integrate with all of PowerShell's implementation assemblies, such as `System.Management.Automation`,
PowerShell's implementation assemblies, such as `System.Management.Automation`,
Publishing an application targeting `Microsoft.Powershell.SDK` will include all these assemblies, and any dependencies PowerShell requires. It will also include other assets that PowerShell required in its build, such as the module manifests for `Microsoft.PowerShell.*` modules and the `ref`
-directory required by [Add-Type][].
+directory required by [Add-Type][Add-Type].
Given the completeness of `Microsoft.Powershell.SDK`, it's best suited for:
functionality when:
`System.Management.Automation.Language` namespace) like the PowerShell parser, AST, and AST visitor APIs (for example for static analysis of PowerShell). - You only wish to execute specific commands from the `Microsoft.PowerShell.Core` module and can
- execute them in a session state created with the [CreateDefault2][] factory method.
+ execute them in a session state created with the [CreateDefault2][CreateDefault2] factory method.
Additionally, `System.Management.Automation` is a useful reference assembly when:
different package for each version of Windows PowerShell:
- [PowerShell 3](https://www.nuget.org/packages/Microsoft.PowerShell.3.ReferenceAssemblies/) Information on how to use the Windows PowerShell reference assemblies can be found in the
-[Windows PowerShell SDK][].
+[Windows PowerShell SDK][pssdk].
## Real-world examples using these NuGet packages
needs. Listed here are some notable examples.
### PSReadLine
-[PSReadLine][], the PowerShell module that provides much of PowerShell's rich console experience,
-targets PowerShell Standard as a dependency rather than a specific PowerShell version, and targets
-the `net461` .NET runtime in its [csproj][].
+[PSReadLine][PSReadLine], the PowerShell module that provides much of PowerShell's rich console
+experience, targets PowerShell Standard as a dependency rather than a specific PowerShell version,
+and targets the `net461` .NET runtime in its [csproj][csproj].
PowerShell 6+ supplies its own shim assemblies that allow a DLL targeting the `net461` runtime to "just work" when loaded in (by redirecting binding to .NET Framework's `mscorlib.dll` to the
The .NET 4.6.1 target does mean that Windows PowerShell running on
### PowerShell Editor Services
-[PowerShell Editor Services][] (PSES) is the backend for the [PowerShell extension][] for
-[Visual Studio Code][], and is actually a form of PowerShell module that gets loaded by a PowerShell
-executable and then takes over that process to rehost PowerShell within itself while also providing
-Language Service Protocol and Debug Adapter features.
+[PowerShell Editor Services][pses] (PSES) is the backend for the [PowerShell extension][psext] for
+[Visual Studio Code][vscode], and is actually a form of PowerShell module that gets loaded by a
+PowerShell executable and then takes over that process to rehost PowerShell within itself while also
+providing Language Service Protocol and Debug Adapter features.
PSES provides concrete implementation targets for `netcoreapp2.1` to target PowerShell 6+ (since PowerShell 7's `netcoreapp3.1` runtime is backwards compatible) and `net461` to target Windows
and PowerShell Standard. This allows it to pull in dependencies required for .NE
Framework platforms, while still simplifying most of the codebase behind a uniform abstraction. Because it is built against PowerShell Standard, PSES requires a runtime implementation of
-PowerShell in order to be tested correctly. To do this, [PSES's xUnit][] tests pull in
+PowerShell in order to be tested correctly. To do this, [PSES's xUnit][xunit] tests pull in
`Microsoft.PowerShell.SDK` and `Microsoft.PowerShell.5.ReferenceAssemblies` in order to provide a PowerShell implementation in the test environment.
-As with PSReadLine, PSES cannot support .NET 4.6 and below, but it [performs a check][] at runtime
-before calling any of the APIs that could cause a crash on the lower .NET Framework runtimes.
+As with PSReadLine, PSES cannot support .NET 4.6 and below, but it [performs a check][check] at
+runtime before calling any of the APIs that could cause a crash on the lower .NET Framework
+runtimes.
### PSScriptAnalyzer
-[PSScriptAnalyzer][], the linter for PowerShell, must target syntactic elements only introduced in
-certain versions of PowerShell. Because recognition of these syntactic elements is accomplished by
-implementing an [AstVisitor2][], it's not possible to use PowerShellStandard and also implement AST
-visitor methods for newer PowerShell syntaxes.
+[PSScriptAnalyzer][pssa], the linter for PowerShell, must target syntactic elements only introduced
+in certain versions of PowerShell. Because recognition of these syntactic elements is accomplished
+by implementing an [AstVisitor2][AstVisitor2], it's not possible to use PowerShellStandard and also
+implement AST visitor methods for newer PowerShell syntaxes.
-Instead, PSScriptAnalyzer [targets each PowerShell version][] as a build configuration, and produces
-a separate DLL for each of them. This increases build size and complexity, but allows:
+Instead, PSScriptAnalyzer [targets each PowerShell version][targets] as a build configuration, and
+produces a separate DLL for each of them. This increases build size and complexity, but allows:
- Version-specific API targeting - Version-specific functionality to be implemented with essentially no runtime cost
If you've skipped to the summary, some broad recommendations are:
<!--link references -->
-[.NET Standard 2.0]: /dotnet/standard/net-standard
+ [about_Modules]: /powershell/module/microsoft.powershell.core/about/about_modules [Add-Type]: /powershell/module/microsoft.powershell.utility/add-type [AstVisitor2]: /dotnet/api/system.management.automation.language.astvisitor2
+[blog]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
+[check]: https://github.com/PowerShell/PowerShellEditorServices/blob/8c500ee1752201d3c1cc2e5d90f1a2af3b1eb15d/src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs#L231-L251
[CmdletProvider]: /dotnet/api/system.management.automation.provider.cmdletprovider [CreateDefault2]: /dotnet/api/system.management.automation.runspaces.initialsessionstate.createdefault2 [csproj]: https://github.com/PowerShell/PSReadLine/blob/master/PSReadLine/PSReadLine.csproj
-[Microsoft.PowerShell.SDK]: https://www.nuget.org/packages/Microsoft.PowerShell.SDK/
-[NETStandard.Library]: https://www.nuget.org/packages/NETStandard.Library/
+[netstd20]: /dotnet/standard/net-standard
+[netstdlib]: https://www.nuget.org/packages/NETStandard.Library/
[NuGet]: https://www.nuget.org/
-[performs a check]: https://github.com/PowerShell/PowerShellEditorServices/blob/8c500ee1752201d3c1cc2e5d90f1a2af3b1eb15d/src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs#L231-L251
[Pester]: https://github.com/Pester/Pester
-[PowerShell Editor Services]: https://github.com/PowerShell/PowerShellEditorServices/
-[PowerShell extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell
-[PowerShell NuGet]: https://www.nuget.org/packages/PowerShell/
-[PowerShell Standard repository]: https://github.com/PowerShell/PowerShellStandard
-[PowerShellStandard.Library]: https://www.nuget.org/packages/PowerShellStandard.Library/
+[PrivateAssets]: /dotnet/core/tools/csproj#packagereference
[PSCmdlet]: /dotnet/api/system.management.automation.pscmdlet
-[PSES's xUnit]: https://github.com/PowerShell/PowerShellEditorServices/blob/8c500ee1752201d3c1cc2e5d90f1a2af3b1eb15d/test/PowerShellEditorServices.Test/PowerShellEditorServices.Test.csproj#L15-L20
+[pses]: https://github.com/PowerShell/PowerShellEditorServices/
+[psext]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell
[PSHost]: /dotnet/api/system.management.automation.host.pshost
-[PrivateAssets attribute]: /dotnet/core/tools/csproj#packagereference
+[psnuget]: https://www.nuget.org/packages/PowerShell/
[PSReadLine]: https://github.com/PowerShell/PSReadLine
-[PSScriptAnalyzer]: https://github.com/powershell/psscriptanalyzer
-[reference assemblies]: https://github.com/dotnet/standard/blob/master/docs/history/evolution-of-design-time-assemblies.md#definitions
+[pssa]: https://github.com/powershell/psscriptanalyzer
+[pssdk]: /powershell/scripting/developer/windows-powershell
+[pssdk]: https://www.nuget.org/packages/Microsoft.PowerShell.SDK/
+[psstdlib]: https://www.nuget.org/packages/PowerShellStandard.Library/
+[psstdrepo]: https://github.com/PowerShell/PowerShellStandard
+[refasm]: https://github.com/dotnet/standard/blob/master/docs/history/evolution-of-design-time-assemblies.md#definitions
+[sma]: https://www.nuget.org/packages/System.Management.Automation/
[Start-Job]: /powershell/module/microsoft.powershell.core/start-job
-[System.Management.Automation]: https://www.nuget.org/packages/System.Management.Automation/
-[targets each PowerShell version]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/Engine/Engine.csproj
-[this blog post]: https://devblogs.microsoft.com/powershell/powershell-standard-library-build-single-module-that-works-across-windows-powershell-and-powershell-core/
-[Visual Studio Code]: https://code.visualstudio.com/
-[Windows PowerShell SDK]: /powershell/scripting/developer/windows-powershell
+[targets]: https://github.com/PowerShell/PSScriptAnalyzer/blob/master/Engine/Engine.csproj
+[vscode]: https://code.visualstudio.com/
+[xunit]: https://github.com/PowerShell/PowerShellEditorServices/blob/8c500ee1752201d3c1cc2e5d90f1a2af3b1eb15d/test/PowerShellEditorServices.Test/PowerShellEditorServices.Test.csproj#L15-L20
dev-cross-plat Create Help Using Platyps https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/create-help-using-platyps.md
cmdlets packaged into modules. However, PowerShell does not provide any tools fo
XML-based help. The SDK documentation explains the structure of MAML help, but leaves you the task of creating the complex, and deeply nested, MAML content by hand.
-This is where the [PlatyPS][] module can help.
+This is where the [PlatyPS][platyps] module can help.
## What is PlatyPS? PlatyPS is an [open-source][platyps-repo] tool that started as a _hackathon_ project to make the creation and maintenance of MAML easier. PlatyPS documents the syntax of parameter sets and the
-individual parameters for each cmdlet in your module. PlatyPS creates structured [Markdown][]
+individual parameters for each cmdlet in your module. PlatyPS creates structured [Markdown][MD]
files that contain the syntax information. It can't create descriptions or provide examples. PlatyPS creates placeholders for you to fill in descriptions and examples. After adding the required
The following flowchart outlines the process for creating or updating PowerShell
`New-MarkdownAboutHelp` creates a new _about_ file named `about_topic_name.md`.
- For more information, see [New-MarkdownHelp][] and [New-MarkdownAboutHelp][].
+ For more information, see [New-MarkdownHelp][New-MarkdownHelp] and
+ [New-MarkdownAboutHelp][New-MarkdownAboutHelp].
### Update existing Markdown content when the module changes
modules that have new cmdlets, new parameters, or parameters that have changed.
- Updated parameter metadata - Updated input and output type information
- For more information, see [Update-MarkdownHelpModule][].
+ For more information, see [Update-MarkdownHelpModule][Update-MarkdownHelpModule].
## Edit the new or updated Markdown files
For detailed information about writing PowerShell content, see the following art
> [!NOTE] > PlatyPS has a specific schema that is uses for cmdlet reference. That schema only allows certain > Markdown blocks in specific sections of the document. If you put content in the wrong location,
-> the PlatyPS build step fails. For more information, see the [schema][] documentation in the
-> PlatyPS repository. For a complete example of well-formed cmdlet reference, see [Get-Item][].
+> the PlatyPS build step fails. For more information, see the [schema][schema] documentation in the
+> PlatyPS repository. For a complete example of well-formed cmdlet reference, see
+> [Get-Item][Get-Item].
After providing the required content for each of your cmdlets, you need to make sure that you update the module landing page. Verify your module has the correct `Module Guid` and `Download Help Link`
violations.
Once this step is complete, you will see `*-help.xml` and `about_*.help.txt` files in the target output folder.
-For more information, see [New-ExternalHelp][]
+For more information, see [New-ExternalHelp][New-ExternalHelp]
### Test the compiled help files
-You can verify the content with the [Get-HelpPreview][] cmdlet:
+You can verify the content with the [Get-HelpPreview][Get-HelpPreview] cmdlet:
```powershell Get-HelpPreview -Path "<ModuleName>-Help.xml"
files available to users. There are two options for providing help in the PowerS
### Packaging help with the module
-The help files can be packaged with your module. See [Writing Help for Modules][] for details of the
-folder structure. You should include the list of Help files in the value of the **FileList** key in
-the module manifest.
+The help files can be packaged with your module. See [Writing Help for Modules][writing] for details
+of the folder structure. You should include the list of Help files in the value of the **FileList**
+key in the module manifest.
### Creating an updateable help package
New-ExternalHelpCab @helpCabParameters
After creating the ZIP and CAB files, upload the ZIP, CAB, and HelpInfo XML files to your HTTP file server. Put the files in the location indicated by the **HelpInfoURI**.
-For more information, see [New-ExternalHelpCab][].
+For more information, see [New-ExternalHelpCab][New-ExternalHelpCab].
### Other publishing options Markdown is a versatile format that is easy to transform to other formats for publishing. Using a
-tool like [Pandoc][], you can convert your Markdown help files to many different document formats,
-including plain text, HTML, PDF, and Office document formats.
+tool like [Pandoc][Pandoc], you can convert your Markdown help files to many different document
+formats, including plain text, HTML, PDF, and Office document formats.
-Also, the cmdlets [ConvertFrom-Markdown][] and [Show-Markdown][] in PowerShell 6 and higher can be
-used to convert Markdown to HTML or create a colorful display in the PowerShell console.
+Also, the cmdlets [ConvertFrom-Markdown]ConvertFrom-Markdown] and [Show-Markdown][Show-Markdown] in
+PowerShell 6 and higher can be used to convert Markdown to HTML or create a colorful display in the
+PowerShell console.
## Known issues
-PlatyPS is very sensitive to the [schema][] for the structure of the Markdown files it creates and
+PlatyPS is very sensitive to the [schema][schema] for the structure of the Markdown files it creates and
compiles. It is very easy write valid Markdown that violates this schema. For more information,
-consult the [PowerShell style guide][] and [Editing reference articles][].
+consult the [PowerShell style guide][style] and [Editing reference articles][edit].
<!-- link references --> [platyps-repo]: https://github.com/PowerShell/platyps [PlatyPS]: https://www.powershellgallery.com/packages/platyPS/
-[Markdown]: https://commonmark.org
-[markdig]: https://github.com/lunet-io/markdig
+[MD]: https://commonmark.org
[schema]: https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md
+[style]: /powershell/scripting/community/contributing/powershell-style-guide
+[edit]: /powershell/scripting/community/contributing/editing-cmdlet-ref
+[writing]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-modules
+[step-by-step]: /powershell/scripting/developer/help/updatable-help-authoring-step-by-step
+[Pandoc]: https://pandoc.org
+ [Get-Item]: https://github.com/MicrosoftDocs/PowerShell-Docs/blob/staging/reference/7.0/Microsoft.PowerShell.Management/Get-Item.md [New-MarkdownHelp]: https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownHelp.md [Update-MarkdownHelpModule]: https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpModule.md
consult the [PowerShell style guide][] and [Editing reference articles][].
[New-ExternalHelp]: https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelp.md [Get-HelpPreview]: https://github.com/PowerShell/platyPS/blob/master/docs/Get-HelpPreview.md [New-ExternalHelpCab]: https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelpCab.md
-[PowerShell style guide]: /powershell/scripting/community/contributing/powershell-style-guide
-[Editing reference articles]: /powershell/scripting/community/contributing/editing-cmdlet-ref
-[Writing Help for Modules]: /powershell/scripting/developer/help/writing-help-for-windows-powershell-modules
-[step-by-step]: /powershell/scripting/developer/help/updatable-help-authoring-step-by-step
-[Pandoc]: https://pandoc.org
[ConvertFrom-Markdown]: /powershell/module/microsoft.powershell.utility/convertfrom-markdown [Show-Markdown]: /powershell/module/microsoft.powershell.utility/show-markdown
dev-cross-plat Create Standard Library Binary Module https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/create-standard-library-binary-Module.md
# How to create a Standard Library binary module I recently had an idea for module that I wanted to implement as a binary module. I have yet to
-create one using the [PowerShell Standard Library][] so this felt like a good opportunity. I used
-the [Creating a cross-platform binary module][] guide to create this module without any roadblocks.
-We're going to walk that same process and I'll add a little extra commentary along the way.
+create one using the [PowerShell Standard Library][psstd] so this felt like a good opportunity. I
+used the [Creating a cross-platform binary module][xplat] guide to create this module without any
+roadblocks. We're going to walk that same process and I'll add a little extra commentary along the
+way.
> [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
-> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> The [original version][article] of this article appeared on the blog written by
+> [@KevinMarquette][KM]. The PowerShell team thanks Kevin for sharing this content with us. Please
+> check out his blog at [PowerShellExplained.com][kmblog].
## What is the PowerShell Standard Library?
New-Item -Path $module -Type Directory
### Binary module setup This article os focused on the binary module so that is where we'll start. This section pulls
-examples from the [Creating a cross-platform binary module][] guide. Review that guide if you
+examples from the [Creating a cross-platform binary module][xplat] guide. Review that guide if you
need more details or have any issues.
-First thing we want to do is check the version of the [dotnet core SDK][] that we installed. I'm
-using 2.1.4, but you should have 2.0.0 or newer before continuing.
+First thing we want to do is check the version of the [dotnet core SDK][netsdk] that we installed.
+I'm using 2.1.4, but you should have 2.0.0 or newer before continuing.
```powershell PS> dotnet --version
Use 2.0.0 if you're using the 2.0 SDK.
dotnet new globaljson --sdk-version 2.1.0 ```
-Add the PowerShell Standard Library [NuGet package][] to the project. Make sure you use the most
-recent version available for the level of compatibility that you need. I would default to the latest
-version but I don't think this module leverages any features newer than PowerShell 3.0.
+Add the PowerShell Standard Library [NuGet package][nuget] to the project. Make sure you use the
+most recent version available for the level of compatibility that you need. I would default to the
+latest version but I don't think this module leverages any features newer than PowerShell 3.0.
```powershell dotnet add package PowerShellStandard.Library --version 7.0.0-preview.1
Cmdlet Resolve-MyCmdlet 1.0.0.0 MyModule
``` If the import fails on your system, try updating .NET to 4.7.1 or newer. The
-[Creating a cross-platform binary module][] guide goes into more details on .NET support and
+[Creating a cross-platform binary module][xplat] guide goes into more details on .NET support and
compatibility for older versions of .NET. ### Module manifest
that loaded the DLL.
### VS Code reload window action
-I do most of my PowerShell dev work in [VS Code][]. When I'm working on a binary module (or a module
-with classes), I've gotten into the habit of reloading VS Code every time I build.
+I do most of my PowerShell dev work in [VS Code][vscode]. When I'm working on a binary module (or a
+module with classes), I've gotten into the habit of reloading VS Code every time I build.
<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> pops the command window and `Reload Window` is always at the top of my list.
PSGallery because module versioning places the new one in a different folder.
You can set up a local PSGallery and publish to that as part of your build. Then do your local install from that PSGallery. This sounds like a lot of work, but this can be as simple as starting a docker container. I cover a way to do that in my post on
-[Using a NuGet server for a PSRepository][].
+[Using a NuGet server for a PSRepository][psrepo].
## Why binary modules?
was able to find lots of things to add to it.
## Final thoughts
-Binary modules are easy to create. I didn't touch on the C# syntax for creating a Cmdlet, but
-there is plenty of documentation on it in the [Windows PowerShell SDK][]. It is definitely something
+Binary modules are easy to create. I didn't touch on the C# syntax for creating a Cmdlet, but there
+is plenty of documentation on it in the [Windows PowerShell SDK][pssdk]. It is definitely something
worth experimenting with as a stepping stone into more serious C#. <!-- link references -->
-[original version]: https://powershellexplained.com/2018-08-04-Powershell-Standard-Library-Binary-Module/
-[powershellexplained.com]: https://powershellexplained.com/
-[@KevinMarquette]: https://twitter.com/KevinMarquette
-[PowerShell Standard Library]: https://github.com/PowerShell/PowerShellStandard
-[Creating a cross-platform binary module]: https://github.com/PowerShell/PowerShell/blob/master/docs/cmdlet-example/command-line-simple-example.md
-[dotnet core SDK]: https://www.microsoft.com/net/download/core
-[Using a NuGet server for a PSRepository]: https://powershellexplained.com/2018-03-03-Powershell-Using-a-NuGet-server-for-a-PSRepository/
-[Windows PowerShell SDK]: /powershell/scripting/developer/windows-powershell-reference
-[VS Code]: https://code.visualstudio.com
-[nuget package]: https://www.nuget.org/packages/PowerShellStandard.Library/
+[article]: https://powershellexplained.com/2018-08-04-Powershell-Standard-Library-Binary-Module/
+[kmblog]: https://powershellexplained.com/
+[KM]: https://twitter.com/KevinMarquette
+[psstd]: https://github.com/PowerShell/PowerShellStandard
+[xplat]: https://github.com/PowerShell/PowerShell/blob/master/docs/cmdlet-example/command-line-simple-example.md
+[netsdk]: https://www.microsoft.com/net/download/core
+[psrepo]: https://powershellexplained.com/2018-03-03-Powershell-Using-a-NuGet-server-for-a-PSRepository/
+[pssdk]: /powershell/scripting/developer/windows-powershell-reference
+[vscode]: https://code.visualstudio.com
+[nuget]: https://www.nuget.org/packages/PowerShellStandard.Library/
dev-cross-plat How To Replicate The ISE Experience In Vscode https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/vscode/How-To-Replicate-the-ISE-Experience-In-VSCode.md
ISE Mode makes the following changes to VS Code settings.
There are a number of ISE themes available for VS Code to make the editor look much more like the ISE.
- In the [Command Palette][] type `theme` to get `Preferences: Color Theme` and press
+ In the [Command Palette][cmdpal] type `theme` to get `Preferences: Color Theme` and press
<kbd>Enter</kbd>. In the drop-down list, select `PowerShell ISE`. You can set this theme in the settings with:
ISE Mode makes the following changes to VS Code settings.
Thanks to the work of [@corbob](https://github.com/corbob), the PowerShell extension has the beginnings of its own command explorer.
- In the [Command Palette][], enter `PowerShell Command Explorer` and press <kbd>Enter</kbd>.
+ In the [Command Palette][cmdpal], enter `PowerShell Command Explorer` and press <kbd>Enter</kbd>.
- Open in the ISE
- If you want to open a file in the Windows PowerShell ISE anyway, open the [Command Palette][],
+ If you want to open a file in the Windows PowerShell ISE anyway, open the [Command Palette][cmdpal],
search for "open in ise", then select **PowerShell: Open Current File in PowerShell ISE**. ## Other resources
ISE Mode makes the following changes to VS Code settings.
If you know of more ways to make VS Code feel more familiar for ISE users, contribute to this doc. If there's a compatibility configuration you're looking for, but you can't find any way to enable it,
-[open an issue][] and ask away!
+[open an issue][ghi] and ask away!
We're always happy to accept PRs and contributions as well! <!-- link references --> [vsc-docs]: https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette
-[Command Palette]: #vs-code-tips
-[open an issue]: https://github.com/PowerShell/VSCode-powershell/issues/new/choose
+[cmdpal]: #vs-code-tips
+[ghi]: https://github.com/PowerShell/VSCode-powershell/issues/new/choose
[4sysops]: https://4sysops.com/archives/make-visual-studio-code-look-and-behave-like-powershell-ise/ [mikefrobbins]: https://mikefrobbins.com/2017/08/24/how-to-install-visual-studio-code-and-configure-it-as-a-replacement-for-the-powershell-ise/
dev-cross-plat Understanding File Encoding https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/vscode/understanding-file-encoding.md
indicate a UTF-8/Windows-1252 encoding problem.
The PowerShell extension interacts with scripts in a number of ways: 1. When scripts are edited in VS Code, the contents are sent by VS Code to the extension. The
- [Language Server Protocol][] mandates that this content is transferred in UTF-8. Therefore, it is
- not possible for the extension to get the wrong encoding.
+ [Language Server Protocol][lsp] mandates that this content is transferred in UTF-8. Therefore, it
+ is not possible for the extension to get the wrong encoding.
1. When scripts are executed directly in the Integrated Console, they're read from the file by PowerShell directly. If PowerShell's encoding differs from VS Code's, something can go wrong here. 1. When a script that is open in VS Code references another script that is not open in VS Code, the extension falls back to loading that script's content from the file system. The PowerShell
- extension defaults to UTF-8 encoding, but uses [byte-order mark][], or BOM, detection to select
- the correct encoding.
+ extension defaults to UTF-8 encoding, but uses [byte-order mark][bom], or BOM, detection to
+ select the correct encoding.
-The problem occurs when assuming the encoding of BOM-less formats (like [UTF-8][] with no BOM and
-[Windows-1252][]). The PowerShell extension defaults to UTF-8. The extension cannot change VS Code's
-encoding settings. For more information, see
+The problem occurs when assuming the encoding of BOM-less formats (like [UTF-8][utf8] with no BOM
+and [Windows-1252][win1252]). The PowerShell extension defaults to UTF-8. The extension cannot
+change VS Code's encoding settings. For more information, see
[issue #824](https://github.com/Microsoft/VSCode/issues/824). ## Choosing the right encoding
encoding settings. For more information, see
Different systems and applications can use different encodings: - In .NET Standard, on the web, and in the Linux world, UTF-8 is now the dominant encoding.-- Many .NET Framework applications use [UTF-16][]. For historical reasons, this is sometimes called
+- Many .NET Framework applications use [UTF-16][utf16]. For historical reasons, this is sometimes called
"Unicode", a term that now refers to a broad [standard](https://en.wikipedia.org/wiki/Unicode) that includes both UTF-8 and UTF-16. - On Windows, many native applications that predate Unicode continue to use Windows-1252 by default.
leading to artifacts in text manipulated with those applications.
VS Code's default encoding is UTF-8 without BOM.
-To set [VS Code's encoding][], go to the VS Code settings (<kbd>Ctrl</kbd>+<kbd>,</kbd>) and set the
-`"files.encoding"` setting:
+To set [VS Code's encoding][vsencode], go to the VS Code settings (<kbd>Ctrl</kbd>+<kbd>,</kbd>) and
+set the `"files.encoding"` setting:
```json "files.encoding": "utf8bom"
field. For example:
} ```
-You may also want to consider installing the [Gremlins tracker][] for Visual Studio Code. This
-extension reveals certain Unicode characters that easily corrupted because they are invisible or
-look like other normal characters.
+You may also want to consider installing the [Gremlins tracker][gremlins] for Visual Studio Code.
+This extension reveals certain Unicode characters that easily corrupted because they are invisible
+or look like other normal characters.
## Configuring PowerShell PowerShell's default encoding varies depending on version: - In PowerShell 6+, the default encoding is UTF-8 without BOM on all platforms.-- In Windows PowerShell, the default encoding is usually Windows-1252, an extension of [latin-1][],
- also known as ISO 8859-1.
+- In Windows PowerShell, the default encoding is usually Windows-1252, an extension of
+ [latin-1][latin1], also known as ISO 8859-1.
In PowerShell 5+ you can find your default encoding with this:
save scripts in a Unicode format with a BOM.
Scripts already on the file system may need to be re-encoded to your new chosen encoding. In the bottom bar of VS Code, you'll see the label UTF-8. Click it to open the action bar and select **Save
-with encoding**. You can now pick a new encoding for that file. See [VS Code's encoding][] for full
-instructions.
+with encoding**. You can now pick a new encoding for that file. See [VS Code's encoding][vsencode]
+for full instructions.
If you need to re-encode multiple files, you can use the following script:
read:
[@mklement0]: https://github.com/mklement0 [@rkeithhill]: https://github.com/rkeithhill
-[Windows-1252]: https://wikipedia.org/wiki/Windows-1252
-[latin-1]: https://wikipedia.org/wiki/ISO/IEC_8859-1
-[UTF-8]: https://wikipedia.org/wiki/UTF-8
-[byte-order mark]: https://wikipedia.org/wiki/Byte_order_mark
-[UTF-16]: https://wikipedia.org/wiki/UTF-16
-[Language Server Protocol]: https://microsoft.github.io/language-server-protocol/
-[VS Code's encoding]: https://code.visualstudio.com/docs/editor/codebasics#_file-encoding-support
-[Gremlins tracker]: https://marketplace.visualstudio.com/items?itemName=nhoizey.gremlins
+[win1252]: https://wikipedia.org/wiki/Windows-1252
+[latin1]: https://wikipedia.org/wiki/ISO/IEC_8859-1
+[utf8]: https://wikipedia.org/wiki/UTF-8
+[bom]: https://wikipedia.org/wiki/Byte_order_mark
+[utf16]: https://wikipedia.org/wiki/UTF-16
+[lsp]: https://microsoft.github.io/language-server-protocol/
+[vsencode]: https://code.visualstudio.com/docs/editor/codebasics#_file-encoding-support
+[gremlins]: https://marketplace.visualstudio.com/items?itemName=nhoizey.gremlins
dev-cross-plat Using Vscode For Debugging Compiled Cmdlets https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/vscode/using-vscode-for-debugging-compiled-cmdlets.md
using Visual Studio Code (VS Code) and the C# extension.
Some familiarity with the Visual Studio Code debugger is assumed. - For a general introduction to the VS Code debugger, see
- [Debugging in Visual Studio Code][].
+ [Debugging in Visual Studio Code][vsdebug].
- For examples of debugging PowerShell script files and modules, see
- [Using Visual Studio Code for remote editing and debugging][].
+ [Using Visual Studio Code for remote editing and debugging][using-vscode].
-This guide assumes you have read and followed the instructions in the [Writing Portable Modules][]
+This guide assumes you have read and followed the instructions in the [Writing Portable Modules][writing]
guide. ## Creating a build task
your source code.
### Configuring launch.json for PowerShell Core
-1. Install the [C# for Visual Studio Code][] extension
+1. Install the [C# for Visual Studio Code][csext] extension
1. In the Debug pane, add a debug configuration
your source code.
The `program` field is used to launch `pwsh` so that the cmdlet being debugged can be run. The `-NoExit` argument prevents the PowerShell session from exiting as soon as the module is imported. The path in the `Import-Module` argument is the default build output path when you've followed the
-[Writing Portable Modules][] guide. If you've created a module manifest (`.psd1` file), you should
-use the path to that instead. The `/` path separator works on Windows, Linux, and macOS. You must
-use the integrated terminal to run the PowerShell commands you want to debug.
+[Writing Portable Modules][writing] guide. If you've created a module manifest (`.psd1` file), you
+should use the path to that instead. The `/` path separator works on Windows, Linux, and macOS. You
+must use the integrated terminal to run the PowerShell commands you want to debug.
> [!NOTE] > If the debugger doesn't stop at any breakpoints, look in the Visual Studio Code Debug Console for a line that says:
To end debugging, click **Stop** in the debug toolbar or press <kbd>Shift</kbd>-
shell used for debugging exits and releases the lock on the compiled DLL file. <!-- reference links -->
-[Debugging in Visual Studio Code]: https://code.visualstudio.com/docs/editor/debugging
-[Using Visual Studio Code for remote editing and debugging]: using-vscode-for-remote-editing-and-debugging.md
-[Writing Portable Modules]: ../writing-portable-modules.md
-[C# for Visual Studio Code]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp
+[vsdebug]: https://code.visualstudio.com/docs/editor/debugging
+[using-vscode]: using-vscode-for-remote-editing-and-debugging.md
+[writing]: ../writing-portable-modules.md
+[csext]: https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp
dev-cross-plat Using Vscode https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/vscode/using-vscode.md
It supports the following PowerShell versions:
- Windows PowerShell 5.1 (Windows-only) > [!NOTE]
-> Visual Studio Code is not the same as [Visual Studio][].
+> Visual Studio Code is not the same as [Visual Studio][vsent].
## Getting started
Import-Module $HOME\.vscode\extensions\ms-vscode.powershell*\modules\PowerShellE
You're prompted with **Do you want to run software from this untrusted publisher?** Type `A` to run the file. Then, open Visual Studio Code and check that the PowerShell extension is functioning
-properly. If you still have problems getting started, let us know on [GitHub issues][].
+properly. If you still have problems getting started, let us know on [GitHub issues][ghi].
> [!NOTE] > The PowerShell extension for Visual Studio Code does not support running in constrained language
If you're interested in contributing, Pull Requests are greatly appreciated. Fol
[pscdn]: /archive/blogs/cdndevs/visual-studio-code-powershell-extension <!-- issues -->
-[GitHub issues]: https://github.com/PowerShell/vscode-powershell/issues
+[ghi]: https://github.com/PowerShell/vscode-powershell/issues
[i1310]: https://github.com/PowerShell/vscode-powershell/issues/1310 [i606]: https://github.com/PowerShell/vscode-powershell/issues/606 <!-- product links -->
-[Visual Studio]: https://visualstudio.microsoft.com/
+[vsent]: https://visualstudio.microsoft.com/
[vscode]: https://code.visualstudio.com/ [psext]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell [vsc-settings]: https://code.visualstudio.com/docs/getstarted/settings
developer Adding Non Terminating Error Reporting To Your Cmdlet https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/developer/cmdlet/adding-non-terminating-error-reporting-to-your-cmdlet.md
description: Adding Non-Terminating Error Reporting to Your Cmdlet
# Adding Non-Terminating Error Reporting to Your Cmdlet Cmdlets can report nonterminating errors by calling the
-[System.Management.Automation.Cmdlet.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.
+[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.
For nonterminating errors (as well as terminating errors), the cmdlet must pass an
-[System.Management.Automation.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
-[System.Management.Automation.ErrorCategory][] enumeration. The user can view errors based on their
-category by setting the `$ErrorView` variable to "CategoryView".
+[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
+[System.Management.Automation.ErrorCategory][ErrorCategory] enumeration. The user can view errors
+based on their category by setting the `$ErrorView` variable to "CategoryView".
For more information about error records, see [Windows PowerShell Error Records](./windows-powershell-error-records.md).
End Property
## Overriding Input Processing Methods All cmdlets must override at least one of the input processing methods provided by the
-[System.Management.Automation.Cmdlet][] class. These methods are discussed in
+[System.Management.Automation.Cmdlet][Cmdlet] class. These methods are discussed in
[Creating Your First Cmdlet](creating-a-cmdlet-without-parameters.md). > [!NOTE] > Your cmdlet should handle each record as independently as possible.
-This Get-Proc cmdlet overrides the [System.Management.Automation.Cmdlet.ProcessRecord][] method to
-handle the **Name** parameter for input provided by the user or a script. This method will get the
-processes for each requested process name or all processes if no name is provided. Details of this
-override are given in [Creating Your First Cmdlet](creating-a-cmdlet-without-parameters.md).
+This Get-Proc cmdlet overrides the
+[System.Management.Automation.Cmdlet.ProcessRecord][ProcessRecord] method to handle the **Name**
+parameter for input provided by the user or a script. This method will get the processes for each
+requested process name or all processes if no name is provided. Details of this override are given
+in [Creating Your First Cmdlet](creating-a-cmdlet-without-parameters.md).
### Things to Remember When Reporting Errors
-The [System.Management.Automation.ErrorRecord][] object that the cmdlet passes when writing an error
-requires an exception at its core. Follow the .NET guidelines when determining the exception to use.
-Basically, if the error is semantically the same as an existing exception, the cmdlet should use or
-derive from that exception. Otherwise, it should derive a new exception or exception hierarchy
-directly from the [System.Exception][] class.
+The [System.Management.Automation.ErrorRecord][ErrorRecord] object that the cmdlet passes when
+writing an error requires an exception at its core. Follow the .NET guidelines when determining the
+exception to use. Basically, if the error is semantically the same as an existing exception, the
+cmdlet should use or derive from that exception. Otherwise, it should derive a new exception or
+exception hierarchy directly from the [System.Exception][Exception] class.
When creating error identifiers (accessed through the FullyQualifiedErrorId property of the ErrorRecord class) keep the following in mind.
Unhandled exceptions are not caught by PowerShell in the following conditions:
## Reporting Nonterminating Errors Any one of the input processing methods can report a nonterminating error to the output stream using
-the [System.Management.Automation.Cmdlet.WriteError][] method.
+the [System.Management.Automation.Cmdlet.WriteError][WriteError] method.
Here is a code example from this Get-Proc cmdlet that illustrates the call to
-[System.Management.Automation.Cmdlet.WriteError][] from within the override of the
-[System.Management.Automation.Cmdlet.ProcessRecord][] method. In this case, the call is made if the
-cmdlet cannot find a process for a specified process identifier.
+[System.Management.Automation.Cmdlet.WriteError][WriteError] from within the override of the
+[System.Management.Automation.Cmdlet.ProcessRecord][ProcessRecord] method. In this case, the call is
+made if the cmdlet cannot find a process for a specified process identifier.
```csharp protected override void ProcessRecord()
input object.
A cmdlet frequently needs to modify the PowerShell action produced by a nonterminating 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][],
-you can also directly influence the action by setting the `$ErrorActionPreference` variable.
+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 is not affected by the setting of `ErrorAction`. Failures can be appended to an existing error
line. Let's test the sample Get-Proc cmdlet to see whether it reports an error:
[Cmdlet Samples](./cmdlet-samples.md)
-[System.Exception]: /dotnet/api/System.Exception
-[System.Management.Automation.ActionPreference]: /dotnet/api/System.Management.Automation.ActionPreference
-[System.Management.Automation.Cmdlet.ProcessRecord]: /dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord
-[System.Management.Automation.Cmdlet.WriteError]: /dotnet/api/System.Management.Automation.Cmdlet.WriteError
-[System.Management.Automation.Cmdlet]: /dotnet/api/System.Management.Automation.Cmdlet
-[System.Management.Automation.ErrorCategory]: /dotnet/api/System.Management.Automation.ErrorCategory
-[System.Management.Automation.ErrorRecord]: /dotnet/api/System.Management.Automation.ErrorRecord
+[Exception]: /dotnet/api/System.Exception
+[ActionPreference]: /dotnet/api/System.Management.Automation.ActionPreference
+[ProcessRecord]: /dotnet/api/System.Management.Automation.Cmdlet.ProcessRecord
+[WriteError]: /dotnet/api/System.Management.Automation.Cmdlet.WriteError
+[Cmdlet]: /dotnet/api/System.Management.Automation.Cmdlet
+[ErrorCategory]: /dotnet/api/System.Management.Automation.ErrorCategory
+[ErrorRecord]: /dotnet/api/System.Management.Automation.ErrorRecord
developer Validatecount Attribute Declaration https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/developer/cmdlet/validatecount-attribute-declaration.md
The ValidateCount attribute specifies the minimum and maximum number of argument
#### Parameters
-`MinLength` ([System.Int32][])
+`MinLength` ([System.Int32][Int32])
Required. Specifies the minimum number of arguments.
-`MaxLength`([System.Int32][])
+`MaxLength`([System.Int32][Int32])
Required. Specifies the maximum number of arguments. ## Remarks -- For more information about how to declare this attribute, see [How to Validate an Argument Count][].--- When this attribute is not invoked, the corresponding cmdlet parameter can have any number of arguments.-
+- For more information about how to declare this attribute, see
+ [How to Validate an Argument Count][howto].
+- When this attribute is not invoked, the corresponding cmdlet parameter can have any number of
+ arguments.
- The Windows PowerShell runtime throws an error under the following conditions:-
- - The `MinLength` and `MaxLength` attribute parameters are not of type [System.Int32][].
-
- - The value of the `MaxLength` attribute parameter is less than the value of the `MinLength` attribute parameter.
--- The ValidateCount attribute is defined by the [System.Management.Automation.ValidateCountAttribute][] class.
+ - The `MinLength` and `MaxLength` attribute parameters are not of type [System.Int32][Int32].
+ - The value of the `MaxLength` attribute parameter is less than the value of the `MinLength`
+ attribute parameter.
+- The ValidateCount attribute is defined by the
+ [System.Management.Automation.ValidateCountAttribute][ValidateCountAttribute] class.
## See Also
-[System.Management.Automation.ValidateCountAttribute][]
-
-[How to Validate an Argument Count][]
+[System.Management.Automation.ValidateCountAttribute][ValidateCountAttribute]
-[Writing a Windows PowerShell Cmdlet][]
+[How to Validate an Argument Count][howto]
-[How to Validate an Argument Count]: how-to-validate-an-argument-count.md
-[Writing a Windows PowerShell Cmdlet]: writing-a-windows-powershell-cmdlet.md
+[Writing a Windows PowerShell Cmdlet][writing]
-[System.Int32]: /dotnet/api/System.Int32
-[System.Management.Automation.ValidateCountAttribute]: /dotnet/api/System.Management.Automation.ValidateCountAttribute
+[howto]: how-to-validate-an-argument-count.md
+[writing]: writing-a-windows-powershell-cmdlet.md
+[Int32]: /dotnet/api/System.Int32
+[ValidateCountAttribute]: /dotnet/api/System.Management.Automation.ValidateCountAttribute
developer Installing A Powershell Module https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/developer/module/installing-a-powershell-module.md
pasting the files with Windows Explorer onto a single remote computer; however,
you may wish to use a more sophisticated installation process. Regardless of how you get your module onto the system, PowerShell can use a number of techniques that will let users find and use your modules. Therefore, the main issue for installation is ensuring that PowerShell will be able to find
-your module. For more information, see [Importing a PowerShell Module](./importing-a-powershell-module.md).
+your module. For more information, see
+[Importing a PowerShell Module](./importing-a-powershell-module.md).
## Rules for Installing Modules
use, modules that you get from other parties, and modules that you distribute to
Whenever possible, install all modules in a path that is listed in the **PSModulePath** environment variable or add the module path to the **PSModulePath** environment variable value.
-The **PSModulePath** environment variable ($Env:PSModulePath) contains the locations of Windows
+The **PSModulePath** environment variable (`$Env:PSModulePath`) contains the locations of Windows
PowerShell modules. Cmdlets rely on the value of this environment variable to find modules. By default, the **PSModulePath** environment variable value contains the following system and user module directories, but you can add to and edit the value. -- `$PSHome\Modules` (%Windir%\System32\WindowsPowerShell\v1.0\Modules)
+- `$PSHome\Modules` (`%Windir%\System32\WindowsPowerShell\v1.0\Modules`)
> [!WARNING] > This location is reserved for modules that ship with Windows. Do not install modules to this > location. -- `$Home\Documents\WindowsPowerShell\Modules` (%UserProfile%\Documents\WindowsPowerShell\Modules)
+- `$Home\Documents\WindowsPowerShell\Modules` (`%UserProfile%\Documents\WindowsPowerShell\Modules`)
-- `$Env:ProgramFiles\WindowsPowerShell\Modules` (%ProgramFiles%\WindowsPowerShell\Modules)
+- `$Env:ProgramFiles\WindowsPowerShell\Modules` (`%ProgramFiles%\WindowsPowerShell\Modules`)
To get the value of the **PSModulePath** environment variable, use either of the following commands.
module directories, but you can add to and edit the value.
#Add the paths in $p to the PSModulePath value. [Environment]::SetEnvironmentVariable("PSModulePath",$p)- ``` > [!IMPORTANT]
C:\Program Files
Fabrikam Fabrikam.psd1 (module manifest) Fabrikam.dll (module assembly)- ``` ### Effect of Incorrect Installation
following, do not work.
- The Module Auto-Loading feature cannot import the module automatically. -- The `ListAvailable` parameter of the [Get-Module](/powershell/module/Microsoft.PowerShell.Core/Get-Module)
- cmdlet cannot find the module.
+- The `ListAvailable` parameter of the
+ [Get-Module](/powershell/module/Microsoft.PowerShell.Core/Get-Module) cmdlet cannot find the
+ module.
- The [Import-Module](/powershell/module/Microsoft.PowerShell.Core/Import-Module) cmdlet cannot find the module. To import the module, you must provide the full path to the root module file or module
following, do not work.
- The [Get-Command](/powershell/module/Microsoft.PowerShell.Core/Get-Command) cmdlet cannot find commands in the module. -- The [Update-Help](/powershell/module/Microsoft.PowerShell.Core/Update-Help) and [Save-Help](/powershell/module/Microsoft.PowerShell.Core/Save-Help)
- cmdlets cannot update or save help for the module.
+- The [Update-Help](/powershell/module/Microsoft.PowerShell.Core/Update-Help) and
+ [Save-Help](/powershell/module/Microsoft.PowerShell.Core/Save-Help) cmdlets cannot update or save
+ help for the module.
- The [Show-Command](/powershell/module/Microsoft.PowerShell.Utility/Show-Command) cmdlet cannot find and display the commands in the module.
C:\Program Files
Fabrikam Fabrikam.psd1 (module manifest) Fabrikam.dll (module assembly)- ``` To enable the Windows PowerShell module discovery features to find the Fabrikam module, the Fabrikam
To install multiple versions of the same module, use the following procedure.
1. Create a directory for each version of the module. Include the version number in the directory name.
-2. Create a module manifest for each version of the module. In the value of the **ModuleVersion**
+1. Create a module manifest for each version of the module. In the value of the **ModuleVersion**
key in the manifest, enter the module version number. Save the manifest file (.psd1) in the version-specific directory for the module.
-3. Add the module root folder path to the value of the **PSModulePath** environment variable, as
+1. Add the module root folder path to the value of the **PSModulePath** environment variable, as
shown in the following examples. To import a particular version of the module, the end-user can use the `MinimumVersion` or
-`RequiredVersion` parameters of the [Import-Module](/powershell/module/Microsoft.PowerShell.Core/Import-Module)
-cmdlet.
+`RequiredVersion` parameters of the
+[Import-Module](/powershell/module/Microsoft.PowerShell.Core/Import-Module) cmdlet.
For example, if the Fabrikam module is available in versions 8.0 and 9.0, the Fabrikam module directory structure might resemble the following.
Users can use the **Prefix** parameter of the `Import-Module` cmdlet to use an a
value of the **Prefix** parameter takes precedence over the value of the **DefaultCommandPrefix** key.
+## Supporting paths on non-Windows systems
+
+Non-Windows platforms use the colon (`:`) character as a path separator and a forward-slash (`/`)
+character as a directory separator. The `[System.IO.Path]` class has static members that can be
+used to make your code work on any platform:
+
+- `[System.IO.Path]::PathSeparator` - returns the character used to separate paths in a PATH
+ environment variable for the host platform
+- `[System.IO.Path]::DirectorySeparatorChar` - returns the character used to separate directory
+ names with a path for the host platform
+
+Use these static properties to in place of the `;` and `\` characters when you are constructing path
+strings.
+ ## See Also [about_Command_Precedence](/powershell/module/microsoft.powershell.core/about/about_command_precedence)
dsc Msft Dsclocalconfigurationmanager https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dsc/reference/mof-classes/msft-dsclocalconfigurationmanager.md
class MSFT_DSCLocalConfigurationManager
The **MSFT_DSCLocalConfigurationManager** class has the following members: -- [Methods][]
+- Methods
### Methods
gallery Module Psedition Support https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/concepts/module-psedition-support.md
feature sets and platform compatibility.
Windows PowerShell 5.1 on reduced footprint Windows Editions such as Windows IoT and Windows Nanoserver.
-For more information on PowerShell editions, see [about_PowerShell_Editions][].
+For more information on PowerShell editions, see
+[about_PowerShell_Editions][about_PowerShell_Editions].
## Declaring compatible editions
Module contents
[Update module manifest](/powershell/module/powershellget/update-modulemanifest)
-[about_PowerShell_Editions][]
+[about_PowerShell_Editions][about_PowerShell_Editions]
[about_PowerShell_Editions]: /powershell/module/Microsoft.PowerShell.Core/About/about_PowerShell_Editions
gallery Getting Started https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/getting-started.md
Gallery. You do not need to sign in to download items from the PowerShell Galler
You can find packages in the PowerShell Gallery by using the **Search** control on the PowerShell Gallery's [home page](https://www.powershellgallery.com), or by browsing through the Modules and Scripts from the [Packages page](https://www.powershellgallery.com/packages). You can also find
-packages from the PowerShell Gallery by running the [Find-Module][], [Find-DscResource], and
-[Find-Script][] cmdlets, depending on the package type, with `-Repository PSGallery`.
+packages from the PowerShell Gallery by running the [Find-Module][Find-Module],
+[Find-DscResource][Find-DscResource], and [Find-Script][Find-Script] cmdlets, depending on the
+package type, with `-Repository PSGallery`.
You can filter results from the Gallery by using the following parameters:
You can filter results from the Gallery by using the following parameters:
- Filter If you're only interested in discovering specific DSC resources in the Gallery, you can run the
-[Find-DscResource][] cmdlet. Find-DscResource returns data on DSC resources contained in the
-Gallery. Because DSC resources are always delivered as part of a module, you still need to run
-[Install-Module][] to install those DSC resources.
+[Find-DscResource][Find-DscResource] cmdlet. Find-DscResource returns data on DSC resources
+contained in the Gallery. Because DSC resources are always delivered as part of a module, you still
+need to run [Install-Module][Install-Module] to install those DSC resources.
## Learning about packages in the PowerShell Gallery
account used to publish the package, and is more trustworthy than the Author fie
If you discover a package that you feel is not published in good faith, click **Report Abuse** on that package's page.
-If you're running [Find-Module][] or [Find-Script][], you can view this data in the returned
-PSGetModuleInfo object. For example, running
+If you're running [Find-Module][Find-Module] or [Find-Script][Find-Script], you can view this data
+in the returned PSGetModuleInfo object. For example, running
`Find-Module -Name PSReadLine -Repository PSGallery |Get-Member` returns data on the PSReadLine module in the Gallery.
We encourage the following process when downloading packages from the PowerShell
### Inspect
-To download a package from the Gallery for inspection, run either the [Save-Module][] or
-[Save-Script][] cmdlet, depending on the package type. This lets you save the package locally
-without installing it, and inspect the package contents. Remember to delete the saved package
-manually.
+To download a package from the Gallery for inspection, run either the [Save-Module][Save-Module] or
+[Save-Script][Save-Script] cmdlet, depending on the package type. This lets you save the package
+locally without installing it, and inspect the package contents. Remember to delete the saved
+package manually.
Some of these packages are authored by Microsoft, and others are authored by the PowerShell community. Microsoft recommends that you review the contents and code of packages on this gallery
that package's page.
### Install
-To install a package from the Gallery for use, run either the [Install-Module][] or
-[Install-Script][] cmdlet, depending on the package type.
+To install a package from the Gallery for use, run either the [Install-Module][Install-Module] or
+[Install-Script][Install-Script] cmdlet, depending on the package type.
-[Install-Module][] installs the module to `$env:ProgramFiles\WindowsPowerShell\Modules` by default.
-This requires an administrator account. If you add the `-Scope CurrentUser` parameter, the module is
-installed to `$env:USERPROFILE\Documents\WindowsPowerShell\Modules` .
+[Install-Module][Install-Module] installs the module to
+`$env:ProgramFiles\WindowsPowerShell\Modules` by default. This requires an administrator account. If
+you add the `-Scope CurrentUser` parameter, the module is installed to
+`$env:USERPROFILE\Documents\WindowsPowerShell\Modules` .
-[Install-Script][] installs the script to `$env:ProgramFiles\WindowsPowerShell\Scripts` by default.
-This requires an administrator account. If you add the `-Scope CurrentUser` parameter, the script is
-installed to `$env:USERPROFILE\Documents\WindowsPowerShell\Scripts` .
+[Install-Script][Install-Script] installs the script to
+`$env:ProgramFiles\WindowsPowerShell\Scripts` by default. This requires an administrator account. If
+you add the `-Scope CurrentUser` parameter, the script is installed to
+`$env:USERPROFILE\Documents\WindowsPowerShell\Scripts` .
-By default, [Install-Module][] and [Install-Script][] installs the most current version of a
-package. To install an older version of the package, add the `-RequiredVersion` parameter.
+By default, [Install-Module][Install-Module] and [Install-Script][Install-Script] installs the most
+current version of a package. To install an older version of the package, add the `-RequiredVersion`
+parameter.
### Deploy
To learn more about Azure Automation, see the [Azure Automation](/azure/automati
## Updating packages from the PowerShell Gallery
-To update packages installed from the PowerShell Gallery, run either the [Update-Module][] or
-[Update-Script][] cmdlet. When run without any additional parameters, [Update-Module][] attempts to
-update all modules installed by running [Install-Module][]. To selectively update modules, add the
-`-Name` parameter.
+To update packages installed from the PowerShell Gallery, run either the
+[Update-Module][Update-Module] or [Update-Script][Update-Script] cmdlet. When run without any
+additional parameters, [Update-Module][Update-Module] attempts to update all modules installed by
+running [Install-Module][Install-Module]. To selectively update modules, add the `-Name` parameter.
-Similarly, when run without any additional parameters, [Update-Script][] also attempts to update all
-scripts installed by running [Install-Script][]. To selectively update scripts, add the `-Name`
-parameter.
+Similarly, when run without any additional parameters, [Update-Script][Update-Script] also attempts
+to update all scripts installed by running [Install-Script][Install-Script]. To selectively update
+scripts, add the `-Name` parameter.
## List packages that you have installed from the PowerShell Gallery To find out which modules you have installed from the PowerShell Gallery, run the
-[Get-InstalledModule][] cmdlet. This command lists all of the modules you have on your system that
-were installed directly from the PowerShell Gallery.
+[Get-InstalledModule][Get-InstalledModule] cmdlet. This command lists all of the modules you have on
+your system that were installed directly from the PowerShell Gallery.
Similarly, to find out which scripts you have installed from the PowerShell Gallery, run the
-[Get-InstalledScript][] cmdlet. This command lists all the scripts you have on your system that were
-installed directly from the PowerShell Gallery.
+[Get-InstalledScript][Get-InstalledScript] cmdlet. This command lists all the scripts you have on
+your system that were installed directly from the PowerShell Gallery.
## Network access to the PowerShell Gallery
gallery Working With Local Psrepositories https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/gallery/how-to/working-with-local-psrepositories.md
These cmdlets enable the following scenarios:
- Deliver PowerShell scripts and modules only available to your organization This article describes how to set up a local PowerShell repository. The article also covers the
-[OfflinePowerShellGetDeploy][] module available from the PowerShell Gallery. This module contains
-cmdlets to install the latest version of PowerShellGet into your local repository.
+[OfflinePowerShellGetDeploy][OfflinePowerShellGetDeploy] module available from the PowerShell
+Gallery. This module contains cmdlets to install the latest version of PowerShellGet into your local
+repository.
## Local repository types
servers or file shares.
The following article lists the steps for setting up your own NuGet Server. -- [NuGet.Server][]
+- [NuGet.Server][nugetsrv]
Follow the steps up to the point of adding packages. The steps for [publishing a package](#publishing-to-a-local-repository) are covered later in this article.
Save-Package -Name 'PackageName' -Provider NuGet -Source https://www.powershellg
If your local PSRepository is web-based, it requires an additional step that uses nuget.exe to publish.
-See the documentation for using [nuget.exe][].
+See the documentation for using [nuget.exe][nuget].
## Installing PowerShellGet on a disconnected system
repository. For more information and instructions, see the [Azure Artifacts docu
<!-- external links --> [OfflinePowerShellGetDeploy]: https://www.powershellgallery.com/packages/OfflinePowerShellGetDeploy/0.1.1
-[Nuget.Server]: /nuget/hosting-packages/nuget-server
-[nuget.exe]: /nuget/tools/nuget-exe-cli-reference
+[nugetsrv]: /nuget/hosting-packages/nuget-server
+[nuget]: /nuget/tools/nuget-exe-cli-reference
install Installing Powershell Core On Linux https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/install/Installing-PowerShell-Core-on-Linux.md
Last updated 02/02/2021
--- # Installing PowerShell on Linux
-All packages are available on our GitHub [releases][] page. After the package is installed, run
+All packages are available on our GitHub [releases][releases] page. After the package is installed, run
`pwsh` from a terminal. Run `pwsh-preview` if you installed a [Preview release](#installing-preview-releases).
PowerShell with `sudo apt-get install powershell`.
### Installation via Direct Download - Ubuntu 16.04
-Download the Debian package `powershell_7.1.3-1.ubuntu.16.04_amd64.deb` from the [releases][] page
-onto the Ubuntu machine.
+Download the Debian package `powershell_7.1.3-1.ubuntu.16.04_amd64.deb` from the
+[releases][releases] page onto the Ubuntu machine.
Then, in the terminal, execute the following commands:
PowerShell with `sudo apt-get install powershell`.
### Installation via Direct Download - Ubuntu 18.04
-Download the Debian package `powershell_7.1.3-1.ubuntu.18.04_amd64.deb` from the [releases][] page
+Download the Debian package `powershell_7.1.3-1.ubuntu.18.04_amd64.deb` from the [releases][releases] page
onto the Ubuntu machine. Then, in the terminal, execute the following commands:
PowerShell with `sudo apt-get install powershell`.
### Installation via Direct Download - Ubuntu 20.04
-Download the Debian package `powershell_7.1.3-1.ubuntu.20.04_amd64.deb` from the [releases][] page
+Download the Debian package `powershell_7.1.3-1.ubuntu.20.04_amd64.deb` from the [releases][releases] page
onto the Ubuntu machine. Then, in the terminal, execute the following commands:
with `sudo apt-get install powershell`.
### Installation via Direct Download - Debian 9
-Download the Debian package `powershell_7.1.3-1.debian.9_amd64.deb` from the [releases][] page
+Download the Debian package `powershell_7.1.3-1.debian.9_amd64.deb` from the [releases][releases] page
onto the Debian machine. Then, in the terminal, execute the following commands:
pwsh
### Installation via Direct Download - Debian 10
-Download the tar.gz package `powershell-7.1.3-linux-x64.tar.gz` from the [releases][] page
+Download the tar.gz package `powershell-7.1.3-linux-x64.tar.gz` from the [releases][releases] page
onto the Debian machine. Then, in the terminal, execute the following commands:
pwsh
### Installation via Direct Download - Alpine 3.9 and 3.10
-Download the tar.gz package `powershell-7.1.3-linux-alpine-x64.tar.gz` from the [releases][] page onto
+Download the tar.gz package `powershell-7.1.3-linux-alpine-x64.tar.gz` from the [releases][releases] page onto
the Alpine machine. Then, in the terminal, execute the following commands:
with `sudo yum update powershell`.
### Installation via Direct Download - CentOS 7
-Using [CentOS 7][], download the RPM package `powershell-7.1.3-1.rhel.7.x86_64.rpm` from the [releases][]
-page onto the CentOS machine.
+Using [CentOS 7][centos7], download the RPM package `powershell-7.1.3-1.rhel.7.x86_64.rpm` from the
+[releases][releases] page onto the CentOS machine.
Then, in the terminal, execute the following commands:
sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v7.1
sudo yum remove powershell ```
-[CentOS 7]: https://www.centos.org/download/
+[centos7]: https://www.centos.org/download/
## Red Hat Enterprise Linux (RHEL) 7
with `sudo yum update powershell`.
### Installation via Direct Download - Red Hat Enterprise Linux (RHEL) 7
-Download the RPM package `powershell-7.1.3-1.rhel.7.x86_64.rpm` from the [releases][] page onto
+Download the RPM package `powershell-7.1.3-1.rhel.7.x86_64.rpm` from the [releases][releases] page onto
the Red Hat Enterprise Linux machine. Then, in the terminal, execute the following commands:
pwsh
### Installation via Direct Download - Fedora 28, 29, and 30
-Download the RPM package `powershell-7.1.3-1.rhel.7.x86_64.rpm` from the [releases][] page onto the
-Fedora machine.
+Download the RPM package `powershell-7.1.3-1.rhel.7.x86_64.rpm` from the [releases][releases] page
+onto the Fedora machine.
Then, in the terminal, execute the following commands:
sudo dnf remove powershell
> [!NOTE] > Arch support is not officially supported by Microsoft and is maintained by the community.
-PowerShell is available from the [Arch Linux][] User Repository (AUR).
+PowerShell is available from the [Arch Linux][arch] User Repository (AUR).
- It can be compiled with the [latest tagged release][arch-release] - It can be compiled from the [latest commit to master][arch-git]
For more information on installing packages from the AUR, see the
[Arch Linux wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages) or [Using PowerShell in Docker](powershell-in-docker.md).
-[Arch Linux]: https://www.archlinux.org/download/
+[arch]: https://www.archlinux.org/download/
[arch-release]: https://aur.archlinux.org/packages/powershell/ [arch-git]: https://aur.archlinux.org/packages/powershell-git/ [arch-bin]: https://aur.archlinux.org/packages/powershell-bin/
support those methods.
[releases]: https://aka.ms/PowerShell-Release?tag=stable [xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html [distros]: https://github.com/dotnet/core/blob/master/release-notes/3.0/3.0-supported-os.md#linux
-[Distribution Support Request]: https://github.com/PowerShell/PowerShell/issues/new?assignees=&labels=Distribution-Request&template=Distribution_Request.md&title=Distribution+Support+Request
install Installing Powershell Core On Windows https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/install/Installing-PowerShell-Core-on-Windows.md
To enable PowerShell remoting over WSMan, the following prerequisites need to be
## Download the installer package
-To install PowerShell on Windows, download the [latest][] install package from GitHub. You can also
-find the latest [preview][] version. Scroll down to the **Assets** section of the Release page. The
-**Assets** section may be collapsed, so you may need to click to expand it.
+To install PowerShell on Windows, download the [latest][latest] install package from GitHub. You can
+also find the latest [preview][preview] version. Scroll down to the **Assets** section of the
+Release page. The **Assets** section may be collapsed, so you may need to click to expand it.
> [!NOTE] > The installation commands in this article are for the latest releases of PowerShell. To install a > different version of PowerShell, adjust the command to match the version you need. To see all
-> PowerShell releases, visit the [releases][] page in the PowerShell repository on GitHub.
+> PowerShell releases, visit the [releases][releases] page in the PowerShell repository on GitHub.
## <a id="msi" />Installing the MSI package
values are changed for each major release.
## <a id="zip" />Installing the ZIP package PowerShell binary ZIP archives are provided to enable advanced deployment scenarios. Download one of
-the following ZIP archives from the [releases][] page.
+the following ZIP archives from the [releases][releases] page.
- PowerShell-7.1.3-win-x64.zip - PowerShell-7.1.3-win-x86.zip
Windows 10 IoT Core adds Windows PowerShell when you include _IOT_POWERSHELL_ fe
use to deploy PowerShell 7. The steps defined above for Windows 10 IoT Enterprise can be followed for IoT Core as well.
-For adding the latest PowerShell in the shipping image, use [Import-PSCoreRelease][] command to
-include the package in the workarea and add _OPENSRC_POWERSHELL_ feature to your image.
+For adding the latest PowerShell in the shipping image, use
+[Import-PSCoreRelease][Import-PSCoreRelease] command to include the package in the workarea and add
+_OPENSRC_POWERSHELL_ feature to your image.
> [!NOTE] > For ARM64 architecture, Windows PowerShell is not added when you include _IOT_POWERSHELL_. So the
In both cases, you need the Windows 10 x64 ZIP release package. Run the commands
image. 1. Unmount the image and boot it. 1. Connect to the built-in instance of Windows PowerShell.
-1. Follow the instructions to create a remoting endpoint using the ["another instance technique"][].
+1. Follow the instructions to create a remoting endpoint using the
+ ["another instance technique"][instance].
### Online Deployment of PowerShell
Deploy PowerShell to Nano Server using the following steps.
``` - If you want WSMan-based remoting, follow the instructions to create a remoting endpoint using the
- ["another instance technique"][].
+ ["another instance technique"][instance].
## Install as a .NET Global tool
For more information, see
> supported. The package is built for testing purposes during the preview period. To manually install the MSIX package on a Windows 10 client, download the MSIX package from our
-GitHub [releases][] page. Scroll down to the **Assets** section of the Release you want to
+GitHub [releases][releases] page. Scroll down to the **Assets** section of the Release you want to
install. The Assets section may be collapsed, so you may need to click to expand it. The MSIX file looks like this - `PowerShell-<version>-win-<os-arch>.msix`
support those methods.
[wsman-remoting]: ../learn/remoting/WSMan-Remoting-in-PowerShell-Core.md [AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell [winget]: /windows/package-manager/winget
-["another instance technique"]: ../learn/remoting/WSMan-Remoting-in-PowerShell-Core.md#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register
+[instance]: ../learn/remoting/WSMan-Remoting-in-PowerShell-Core.md#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register
[Import-PSCoreRelease]: https://github.com/ms-iot/iot-adk-addonkit/blob/master/Tools/IoTCoreImaging/Docs/Import-PSCoreRelease.md#Import-PSCoreRelease
install Installing Powershell Core On Macos https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/install/Installing-PowerShell-Core-on-macOS.md
Last updated 04/26/2021
# Installing PowerShell on macOS PowerShell 7.0 or higher require macOS 10.13 and higher. All packages are available on our GitHub
-[releases][] page. After the package is installed, run `pwsh` from a terminal.
+[releases][releases] page. After the package is installed, run `pwsh` from a terminal.
> [!NOTE] > PowerShell 7.1 is an in-place upgrade that removes PowerShell Core 6.x and 7.0.
brew upgrade powershell
## Installation via Direct Download
-Download the PKG package `powershell-7.1.3-osx-x64.pkg` from the [releases][] page onto your
+Download the PKG package `powershell-7.1.3-osx-x64.pkg` from the [releases][releases] page onto your
macOS machine. You can double-click the file and follow the prompts, or install it from the terminal:
install Powershell In Docker https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/install/PowerShell-in-Docker.md
docker rmi mcr.microsoft.com/powershell
## Legal and Licensing
-PowerShell is licensed under the [MIT license][].
+PowerShell is licensed under the [MIT license][mit].
### Windows Docker File and Image Licenses
PowerShell from the installed location. The telemetry we collect falls under the
[install]: https://docs.docker.com/engine/installation/ [docker-release]: https://hub.docker.com/r/microsoft/powershell/ [appinsights]: https://azure.microsoft.com/services/application-insights/
-[MIT license]: https://github.com/PowerShell/PowerShell/tree/master/LICENSE.txt
+[mit]: https://github.com/PowerShell/PowerShell/tree/master/LICENSE.txt
[PowerShell-Docker]: https://github.com/PowerShell/PowerShell-Docker [Window Server Core]: https://hub.docker.com/r/microsoft/windowsservercore/ [Nano Server]: https://hub.docker.com/r/microsoft/nanoserver/
lang-spec Chapter 01 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-01.md
another.)
PowerShell includes a very rich scripting language that supports constructs for looping, conditions, flow-control, and variable assignment. This language has syntax features and keywords similar to
-those used in the C# programming language ([§C.][]).
+those used in the C# programming language ([§C.][§C.]).
There are four kinds of commands in PowerShell: scripts, functions and methods, cmdlets, and native commands.
lang-spec Chapter 02 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-02.md
Title: Lexical structure
## 2.1 Grammars This specification shows the syntax of the PowerShell language using two grammars. The *lexical
-grammar* ([§B.1][]) shows how Unicode characters are combined to form line terminators, comments,
-white space, and tokens. The *syntactic grammar* ([§B.2][]) shows how the tokens resulting from the
+grammar* ([§B.1][§B.1]) shows how Unicode characters are combined to form line terminators, comments,
+white space, and tokens. The *syntactic grammar* ([§B.2][§B.2]) shows how the tokens resulting from the
lexical grammar are combined to form PowerShell scripts. For convenience, fragments of these grammars are replicated in appropriate places throughout this
Description:
The presence of *new-line-character*s in the input source stream divides it into lines that can be used for such things as error reporting and the detection of the end of a single-line comment.
-A line terminator can be treated as white space ([§2.2.4][]).
+A line terminator can be treated as white space ([§2.2.4][§2.2.4]).
### 2.2.3 Comments
Description:
Except for the fact that white space may act as a separator for tokens, it is ignored.
-Unlike some popular languages, PowerShell does not consider line-terminator characters ([§2.2.2][])
+Unlike some popular languages, PowerShell does not consider line-terminator characters ([§2.2.2][§2.2.2])
to be white space. However, a line terminator can be treated as white space by preceding it immediately by a backtick character, `` ` `` (U+0060). This is necessary when the contents of a line are complete syntactically, yet the following line contains tokens intended to be associated with
escaped-character:
Description:
-Variables are discussed in detail in (§5). The variable $? is discussed in [§2.3.2.2][]. Scopes are
-discussed in [§3.5][].
+Variables are discussed in detail in (§5). The variable $? is discussed in [§2.3.2.2][§2.3.2.2]. Scopes are
+discussed in [§3.5][§3.5].
The variables `$$` and `$^` are reserved for use in an interactive environment, which is outside the scope of this specification.
${E:\\File.txt}
There is no limit on the length of a variable name, all characters in a variable name are significant, and letter case is *not* distinct.
-There are several different kinds of variables: user-defined ([§2.3.2.1][]), automatic
-([§2.3.2.2][]), and preference ([§2.3.2.3][]). They can all coexist in the same scope ([§3.5][]).
+There are several different kinds of variables: user-defined ([§2.3.2.1][§2.3.2.1]), automatic
+([§2.3.2.2][§2.3.2.2]), and preference ([§2.3.2.3][§2.3.2.3]). They can all coexist in the same scope ([§3.5][§3.5]).
Consider the following function definition and calls:
This is achieved by using `@` instead of `$` as the first character of the varia
This notation can only be used in an argument to a command. Names are partitioned into various namespaces each of which is stored on a virtual drive
-([§3.1][]). For example, variables are stored on `Variable:`, environment variables are stored on
+([§3.1][§3.1]). For example, variables are stored on `Variable:`, environment variables are stored on
`Env:`, functions are stored on `Function:`, and aliases are stored on `Alias:`. All of these names can be accessed as variables using the *variable-namespace* production within *variable-scope*. For example,
matching parameters to arguments is called *parameter binding*.
There are three kinds of argument: -- Switch parameter ([§8.10.5][]) -- This has the form *command-parameter* where
+- Switch parameter ([§8.10.5][§8.10.5]) -- This has the form *command-parameter* where
*first-parameter-char* and *parameter-chars* together make up the switch name, which corresponds to the name of a parameter (without its leading `-`) in the command being invoked. If the trailing colon is omitted, the presence of this argument indicates that the corresponding parameter be set
There are three kinds of argument:
Set-MyProcess -Strict: $true ``` -- Parameter with argument ([§8.10.2][]) -- This has the form *command-parameter* where
+- Parameter with argument ([§8.10.2][§8.10.2]) -- This has the form *command-parameter* where
*first-parameter-char* and *parameter-chars* together make up the parameter name, which corresponds to the name of a parameter (without its leading -) in the command being invoked. There must be no trailing colon. The argument immediately following designates an associated value. For
There are three kinds of argument:
Get-Power -exponent 3 -base 5 ``` -- Positional argument ([§8.10.2][]) - Arguments and their corresponding parameters inside commands
+- Positional argument ([§8.10.2][§8.10.2]) - Arguments and their corresponding parameters inside commands
have positions with the first having position zero. The argument in position 0 is bound to the parameter in position 0; the argument in position 1 is bound to the parameter in position 1; and so on. For example, given a command `Get-Power`, that has parameters `$base` and `$exponent` in
There are three kinds of argument:
Get-Power 5 3 ```
-See [§8.2][] for details of the special parameters `--` and `--%`.
+See [§8.2][§8.2] for details of the special parameters `--` and `--%`.
When a command is invoked, a parameter name may be abbreviated; any distinct leading part of the full name may be used, provided that is unambiguous with respect to the names of the other parameters accepted by the same command.
-For information about parameter binding see [§8.14][].
+For information about parameter binding see [§8.14][§8.14].
### 2.3.5 Literals
literal:
#### 2.3.5.1 Numeric literals
-There are two kinds of numeric literals: integer ([§2.3.5.1.1][]) and real ([§2.3.5.1.2][]). Both
-can have multiplier suffixes ([§2.3.5.1.3][]).
+There are two kinds of numeric literals: integer ([§2.3.5.1.1][§2.3.5.1.1]) and real ([§2.3.5.1.2][§2.3.5.1.2]). Both
+can have multiplier suffixes ([§2.3.5.1.3][§2.3.5.1.3]).
##### 2.3.5.1.1 Integer literals
numeric-multiplier: one of
Description: The type of an integer literal is determined by its value, the presence or absence of
-*long-type-suffix*, and the presence of a *numeric-multiplier* ([§2.3.5.1.3][]).
+*long-type-suffix*, and the presence of a *numeric-multiplier* ([§2.3.5.1.3][§2.3.5.1.3]).
For an integer literal with no *long-type-suffix* -- If its value can be represented by type int ([§4.2.3][]), that is its type;-- Otherwise, if its value can be represented by type long ([§4.2.3][]), that is its type.-- Otherwise, if its value can be represented by type decimal ([§2.3.5.1.2][]), that is its type.-- Otherwise, it is represented by type double ([§2.3.5.1.2][]).
+- If its value can be represented by type int ([§4.2.3][§4.2.3]), that is its type;
+- Otherwise, if its value can be represented by type long ([§4.2.3][§4.2.3]), that is its type.
+- Otherwise, if its value can be represented by type decimal ([§2.3.5.1.2][§2.3.5.1.2]), that is its type.
+- Otherwise, it is represented by type double ([§2.3.5.1.2][§2.3.5.1.2]).
For an integer literal with *long-type-suffix* -- If its value can be represented by type long ([§4.2.3][]), that is its type;
+- If its value can be represented by type long ([§4.2.3][§4.2.3]), that is its type;
- Otherwise, that literal is ill formed. In the twos-complement representation of integer values, there is one more negative value than there
dash:
Description:
-A real literal may contain a *numeric-multiplier* ([§2.3.5.1.3][]).
+A real literal may contain a *numeric-multiplier* ([§2.3.5.1.3][§2.3.5.1.3]).
There are two kinds of real literal: *double* and *decimal*. These are indicated by the absence or presence, respectively, of *decimal-type-suffix*. (There is no such thing as a *float real literal*.)
-A double real literal has type double ([§4.2.4.1][]). A decimal real literal has type decimal
-([§4.2.4.2][]). Trailing zeros in the fraction part of a decimal real literal are significant.
+A double real literal has type double ([§4.2.4.1][§4.2.4.1]). A decimal real literal has type decimal
+([§4.2.4.2][§4.2.4.2]). Trailing zeros in the fraction part of a decimal real literal are significant.
If the value of *exponent-part*'s *decimal-digits* in a double real literal is less than the minimum supported, the value of that double real literal is 0. If the value of *exponent-part*'s
Some examples of decimal real literals are 1d (which has scale 0), 1.20d (which
> [!NOTE] > Although PowerShell does not provide literals for infinities and NaNs, double real literal-like > equivalents can be obtained from the static read-only properties PositiveInfinity,
-> NegativeInfinity, and NaN of the types float and double ([§4.2.4.1][]).
+> NegativeInfinity, and NaN of the types float and double ([§4.2.4.1][§4.2.4.1]).
The grammar permits what starts out as a double real literal to have an `l` or `L` type suffix. Such a token is really an integer literal whose value is represented by type long.
start of the first source line following the opening delimiter, and ends at the
source line preceding the closing delimiter. The body may be empty. The line terminator on the last source line preceding the closing delimiter is not part of that literal's body.
-A literal of any of these kinds has type string ([§4.3.1][]).
+A literal of any of these kinds has type string ([§4.3.1][§4.3.1]).
The character used to delimit a *verbatim-string-literal* or *expandable-string-literal* can be contained in such a string literal by writing that character twice, in succession. For example,
special meaning inside an *expandable-string-literal*, and a *double-quote-chara
meaning inside a *verbatim-string-literal*. An *expandable-string-literal* and an *expandable-here-string-literal* may contain
-*escaped-character*s ([§2.3.7][]). For example, when the following string literal is written to the
+*escaped-character*s ([§2.3.7][§2.3.7]). For example, when the following string literal is written to the
pipeline, the result is as shown below: ```powershell
second line, "Hello", `Q5!
If an *expandable-string-literal* or *expandable-here-string-literal* contains the name of a variable, unless that name is preceded immediately by an escape character, it is replaced by the
-string representation of that variable's value ([§6.7][]). This is known as *variable substitution*.
+string representation of that variable's value ([§6.7][§6.7]). This is known as *variable substitution*.
> [!NOTE] > If the variable name is part of some larger expression, only the variable name is replaced. For
$a[0] is red blue[0], $a[0] is red
*expandable-string-literal*s and *expandable-here-string-literal*s also support a kind of substitution called *sub-expression expansion*, by treating text of the form `$( ... )` as a
-*sub-expression* ([§7.1.6][]). Such text is replaced by the string representation of that
-expression's value ([§6.8][]). Any white space used to separate tokens within *sub-expression*'s
+*sub-expression* ([§7.1.6][§7.1.6]). Such text is replaced by the string representation of that
+expression's value ([§6.8][§6.8]). Any white space used to separate tokens within *sub-expression*'s
*statement-list* is ignored as far as the result string's construction is concerned. The examples,
body. The resulting literal is equivalent to:
> [!NOTE] > To aid readability of source, long string literals can be broken across multiple source lines > without line terminators being inserted. This is done by writing each part as a separate literal
-> and concatenating the parts with the + operator ([§7.7.2][]). This operator allows its operands to
+> and concatenating the parts with the + operator ([§7.7.2][§7.7.2]). This operator allows its operands to
> designate any of the four kinds of string literal. > [!NOTE]
within the body is represented exactly as it was provided.
#### 2.3.5.3 Null literal
-See the automatic variable `$null` ([§2.3.2.2][]).
+See the automatic variable `$null` ([§2.3.2.2][§2.3.2.2]).
#### 2.3.5.4 Boolean literals
-See the automatic variables `$false` and `$true` ([§2.3.2.2][]).
+See the automatic variables `$false` and `$true` ([§2.3.2.2][§2.3.2.2]).
#### 2.3.5.5 Array literals PowerShell allows expressions of array type (§9) to be written using the unary comma operator
-([§7.2.1][]), *array-expression* ([§7.1.7][]), the binary comma operator ([§7.3][]), and the range
-operator ([§7.4][]).
+([§7.2.1][§7.2.1]), *array-expression* ([§7.1.7][§7.1.7]), the binary comma operator ([§7.3][§7.3]), and the range
+operator ([§7.4][§7.4]).
#### 2.3.5.6 Hash literals PowerShell allows expressions of type Hashtable (§10) to be written using a
-*hash-literal-expression* ([§7.1.9][])
+*hash-literal-expression* ([§7.1.9][§7.1.9])
#### 2.3.5.7 Type names
lang-spec Chapter 03 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-03.md
stores:
| **Provider** | **Drive Name** | **Description** | **Ref.** | |--------------|-----------------|-------------------------------------|----------|
-| Alias | Alias: | PowerShell aliases | [§3.1.1][] |
-| Environment | Env: | Environment variables | [§3.1.2][] |
-| FileSystem | A:, B:, C:, ... | Disk drives, directories, and files | [§3.1.3][] |
-| Function | Function: | PowerShell functions | [§3.1.4][] |
-| Variable | Variable: | PowerShell variables | [§3.1.5][] |
+| Alias | Alias: | PowerShell aliases | [§3.1.1][§3.1.1] |
+| Environment | Env: | Environment variables | [§3.1.2][§3.1.2] |
+| FileSystem | A:, B:, C:, ... | Disk drives, directories, and files | [§3.1.3][§3.1.3] |
+| Function | Function: | PowerShell functions | [§3.1.4][§3.1.4] |
+| Variable | Variable: | PowerShell variables | [§3.1.5][§3.1.5] |
Windows PowerShell:
The following cmdlets deal with providers and drives:
or more providers - [Get-PSDrive](xref:Microsoft.PowerShell.Management.Get-PSDrive): Gets information about one or more drives
-The type of an object that represents a provider is described in [§4.5.1][]. The type of an object
-that represents a drive is described in [§4.5.2][].
+The type of an object that represents a provider is described in [§4.5.1][§4.5.1]. The type of an object
+that represents a drive is described in [§4.5.2][§4.5.2].
### 3.1.1 Aliases An *alias* is an alternate name for a command. A command can have multiple aliases, and the original name and all of its aliases can be used interchangeably. An alias can be reassigned. An alias is an
-item ([§3.3][]).
+item ([§3.3][§3.3]).
An alias can be assigned to another alias; however, the new alias is not an alias of the original command.
parameters to be included.
> It is a simple matter, however, to create a function that does nothing more than contain the > invocation of that command with all desired parameters, and to assign an alias to that function.
-The type of an object that represents an alias is described in [§4.5.4][].
+The type of an object that represents an alias is described in [§4.5.4][§4.5.4].
-Alias objects are stored on the drive Alias: ([§3.1][]).
+Alias objects are stored on the drive Alias: ([§3.1][§3.1]).
### 3.1.2 Environment variables
An environment variable's name cannot include the equal sign (`=`).
Changes to the environment variables affect the current session only.
-An environment variable is an item ([§3.3][]).
+An environment variable is an item ([§3.3][§3.3]).
-The type of an object that represents an environment variable is described in [§4.5.6][].
+The type of an object that represents an environment variable is described in [§4.5.6][§4.5.6].
-Environment variable objects are stored on the drive Env: ([§3.1][]).
+Environment variable objects are stored on the drive Env: ([§3.1][§3.1]).
### 3.1.3 File system
deleted.
The file system provider is a hierarchical namespace that contains objects that represent the underlying file system.
-Files are stored on drives with names like A:, B:, C:, and so on ([§3.1][]). Directories and files
-are accessed using path notation ([§3.4][]).
+Files are stored on drives with names like A:, B:, C:, and so on ([§3.1][§3.1]). Directories and files
+are accessed using path notation ([§3.4][§3.4]).
-A directory or file is an item ([§3.3][]).
+A directory or file is an item ([§3.3][§3.3]).
### 3.1.4 Functions
-The PowerShell function provider allows functions ([§8.10][]) and filters ([§8.10][].1) to be
+The PowerShell function provider allows functions ([§8.10][§8.10]) and filters ([§8.10][§8.10].1) to be
retrieved, added, changed, cleared, and deleted. The provider Function is a flat namespace that contains only the function and filter objects.
Neither functions nor filters have child items.
Changes to the functions affect the current session only.
-A function is an item ([§3.3][]).
+A function is an item ([§3.3][§3.3]).
-The type of an object that represents a function is described in [§4.5.10][]. The type of an object
-that represents a filter is described in [§4.5.11][].
+The type of an object that represents a function is described in [§4.5.10][§4.5.10]. The type of an object
+that represents a filter is described in [§4.5.11][§4.5.11].
-Function objects are stored on drive Function: ([§3.1][]).
+Function objects are stored on drive Function: ([§3.1][§3.1]).
### 3.1.5 Variables
The following cmdlets also deal with variables:
- [Remove-Variable](xref:Microsoft.PowerShell.Utility.Remove-Variable): Deletes one or more variables
-As a variable is an item ([§3.3][]), it can be manipulated by most Item-related cmdlets.
+As a variable is an item ([§3.3][§3.3]), it can be manipulated by most Item-related cmdlets.
-The type of an object that represents a variable is described in [§4.5.3][].
+The type of an object that represents a variable is described in [§4.5.3][§4.5.3].
-Variable objects are stored on drive Variable: ([§3.1][]).
+Variable objects are stored on drive Variable: ([§3.1][§3.1]).
## 3.2 Working locations The *current working location* is the default location to which commands point. This is the location
-used if an explicit path ([§3.4][]) is not supplied when a command is invoked. This location
+used if an explicit path ([§3.4][§3.4]) is not supplied when a command is invoked. This location
includes the *current drive*. A PowerShell host may have multiple drives, in which case, each drive has its own current location.
The following cmdlets deal with locations:
location from the top of a specified stack of locations The object types that represents a working location and a stack of working locations are described
-in [§4.5.5][].
+in [§4.5.5][§4.5.5].
## 3.3 Items
-An *item* is an alias ([§3.1.1][]), a variable ([§3.1.5][]), a function ([§3.1.4][]), an environment
-variable ([§3.1.2][]), or a file or directory in a file system ([§3.1.3][]).
+An *item* is an alias ([§3.1.1][§3.1.1]), a variable ([§3.1.5][§3.1.5]), a function ([§3.1.4][§3.1.4]), an environment
+variable ([§3.1.2][§3.1.2]), or a file or directory in a file system ([§3.1.3][§3.1.3]).
The following cmdlets deal with items:
The following cmdlets deal with the content of items:
- [Clear-Content](xref:Microsoft.PowerShell.Management.Clear-Content): Deletes the contents of an item
-The type of an object that represents a directory is described in [§4.5.17][]. The type of an object
-that represents a file is described in [§4.5.18][].
+The type of an object that represents a directory is described in [§4.5.17][§4.5.17]. The type of an object
+that represents a file is described in [§4.5.18][§4.5.18].
## 3.4 Path names
Some cmdlets (such as [Add-Content](xref:Microsoft.PowerShell.Management.Add-Con
`Copy-Item` use file filters. A *file filter* is a mechanism for specifying the criteria for selecting from a set of paths.
-The object type that represents a resolved path is described in [§4.5.5][]. Paths are often
+The object type that represents a resolved path is described in [§4.5.5][§4.5.5]. Paths are often
manipulated as strings. ## 3.5 Scopes
scopes are *child scopes* of that parent. The scope of a name is the scope in wh
and all child scopes, unless it is made private. Within a child scope, a name defined there hides any items defined with the same name in parent scopes.
-Unless dot source notation ([§3.5.5][]) is used, each of the following creates a new scope:
+Unless dot source notation ([§3.5.5][§3.5.5]) is used, each of the following creates a new scope:
- A script file - A script block
also shows the scope when no scope is specified explicitly:
| none | Global/Script/Local scope | Local scope | Local scope | Variable scope information can also be specified when using the family of cmdlets listed in
-([§3.1.5][]). In particular, refer to the parameter `Scope`, and the parameters `Option Private` and
+([§3.1.5][§3.1.5]). In particular, refer to the parameter `Scope`, and the parameters `Option Private` and
`Option AllScope` for more information. The scope `using` is used to access variables defined in another scope while running scripts via
defined in the workflow.
### 3.5.4 Function name scope A function name may also have one of the four different scopes, and the visibility of that name is
-the same as for variables ([§3.5.3][]).
+the same as for variables ([§3.5.3][§3.5.3]).
### 3.5.5 Dot source notation
instead. For example,
### 3.5.6 Modules Just like a top-level script file is at the root of a hierarchical nested scope tree, so too is each
-module ([§3.14][]). However, by default, only those names exported by a module are available by name
+module ([§3.14][§3.14]). However, by default, only those names exported by a module are available by name
from within the importing context. The Global parameter of the cmdlet [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module) allows exported names to have increased visibility.
increased visibility.
## 3.6 ReadOnly and Constant Properties Variables and aliases are described by objects that contain a number of properties. These properties
-are set and manipulated by two families of cmdlets ([§3.1.5][], [§3.1.1][]). One such property is
+are set and manipulated by two families of cmdlets ([§3.1.5][§3.1.5], [§3.1.1][§3.1.1]). One such property is
Options, which can be set to ReadOnly or Constant (using the Option parameter). A variable or alias marked ReadOnly can be removed, and its properties can changed provided the Force parameter is specified. However, a variable or alias marked Constant cannot be removed nor have its properties
The name of a method along with the number and types of its parameters are colle
method's *signature*. (Note that the signature does not include the method's return type.) The execution environment may allow a type to have multiple methods with the same name provided each has a different signature. When multiple versions of some method are defined, that method is said to be
-*overloaded*. For example, the type Math ([§4.3.8][]) contains a set of methods called `Abs`, which
+*overloaded*. For example, the type Math ([§4.3.8][§4.3.8]) contains a set of methods called `Abs`, which
computes the absolute value of a specified number, where the specified number can have one of a number of types. The methods in that set have the following signatures:
Abs(Int16)
In this case, all of the methods have the same number of arguments; their signatures differ by argument type only.
-Another example involves the type Array ([§4.3.2][]), which contains a set of methods called Copy
+Another example involves the type Array ([§4.3.2][§4.3.2]), which contains a set of methods called Copy
that copies a range of elements from one array to another, starting at the beginning of each array (by default) or at some designated element. The methods in that set have the following signatures:
exactly, PowerShell does not itself provide a way to define overloaded methods.
### 3.7.2 Method overload resolution
-Given a method call ([§7.1.3][]) having a list of argument expressions, and a set of *candidate
+Given a method call ([§7.1.3][§7.1.3]) having a list of argument expressions, and a set of *candidate
method*s (i.e., those methods that could be called), the mechanism for selecting the *best method* is called *overload resolution*.
-Given the set of applicable candidate methods ([§3.7.3][]), the best method in that set is selected.
+Given the set of applicable candidate methods ([§3.7.3][§3.7.3]), the best method in that set is selected.
If the set contains only one method, then that method is the best method. Otherwise, the best method is the one method that is better than all other methods with respect to the given argument list
-using the rules shown in [§3.7.4][]. If there is not exactly one method that is better than all
+using the rules shown in [§3.7.4][§3.7.4]. If there is not exactly one method that is better than all
other methods, then the method invocation is ambiguous and an error is reported. The best method must be accessible in the context in which it is called. For example, a PowerShell
In addition to having an appropriate number of arguments, each argument in A mus
parameter-passing mode of the argument, and the argument type must match the parameter type, or there must be a conversion from the argument type to the parameter type.
-If the argument type is ref ([§4.3.6][]), the corresponding parameter must also be ref, and the
+If the argument type is ref ([§4.3.6][§4.3.6]), the corresponding parameter must also be ref, and the
argument type for conversion purposes is the type of the property Value from the ref argument. If the argument type is `ref`, the corresponding parameter could be `out` instead of `ref`.
lookup is performed in such a case is alias, function, cmdlet, and external comm
## 3.9 Type name lookup
-[§7.1.10][] contains the statement, "A *type-literal* is represented in an implementation by some
+[§7.1.10][§7.1.10] contains the statement, "A *type-literal* is represented in an implementation by some
unspecified *underlying type*. As a result, a type name is a synonym for its underlying type." Example of types are `int`, `double`, `long[]`, and `Hashtable`.
order in which these expressions are evaluated relative to each other is unspeci
## 3.12 Error handling When a command fails, this is considered an *error*, and information about that error is recorded in
-an *error record*, whose type is unspecified ([§4.5.15][]); however, this type supports
+an *error record*, whose type is unspecified ([§4.5.15][§4.5.15]); however, this type supports
subscripting. An error falls into one of two categories. Either it terminates the operation (a *terminating
continues.
Non-terminating errors are written to the error stream. Although that information can be redirected to a file, the error objects are first converted to strings and important information in those objects would not be captured making diagnosis difficult if not impossible. Instead, the error text
-can be redirected ([§7.12][]) and the error object saved in a variable, as in
+can be redirected ([§7.12][§7.12]) and the error object saved in a variable, as in
`$Error1 = command 2>&1`. The automatic variable `$Error` contains a collection of error records that represent recent errors,
records are discarded as new ones are added. The automatic variable `$MaximumErr
the number of records that can be stored. `$Error` contains all of the errors from all commands mixed in together in one collection. To
-collect the errors from a specific command, use the common parameter [ErrorVariable][],
+collect the errors from a specific command, use the common parameter [ErrorVariable][ErrorVariable],
which allows a user-defined variable to be specified to hold the collection. ## 3.13 Pipelines
within it can be used. Once imported, commands and items behave as if they were
module is imported explicitly with the `Import-Module` command. A module may also be imported automatically as determined in an implementation defined manner.
-The type of an object that represents a module is described in [§4.5.12][].
+The type of an object that represents a module is described in [§4.5.12][§4.5.12].
-Modules are discussed in detail in [§11.][]
+Modules are discussed in detail in [§11.][§11.]
## 3.15 Wildcard expressions
lang-spec Chapter 04 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-04.md
making a copy of the object as well.
A *numeric* type is one that allows representation of integer or fractional values, and that supports arithmetic operations on those values. The set of numerical types includes the integer
-([§4.2.3][]) and real number ([§4.2.4][]) types, but does not include bool ([§4.2.1][]) or char
-([§4.2.2][]). An implementation may provide other numeric types (such as signed byte, unsigned
+([§4.2.3][§4.2.3]) and real number ([§4.2.4][§4.2.4]) types, but does not include bool ([§4.2.1][§4.2.1]) or char
+([§4.2.2][§4.2.2]). An implementation may provide other numeric types (such as signed byte, unsigned
integer, and integers of other sizes). A *collection* is a group of one or more related items, which need not have the same type. Examples of collection types are arrays, stacks, queues, lists, and hash tables. A program can *enumerate* (or *iterate*) over the elements in a collection, getting access to each element one at a time.
-Common ways to do this are with the foreach statement ([§8.4.4][]) and the
+Common ways to do this are with the foreach statement ([§8.4.4][§8.4.4]) and the
[ForEach-Object](xref:Microsoft.PowerShell.Core.ForEach-Object) cmdlet. The type of an object that
-represents an enumerator is described in [§4.5.16][].
+represents an enumerator is described in [§4.5.16][§4.5.16].
In this chapter, there are tables that list the accessible members for a given type. For methods, the **Type** is written with the following form: *returnType*/*argumentTypeList*. If the argument
their generic equivalents.
### 4.1.1 The void type This type cannot be instantiated. It provides a means to discard a value explicitly using the cast
-operator ([§7.2.9][]).
+operator ([§7.2.9][§7.2.9]).
### 4.1.2 The null type
-The *null type* has one instance, the automatic variable $null ([§2.3.2.2][]), also known as the
+The *null type* has one instance, the automatic variable $null ([§2.3.2.2][§2.3.2.2]), also known as the
null value. This value provides a means for expressing "nothingness" in reference contexts. The characteristics of this type are unspecified. ### 4.1.3 The object type
-Every type in PowerShell except the null type ([§4.1.2][]) is derived directly or indirectly from
+Every type in PowerShell except the null type ([§4.1.2][§4.1.2]) is derived directly or indirectly from
the type object, so object is the ultimate base type of all non-null types. A variable constrained
-([§5.3][]) to type object is really not constrained at all, as it can contain a value of any type.
+([§5.3][§5.3]) to type object is really not constrained at all, as it can contain a value of any type.
## 4.2 Value types ### 4.2.1 Boolean The Boolean type is `bool`. There are only two values of this type, **False** and **True**,
-represented by the automatic variables `$false` and `$true`, respectively ([§2.3.2.2][]).
+represented by the automatic variables `$false` and `$true`, respectively ([§2.3.2.2][§2.3.2.2]).
In PowerShell, `bool` maps to `System.Boolean`.
In PowerShell, `decimal` maps to `System.Decimal`. The representation of decimal
### 4.2.5 The switch type
-This type is used to constrain the type of a parameter in a command ([§8.10.5][]). If an argument
+This type is used to constrain the type of a parameter in a command ([§8.10.5][§8.10.5]). If an argument
having the corresponding parameter name is present the parameter tests $true; otherwise, it tests `$false`.
In PowerShell, `switch` maps to `System.Management.Automation.SwitchParameter`.
An enumeration type is one that defines a set of named constants representing all the possible values that can be assigned to an object of that enumeration type. In some cases, the set of values are such that only one value can be represented at a time. In other cases, the set of values are
-distinct powers of two, and by using the -bor operator ([§7.8.5][]), multiple values can be encoded
+distinct powers of two, and by using the -bor operator ([§7.8.5][§7.8.5]), multiple values can be encoded
in the same object. The PowerShell environment provides a number of enumeration types, as described in the following
Copy(<em>source</em>, <em>sourceIndex</em>, <em>destination</em>, <em>destinatio
</tbody> </table>
-For more details on arrays, see [§9.][]
+For more details on arrays, see [§9.][§9.]
In PowerShell, `Array` maps to `System.Array`.
in an object of type `DictionaryEntry`, and the collections returned by Keys and
Type xml implements the W3C Document Object Model (DOM) Level 1 Core and the Core DOM Level 2. The DOM is an in-memory (cache) tree representation of an XML document and enables the navigation and
-editing of this document. This type supports the subscript operator [] ([§7.1.4.4][]).
+editing of this document. This type supports the subscript operator [] ([§7.1.4.4][§7.1.4.4]).
In PowerShell, `xml` maps to `System.Xml.XmlDocument`. ### 4.3.5 The regex type Type `regex` provides machinery for supporting regular expression processing. It is used to
-constrain the type of a parameter ([§5.3][]) whose corresponding argument might contain a regular
+constrain the type of a parameter ([§5.3][§5.3]) whose corresponding argument might contain a regular
expression. In PowerShell, `regex` maps to `System.Text.RegularExpressions.Regex`.
In PowerShell, `ref` maps to `System.Management.Automation.PSReference`.
### 4.3.7 The scriptblock type
-Type `scriptblock` represents a precompiled block of script text ([§7.1.8][]) that can be used as a
+Type `scriptblock` represents a precompiled block of script text ([§7.1.8][§7.1.8]) that can be used as a
single unit. It has the following accessible members: <table>
single unit. It has the following accessible members:
<tr class="odd"> <td>Module</td> <td>Instance property (read-only)</td>
-<td>implementation defined ([§4.5.12][])</td>
+<td>implementation defined ([§4.5.12][§4.5.12])</td>
<td>Gets information about the module in which the script block is defined.</td> </tr> <tr class="even">
handling some subset of types when it is used. For example,
- A stack of stack of strings might be written as `Stack[Stack[string]]`. Although PowerShell does not define any built-in generic types, it can use such types if they are
-provided by the host environment. See the syntax in [§7.1.10][].
+provided by the host environment. See the syntax in [§7.1.10][§7.1.10].
The complete name for the type `Stack[string]` suggested above is `System.Collections.Generic.Stack[string]`. The complete name for the type `Dictionary[int,string]`
This type encapsulates the state of a provider. It has the following accessible
| **Member** | **Member Kind** | **Type** | **Purpose** | | ---------- | ----------------------------- | ----------------------------------- | ----------------------------------------- |
-| Drives | Instance property (read-only) | Implementation defined ([§4.5.2][]) | A collection of drive description objects |
+| Drives | Instance property (read-only) | Implementation defined ([§4.5.2][§4.5.2]) | A collection of drive description objects |
| Name | Instance property (read-only) | string | The name of the provider | In PowerShell, this type is `System.Management.Automation.ProviderInfo`.
This type encapsulates the state of a drive. It has the following accessible mem
| **Member** | **Member Kind** | **Type** | **Purpose** | | --------------- | ------------------------------ | -------- | ------------------------------------------------------ |
-| CurrentLocation | Instance property (read-write) | string | The current working location ([§3.1.4][]) of the drive |
+| CurrentLocation | Instance property (read-write) | string | The current working location ([§3.1.4][§3.1.4]) of the drive |
| Description | Instance property (read-write) | string | The description of the drive | | Name | Instance property (read-only) | string | The name of the drive | | Root | Instance property (read-only) | string | The name of the drive |
This type encapsulates the state of a variable. It has the following accessible
| ----------- | ------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Attributes | Instance property (read-only) | Implementation defined | A collection of attributes | | Description | Instance property (read-write) | string | The description assigned to the variable via the [New-Variable](xref:Microsoft.PowerShell.Utility.New-Variable) or [Set-Variable](xref:Microsoft.PowerShell.Utility.Set-Variable) cmdlets. |
-| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module from which this variable was exported |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module from which this variable was exported |
| ModuleName | Instance property (read-only) | string | The module in which this variable was defined | | Name | Instance property (read-only) | string | The name assigned to the variable when it was created in the PowerShell language or via the `New-Variable` and `Set-Variable` cmdlets. | | Options | Instance property (read-write) | string | The options assigned to the variable via the `New-Variable` and `Set-Variable` cmdlets. |
This type encapsulates the state of an alias. It has the following accessible me
| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Alias". | | Definition | Instance property (read-only) | string | The command or alias to which the alias was assigned via the [New-Alias](xref:Microsoft.PowerShell.Utility.New-Alias) or [Set-Alias](xref:Microsoft.PowerShell.Utility.Set-Alias) cmdlets. | | Description | Instance property (read-write) | string | The description assigned to the alias via the `New-Alias` or `Set-Alias` cmdlets. |
-| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module from which this alias was exported |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module from which this alias was exported |
| ModuleName | Instance property (read-only) | string | The module in which this alias was defined | | Name | Instance property (read-only) | string | The name assigned to the alias when it was created via the `New-Alias` or `Set-Alias` cmdlets. | | Options | Instance property (read-write) | string | The options assigned to the alias via the New-Alias `New-Alias` or `Set-Alias` cmdlets. |
This type encapsulates the state of a working location. It has the following acc
| **Member** | **Member Kind** | **Type** | **Purpose** | | ------------ | ----------------------------- | ----------------------------------- | -------------------------------- |
-| Drive | Instance property (read-only) | Implementation defined ([§4.5.2][]) | A drive description object |
+| Drive | Instance property (read-only) | Implementation defined ([§4.5.2][§4.5.2]) | A drive description object |
| Path | Instance property (read-only) | string | The working location |
-| Provider | Instance property (read-only) | Implementation defined ([§4.5.1][]) | The provider |
+| Provider | Instance property (read-only) | Implementation defined ([§4.5.1][§4.5.1]) | The provider |
| ProviderPath | Instance property (read-only) | string | The current path of the provider | A stack of working locations is a collection of working location objects, as described above.
This type encapsulates the state of an application. It has the following accessi
| CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "Application". | | Definition | Instance property (read-only) | string | A description of the application. | | Extension | Instance property (read-write) | string | The extension of the application file. |
-| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module that defines this command. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module that defines this command. |
| ModuleName | Instance property (read-only) | string | The name of the module that defines the command. | | Name | Instance property (read-only) | string | The name of the command. | | OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output by the command. |
This type encapsulates the state of a cmdlet. It has the following accessible me
| Definition | Instance property (read-only) | string | A description of the cmdlet. | | HelpFile | Instance property (read-write) | string | The path to the Help file for the cmdlet. | | ImplementingType | Instance property (read-write) | Implementation defined | The type that implements the cmdlet. |
-| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module that defines this cmdlet. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module that defines this cmdlet. |
| ModuleName | Instance property (read-only) | string | The name of the module that defines the cmdlet. | | Name | Instance property (read-only) | string | The name of the cmdlet. | | Noun | Instance property (read-only) | string | The noun name of the cmdlet. |
PowerShell, but is not built in). It has the following accessible members:
| ---------------- | ----------------------------- | ------------------------------------ | ---------------------------------------------------------------------------- | | CommandType | Instance property (read-only) | Implementation defined | Should compare equal with "ExternalScript". | | Definition | Instance property (read-only) | string | A definition of the script. |
-| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module that defines this script. |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module that defines this script. |
| ModuleName | Instance property (read-only) | string | The name of the module that defines the script. | | Name | Instance property (read-only) | string | The name of the script. | | OriginalEncoding | Instance property (read-only) | Implementation defined | The original encoding used to convert the characters of the script to bytes. |
This type encapsulates the state of a function. It has the following accessible
| **Member** | **Member Kind** | **Type** | **Purpose** | | ------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| CmdletBinding | Instance property (read-only) | bool | Indicates whether the function uses the same parameter binding that compiled cmdlets use (see [§12.3.5][]). |
+| CmdletBinding | Instance property (read-only) | bool | Indicates whether the function uses the same parameter binding that compiled cmdlets use (see [§12.3.5][§12.3.5]). |
| CommandType | Instance property (read-only) | Implementation defined | Can be compared for equality with "Function" or "Filter" to see which of those this object represents. |
-| DefaultParameterSet | Instance property (read-only) | string | Specifies the parameter set to use if that cannot be determined from the arguments (see [§12.3.5][]). |
+| DefaultParameterSet | Instance property (read-only) | string | Specifies the parameter set to use if that cannot be determined from the arguments (see [§12.3.5][§12.3.5]). |
| Definition | Instance property (read-only) | string | A string version of ScriptBlock | | Description | Instance property (read-write) | string | The description of the function. |
-| Module | Instance property (read-only) | Implementation defined ([§4.5.12][]) | The module from which this function was exported |
+| Module | Instance property (read-only) | Implementation defined ([§4.5.12][§4.5.12]) | The module from which this function was exported |
| ModuleName | Instance property (read-only) | string | The module in which this function was defined | | Name | Instance property (read-only) | string | The name of the function |
-| Options | Instance property (read-write) | Implementation defined | The scope options for the function ([§3.5.4][]). |
-| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output, in order (see [§12.3.6][]). |
-| Parameters | Instance property (read-only) | Implementation defined collection | Specifies the parameter names, in order. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][] are included at the end of the collection. |
-| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. For each parameter, the result shows the parameter name and type, and indicates if the parameter is mandatory, by position or a switch parameter. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][] are included at the end of the collection. |
-| ScriptBlock | Instance property (read-only) | scriptblock ([§4.3.6][]) | The body of the function |
+| Options | Instance property (read-write) | Implementation defined | The scope options for the function ([§3.5.4][§3.5.4]). |
+| OutputType | Instance property (read-only) | Implementation defined collection | Specifies the types of the values output, in order (see [§12.3.6][§12.3.6]). |
+| Parameters | Instance property (read-only) | Implementation defined collection | Specifies the parameter names, in order. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][common parameters] are included at the end of the collection. |
+| ParameterSets | Instance property (read-only) | Implementation defined collection | Information about the parameter sets associated with the command. For each parameter, the result shows the parameter name and type, and indicates if the parameter is mandatory, by position or a switch parameter. If the function acts like a cmdlet (see CmdletBinding above) the [common parameters][common parameters] are included at the end of the collection. |
+| ScriptBlock | Instance property (read-only) | scriptblock ([§4.3.6][§4.3.6]) | The body of the function |
In PowerShell, this type is `System.Management.Automation.FunctionInfo`.
In PowerShell, this type is `System.Management.Automation.FunctionInfo`.
### 4.5.11 Filter description type This type encapsulates the state of a filter. It has the same set of accessible members as the
-function description type ([§4.5.10][]).
+function description type ([§4.5.10][§4.5.10]).
In PowerShell, this type is `System.Management.Automation.FilterInfo`. It has the same set of
-properties as `System.Management.Automation.FunctionInfo` ([§4.5.11][]).
+properties as `System.Management.Automation.FunctionInfo` ([§4.5.11][§4.5.11]).
### 4.5.12 Module description type
In PowerShell, this type is System.Management.Automation.PSScriptCmdlet.
### 4.5.15 Error record description type The automatic variable `$Error` contains a collection of error records that represent recent errors
-([§3.12][]). Although the type of this collection is unspecified, it does support subscripting to get
+([§3.12][§3.12]). Although the type of this collection is unspecified, it does support subscripting to get
access to individual error records. In PowerShell, the collection type is `System.Collections.ArrayList`. The type of an individual
defined; it has the following accessible members:
| **Member** | **Member Kind** | **Type** | **Purpose** | | ------------- | ------------------------------ | ------------------------------------- | ------------------------------------------------------------------- |
-| Attributes | Instance property (read-write) | Implementation defined ([§4.2.6.3][]) | Gets or sets one or more of the attributes of the directory object. |
-| CreationTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the creation time of the directory object. |
+| Attributes | Instance property (read-write) | Implementation defined ([§4.2.6.3][§4.2.6.3]) | Gets or sets one or more of the attributes of the directory object. |
+| CreationTime | Instance property (read-write) | Implementation defined ([§4.5.19][§4.5.19]) | Gets and sets the creation time of the directory object. |
| Extension | Instance property (read- only) | string | Gets the extension part of the directory name. | | FullName | Instance property (read-only) | string | Gets the full path of the directory. |
-| LastWriteTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the time when the directory was last written to. |
+| LastWriteTime | Instance property (read-write) | Implementation defined ([§4.5.19][§4.5.19]) | Gets and sets the time when the directory was last written to. |
| Name | Instance property (read- only) | string | Gets the name of the directory. | In PowerShell, this type is `System.IO.DirectoryInfo`. The type of the **Attributes** property is
file description object is implementation defined; it has the following accessib
| **Member** | **Member Kind** | **Type** | **Purpose** | | ------------- | ------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| Attributes | Instance property (read-write) | Implementation defined ([§4.2.6.3][]) | Gets or sets one or more of the attributes of the file object. |
+| Attributes | Instance property (read-write) | Implementation defined ([§4.2.6.3][§4.2.6.3]) | Gets or sets one or more of the attributes of the file object. |
| BaseName | Instance property (read- only) | string | Gets the name of the file excluding the extension. |
-| CreationTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the creation time of the file object. |
+| CreationTime | Instance property (read-write) | Implementation defined ([§4.5.19][§4.5.19]) | Gets and sets the creation time of the file object. |
| Extension | Instance property (read- only) | string | Gets the extension part of the file name. | | FullName | Instance property (read-only) | string | Gets the full path of the file. |
-| LastWriteTime | Instance property (read-write) | Implementation defined ([§4.5.19][]) | Gets and sets the time when the file was last written to. |
+| LastWriteTime | Instance property (read-write) | Implementation defined ([§4.5.19][§4.5.19]) | Gets and sets the time when the file was last written to. |
| Length | Instance property (read- only) | long | Gets the size of the file, in bytes. | | Name | Instance property (read- only) | string | Gets the name of the file. | | VersionInfo | Instance property (read- only) | Implementation defined | Windows PowerShell: This ScriptProperty returns a System.Diagnostics.FileVersionInfo for the file. |
following accessible members:
| ---------- | --------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Invoke | Instance method | object/variable number and type | Takes a variable number of arguments, and indirectly calls the method referred to by the parent method designator, passing in the arguments. |
-An object of this type can be created by an *invocation-expression* ([§7.1.3][]).
+An object of this type can be created by an *invocation-expression* ([§7.1.3][§7.1.3]).
In PowerShell, this type is System.Management.Automation.PSMethod.
In PowerShell, this type is `Microsoft.PowerShell.Commands.MemberDefinition`.
A PowerShell implementation includes a family of core types (which are documented in this chapter) that each contain their own set of *base members*. Those members can be methods or properties, and they can be instance or static members. For example, the base members of the type string
-([§4.3.1][]) are the instance property Length and the instance methods ToLower and ToUpper.
+([§4.3.1][§4.3.1]) are the instance property Length and the instance methods ToLower and ToUpper.
When an object is created, it contains all the instance properties of that object's type, and the instance methods of that type can be called on that object. An object may be customized via the
lang-spec Chapter 05 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-05.md
that with which it was declared at compile time. Object-oriented languages add t
inheritance, which allows the runtime type of a variable to be that with which it was declared at compile time or some type derived from that type. Being a dynamically typed language, PowerShell's variables do not have types, per se. In fact, variables are not defined; they simply come into being
-when they are first assigned a value. And while a variable may be constrained ([§5.3][]) to holding
+when they are first assigned a value. And while a variable may be constrained ([§5.3][§5.3]) to holding
a value of a given type, type information in an assignment cannot always be verified statically. At different times, a variable may be associated with values of different types either through
-assignment ([§7.11][]) or the use of the `++` and `‑‑` operators ([§7.1.5][], [§7.2.6][]). When the
+assignment ([§7.11][§7.11]) or the use of the `++` and `‑‑` operators ([§7.1.5][§7.1.5], [§7.2.6][§7.2.6]). When the
value associated with a variable is changed, that value's type may change. For example, ```powershell
been defined, use the [Test-Path](xref:Microsoft.PowerShell.Management.Test-Path
A *writable location* is an expression that designates a resource to which a command has both read and write access. A writable location may be a variable (§5), an array element (§9), an associated
-value in a Hashtable accessed via a subscript (§10), a property ([§7.1.2][]), or storage managed by
-a provider ([§3.1][]).
+value in a Hashtable accessed via a subscript (§10), a property ([§7.1.2][§7.1.2]), or storage managed by
+a provider ([§3.1][§3.1]).
## 5.2 Variable categories
function F ($p1, $p2) {
### 5.2.1 Static variables A data member of an object that belongs to the object's type rather than to that particular instance
-of the type is called a *static variable*. See [§4.2.3][], [§4.2.4.1][], and [§4.3.8][] for some
+of the type is called a *static variable*. See [§4.2.3][§4.2.3], [§4.2.4.1][§4.2.4.1], and [§4.3.8][§4.3.8] for some
examples. PowerShell provides no way to create new types that contain static variables; however, objects of
such types may be provided by the host environment.
Memory for creating and deleting objects containing static variables is managed by the host environment and the garbage collection system.
-See [§7.1.2][] for information about accessing a static variable.
+See [§7.1.2][§7.1.2] for information about accessing a static variable.
A static data member can be a field or a property. ### 5.2.2 Instance variables A data member of an object that belongs to a particular instance of the object's type rather than to
-the type itself is called an *instance variable*. See [§4.3.1][], [§4.3.2][], and [§4.3.3][] for
+the type itself is called an *instance variable*. See [§4.3.1][§4.3.1], [§4.3.2][§4.3.2], and [§4.3.3][§4.3.3] for
some examples. A PowerShell host environment might provide a way to create new types that contain instance
variables or to add new instance variables to existing types.
Memory for creating and deleting objects containing static variables is managed by the host environment and the garbage collection system.
-See [§7.1.2][] for information about accessing an instance variable.
+See [§7.1.2][§7.1.2] for information about accessing an instance variable.
An instance data member can be a field or a property. ### 5.2.3 Array elements
-An array can be created via a unary comma operator ([§7.2.1][]), *sub-expression* ([§7.1.6][]),
-*array-expression* ([§7.1.7][]), binary comma operator ([§7.3][]), range operator ([§7.4][]), or
+An array can be created via a unary comma operator ([§7.2.1][§7.2.1]), *sub-expression* ([§7.1.6][§7.1.6]),
+*array-expression* ([§7.1.7][§7.1.7]), binary comma operator ([§7.3][§7.3]), range operator ([§7.4][§7.4]), or
[New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet. Memory for creating and deleting arrays is managed by the host environment and the garbage collection system.
-Arrays and array elements are discussed in [§9.][]
+Arrays and array elements are discussed in [§9.][§9.]
### 5.2.4 Hashtable key/value pairs
-A Hashtable is created via a hash literal ([§2.3.5.6][]) or the
+A Hashtable is created via a hash literal ([§2.3.5.6][§2.3.5.6]) or the
[New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet. A new key/value pair can be added
-via the `[]` operator ([§7.1.4.3][]).
+via the `[]` operator ([§7.1.4.3][§7.1.4.3]).
Memory for creating and deleting Hashtables is managed by the host environment and the garbage collection system.
A parameter is created when its parent command is invoked, and it is initialized
the argument provided in the invocation or by the host environment. A parameter ceases to exist when its parent command terminates.
-Parameters are discussed in [§8.10][].
+Parameters are discussed in [§8.10][§8.10].
### 5.2.6 Ordinary variables
-An *ordinary variable* is defined by an *assignment-expression* ([§7.11][]) or a *foreach-statement*
-([§8.4.4][]). Some ordinary variables are predefined by the host environment while others are
+An *ordinary variable* is defined by an *assignment-expression* ([§7.11][§7.11]) or a *foreach-statement*
+([§8.4.4][§8.4.4]). Some ordinary variables are predefined by the host environment while others are
transient, coming and going as needed at runtime. The lifetime of an ordinary variable is that part of program execution during which storage is
entered recursively or iteratively, a new instance of the local variable is crea
The storage referred to by an ordinary variable is reclaimed independently of the lifetime of that variable.
-An ordinary variable can be named explicitly with a **Variable:** namespace prefix ([§5.2.7][]).
+An ordinary variable can be named explicitly with a **Variable:** namespace prefix ([§5.2.7][§5.2.7]).
### 5.2.7 Variables on provider drives
-The concept of providers and drives is introduced in [§3.1][], with each provider being able to
+The concept of providers and drives is introduced in [§3.1][§3.1], with each provider being able to
provide its own namespace drive(s). This allows resources on those drives to be accessed as though
-they were ordinary variables ([§5.2.6][]). In fact, an ordinary variable is stored on the file
-system provider drive Variable: ([§3.1.5][]) and can be accessed by its ordinary name or its fully
+they were ordinary variables ([§5.2.6][§5.2.6]). In fact, an ordinary variable is stored on the file
+system provider drive Variable: ([§3.1.5][§3.1.5]) and can be accessed by its ordinary name or its fully
qualified namespace name.
-Some namespace variable types are constrained implicitly ([§5.3][]).
+Some namespace variable types are constrained implicitly ([§5.3][§5.3]).
## 5.3 Constrained variables
function F ([int]$p1, [switch]$p2, [regex]$p3) { ... }
``` Any variable belonging to the namespace **Env:**, **Alias:**, or to the file system namespace
-([§2.3.2][], [§3.1][]) is constrained implicitly to the type `string`. Any variable belonging to the
-namespace **Function:** ([§2.3.2][], [§3.1][]) is constrained implicitly to the type `scriptblock`.
+([§2.3.2][§2.3.2], [§3.1][§3.1]) is constrained implicitly to the type `string`. Any variable belonging to the
+namespace **Function:** ([§2.3.2][§2.3.2], [§3.1][§3.1]) is constrained implicitly to the type `scriptblock`.
<!-- reference links --> [§2.3.2]: chapter-02.md#232-variables
lang-spec Chapter 06 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-06.md
common example of this is with some operators that need to convert one or more o
designated by their operands.) Implicit conversion is permitted provided the sense of the source value is preserved, such as no loss of precision of a number when it is converted.
-The cast operator ([§7.2.9][]) allows for *explicit conversion*.
+The cast operator ([§7.2.9][§7.2.9]) allows for *explicit conversion*.
Conversions are discussed below, with supplementary information being provided as necessary in the
-description of each operator in [§6.19][].
+description of each operator in [§6.19][§6.19].
Explicit conversion of a value to the type it already has causes no change to that value or its representation. The rules for handing conversion when the value of an expression is being bound to a parameter are
-covered in [§6.17][].
+covered in [§6.17][§6.17].
## 6.1 Conversion to void
follows:
- A numeric type value whose value after rounding of any fractional part can be represented in the destination type has that rounded value; otherwise, the conversion is in error. - A value of null type is converted to zero.-- A string that represents a number is converted as described in [§6.16][]. If after truncation of
+- A string that represents a number is converted as described in [§6.16][§6.16]. If after truncation of
the fractional part the result can be represented in the destination type the string is well formed and it has the destination type; otherwise, the conversion is in error. If the string does not represent a number, the conversion is in error.
follows:
conversions to float, and for long and decimal conversions to double, some of the least significant bits of the integer value may be lost. - A value of null type is converted to zero.-- A string that represents a number is converted as described in [§6.16][]; otherwise, the
+- A string that represents a number is converted as described in [§6.16][§6.16]; otherwise, the
conversion is in error. - For other reference type values, if the reference type supports such a conversion, that conversion is used; otherwise, the conversion is in error.
The rules for converting any value to type decimal are as follows:
- A numeric type value is represented exactly; however, if that value is too large or too small to fit in the destination type, the conversion is in error. - A value of null type is converted to zero.-- A string that represents a number is converted as described in [§6.16][]; otherwise, the
+- A string that represents a number is converted as described in [§6.16][§6.16]; otherwise, the
conversion is in error. - For other reference type values, if the reference type supports such a conversion, that conversion is used; otherwise, the conversion is in error.
The rules for converting any value to type string are as follows:
- A value of null type is converted to the empty string. - For a 1-dimensional array, the result is a string containing the value of each element in that array, from start to end, converted to string, with elements being separated by the current Output
- Field Separator ([§2.3.2.2][]). For an array having elements that are themselves arrays, only the
+ Field Separator ([§2.3.2.2][§2.3.2.2]). For an array having elements that are themselves arrays, only the
top-level elements are converted. The string used to represent the value of an element that is an
- array, is implementation defined. For a multi-dimensional array, it is flattened ([§9.12][]) and
+ array, is implementation defined. For a multi-dimensional array, it is flattened ([§9.12][§9.12]) and
then treated as a 1ΓÇædimensional array. - A value of null type is converted to the empty string. - A scriptblock type value is converted to a string containing the text of that block without the
The rules for converting any value to an array type are as follows:
created whose value is the scalar after conversion to the target element type. - For a 1-dimensional array value, a new array of the target type is created, and each element is copied with conversion from the source array to the corresponding element in the target array.-- For a multi-dimensional array value, that array is first flattened ([§9.12][]), and then treated
+- For a multi-dimensional array value, that array is first flattened ([§9.12][§9.12]), and then treated
as a 1-dimensional array value. - A string value is converted to an array of char having the same length with successive characters from the string occupying corresponding positions in the array.
If neither operand designates a value having numeric type, then
- Otherwise, if the left operand designates a value of type char and the right operand designates a value of type bool, the conversion is in error. - Otherwise, if the left operand designates a value of type string but does not represent a number
- ([§6.16][]), the conversion is in error.
+ ([§6.16][§6.16]), the conversion is in error.
- Otherwise, if the right operand designates a value of type string but does not represent a number
- ([§6.16][]), the conversion is in error.
-- Otherwise, all operands designating values of type string are converted to numbers ([§6.16][]),
+ ([§6.16][§6.16]), the conversion is in error.
+- Otherwise, all operands designating values of type string are converted to numbers ([§6.16][§6.16]),
and the process continues with the numeric conversions listed below. - Otherwise, the conversion is in error.
implicitly to a numeric value. Specifically,
## 6.17 Conversion during parameter binding
-For information about parameter binding see [§8.14][].
+For information about parameter binding see [§8.14][§8.14].
When the value of an expression is being bound to a parameter, there are extra conversion considerations, as described below: -- If the parameter type is bool or switch ([§4.2.5][], [§8.10.5][]) and the parameter has no
+- If the parameter type is bool or switch ([§4.2.5][§4.2.5], [§8.10.5][§8.10.5]) and the parameter has no
argument, the value of the parameter in the called command is set to `$true`. If the parameter type is other than bool or switch, a parameter having no argument is in error. - If the parameter type is switch and the argument value is `$null`, the parameter value is set to
considerations, as described below:
argument collection. If necessary, the argument collection element values are converted to type T2 using the conversion rules of this section. - If the steps above and the conversions specified earlier in this chapter do not suffice, the rules
- in [§6.18][] are applied. If those fail, the parameter binding fails.
+ in [§6.18][§6.18] are applied. If those fail, the parameter binding fails.
## 6.18 .NET Conversion
a conversion is found, but it throws an exception, the conversion has failed.
The rules for converting any value to the pseudo-type ordered are as follows: -- If the value is a hash literal ([§2.3.5.6][]), the result is an object with an implementation
+- If the value is a hash literal ([§2.3.5.6][§2.3.5.6]), the result is an object with an implementation
defined type that behaves like a hashtable and the order of the keys matches the order specified in the hash literal. - Otherwise, the behavior is implementation defined.
-Only hash literals ([§2.3.5.6][]) can be converted to ordered. The result is an instance of
+Only hash literals ([§2.3.5.6][§2.3.5.6]) can be converted to ordered. The result is an instance of
`System.Collections.Specialized.OrderedDictionary`. ## 6.20 Conversion to pscustomobject
lang-spec Chapter 07 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-07.md
operations defined on them. All details of such types and operations are impleme
A *top-level expression* is one that is not part of some larger expression. If a top-level expression contains a side-effect operator the value of that expression is not written to the
-pipeline; otherwise, it is. See [§7.1.1][] for a detailed discussion of this.
+pipeline; otherwise, it is. See [§7.1.1][§7.1.1] for a detailed discussion of this.
Ordinarily, an expression that designates a collection (§4) is enumerated into its constituent elements when the value of that expression is used. However, this is not the case when the
expression in parentheses, as follows:
As such, the grouping parentheses in this case are not redundant.
-In the following example, we have variable substitution ([§2.3.5.2][]) taking place in a string
+In the following example, we have variable substitution ([§2.3.5.2][§2.3.5.2]) taking place in a string
literal: ```powershell
unspecified.
This operator is left associative.
-The type of the result of an *invocation-expression* is a *method designator* ([§4.5.24][]).
+The type of the result of an *invocation-expression* is a *method designator* ([§4.5.24][§4.5.24]).
Examples:
There must not be any white space between *primary-expression* and the left squa
Description:
-Arrays are discussed in detail in [§9.][] If *expression* is a 1-dimensional array, see
-[§7.1.4.5][].
+Arrays are discussed in detail in [§9.][§9.] If *expression* is a 1-dimensional array, see
+[§7.1.4.5][§7.1.4.5].
When *primary-expression* designates a 1-dimensional array *A*, the operator `[]` returns the element located at `A[0 + expression]` after the value of *expression* has been converted to `int`.
For a multidimensional-array subscript expression, the order of evaluation of th
expressions is unspecified. For example, given a 3-dimensional array `$a`, the behavior of `$a[$i++,$i,++$i]` is unspecified.
-If *expression* is an array, see [§7.1.4.5][].
+If *expression* is an array, see [§7.1.4.5][§7.1.4.5].
This operator is left associative.
with the key(s) designated by *expression*. The type of *expression* is not rest
When *expression* is a single key name, the result is the associated value and has that type, unless no such key exists, in which case, the result is `$null`. If `$null` is used as the key the behavior
-is implementation defined. If *expression* is an array of key names, see [§7.1.4.5][].
+is implementation defined. If *expression* is an array of key names, see [§7.1.4.5][§7.1.4.5].
-If *expression* is an array, see [§7.1.4.5][].
+If *expression* is an array, see [§7.1.4.5][§7.1.4.5].
Examples:
The type of the result is `System.Xml.XmlElement` or `System.String`.
#### 7.1.4.5 Generating array slices When *primary-expression* designates an object of a type that is enumerable (§4) or a Hashtable, and
-*expression* is a 1-dimensional array, the result is an array slice ([§9.9][]) containing the
+*expression* is a 1-dimensional array, the result is an array slice ([§9.9][§9.9]) containing the
elements of *primary-expression* designated by the elements of *expression*. In the case of a Hashtable, the array slice contains the associated values to the keys provided,
Description:
The *primary-expression* must designate a writable location having a value of numeric type (§4) or the value `$null`. If the value designated by the operand is `$null`, that value is converted to type int and value zero before the operator is evaluated. The type of the value designated by
-*primary-expression* may change when the result is stored. See [§7.11][] for a discussion of type
+*primary-expression* may change when the result is stored. See [§7.11][§7.11] for a discussion of type
change via assignment. The result produced by the postfix `++` operator is the value designated by the operand. After that result is obtained, the value designated by the operand is incremented by 1 of the appropriate type. The type of the result of expression `E++` is the same as for the result of the expression `E + 1`
-([§7.7][]).
+([§7.7][§7.7]).
The result produced by the postfix `--` operator is the value designated by the operand. After that result is obtained, the value designated by the operand is decremented by 1 of the appropriate type. The type of the result of expression `E--` is the same as for the result of the expression `E - 1`
-([§7.7][]).
+([§7.7][§7.7]).
These operators are left associative.
script-block-body:
Description:
-*param-block* is described in [§8.10.9][]. *named-block-list* is described in [§8.10.7][].
+*param-block* is described in [§8.10.9][§8.10.9]. *named-block-list* is described in [§8.10.7][§8.10.7].
A script block is an unnamed block of statements that can be used as a single unit. Script blocks can be used to invoke a block of code as if it was a single command, or they can be assigned to
variables that can be executed.
The *named-block-list* or *statement-list* is executed and the type and value(s) of the result are the type and value(s) of the results of those statement sets.
-A *script-block-expression* has type scriptblock ([§4.3.7][]).
+A *script-block-expression* has type scriptblock ([§4.3.7][§4.3.7]).
If *param-block* is omitted, any arguments passed to the script block are available via `$args`
-([§8.10.1][]).
+([§8.10.1][§8.10.1]).
During parameter binding, a script block can be passed either as a script block object or as the
-result after the script block has been evaluated. See [§6.17][] for further information.
+result after the script block has been evaluated. See [§6.17][§6.17] for further information.
### 7.1.9 Hash literal expression
result, a type name is a synonym for its underlying type.
Type literals are used in a number of contexts: -- Specifying an explicit conversion (§6, [§7.2.9][])-- Creating a type-constrained array ([§9.4][])-- Accessing the static members of an object ([§7.1.2][])-- Specifying a type constraint on a variable ([§5.3][]) or a function parameter ([§8.10.2][])
+- Specifying an explicit conversion (§6, [§7.2.9][§7.2.9])
+- Creating a type-constrained array ([§9.4][§9.4])
+- Accessing the static members of an object ([§7.1.2][§7.1.2])
+- Specifying a type constraint on a variable ([§5.3][§5.3]) or a function parameter ([§8.10.2][§8.10.2])
Examples:
-Examples of type literals are `[int]`, `[object[]`, and `[int[,,]]`. A generic stack type ([§4.4][])
+Examples of type literals are `[int]`, `[object[]`, and `[int[,,]]`. A generic stack type ([§4.4][§4.4])
that is specialized to hold strings might be written as `[Stack[string]]`, and a generic dictionary type that is specialized to hold `int` keys with associated string values might be written as `[Dictionary[int,string]]`.
$a = ,,10 # create an unconstrained array of 1 element, which is
Description:
-The operator -not converts the value designated by *unary-expression* to type bool ([§6.2][]), if
+The operator -not converts the value designated by *unary-expression* to type bool ([§6.2][§6.2]), if
necessary, and produces a result of that type. If *unary-expression*'s value is True, the result is False, and vice versa. The operator ! is an alternate spelling for -not.
Examples:
Description: The operator -bnot converts the value designated by *unary-expression* to an integer type
-([§6.4][]), if necessary. If the converted value can be represented in type int then that is the
+([§6.4][§6.4]), if necessary. If the converted value can be represented in type int then that is the
result type. Else, if the converted value can be represented in type long then that is the result type. Otherwise, the expression is ill formed. The resulting value is the ones-complement of the converted value.
Examples:
Description: An expression of the form +*unary-expression* is treated as if it were written as
-`0 + unary-expression` ([§7.7][]). The integer literal 0 has type `int`.
+`0 + unary-expression` ([§7.7][§7.7]). The integer literal 0 has type `int`.
This operator is right associative.
Examples:
Description: An expression of the form -*unary-expression* is treated as if it were written as
-`0 - unary-expression` ([§7.7][]). The integer literal 0 has type `int`.
+`0 - unary-expression` ([§7.7][§7.7]). The integer literal 0 has type `int`.
This operator is right associative.
value is converted to type int and value zero before the operator is evaluated.
> [!NOTE] > The type of the value designated by *unary-expression* may change when the result is stored. See
-> [§7.11][] for a discussion of type change via assignment.
+> [§7.11][§7.11] for a discussion of type change via assignment.
For the prefix `++` operator, the value of *unary-expression* is incremented by 1 of the appropriate type. The result is the new value after incrementing has taken place. The expression `++E` is
-equivalent to `E += 1` ([§7.11.2][]).
+equivalent to `E += 1` ([§7.11.2][§7.11.2]).
For the prefix `--` operator, the value of *unary-expression* is decremented by 1 of the appropriate type. The result is the new value after decrementing has taken place. The expression `--E` is
-equivalent to `E -= 1` ([§7.11.2][]).
+equivalent to `E -= 1` ([§7.11.2][§7.11.2]).
These operators are right associative.
Description:
The unary `-join` operator produces a string that is the concatenation of the value of one or more objects designated by *unary-expression*. (A separator can be inserted by using the binary version
-of this operator ([§7.8.4.4][]).)
+of this operator ([§7.8.4.4][§7.8.4.4]).)
*unary-expression* can be a scalar value or a collection.
Description:
The unary `-split` operator splits one or more strings designated by *unary-expression*, returning their subparts in a constrained 1-dimensional array of string. It treats any contiguous group of white space characters as the delimiter between successive subparts. (An explicit delimiter string
-can be specified by using the binary version of this operator ([§7.8.4.5][]).) This operator has two
-variants ([§7.8][]).
+can be specified by using the binary version of this operator ([§7.8.4.5][§7.8.4.5]).) This operator has two
+variants ([§7.8][§7.8]).
The delimiter text is not included in the resulting strings. Leading and trailing white space in the input string is ignored. An input string that is empty or contains white space only results in an
Description:
A *range-expression* creates an unconstrained 1-dimensional array whose elements are the values of the int sequence specified by the range bounds. The values designated by the operands are converted
-to int, if necessary ([§6.4][]). The operand designating the lower value after conversion is the
+to int, if necessary ([§6.4][§6.4]). The operand designating the lower value after conversion is the
*lower bound*, while the operand designating the higher value after conversion is the *upper bound*. Both bounds may be the same, in which case, the resulting array has length 1. If the left operand designates the lower bound, the sequence is in ascending order. If the left operand designates the
example, the range `5..8` can also be generated using `5,6,7,8`. However, if an
descending sequence is needed without having an array, an implementation may avoid generating an actual array. For example, in `foreach ($i in 1..5) { ... }`, no array need be created.
-A *range-expression* can be used to specify an array slice ([§9.9][]).
+A *range-expression* can be used to specify an array slice ([§9.9][§9.9]).
Examples:
display width, and *FormatString* indicates the (optional) format. If the width
exceeds the specified width, the width is increased accordingly. Values whose positions are not referenced in *FormatString* are ignored after being evaluated for any side effects. If *N* refers to a non-existent position, the behavior is implementation defined. Value of type `$null` and void
-are formatted as empty strings. Arrays are formatted as for *sub-expression* ([§7.1.6][]). To
+are formatted as empty strings. Arrays are formatted as for *sub-expression* ([§7.1.6][§7.1.6]). To
include the characters "{" and "}" in a format specification without their being interpreted as format delimiters, write them as "{{" and "}}", respectively.
multiplicative-expression:
Description: The result of the multiplication operator `*` is the product of the values designated by the two
-operands after the usual arithmetic conversions ([§6.15][]) have been applied.
+operands after the usual arithmetic conversions ([§6.15][§6.15]) have been applied.
This operator is left associative.
Description:
When the left operand designates a string the binary `*` operator creates a new string that contains the one designated by the left operand replicated the number of times designated by the value of the
-right operand as converted to integer type ([§6.4][]).
+right operand as converted to integer type ([§6.4][§6.4]).
This operator is left associative.
Description:
When the left operand designates an array the binary `*` operator creates a new unconstrained 1ΓÇædimensional array that contains the value designated by the left operand replicated the number of
-times designated by the value of the right operand as converted to integer type ([§6.4][]). A
+times designated by the value of the right operand as converted to integer type ([§6.4][§6.4]). A
replication count of zero results in an array of length 1. If the left operand designates a
-multidimensional array, it is flattened ([§9.12][]) before being used.
+multidimensional array, it is flattened ([§9.12][§9.12]) before being used.
This operator is left associative.
Description:
The result of the division operator `/` is the quotient when the value designated by the left operand is divided by the value designated by the right operand after the usual arithmetic
-conversions ([§6.15][]) have been applied.
+conversions ([§6.15][§6.15]) have been applied.
If an attempt is made to perform integer or decimal division by zero, an implementation-defined terminating error is raised.
Description:
The result of the remainder operator `%` is the remainder when the value designated by the left operand is divided by the value designated by the right operand after the usual arithmetic
-conversions ([§6.15][]) have been applied.
+conversions ([§6.15][§6.15]) have been applied.
If an attempt is made to perform integer or decimal division by zero, an implementation-defined terminating error is raised.
additive-expression:
Description: The result of the addition operator `+` is the sum of the values designated by the two operands
-after the usual arithmetic conversions ([§6.15][]) have been applied.
+after the usual arithmetic conversions ([§6.15][§6.15]) have been applied.
This operator is left associative.
Description:
When the left operand designates a string the binary `+` operator creates a new string that contains the value designated by the left operand followed immediately by the value(s) designated by the
-right operand as converted to type string ([§6.8][]).
+right operand as converted to type string ([§6.8][§6.8]).
This operator is left associative.
Description:
When the left operand designates an array the binary `+` operator creates a new unconstrained 1ΓÇædimensional array that contains the elements designated by the left operand followed immediately by the value(s) designated by the right operand. Multidimensional arrays present in either operand
-are flattened ([§9.12][]) before being used.
+are flattened ([§9.12][§9.12]) before being used.
This operator is left associative.
Description:
The result of the subtraction operator `-` is the difference when the value designated by the right operand is subtracted from the value designated by the left operand after the usual arithmetic
-conversions ([§6.15][]) have been applied.
+conversions ([§6.15][§6.15]) have been applied.
This operator is left associative.
Description:
There are two *equality* *operators*: equality (`-eq`) and inequality (`-ne`); and four *relational operators*: less-than (`-lt`), less-than-or-equal-to (`-le`), greater-than (`-gt`), and
-greater-than-or-equal-to (`-ge`). Each of these has two variants ([§7.8][]).
+greater-than-or-equal-to (`-ge`). Each of these has two variants ([§7.8][§7.8]).
For two strings to compare equal, they must have the same length and contents, and letter case, if appropriate.
Examples:
Description: There are four *containment* *operators*: contains (`-contains`), does-not-contain (`ΓÇænotcontains`),
-in (`-in`) and not-in (`-notin`). Each of these has two variants ([§7.8][]).
+in (`-in`) and not-in (`-notin`). Each of these has two variants ([§7.8][§7.8]).
The containment operators return a result of type bool that indicates whether a value occurs (or does not occur) at least once in the elements of an array. With `-contains` and `ΓÇænotcontains`, the
Description:
If the left operand does not designate a collection, the result has type `bool`. Otherwise, the result is a possibly empty unconstrained 1-dimensional array containing the elements of the collection that test True when compared to the value designated by the right operand. The right
-operand may designate a string that contains wildcard expressions ([§3.15][]). These operators have
-two variants ([§7.8][]).
+operand may designate a string that contains wildcard expressions ([§3.15][§3.15]). These operators have
+two variants ([§7.8][§7.8]).
Examples:
is `$true`, the elements of the Hashtable `$matches` are set to the strings that
do-not-match) the value designated by the right operand. Otherwise, the result is a possibly empty unconstrained 1-dimensional array containing the elements of the collection that test True when compared to the value designated by the right operand, and `$matches` is not set. The right operand
-may designate a string that contains regular expressions ([§3.16][]), in which case, it is referred
-to as a *pattern*. These operators have two variants ([§7.8][]).
+may designate a string that contains regular expressions ([§3.16][§3.16]), in which case, it is referred
+to as a *pattern*. These operators have two variants ([§7.8][§7.8]).
-These operators support submatches ([§7.8.4.6][]).
+These operators support submatches ([§7.8.4.6][§7.8.4.6]).
Examples:
Description:
The `-replace` operator allows text replacement in one or more strings designated by the left operand using the values designated by the right operand. This operator has two variants
-([§7.8][]). The right operand has one of the following forms:
+([§7.8][§7.8]). The right operand has one of the following forms:
-- The string to be located, which may contain regular expressions ([§3.16][]). In this case, the
+- The string to be located, which may contain regular expressions ([§3.16][§3.16]). In this case, the
replacement string is implicitly "". - An array of 2 objects containing the string to be located, followed by the replacement string.
If the left operand designates a string, the result has type string. If the left
a 1ΓÇædimensional array of string, the result is an unconstrained 1-dimensional array, whose length is the same as for left operand's array, containing the input strings after replacement has completed.
-This operator supports submatches ([§7.8.4.6][]).
+This operator supports submatches ([§7.8.4.6][§7.8.4.6]).
Examples:
Examples:
Description: The binary `-join` operator produces a string that is the concatenation of the value of one or more
-objects designated by the left operand after having been converted to string ([§6.7][]), if
+objects designated by the left operand after having been converted to string ([§6.7][§6.7]), if
necessary. The string designated by the right operand is used to separate the (possibly empty) values in the resulting string.
Description:
The binary `-split` operator splits one or more strings designated by the left operand, returning their subparts in a constrained 1-dimensional array of string. This operator has two variants
-([§7.8][]). The left operand can designate a scalar value or an array of strings. The right operand
+([§7.8][§7.8]). The left operand can designate a scalar value or an array of strings. The right operand
has one of the following forms: - A *delimiter string*
has one of the following forms:
- A script block - An array of 2 objects containing a script block followed by a numeric split count
-The delimiter string may contain regular expressions ([§3.16][]). It is used to locate subparts with
+The delimiter string may contain regular expressions ([§3.16][§3.16]). It is used to locate subparts with
the input strings. The delimiter is not included in the resulting strings. If the left operand designates an empty string, that results in an empty string element. If the delimiter string is an empty string, it is found at every character position in the input strings.
Here is the set of option names:
| SimpleMatch | Use simple string comparison when evaluating the delimiter. | | Singleline | This mode recognizes only the start and end of strings. It is the default mode. |
-The script block ([§7.1.8][]) specifies the rules for determining the delimiter, and must evaluate
+The script block ([§7.1.8][§7.1.8]) specifies the rules for determining the delimiter, and must evaluate
to type bool. Examples:
Description:
The shift left (`-shl`) operator and shift right (`-shr`) operator convert the value designed by the left operand to an integer type and the value designated by the right operand to int, if necessary,
-using the usual arithmetic conversions ([§6.15][]).
+using the usual arithmetic conversions ([§6.15][§6.15]).
The shift left operator shifts the left operand left by a number of bits computed as described below. The low-order empty bit positions are set to zero.
Description:
The bitwise AND operator `-band`, the bitwise OR operator `-bor`, and the bitwise XOR operator -bxor convert the values designated by their operands to integer types, if necessary, using the usual
-arithmetic conversions ([§6.15][]). After conversion, if both values have type int that is the type
+arithmetic conversions ([§6.15][§6.15]). After conversion, if both values have type int that is the type
of the result. Otherwise, if both values have type long, that is the type of the result. If one value has type int and the other has type long, the type of the result is long. Otherwise, the expression is ill formed. The result is the bitwise AND, bitwise OR, or bitwise XOR, respectively,
logical-expression:
Description: The logical AND operator `-and` converts the values designated by its operands to `bool`, if
-necessary ([§6.2][]). The result is the logical AND of the possibly converted operand values, and
+necessary ([§6.2][§6.2]). The result is the logical AND of the possibly converted operand values, and
has type `bool`. If the left operand evaluates to False the right operand is not evaluated. The logical OR operator `-or` converts the values designated by its operands to `bool`, if necessary
-([§6.2][]). The result is the logical OR of the possibly converted operand values, and has type
+([§6.2][§6.2]). The result is the logical OR of the possibly converted operand values, and has type
`bool`. If the left operand evaluates to True the right operand is not evaluated. The logical XOR operator `-xor` converts the values designated by its operands to `bool`
-([§6.2][]). The result is the logical XOR of the possibly converted operand values, and has type
+([§6.2][§6.2]). The result is the logical XOR of the possibly converted operand values, and has type
`bool`. These operators are left associative.
assignment-operator: *one of
Description: An assignment operator stores a value in the writable location designated by *expression*. For a
-discussion of *assignment-operator* `=` see [§7.11.1][]. For a discussion of all other
-*assignment-operator*s see [§7.11.2][].
+discussion of *assignment-operator* `=` see [§7.11.1][§7.11.1]. For a discussion of all other
+*assignment-operator*s see [§7.11.2][§7.11.2].
An assignment expression has the value designated by *expression* after the assignment has taken place; however, that assignment expression does not itself designate a writable location. If
-*expression* is type-constrained ([§5.3][]), the type used in that constraint is the type of the
+*expression* is type-constrained ([§5.3][§5.3]), the type used in that constraint is the type of the
result; otherwise, the type of the result is the type after the usual arithmetic conversions
-([§6.15][]) have been applied.
+([§6.15][§6.15]) have been applied.
This operator is right associative.
than there are *expression* writable locations, all but the right-most *expressi
the corresponding *statement* value and the right-most *expression* location becomes an unconstrained 1-dimensional array with all the remaining *statement* values as elements.
-For statements that have values ([§8.1.2][]), *statement* can be a statement.
+For statements that have values ([§8.1.2][§8.1.2]), *statement* can be a statement.
Examples:
Description:
A *compound assignment* has the form `E1 op= E2`, and is equivalent to the simple assignment expression `E1 = E1 op (E2)` except that in the compound assignment case the expression *E1* is
-evaluated only once. If *expression* is type-constrained ([§5.3][]), the type used in that
+evaluated only once. If *expression* is type-constrained ([§5.3][§5.3]), the type used in that
constraint is the type of the result; otherwise, the type of the result is determined by *op*. For
-`*=`, see [§7.6.1][], [§7.6.2][], [§7.6.3][]; for `/=`, see [§7.6.4][]; for `%=`, see [§7.6.5][];
-for `+=`, see [§7.7.1][], [§7.7.2][], [§7.7.3][]; for `-=`, see [§7.7.5][].
+`*=`, see [§7.6.1][§7.6.1], [§7.6.2][§7.6.2], [§7.6.3][§7.6.3]; for `/=`, see [§7.6.4][§7.6.4]; for `%=`, see [§7.6.5][§7.6.5];
+for `+=`, see [§7.7.1][§7.7.1], [§7.7.2][§7.7.2], [§7.7.3][§7.7.3]; for `-=`, see [§7.7.5][§7.7.5].
> [!NOTE] > An operand designating an unconstrained value of numeric type may have its type changed by an
lang-spec Chapter 08 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-08.md
labeled-statement:
Description:
-An iteration statement ([§8.4][]) or a switch statement ([§8.6][]) may optionally be preceded
+An iteration statement ([§8.4][§8.4]) or a switch statement ([§8.6][§8.6]) may optionally be preceded
immediately by one statement label, *label*. A statement label is used as the optional target of a
-break ([§8.5.1][]) or continue ([§8.5.2][]) statement. However, a label does not alter the flow of
+break ([§8.5.1][§8.5.1]) or continue ([§8.5.2][§8.5.2]) statement. However, a label does not alter the flow of
control. White space is not permitted between the colon (`:`) and the token that follows it.
verbatim-command-argument:
Description:
-*redirections* is discussed in [§7.12][]; *assignment-expression* is discussed in [§7.11][]; and the
-*command-invocation-operator* dot (`.`) is discussed in [§3.5.5][]. For a discussion of
-argument-to-parameter mapping in command invocations, see [§8.14][].
+*redirections* is discussed in [§7.12][§7.12]; *assignment-expression* is discussed in [§7.11][§7.11]; and the
+*command-invocation-operator* dot (`.`) is discussed in [§3.5.5][§3.5.5]. For a discussion of
+argument-to-parameter mapping in command invocations, see [§8.14][§8.14].
The first command in a *pipeline* is an expression or a command invocation. Typically, a command invocation begins with a *command-name*, which is usually a bare identifier. *command-elements*
governing arguments are as follows:
- An argument that is not an expression, but which contains arbitrary text without unescaped white space, is treated as though it were double quoted. Letter case is preserved. -- Variable substitution and sub-expression expansion ([§2.3.5.2][]) takes place inside
+- Variable substitution and sub-expression expansion ([§2.3.5.2][§2.3.5.2]) takes place inside
*expandable-string-literal*s and *expandable-here-string-literal*s. - Text inside quotes allows leading, trailing, and embedded white space to be included in the
governing arguments are as follows:
- Putting parentheses around an argument causes that expression to be evaluated with the result being passed instead of the text of the original expression. -- To pass an argument that looks like a switch parameter ([§2.3.4][]) but is not intended as such,
+- To pass an argument that looks like a switch parameter ([§2.3.4][§2.3.4]) but is not intended as such,
enclose that argument in quotes. - When specifying an argument that matches a parameter having the `[switch]` type constraint
- ([§8.10.5][]), the presence of the argument name on its own causes that parameter to be set to
+ ([§8.10.5][§8.10.5]), the presence of the argument name on its own causes that parameter to be set to
`$true`. However, the parameter's value can be set explicitly by appending a suffix to the argument. For example, given a type constrained parameter *p*, an argument of `-p:$true` sets p to True, while `-p:$false` sets p to False.
echoargs.exe --% "%path%" # %path% is replaced with the value $env:path
The order of evaluation of arguments is unspecified.
-For information about parameter binding see [§8.14][]. For information about name lookup see
-[§3.8][].
+For information about parameter binding see [§8.14][§8.14]. For information about name lookup see
+[§3.8][§3.8].
Once argument processing has been completed, the command is invoked. If the invoked command
-terminates normally ([§8.5.4][]), control reverts to the point in the script or function immediately
+terminates normally ([§8.5.4][§8.5.4]), control reverts to the point in the script or function immediately
following the command invocation. For a description of the behavior on abnormal termination see
-`break` ([§8.5.1][]), `continue` ([§8.5.2][]), `throw` ([§8.5.3][]), `exit` ([§8.5.5][]), `try`
-([§8.7][]), and `trap` ([§8.8][]).
+`break` ([§8.5.1][§8.5.1]), `continue` ([§8.5.2][§8.5.2]), `throw` ([§8.5.3][§8.5.3]), `exit` ([§8.5.5][§8.5.5]), `try`
+([§8.7][§8.7]), and `trap` ([§8.8][§8.8]).
Ordinarily, a command is invoked by using its name followed by any arguments. However, the command-invocation operator, &, can be used. If the command name contains unescaped white space, it
value `$null`, *pipeline* is treated as a collection of zero elements.
If the *foreach-parameter* `-parallel` is specified, the behavior is implementation defined.
-The *foreach-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][]).
+The *foreach-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][§8.10.2]).
-Every foreach statement has its own enumerator, `$foreach` ([§2.3.2.2][], [§4.5.16][]), which exists
+Every foreach statement has its own enumerator, `$foreach` ([§2.3.2.2][§2.3.2.2], [§4.5.16][§4.5.16]), which exists
only while that loop is executing. The objects produced by *pipeline* are collected before *statement-block* begins to execute.
A break statement with a *label-expression* is referred to as a *labeled break s
statement without a *label-expression* is referred to as an *unlabeled break statement*. Outside a trap statement, an unlabeled break statement directly within an iteration statement
-([§8.4][]) terminates execution of that smallest enclosing iteration statement. An unlabeled break
-statement directly within a switch statement ([§8.6][]) terminates pattern matching for the current
-switch's *switch-condition*. See ([§8.8][]) for details of using break from within a trap statement.
+([§8.4][§8.4]) terminates execution of that smallest enclosing iteration statement. An unlabeled break
+statement directly within a switch statement ([§8.6][§8.6]) terminates pattern matching for the current
+switch's *switch-condition*. See ([§8.8][§8.8]) for details of using break from within a trap statement.
An iteration statement or a switch statement may optionally be preceded immediately by one statement
-label ([§8.1.1][]).Such a statement label may be used as the target of a labeled break statement, in
+label ([§8.1.1][§8.1.1]).Such a statement label may be used as the target of a labeled break statement, in
which case, that statement terminates execution of the targeted enclosing iteration statement. A labeled break need not be resolved in any local scope; the search for a matching label may
Description:
A `continue` statement with a *label-expression* is referred to as a *labeled continue statement*. A continue statement without a *label-expression* is referred to as an *unlabeled continue statement*.
-The use of `continue` from within a trap statement is discussed in [§8.8][].
+The use of `continue` from within a trap statement is discussed in [§8.8][§8.8].
An unlabeled `continue` statement within a loop terminates execution of the current loop and
-transfers control to the closing brace of the smallest enclosing iteration statement ([§8.4][]). An
+transfers control to the closing brace of the smallest enclosing iteration statement ([§8.4][§8.4]). An
unlabeled `continue` statement within a switch terminates execution of the current `switch`
-iteration and transfers control to the smallest enclosing `switch`'s *switch-condition* ([§8.6][]).
+iteration and transfers control to the smallest enclosing `switch`'s *switch-condition* ([§8.6][§8.6]).
-An iteration statement or a `switch` statement ([§8.6][]) may optionally be preceded immediately by
-one statement label ([§8.1.1][]). Such a statement label may be used as the target of an enclosed
+An iteration statement or a `switch` statement ([§8.6][§8.6]) may optionally be preceded immediately by
+one statement label ([§8.1.1][§8.1.1]). Such a statement label may be used as the target of an enclosed
labeled `continue` statement, in which case, that statement terminates execution of the current loop or `switch` iteration, and transfers control to the targeted enclosing iteration or `switch` statement label.
for ($i = 1; $i -le 2; $i++) {
Description: An exception is a way of handling a system- or application-level error condition. The throw
-statement raises an exception. (See [§8.7][] for a discussion of exception handling.)
+statement raises an exception. (See [§8.7][§8.7] for a discussion of exception handling.)
If *pipeline* is omitted and the throw statement is not in a *catch-clause*, the behavior is implementation defined. If *pipeline* is present and the throw statement is in a *catch-clause*, the
If *pipeline* is present, the type of the exception thrown is implementation def
When an exception is thrown, control is transferred to the first catch clause in an enclosing try statement that can handle the exception. The location at which the exception is thrown initially is
-called the *throw point*. Once an exception is thrown the steps described in [§8.7][] are followed
+called the *throw point*. Once an exception is thrown the steps described in [§8.7][§8.7] are followed
repeatedly until a catch clause that matches the exception is found or none can be found. Examples:
patterns with different types.
If the value of *switch-condition* matches a pattern value, that pattern's *statement-block* is executed. If multiple pattern values match the value of *switch-condition*, each matching pattern's *statement-block* is executed, in lexical order, unless any of those *statement-block*s contains a
-`break` statement ([§8.5.1][]).
+`break` statement ([§8.5.1][§8.5.1]).
If the value of *switch-condition* does not match any pattern value, if a `default` switch clause exists, its *statement-block* is executed; otherwise, pattern matching for that *switch-condition*
On entry to each *statement-block*, `$_` is automatically assigned the value of
*switch-condition* that caused control to go to that *statement-block*. `$_` is also available in that *statement-block*'s *switch-clause-condition*.
-Matching of non-strings is done by testing for equality ([§7.8.1][]).
+Matching of non-strings is done by testing for equality ([§7.8.1][§7.8.1]).
If the matching involves strings, by default, the comparison is case-insensitive. The presence of the *switch-parameter* `-casesensitive` makes the comparison case-sensitive.
-A pattern may contain wildcard characters ([§3.15][]), in which case, wildcard string comparisons
+A pattern may contain wildcard characters ([§3.15][§3.15]), in which case, wildcard string comparisons
are performed, but only if the *switch-parameter* -wildcard is present. By default, the comparison is case-insensitive.
-A pattern may contain a regular expression ([§3.16][]), in which case, regular expression string
+A pattern may contain a regular expression ([§3.16][§3.16]), in which case, regular expression string
comparisons are performed, but only if the *switch-parameter* `-regex` is present. By default, the comparison is case-insensitive. If `-regex` is present and a pattern is matched, `$matches` is defined in the *switch-clause* *statement-block* for that pattern.
If conflicting *switch-parameter*s are specified, the lexically final one prevai
If the *switch-parameter* `ΓÇæparallel` is specified, the behavior is implementation defined.
-The *switch-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][]).
+The *switch-parameter* `‑parallel` is only allowed in a workflow ([§8.10.2][§8.10.2]).
If a pattern is a *script-block-expression*, that block is evaluated and the result is converted to bool, if necessary. If the result has the value `$true`, the corresponding *statement-block* is
executed; otherwise, it is not.
If *switch-condition* designates multiple values, the switch is applied to each value in lexical order using the rules described above for a *switch-condition* that designates a single value. Every
-switch statement has its own enumerator, `$switch` ([§2.3.2.2][], [§4.5.16][]), which exists only
+switch statement has its own enumerator, `$switch` ([§2.3.2.2][§2.3.2.2], [§4.5.16][§4.5.16]), which exists only
while that switch is executing.
-A switch statement may have a label, and it may contain labeled and unlabeled break ([§8.5.1][]) and
-continue ([§8.5.2][]) statements.
+A switch statement may have a label, and it may contain labeled and unlabeled break ([§8.5.1][§8.5.1]) and
+continue ([§8.5.2][§8.5.2]) statements.
If *switch-condition* is `-file` *switch-filename*, instead of iterating over the values in an expression, the switch iterates over the values in the file designated by *switch-filename*.The file
Description:
The try statement provides a mechanism for catching exceptions that occur during execution of a block. The try statement also provides the ability to specify a block of code that is always executed when control leaves the try statement. The process of raising an exception via the throw
-statement is described in [§8.5.3][].
+statement is described in [§8.5.3][§8.5.3].
A *try block* is the *statement-block* associated with the try statement. A *catch block* is the *statement-block* associated with a *catch-clause*. A *finally block* is the *statement-block*
next enclosing `try` statement. If another exception was in the process of being
exception is lost. The process of generating an exception is further discussed in the description of the `throw` statement.
-`try` statements can co-exist with `trap` statements; see [§8.8][] for details.
+`try` statements can co-exist with `trap` statements; see [§8.8][§8.8] for details.
Examples:
trap-statement:
Description:
-A `trap` statement with and without *type-literal* is analogous to a `catch` block ([§8.7][]) with
+A `trap` statement with and without *type-literal* is analogous to a `catch` block ([§8.7][§8.7]) with
and without *catch-type-list*, respectively, except that a `trap` statement can trap only one type at a time.
stream, the exception is considered handled, and execution continues with the st
following the one in the scope containing the `trap` statement that made the exception visible. The cause of the exception might be in a command called by the command containing the `trap` statement.
-If the final statement executed in a `trap`'s *statement-body* is continue ([§8.5.2][]), the writing
+If the final statement executed in a `trap`'s *statement-body* is continue ([§8.5.2][§8.5.2]), the writing
of the error object to the error stream is suppressed, and execution continues with the statement immediately following the one in the scope containing the trap statement that made the exception
-visible. If the final statement executed in a `trap`'s *statement-body* is break ([§8.5.1][]), the
+visible. If the final statement executed in a `trap`'s *statement-body* is break ([§8.5.1][§8.5.1]), the
writing of the error object to the error stream is suppressed, and the exception is re-thrown. Within a `trap` statement the variable `$_` contains a description of the current error.
Whereas an ordinary function runs once in a pipeline and accesses the input coll
a *filter* is a special kind of function that executes once for each object in the input collection. The object currently being processed is available via the variable `$_`.
-A filter with no named blocks ([§8.10.7][]) is equivalent to a function with a process block, but
+A filter with no named blocks ([§8.10.7][§8.10.7]) is equivalent to a function with a process block, but
without any begin block or end block. Consider the following filter function definition and calls:
filter Get-Square2 { # make the function a filter
6, 10, -3 | Get-Square2 # collection has 3 elements ```
-Each filter is an instance of the class `System.Management.Automation.FilterInfo` ([§4.5.11][]).
+Each filter is an instance of the class `System.Management.Automation.FilterInfo` ([§4.5.11][§4.5.11]).
### 8.10.2 Workflow functions
that, for non-negative exponent values, computes `$base^$exponent^` and returns
When a script, function, or filter begins execution, each parameter is initialized to its corresponding argument's value. If there is no corresponding argument and a default value
-([§8.10.4][]) is supplied, that value is used; otherwise, the value `$null` is used. As such, each
+([§8.10.4][§8.10.4]) is supplied, that value is used; otherwise, the value `$null` is used. As such, each
parameter is a new variable just as if it was initialized by assignment at the start of the *script-block*.
F -a 2 -d 3 4 5 # $a is 2, $b is 4, $c is 5, $d is 3, $args Length 0
F 2 3 4 5 -c 7 -a 1 # $a is 1, $b is 2, $c is 7, $d is 3, $args Length 2 ```
-For more information about parameter binding see [§8.14][].
+For more information about parameter binding see [§8.14][§8.14].
### 8.10.4 Parameter initializers
Process 10 20 -trace:$true # $trace is True, $p1 is 10, $p2 is 20
When a script, function, or filter is used in a pipeline, a collection of values is delivered to that script or function. The script, function, or filter gets access to that collection via the
-enumerator $input ([§2.3.2.2][], [§4.5.16][]), which is defined on entry to that script, function,
+enumerator $input ([§2.3.2.2][§2.3.2.2], [§4.5.16][§4.5.16]), which is defined on entry to that script, function,
or filter. Consider the following function definition and calls:
the last pipeline object has been delivered.
### 8.10.8 dynamicParam block
-The subsections of [§8.10][] thus far deal with *static parameters*, which are defined as part of
+The subsections of [§8.10][§8.10] thus far deal with *static parameters*, which are defined as part of
the source code. It is also possible to define *dynamic parameters* via a *dynamicParam block*,
-another form of named block ([§8.10.7][]), which is marked with the keyword `dynamicParam`. Much of
+another form of named block ([§8.10.7][§8.10.7]), which is marked with the keyword `dynamicParam`. Much of
this machinery is implementation defined. Dynamic parameters are parameters of a cmdlet, function, filter, or script that are available under
param ( [Parameter(Mandatory = $true, ValueFromPipeline=$true)]
The one parameter, `$ComputerName`, has type `string[]`, it is required, and it takes input from the pipeline.
-See [§12.3.7][] for a discussion of the **Parameter** attribute and for more examples.
+See [§12.3.7][§12.3.7] for a discussion of the **Parameter** attribute and for more examples.
## 8.11 The parallel statement
parallel-statement:
The parallel statement contains zero or more statements that are executed in an implementation defined manner.
-A parallel statement is only allowed in a workflow ([§8.10.2][]).
+A parallel statement is only allowed in a workflow ([§8.10.2][§8.10.2]).
## 8.12 The sequence statement
sequence-statement:
The sequence statement contains zero or more statements that are executed in an implementation defined manner.
-A sequence statement is only allowed in a workflow ([§8.10.2][]).
+A sequence statement is only allowed in a workflow ([§8.10.2][§8.10.2]).
## 8.13 The inlinescript statement
inlinescript-statement:
The inlinescript statement contains zero or more statements that are executed in an implementation defined manner.
-A inlinescript statement is only allowed in a workflow ([§8.10.2][]).
+A inlinescript statement is only allowed in a workflow ([§8.10.2][§8.10.2]).
## 8.14 Parameter binding
The same parameter name cannot be used multiple times with or without different
values. Parameters can have attributes (§12). For information about the individual attributes see the
-sections within [§12.3][]. For information about parameter sets see [§12.3][].7.
+sections within [§12.3][§12.3]. For information about parameter sets see [§12.3][§12.3].7.
A script, function, filter, or cmdlet can receive arguments via the invocation command line, from the pipeline, or from both. Here are the steps, in order, for resolving parameter binding: 1. Bind all named parameters, then 1. Bind positional parameters, then
-1. Bind from the pipeline by value ([§12.3.7][]) with exact match, then
-1. Bind from the pipeline by value ([§12.3.7][]) with conversion, then
-1. Bind from the pipeline by name ([§12.3.7][]) with exact match, then
-1. Bind from the pipeline by name ([§12.3.7][]) with conversion
+1. Bind from the pipeline by value ([§12.3.7][§12.3.7]) with exact match, then
+1. Bind from the pipeline by value ([§12.3.7][§12.3.7]) with conversion, then
+1. Bind from the pipeline by name ([§12.3.7][§12.3.7]) with exact match, then
+1. Bind from the pipeline by name ([§12.3.7][§12.3.7]) with conversion
-Several of these steps involve conversion, as described in [§6.][] However, the set of conversions
+Several of these steps involve conversion, as described in [§6.][§6.] However, the set of conversions
used in binding is not exactly the same as that used in language conversions. Specifically, - Although the value `$null` can be cast to bool, `$null` cannot be bound to `bool`.
lang-spec Chapter 09 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-09.md
Title: Arrays
PowerShell supports arrays of one or more dimensions with each dimension having zero or more *elements*. Within a dimension, elements are numbered in ascending integer order starting at zero.
-Any individual element can be accessed via the array subscript operator `[]` ([§7.1.4][]). The
+Any individual element can be accessed via the array subscript operator `[]` ([§7.1.4][§7.1.4]). The
number of dimensions in an array is called its *rank*. An element can contain a value of any type including an array type. An array having one or more
$a[1,1] = $null
A 1-dimensional array has type `type[]`, a 2-dimensional array has type `type[,]`, a 3-dimensional array has type `type[,,]`, and so on, where *type* is object for an unconstrained type array, or the
-constrained type for a constrained array ([§9.4][]).
+constrained type for a constrained array ([§9.4][§9.4]).
-All array types are derived from the type Array ([§4.3.2][]).
+All array types are derived from the type Array ([§4.3.2][§4.3.2]).
## 9.2 Array creation An array is created via an *array creation expression*, which has the following forms: unary comma
-operator ([§7.2.1][]) ,*array-expression* ([§7.1.7][]), binary comma operator ([§7.3][]), range
-operator ([§7.4][]), or [New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet.
+operator ([§7.2.1][§7.2.1]) ,*array-expression* ([§7.1.7][§7.1.7]), binary comma operator ([§7.3][§7.3]), range
+operator ([§7.4][§7.4]), or [New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet.
Here are some examples of array creation and usage:
element's type (that is, `$false`, zero, or `$null`).
Arrays of arbitrary type and length can be concatenated via the `+` and `+=` operators, both of which result in the creation of a new unconstrained 1-dimensional array. The existing arrays are
-unchanged. See [§7.7.3][] for more information, and [§9.4][] for a discussion of adding to an array
+unchanged. See [§7.7.3][§7.7.3] for more information, and [§9.4][§9.4] for a discussion of adding to an array
of constrained type. ## 9.4 Constraining element types
The syntax for creating a multidimensional array requires the specification of a
becomes the constraint type for that array. However, by specifying type `object[]`, there really is no constraint as a value of any type can be assigned to an element of an array of that type.
-Concatenating two arrays ([§7.7.3][]) always results in a new array that is unconstrained even if
+Concatenating two arrays ([§7.7.3][§7.7.3]) always results in a new array that is unconstrained even if
both arrays are constrained by the same type. For example, ```powershell
$a[1,1] = [int[]](92,93) # element is an array of 2 ints
## 9.7 Negative subscripting
-This is discussed in [§7.1.4.1][].
+This is discussed in [§7.1.4.1][§7.1.4.1].
## 9.8 Bounds checking
-This is discussed in [§7.1.4.1][].
+This is discussed in [§7.1.4.1][§7.1.4.1].
## 9.9 Array slices An *array slice* is an unconstrained 1-dimensional array whose elements are copies of zero or more elements from a collection. An array slice is created via the subscript operator `[]`
-([§7.1.4.5][]).
+([§7.1.4.5][§7.1.4.5]).
## 9.10 Copying an array
foreach ($elem in $a) {
## 9.12 Multidimensional array flattening
-Some operations on a multidimensional array (such as replication ([§7.6.3][]) and concatenation
-([§7.7.3][])) require that array to be *flattened*; that is, to be turned into a 1-dimensional array
+Some operations on a multidimensional array (such as replication ([§7.6.3][§7.6.3]) and concatenation
+([§7.7.3][§7.7.3])) require that array to be *flattened*; that is, to be turned into a 1-dimensional array
of unconstrained type. The resulting array takes on all the elements in row-major order. Consider the following example:
lang-spec Chapter 10 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-10.md
Given a key/value pair object, the key and associated value can be obtained by u
properties Key and Value, respectively. Given one or more keys, the corresponding value(s) can be accessed via the Hashtable subscript
-operator `[]` ([§7.1.4.3][]).
+operator `[]` ([§7.1.4.3][§7.1.4.3]).
-All Hashtables have type `Hashtable` ([§4.3.3][]).
+All Hashtables have type `Hashtable` ([§4.3.3][§4.3.3]).
The order of the keys in the collection returned by Keys is unspecified; however, it is the same order as the associated values in the collection returned by Values.
returned by Keys and Values have type **ICollection**.
## 10.2 Hashtable creation
-A `Hashtable` is created via a hash literal ([§7.1.9][]) or the
+A `Hashtable` is created via a hash literal ([§7.1.9][§7.1.9]) or the
[New-Object](xref:Microsoft.PowerShell.Utility.New-Object) cmdlet. It can be created with zero or more elements. The Count property returns the current element count. ## 10.3 Adding and removing Hashtable elements
-An element can be added to a `Hashtable` by assigning ([§7.11.1][]) a value to a non-existent key
-name or to a subscript ([§7.1.4.3][]) that uses a non-existent key name. Removal of an element
+An element can be added to a `Hashtable` by assigning ([§7.11.1][§7.11.1]) a value to a non-existent key
+name or to a subscript ([§7.1.4.3][§7.1.4.3]) that uses a non-existent key name. Removal of an element
requires the use of the Remove method. For example, ```powershell
$h1.Remove("Salaried") # removes element Salaried
## 10.4 Hashtable concatenation Hashtables can be concatenated via the `+` and `+=` operators, both of which result in the creation
-of a new `Hashtable`. The existing Hashtables are unchanged. See [§7.7.4][] for more information.
+of a new `Hashtable`. The existing Hashtables are unchanged. See [§7.7.4][§7.7.4] for more information.
## 10.5 Hashtables as reference types
lang-spec Chapter 11 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-11.md
Title: Modules
## 11.1 Introduction
-As stated in [§3.14][], a module is a self-contained reusable unit that allows PowerShell code to be
+As stated in [§3.14][§3.14], a module is a self-contained reusable unit that allows PowerShell code to be
partitioned, organized, and abstracted. A module can contain one or more *module members*, which are commands (such as cmdlets and functions) and items (such as variables and aliases). The names of these members can be kept private to the module or they may be *exported* to the session into which
The following cmdlets deal with modules:
- [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module): Identifies the modules that have been, or can be imported - [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module): Adds one or more modules to the
- current session (see [§11.4][])
+ current session (see [§11.4][§11.4])
- [Export-ModuleMember](xref:Microsoft.PowerShell.Core.Export-ModuleMember): Identifies the module members that are to be exported - [Remove-Module](xref:Microsoft.PowerShell.Core.Remove-Module): Removes one or more modules from
- the current session (see [§11.5][])
-- [New-Module](xref:Microsoft.PowerShell.Core.New-Module): Creates a dynamic module (see [§11.7][])
+ the current session (see [§11.5][§11.5])
+- [New-Module](xref:Microsoft.PowerShell.Core.New-Module): Creates a dynamic module (see [§11.7][§11.7])
## 11.2 Writing a script module
When a module is imported, its script file is executed. That process can be conf
one or more parameters in the script file, and passing in corresponding arguments via the ArgumentList parameter of `Import-Module`.
-Consider the following script that uses these functions and aliases defined in [§11.2][]:
+Consider the following script that uses these functions and aliases defined in [§11.2][§11.2]:
`Import-Module` "E:\Scripts\Modules\PSTest\_Temperature" -Verbose
the argument 100.
When the session includes commands of the same kind with the same name, such as two cmdlets with the same name, by default it runs the most recently added command.
-See [§3.5.6][] for a discussion of scope as it relates to modules.
+See [§3.5.6][§3.5.6] for a discussion of scope as it relates to modules.
## 11.5 Removing a script module
removal, as follows:
## 11.6 Module manifests
-As stated in [§11.1][], a manifest module is a file that contains information about a module, and
+As stated in [§11.1][§11.1], a manifest module is a file that contains information about a module, and
controls certain aspects of that module's use. A module need not have a corresponding manifest, but if it does, that manifest has the same name as
$v2 = Get-NextID 100 # get a scriptblock with $startValue of 100
The intent here is that `Get-NextID` return the next ID in a sequence whose start value can be specified. However, multiple sequences must be supported, each with its own `$startValue` and `$nextID` context. This is achieved by the call to the method `[scriptblock]::GetNewClosure`
-([§4.3.7][]).
+([§4.3.7][§4.3.7]).
Each time a new closure is created by `GetNewClosure`, a new dynamic module is created, and the variables in the caller's scope (in this case, the script block containing the increment) are copied
lang-spec Chapter 12 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-12.md
Title: Attributes
# 12. Attributes An *attribute* object associates predefined system information with a *target element*, which can be
-a param block or a parameter ([§8.10][]). Each attribute object has an *attribute type*.
+a param block or a parameter ([§8.10][§8.10]). Each attribute object has an *attribute type*.
Information provided by an attribute is also known as *metadata*. Metadata can be examined by the command or the execution environment to control how the command processes data or before run time by
The positional arguments (if any) precede the named arguments. A named argument
*simple-name*, optionally followed by an equal sign and followed by an *expression*. If the expression is omitted, the value `$true` is assumed.
-The *attribute-name* is a reserved attribute type ([§12.3][]) or some implementation-defined
+The *attribute-name* is a reserved attribute type ([§12.3][§12.3]) or some implementation-defined
attribute type. ## 12.2 Attribute instances
run-time.
To create an object of some attribute type *A*, use the notation `A()`. An attribute is declared by enclosing its instance inside `[]`, as in `[A()]`. Some attribute types have positional and named
-parameters ([§8.14][]), just like functions and cmdlets. For example,
+parameters ([§8.14][§8.14]), just like functions and cmdlets. For example,
`[A(10,IgnoreCase=$true)]`
conversion from `$null` to int.
This attribute is used in the *attribute-list* of *param-block* of a function to indicate that function acts similar to a cmdlet. Specifically, it allows functions to access a number of methods and properties through the $PsCmdlet variable by using begin, process, and end named blocks
-([§8.10.7][]).
+([§8.10.7][§8.10.7]).
When this attribute is present, positional arguments that have no matching positional parameters cause parameter binding to fail and $args is not defined. (Without this attribute $args would take
The following arguments are used to define the characteristics of the parameter:
<tr class="odd"> <td>DefaultParameterSetName (named)</td> <td><p>Type: string; Default value: "__AllParameterSets"</p>
-<p>Specifies the parameter set to use if that cannot be determined from the arguments. See the named argument ParameterSetName in the attribute Parameter ([§12.3.7][]).</p></td>
+<p>Specifies the parameter set to use if that cannot be determined from the arguments. See the named argument ParameterSetName in the attribute Parameter ([§12.3.7][§12.3.7]).</p></td>
</tr> <tr class="even"> <td>PositionalBinding (named)</td> <td><p>Type: bool; Default value: $true</p>
-<p>Specifies whether positional binding is supported or not. The value of this argument is ignored if any parameters specify non-default values for either the named argument Position or the named argument ParameterSetName in the attribute Parameter ([§12.3.7][]). Otherwise, if the argument is $false then no parameters are positional, otherwise parameters are assigned a position based on the order the parameters are specified.</p></td>
+<p>Specifies whether positional binding is supported or not. The value of this argument is ignored if any parameters specify non-default values for either the named argument Position or the named argument ParameterSetName in the attribute Parameter ([§12.3.7][§12.3.7]). Otherwise, if the argument is $false then no parameters are positional, otherwise parameters are assigned a position based on the order the parameters are specified.</p></td>
</tr> </tbody> </table>
HelpMessage = "An array of computer names.")]<br />
<p>For parameters that belong to multiple parameter sets, add a Parameter attribute for each parameter set. This allows the parameter to be defined differently for each parameter set.</p> <p>A parameter set that contains multiple positional parameters must define unique positions for each parameter. No two positional parameters can specify the same position.</p> <p>If no parameter set is specified for a parameter, the parameter belongs to all parameter sets.</p>
-<p>When multiple parameter sets are defined, the named argument DefaultParameterSetName of the attribute CmdletBinding ([§12.3.5][]) is used to specify the default parameter set. The runtime uses the default parameter set if it cannot determine the parameter set to use based on the information provided by the command, or raises an exception if no default parameter set has been specified.</p>
+<p>When multiple parameter sets are defined, the named argument DefaultParameterSetName of the attribute CmdletBinding ([§12.3.5][§12.3.5]) is used to specify the default parameter set. The runtime uses the default parameter set if it cannot determine the parameter set to use based on the information provided by the command, or raises an exception if no default parameter set has been specified.</p>
<p>The following example shows a function Test with a parameter declaration of two parameters that belong to two different parameter sets, and a third parameter that belongs to both sets:</p> <p>param ( [Parameter(Mandatory = $true,<br /> ParameterSetName = "Computer")]<br />
Test -UserName "Mary","Jack" -SharedParam 20</p></td>
<p>param ( [Parameter(Mandatory = $true,<br /> ValueFromPipeline=$true)]<br /> [string[]] $ComputerName )</p>
-<p>For an example of using this parameter in conjunction with the Alias attribute see [§12.3.1][]. </p></td>
+<p>For an example of using this parameter in conjunction with the Alias attribute see [§12.3.1][§12.3.1]. </p></td>
</tr> <tr class="even"> <td>ValueFromPipelineByPropertyName (named)</td>
characteristics of the parameter:
<tr class="even"> <td>Options (named)</td> <td><p>Type: Regular-Expression-Option</p>
-<p>See [§4.2.6.4][] for the allowed values.</p></td>
+<p>See [§4.2.6.4][§4.2.6.4] for the allowed values.</p></td>
</tr> </tbody> </table>
lang-spec Chapter 13 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-13.md
case-sensitive.
The *common parameters* are a set of cmdlet parameters that can be used with any cmdlet. They are implemented by the PowerShell runtime environment itself, not by the cmdlet developer, and they are automatically available to any cmdlet or function that uses the **Parameter** attribute
-([§12.3.7][]) or **CmdletBinding** attribute ([§12.3.5][]).
+([§12.3.7][§12.3.7]) or **CmdletBinding** attribute ([§12.3.5][§12.3.5]).
Although the common parameters are accepted by any cmdlet, they might not have any semantics for that cmdlet. For example, if a cmdlet does not generate any verbose output, using the **Verbose** common parameter has no effect. Several common parameters override system defaults or preferences that can be set via preference
-variables ([§2.3.2.3][]). Unlike the preference variables, the common parameters affect only the
+variables ([§2.3.2.3][§2.3.2.3]). Unlike the preference variables, the common parameters affect only the
commands in which they are used. > [!NOTE]
lang-spec Chapter 14 https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/lang-spec/chapter-14.md
directives. Comments using such syntax are called *help comments*. The cmdlet
A help comment contains a *help directive* of the form .*name* followed on one or more subsequent lines by the help content text. The help comment can be made up of a series of
-*single-line-comment*s or a *delimited-comment* ([§2.2.3][]). The set of comments comprising the
+*single-line-comment*s or a *delimited-comment* ([§2.2.3][§2.2.3]). The set of comments comprising the
documentation for a single entity is called a *help topic*. For example,
Syntax:
Description: This directive allows for a detailed description of the function or script. (The `.SYNOPSIS`
-directive ([§A.2.11][]) is intended for a brief description.) This directive can be used only once
+directive ([§A.2.11][§A.2.11]) is intended for a brief description.) This directive can be used only once
in each topic. Examples:
Syntax:
Description:
-Specifies the help category of the item in **ForwardHelpTargetName** ([§A.2.5][]). Valid values are
+Specifies the help category of the item in **ForwardHelpTargetName** ([§A.2.5][§A.2.5]). Valid values are
**Alias**, **All**, **Cmdlet**, **ExternalScript**, **FAQ**, **Filter**, **Function**, **General**, **Glossary**, **HelpFile**, **Provider**, and **ScriptCommand**. Use this directive to avoid conflicts when there are commands with the same name. Examples:
-See [§A.2.5][].
+See [§A.2.5][§A.2.5].
### A.2.5 .FORWARDHELPTARGETNAME
Syntax:
Description: This directive allows for a brief description of the function or script. (The `.DESCRIPTION`
-directive ([§A.2.1][]) is intended for a detailed description.) This directive can be used only once
+directive ([§A.2.1][§A.2.1]) is intended for a detailed description.) This directive can be used only once
in each topic. Examples:
learn Add Credentials To Powershell Functions https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/add-credentials-to-powershell-functions.md
# Add Credential support to PowerShell functions > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@joshduffney][]. This
+> The [original version][original version] of this article appeared on the blog written by [@joshduffney][@joshduffney]. This
> article has been edited for inclusion on this site. The PowerShell team thanks Josh for sharing
-> this content with us. Please check out his blog at [duffney.io][].
+> this content with us. Please check out his blog at [duffney.io][duffney.io].
This article shows you how to add credential parameters to PowerShell functions and why you'd want to. A credential parameter is to allow you to run the function or cmdlet as a different user. The
PowerShell session doesn't have that access already.
## Creating credential object
-The [PSCredential][] object represents a set of security credentials such as a user name and
+The [PSCredential][PSCredential] object represents a set of security credentials such as a user name and
password. The object can be passed as a parameter to a function that runs as the user account in that credential object. There are a few ways that you can create a credential object. The first way to create a credential object is to use the PowerShell cmdlet `Get-Credential`. When you run without
things you can add to make it more robust.
## Using credential parameters The following example demonstrates how to use credential parameters. This example shows a function
-called `Set-RemoteRegistryValue`, which is out of [The Pester Book][]. This function defines the
+called `Set-RemoteRegistryValue`, which is out of [The Pester Book][The Pester Book]. This function defines the
credential parameter using the techniques describe in the previous section. The function calls `Invoke-Command` using the `$Credential` variable created by the function. This allows you to change the user who's running `Invoke-Command`. Because the default value of `$Credential` is an empty
Using `Get-Credential` in parentheses `()` at run time causes the `Get-credentia
are prompted for a username and password. You could use the **Credential** or **UserName** parameters of `Get-credential` to pre-populate the username and domain. The following example uses a technique called splatting to pass parameters to the `Set-RemoteRegistryValue` function. For more
-information about splatting, check out the [about_Splatting][] article.
+information about splatting, check out the [about_Splatting][about_Splatting] article.
```powershell $remoteKeyParams = @{
You can also populate a credential variable ahead of time and pass it to the **C
parameter of `Set-RemoteRegistryValue` function. Use this method with Continuous Integration / Continuous Deployment (CI/CD) tools such as Jenkins, TeamCity, and Octopus Deploy. For an example using Jenkins, check out Hodge's blog post
-[Automating with Jenkins and PowerShell on Windows - Part 2][].
+[Automating with Jenkins and PowerShell on Windows - Part 2][Automating with Jenkins and PowerShell on Windows - Part 2].
This example uses the .NET method to create the credential object and a secure string to pass in the password.
function Set-RemoteRegistryValue {
This example uses parameter splatting to call the legacy cmdlet. The `$Credential` object is conditionally added to the hash table for splatting and avoids the need to repeat the `Invoke-Command` script block. To learn more about splatting inside functions, see the
-[Splatting Parameters Inside Advanced Functions][] blog post.
+[Splatting Parameters Inside Advanced Functions][Splatting Parameters Inside Advanced Functions] blog post.
```powershell function Set-RemoteRegistryValue {
Get-AllSQLDatabases -SQLServer SQL01 -Credential $Credential
Creating and storing credential objects securely can be difficult. The following resources can help you maintain PowerShell credentials. -- [BetterCredentials][]-- [Azure Key Vault][]-- [Vault Project][]-- [SecretManagement module][]
+- [BetterCredentials][BetterCredentials]
+- [Azure Key Vault][Azure Key Vault]
+- [Vault Project][Vault Project]
+- [SecretManagement module][SecretManagement module]
<!-- link references --> [original version]: https://duffney.io/addcredentialstopowershellfunctions/
learn Everything About Arrays https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-arrays.md
--- # Everything you wanted to know about arrays
-[Arrays][] are a fundamental language feature of most programming languages. They're a collection of
+[Arrays][Arrays] are a fundamental language feature of most programming languages. They're a collection of
values or objects that are difficult to avoid. Let's take a close look at arrays and everything they have to offer. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## What is an array?
classic off-by-one error.
#### Switch loop
-This is one that is easy to overlook. If you provide an array to a [switch statement][], it
+This is one that is easy to overlook. If you provide an array to a [switch statement][switch statement], it
checks each item in the array. ```powershell
$servers | Select-String SQL
``` I take a closer look at `Select-String`,`-match` and the `$matches` variable in another post called
-[The many ways to use regex][].
+[The many ways to use regex][The many ways to use regex].
### $null or empty
if ( $null -ne $array -and @($array).count -gt 0 )
### All -eq
-I recently saw someone ask [how to verify that every value in an array matches a given value][].
-Reddit user **/u/bis** had this clever [solution][] that checks for any incorrect values and then
+I recently saw someone ask [how to verify that every value in an array matches a given value][how to verify that every value in an array matches a given value].
+Reddit user **/u/bis** had this clever [solution][solution] that checks for any incorrect values and then
flips the result. ```powershell
The reason I'm using `[void]` at the beginning of the line is to suppress the re
.NET calls do this and can create unexpected output. If the only data that you have in your array is strings, then also take a look at using
-[StringBuilder][]. It's almost the same thing but has some methods that are just for dealing with
+[StringBuilder][StringBuilder]. It's almost the same thing but has some methods that are just for dealing with
strings. The `StringBuilder` is specially designed for performance. It's common to see people move to `ArrayList` from arrays. But it comes from a time where C# didn't
every time you read it and that it turns out to be a good reference for you for
come. If you found this to be helpful, please share it with others you think may get value out of it.
-From here, I would recommend you check out a similar post that I wrote about [hashtables][].
+From here, I would recommend you check out a similar post that I wrote about [hashtables][hashtables].
<!-- link references --> [original version]: https://powershellexplained.com/2018-10-15-Powershell-arrays-Everything-you-wanted-to-know/
learn Everything About Exceptions https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md
can easily handle exceptions generated by other people's code or you can generat
exceptions for others to handle. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## Basic terminology
catch [System.IO.FileNotFoundException]
#### The big list of .NET exceptions
-I compiled a master list with the help of the [Reddit/r/PowerShell community][] that contains
+I compiled a master list with the help of the [Reddit/r/PowerShell community][Reddit/r/PowerShell community] that contains
hundreds of .NET exceptions to complement this post. -- [The big list of .NET exceptions][]
+- [The big list of .NET exceptions][The big list of .NET exceptions]
I start by searching that list for exceptions that feel like they would be a good fit for my situation. You should try to use exceptions in the base `System` namespace.
situation. You should try to use exceptions in the base `System` namespace.
### Exceptions are objects If you start using a lot of typed exceptions, remember that they are objects. Different exceptions
-have different constructors and properties. If we look at the [FileNotFoundException][]
+have different constructors and properties. If we look at the [FileNotFoundException][FileNotFoundException]
documentation for `System.IO.FileNotFoundException`, we see that we can pass in a message and a file path.
catch [System.IO.FileNotFoundException]
} ```
-You should consult the [.NET documentation][] for other constructors and object properties.
+You should consult the [.NET documentation][.NET documentation] for other constructors and object properties.
### Re-throwing an exception
learn Everything About Hashtable https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-hashtable.md
--- # Everything you wanted to know about hashtables
-I want to take a step back and talk about [hashtables][]. I use them all the time now. I was
+I want to take a step back and talk about [hashtables][hashtables]. I use them all the time now. I was
teaching someone about them after our user group meeting last night and I realized I had the same confusion about them as he had. Hashtables are really important in PowerShell so it's good to have a solid understanding of them. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## Hashtable as a collection of things
for more advanced stuff later. Skipping this understanding is often a source of
## What is an array?
-Before I jump into what a **Hashtable** is, I need to mention [arrays][] first. For the purpose of
+Before I jump into what a **Hashtable** is, I need to mention [arrays][arrays] first. For the purpose of
this discussion, an array is a list or collection of values or objects. ```powershell
using this approach when you need to cross reference something. I think we would
if PowerShell wasn't so good at filtering on the pipe with `Where-Object`. If you're ever in a situation where performance matters, this approach needs to be considered.
-I won't say that it's faster, but it does fit into the rule of [If performance matters, test it][].
+I won't say that it's faster, but it does fit into the rule of [If performance matters, test it][If performance matters, test it].
#### Multiselection
Here is an example of creating a DHCP scope the normal way.
Add-DhcpServerv4Scope -Name 'TestNetwork' -StartRange'10.0.0.2' -EndRange '10.0.0.254' -SubnetMask '255.255.255.0' -Description 'Network for testlab A' -LeaseDuration (New-TimeSpan -Days 8) -Type "Both" ```
-Without using [splatting][], all those things need to be defined on a single line. It either scrolls
+Without using [splatting][splatting], all those things need to be defined on a single line. It either scrolls
off the screen or will wrap where ever it feels like. Now compare that to a command that uses splatting.
name age
Kevin 36 ```
-I already have detailed write-up for [pscustomobject][] that you should go read after this one. It
+I already have detailed write-up for [pscustomobject][pscustomobject] that you should go read after this one. It
builds on a lot of the things learned here. ## Reading and writing hashtables to file
if you start with a `pscustomobject` so the column order is preserved. But you c
$person | ForEach-Object{ [pscustomobject]$_ } | Export-CSV -Path $path ```
-Again, check out my write-up on using a [pscustomobject][].
+Again, check out my write-up on using a [pscustomobject][pscustomobject].
### Saving a nested hashtable to file
If you need it to be a `[hashtable]` on import, then you need to use the `Export
### Converting JSON to Hashtable If you need to convert JSON to a `[hashtable]`, there's one way that I know of to do it with the
-[JavaScriptSerializer][] in .NET.
+[JavaScriptSerializer][JavaScriptSerializer] in .NET.
```powershell [Reflection.Assembly]::LoadWithPartialName("System.Web.Script.Serialization")
used with member access (`.`) notation. Or, you can use array index (`[]`) notat
### $PSBoundParameters
-[$PSBoundParameters][] is an automatic variable that only exists inside the context of a function.
+[$PSBoundParameters][$PSBoundParameters] is an automatic variable that only exists inside the context of a function.
It contains all the parameters that the function was called with. This isn't exactly a hashtable but close enough that you can treat it like one. That includes removing keys and splatting it to other functions. If you find yourself writing proxy functions, take a closer look at this one.
-See [about_Automatic_Variables][] for more details.
+See [about_Automatic_Variables][about_Automatic_Variables] for more details.
### PSBoundParameters gotcha
$PSDefaultParameterValues[ "Get-*:Verbose" ] = $true
$PSDefaultParameterValues[ "*:Credential" ] = Get-Credential ```
-For a more in-depth breakdown, see this great article on [Automatic Defaults][] by
-[Michael Sorens][].
+For a more in-depth breakdown, see this great article on [Automatic Defaults][Automatic Defaults] by
+[Michael Sorens][Michael Sorens].
## Regex $Matches
learn Everything About If https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-if.md
# Everything you wanted to know about the `if` statement Like many other languages, PowerShell has statements for conditionally executing code in your
-scripts. One of those statements is the [If][] statement. Today we will take a deep dive into one of
+scripts. One of those statements is the [If][If] statement. Today we will take a deep dive into one of
the most fundamental commands in PowerShell. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## Conditional execution
if ( $value -match 'SQL')
``` Regex is a complex language of its own and worth looking into. I talk more about `-match` and
-[the many ways to use regex][] in another article.
+[the many ways to use regex][the many ways to use regex] in another article.
**Variations:**
why I would ever use it.
## Bitwise operators Bitwise operators perform calculations on the bits within the values and produce a new value as the
-result. Teaching [bitwise operators][] is beyond the scope of this article, but here is the list the
+result. Teaching [bitwise operators][bitwise operators] is beyond the scope of this article, but here is the list the
them. - `-band` binary AND
if ( $null -eq $value )
``` There are quite a few nuances when dealing with `$null` values in PowerShell. If you're interested
-in diving deeper, I have an article about [everything you wanted to know about $null][].
+in diving deeper, I have an article about [everything you wanted to know about $null][everything you wanted to know about $null].
### Variable assignment within the condition
-I almost forgot to add this one until [Prasoon Karunan V][] reminded me of it.
+I almost forgot to add this one until [Prasoon Karunan V][Prasoon Karunan V] reminded me of it.
```powershell if ($process=Get-Process notepad -ErrorAction ignore) {$process} else {$false}
switch ( $itemType )
There three possible values that can match the `$itemType`. In this case, it matches with `Role`. I used a simple example just to give you some exposure to the `switch` operator. I talk more
-about [everything you ever wanted to know about the switch statement][] in another article.
+about [everything you ever wanted to know about the switch statement][everything you ever wanted to know about the switch statement] in another article.
### Array inline
-I have a function called [Invoke-SnowSql][] that launches an executable with several command-line
+I have a function called [Invoke-SnowSql][Invoke-SnowSql] that launches an executable with several command-line
arguments. Here is a clip from that function where I build the array of arguments. ```powershell
I like to say that if you expect an exception to happen, then it's not really an
your values and validate your conditions where you can. If you want to dive a little more into actual exception handling, I have an article on
-[everything you ever wanted to know about exceptions][].
+[everything you ever wanted to know about exceptions][everything you ever wanted to know about exceptions].
## Final words
learn Everything About Null https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-null.md
The PowerShell `$null` often appears to be simple but it has a lot of nuances. L
look at `$null` so you know what happens when you unexpectedly run into a `$null` value. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## What is NULL?
everything that doesn't match `$null` and in this case there are no results (Thi
Not only can we create a value that makes both of them evaluate to `$false`, it's possible to create a value where they both evaluate to `$true`. Mathias Jessen (@IISResetMe) has a
-[good post][] that dives into that scenario.
+[good post][good post] that dives into that scenario.
### PSScriptAnalyzer and VSCode
-The [PSScriptAnalyzer][] module has a rule that checks for this issue called
+The [PSScriptAnalyzer][PSScriptAnalyzer] module has a rule that checks for this issue called
`PSPossibleIncorrectComparisonWithNull`. ```powershell
if ( $value.count -eq 1 )
## Empty null There is one special type of `$null` that acts differently than the others. I am going to call it
-the empty `$null` but it's really a [System.Management.Automation.Internal.AutomationNull][]. This
+the empty `$null` but it's really a [System.Management.Automation.Internal.AutomationNull][System.Management.Automation.Internal.AutomationNull]. This
empty `$null` is the one you get as the result of a function or script block that returns nothing (a void result).
learn Everything About Pscustomobject https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-pscustomobject.md
have a simple way to create structured data. Take a look at the first example an
better idea of what that means. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## Creating a PSCustomObject
$myObject = Get-Content -Path $Path | ConvertFrom-Json
``` I cover more ways to save objects to a file in my article on
-[The many ways to read and write to files][].
+[The many ways to read and write to files][The many ways to read and write to files].
## Working with properties
people do it:
$myObject.PSObject.TypeNames.Insert(0,"My.Object") ```
-I recently discovered another way to do this from this [post by /u/markekraus][]. I did a little
-digging and more posts about the idea from [Adam Bertram][] and [Mike Shepard][] where they talk
+I recently discovered another way to do this from this [post by /u/markekraus][post by /u/markekraus]. I did a little
+digging and more posts about the idea from [Adam Bertram][Adam Bertram] and [Mike Shepard][Mike Shepard] where they talk
about this approach that allows you to define it inline. ```powershell
name, we can do some more things.
## Using DefaultPropertySet (the long way) PowerShell decides for us what properties to display by default. A lot of the native commands have a
-`.ps1xml` [formatting file][] that does all the heavy lifting. From this [post by Boe Prox][],
+`.ps1xml` [formatting file][formatting file] that does all the heavy lifting. From this [post by Boe Prox][post by Boe Prox],
there's another way for us to do this on our custom object using just PowerShell. We can give it a `MemberSet` for it to use.
Now when my object just falls to the shell, it will only show those properties b
This is nice but I recently saw a better way when watching [PowerShell unplugged 2016 with Jeffrey Snover & Don Jones][psunplugged]. Jeffrey was using
-[Update-TypeData][] to specify the default properties.
+[Update-TypeData][Update-TypeData] to specify the default properties.
```powershell $TypeData = @{
code or compared to the actual function output.
The main reason you would use an output type is so that meta information about your function reflects your intentions. Things like `Get-Command` and `Get-Help` that your development environment can take advantage of. If you want more information, then take a look at the help for it:
-[about_Functions_OutputTypeAttribute][].
+[about_Functions_OutputTypeAttribute][about_Functions_OutputTypeAttribute].
With that said, if you're using Pester to unit test your functions then it would be a good idea to validate the output objects match your **OutputType**. This could catch variables that just fall
learn Everything About Shouldprocess https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-shouldprocess.md
One important feature that is often overlooked is `-WhatIf` and `-Confirm` suppo
add to your functions. In this article, we dive deep into how to implement this feature. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
This is a simple feature you can enable in your functions to provide a safety net for the users that need it. There's nothing scarier than running a command that you know can be dangerous for the
first time. The option to run it with `-WhatIf` can make a big difference.
## CommonParameters
-Before we look at implementing these [common parameters][], I want to take a quick look at how
+Before we look at implementing these [common parameters][common parameters], I want to take a quick look at how
they're used. ## Using -WhatIf
Remove-Item @RemoveSplat
``` If you're new to hashtables or splatting, I have another article on that covers
-[everything you wanted to know about hashtables][].
+[everything you wanted to know about hashtables][everything you wanted to know about hashtables].
## SupportsShouldProcess
learn Everything About String Substitutions https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-string-substitutions.md
referring to any time you want to format a string to include values from variabl
something that I often find myself explaining to new scripters. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## Concatenation
This is not splatting because I'm passing the whole array in, but the idea is si
## Advanced formatting I intentionally called these out as coming from .NET because there are lots of formatting options
-already well [documented][] on it. There are built in ways to format various data types.
+already well [documented][documented] on it. There are built in ways to format various data types.
```powershell "{0:yyyyMMdd}" -f (Get-Date)
The great thing about this is it works out the backslashes correctly when it put
together. This is especially important if you are taking values from users or config files. This also goes well with `Split-Path` and `Test-Path`. I also cover these in my post about
-[reading and saving to files][].
+[reading and saving to files][reading and saving to files].
## Strings are arrays
$tester = "Better"
Write-Host "$test $tester ${test}ter" ```
-Thank you [/u/real_parbold][] for that one.
+Thank you [/u/real_parbold][/u/real_parbold] for that one.
Here is an alternate to this approach:
foreach($name in $nameList){
``` To keep going on this idea; you could be importing a large email template from a text file to do
-this. I have to thank [Mark Kraus][] for this [suggestion][].
+this. I have to thank [Mark Kraus][Mark Kraus] for this [suggestion][suggestion].
## Whatever works the best for you
learn Everything About Switch https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/everything-about-switch.md
# Everything you ever wanted to know about the switch statement Like many other languages, PowerShell has commands for controlling the flow of execution within your
-scripts. One of those statements is the [switch][] statement and in PowerShell, it offers features
+scripts. One of those statements is the [switch][switch] statement and in PowerShell, it offers features
that aren't found in other languages. Today, we take a deep dive into working with the PowerShell `switch`. > [!NOTE]
-> The [original version][] of this article appeared on the blog written by [@KevinMarquette][]. The
+> The [original version][original version] of this article appeared on the blog written by [@KevinMarquette][@KevinMarquette]. The
> PowerShell team thanks Kevin for sharing this content with us. Please check out his blog at
-> [PowerShellExplained.com][].
+> [PowerShellExplained.com][PowerShellExplained.com].
## The `if` statement
switch -Regex ( $message )
} ```
-I have more examples of using regex in another article I wrote: [The many ways to use regex][].
+I have more examples of using regex in another article I wrote: [The many ways to use regex][The many ways to use regex].
### -File
It still executes the same way and gives a better visual break when quickly look
We need to revisit regex to touch on something that isn't immediately obvious. The use of regex populates the `$matches` variable. I do go into the use of `$matches` more when I talk about
-[The many ways to use regex][]. Here is a quick sample to show it in action with named matches.
+[The many ways to use regex][The many ways to use regex]. Here is a quick sample to show it in action with named matches.
``` powershell $message = 'my ssn is 123-23-3456 and credit card: 1234-5678-1234-5678'
access that value directly. I would call it madness.
### Hashtables
-One of my most popular posts is the one I did on [hashtables][]. One of the use cases for a
+One of my most popular posts is the one I did on [hashtables][hashtables]. One of the use cases for a
`hashtable` is to be a lookup table. That is an alternate approach to a common pattern that a `switch` statement is often addressing.
learn Overview https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/deep-dives/overview.md
articles don't replace the reference articles, but provide diverse examples, ill
cases, and warn about pitfalls and common mistakes. This collection is also a showcase for community contributions. The inaugural set of articles come
-from [@KevinMarquette][] and were originally published at [PowerShellExplained.com][].
+from [@KevinMarquette][@KevinMarquette] and were originally published at [PowerShellExplained.com][PowerShellExplained.com].
## How to contribute content If you're interested in contributing content to this collection, please read the
-[Contributor Guide][]. When you are ready to propose a contribution, submit an issue in the GitHub
-repository using the [Document Idea template][] and include a link to the existing content you want
+[Contributor Guide][Contributor Guide]. When you are ready to propose a contribution, submit an issue in the GitHub
+repository using the [Document Idea template][Document Idea template] and include a link to the existing content you want
to share. <!-- link references -->
learn 00 Introduction https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/00-introduction.md
covered in that chapter.
Mike F Robbins is a former Microsoft MVP, co-author of _Windows PowerShell TFM 4th Edition_, and a contributing author in the _PowerShell Deep Dives_ book. Mike has been a strong supporter of the
-PowerShell community and is now the lead writer for [Azure PowerShell][] at Microsoft. He blogs at
-[mikefrobbins.com][] and can be found on twitter [@mikefrobbins][].
+PowerShell community and is now the lead writer for [Azure PowerShell][Azure PowerShell] at Microsoft. He blogs at
+[mikefrobbins.com][mikefrobbins.com] and can be found on twitter [@mikefrobbins][@mikefrobbins].
## Lab environment
learn 01 Getting Started https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/01-getting-started.md
walk through the examples shown in this chapter on your Windows 10 lab environme
All modern versions of Windows operating systems ship with PowerShell installed. If you're running a version older than 5.1, you should install the latest version. -- To upgrade to Windows PowerShell 5.1, see [Upgrading existing Windows PowerShell][]-- To install the latest version of PowerShell, see [Installing PowerShell][]
+- To upgrade to Windows PowerShell 5.1, see [Upgrading existing Windows PowerShell][Upgrading existing Windows PowerShell]
+- To install the latest version of PowerShell, see [Installing PowerShell][Installing PowerShell]
## Where do I find PowerShell?
to run the 64-bit version of PowerShell unless you have a specific reason for ru
version. For information about starting PowerShell on other versions of Windows, see
-[Starting Windows PowerShell][].
+[Starting Windows PowerShell][Starting Windows PowerShell].
## How do I launch PowerShell?
SerializationVersion 1.1.0.1
Newer versions of Windows PowerShell are distributed as part of the Windows Management Framework (WMF). A specific version of the .NET Framework is required depending on the WMF version. To upgrade
-to Windows PowerShell 5.1, see [Upgrading existing Windows PowerShell][].
+to Windows PowerShell 5.1, see [Upgrading existing Windows PowerShell][Upgrading existing Windows PowerShell].
## Execution Policy
at http://go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the exec
``` Be sure to read the warning that's displayed when changing the execution policy. I also recommend
-taking a look at the [about_Execution_Policies][] help topic to make sure you understand the
+taking a look at the [about_Execution_Policies][about_Execution_Policies] help topic to make sure you understand the
security implications of changing the execution policy. Now that the execution policy has been set to **RemoteSigned**, the `Stop-TimeService.ps1` script
how to change it.
For those who want to know more information about the topics covered in this chapter, I recommend reading the following PowerShell help topics. -- [about_Automatic_Variables][]-- [about_Hash_Tables][]-- [about_Execution_Policies][]
+- [about_Automatic_Variables][about_Automatic_Variables]
+- [about_Hash_Tables][about_Hash_Tables]
+- [about_Execution_Policies][about_Execution_Policies]
In the next chapter, you'll learn about the discoverability of commands in PowerShell. One of the things that will be covered is how to update PowerShell so those help topics can be viewed right
learn 02 Help System https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/02-help-system.md
All of the cryptic syntax such as square and angle brackets in the syntax sectio
but will be covered in Appendix A of this book. While important, learning the cryptic syntax is often difficult to retain for someone who is new to PowerShell and may not use it everyday.
-For more information to better understand the cryptic syntax, see [Appendix A][].
+For more information to better understand the cryptic syntax, see [Appendix A][Appendix A].
For beginners, there's an easier way to figure out the same information except in plain language.
A better option is to use either the **Verb** or **Noun** parameter or both of t
PowerShell commands have both verbs and nouns. Found something wrong with a help topic? The good news is the help topics for PowerShell have been
-open-sourced and available in the [PowerShell-Docs][] repository on GitHub. Pay it forward by not
+open-sourced and available in the [PowerShell-Docs][PowerShell-Docs] repository on GitHub. Pay it forward by not
only fixing the incorrect information for yourself, but everyone else as well. Simply fork the PowerShell documentation repository on GitHub, update the help topic, and submit a pull request. Once the pull request is accepted, the corrected documentation is available for everyone.
Get-Command | Get-Random | Get-Help -Full
If you want to know more information about the topics covered in this chapter, I recommend reading the following PowerShell help topics. -- [Get-Help][]-- [Get-Command][]-- [Update-Help][]-- [Save-Help][]-- [about_Updatable_Help][]-- [about_Command_Syntax][]
+- [Get-Help][Get-Help]
+- [Get-Command][Get-Command]
+- [Update-Help][Update-Help]
+- [Save-Help][Save-Help]
+- [about_Updatable_Help][about_Updatable_Help]
+- [about_Command_Syntax][about_Command_Syntax]
In the next chapter, you'll learn about the `Get-Member` cmdlet as well as objects, properties, and methods.
learn 03 Discovering Objects https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/03-discovering-objects.md
The Active Directory PowerShell module is required by some of the examples shown
The module is part of the Remote Server Administration Tools (RSAT) for Windows. For the 1809 (or higher) build of Windows, the RSAT tools are installed as a Windows feature. -- For information about installing the RSAT tools, see [Windows Management modules][].-- For older versions of Windows, see [RSAT for Windows][].
+- For information about installing the RSAT tools, see [Windows Management modules][Windows Management modules].
+- For older versions of Windows, see [RSAT for Windows][RSAT for Windows].
## Get-Member
that limit the properties that are returned by default.
## Recommended Reading -- [Get-Member][]-- [Viewing Object Structure (Get-Member)][]-- [about_Objects][]-- [about_Properties][]-- [about_Methods][]
+- [Get-Member][Get-Member]
+- [Viewing Object Structure (Get-Member)][Viewing Object Structure (Get-Member)]
+- [about_Objects][about_Objects]
+- [about_Properties][about_Properties]
+- [about_Methods][about_Methods]
- [No PowerShell Cmdlet to Start or Stop Something? Don't Forget to Check for Methods on the Get Cmdlets][use-methods] <!-- link references -->
learn 04 Pipelines https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/04-pipelines.md
and updating PowerShell modules (and other artifacts) to or from a NuGet reposit
ships with PowerShell version 5.0 and higher. It is available as a separate download for PowerShell version 3.0 and higher.
-Microsoft hosts an online NuGet repository called the [PowerShell Gallery][]. Although this
+Microsoft hosts an online NuGet repository called the [PowerShell Gallery][PowerShell Gallery]. Although this
repository is hosted by Microsoft, the majority of the modules contained within the repository aren't written by Microsoft. Any code obtain from the PowerShell Gallery should be thoroughly reviewed in an isolated test environment before being considered suitable for use in a production
one-liner. You've also learned about filtering left, the pipeline, and PowerShel
## Recommended Reading -- [about_Pipelines][]-- [about_Command_Syntax][]-- [about_Parameters][]
+- [about_Pipelines][about_Pipelines]
+- [about_Command_Syntax][about_Command_Syntax]
+- [about_Parameters][about_Parameters]
- [PowerShellGet: The BIG EASY way to discover, install, and update PowerShell modules][psget] <!-- link references-->
learn 05 Formatting Aliases Providers Comparison https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/05-formatting-aliases-providers-comparison.md
SQL Sat - Baton Rouge
Be careful when using methods to transform data because you can run into unforeseen problems, such as failing the _Turkey Test_. For an example, see the blog article titled
-[Using Pester to Test PowerShell Code with Other Cultures][]. My recommendation is to use an
+[Using Pester to Test PowerShell Code with Other Cultures][Using Pester to Test PowerShell Code with Other Cultures]. My recommendation is to use an
operator instead of a method whenever possible to avoid these types of problems. While the comparison operators can be used as shown in the previous examples, I normally find myself
Providers, and Comparison Operators.
## Recommended Reading -- [Format-Table][]-- [Format-List][]-- [Format-Wide][]-- [about_Aliases][]-- [about_Providers][]-- [about_Comparison_Operators][]-- [about_Arrays][]
+- [Format-Table][Format-Table]
+- [Format-List][Format-List]
+- [Format-Wide][Format-Wide]
+- [about_Aliases][about_Aliases]
+- [about_Providers][about_Providers]
+- [about_Comparison_Operators][about_Comparison_Operators]
+- [about_Arrays][about_Arrays]
<!-- link references --> [SMSS]: /sql/ssms/download-sql-server-management-studio-ssms
learn 06 Flow Control https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/06-flow-control.md
foreach ($n in $number) {
Notice that in the previous example, return outputs the first result and then exists out of the loop. A more thorough explanation of the result statement can be found in one of my blog articles:
-["The PowerShell return keyword"][].
+["The PowerShell return keyword"]["The PowerShell return keyword"].
## Summary
In this chapter, you've learned about the different types of loops that exist in
## Recommended Reading -- [ForEach-Object][]-- [about_ForEach][]-- [about_For][]-- [about_Do][]-- [about_While][]-- [about_Break][]-- [about_Continue][]-- [about_Return][]
+- [ForEach-Object][ForEach-Object]
+- [about_ForEach][about_ForEach]
+- [about_For][about_For]
+- [about_Do][about_Do]
+- [about_While][about_While]
+- [about_Break][about_Break]
+- [about_Continue][about_Continue]
+- [about_Return][about_Return]
<!-- link references --> [ForEach-Object]: /powershell/module/microsoft.powershell.core/foreach-object
learn 07 Working With Wmi https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/07-working-with-wmi.md
PSComputerName : sql03
I've written numerous blog articles about the WMI and CIM cmdlets. One of the most useful ones is about a function that I created to automatically determine if WSMan or DCOM should be used and set up the CIM session automatically without having to figure out which one manually. That blog article
-is titled [PowerShell Function to Create CimSessions to Remote Computers with Fallback to Dcom][].
+is titled [PowerShell Function to Create CimSessions to Remote Computers with Fallback to Dcom][PowerShell Function to Create CimSessions to Remote Computers with Fallback to Dcom].
When you're finished with the CIM sessions, you should remove them with the `Remove-CimSession` cmdlet. To remove all CIM sessions, simply pipe `Get-CimSession` to `Remove-CimSession`.
the WSMan or DCOM protocol.
## Recommended Reading -- [about_WMI][]-- [about_WMI_Cmdlets][]-- [about_WQL][]-- [CimCmdlets Module][]-- [Video: Using CIM Cmdlets and CIM Sessions][]
+- [about_WMI][about_WMI]
+- [about_WMI_Cmdlets][about_WMI_Cmdlets]
+- [about_WQL][about_WQL]
+- [CimCmdlets Module][CimCmdlets Module]
+- [Video: Using CIM Cmdlets and CIM Sessions][Video: Using CIM Cmdlets and CIM Sessions]
<!-- link references --> [about_WMI]: /powershell/module/microsoft.powershell.core/about/about_wmi
learn 08 Powershell Remoting https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/08-powershell-remoting.md
multiple commands against the same remote computer.
## Recommended Reading -- [about_Remote][]-- [about_Remote_Output][]-- [about_Remote_Requirements][]-- [about_Remote_Troubleshooting][]-- [about_Remote_Variables][]-- [PowerShell Remoting FAQ][]
+- [about_Remote][about_Remote]
+- [about_Remote_Output][about_Remote_Output]
+- [about_Remote_Requirements][about_Remote_Requirements]
+- [about_Remote_Troubleshooting][about_Remote_Troubleshooting]
+- [about_Remote_Variables][about_Remote_Variables]
+- [PowerShell Remoting FAQ][PowerShell Remoting FAQ]
<!-- link references --> [PowerShell Remoting FAQ]: ../remoting/powershell-remoting-faq.yml
learn 09 Functions https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/09-functions.md
way when writing any PowerShell code.
## Naming
-When naming your functions in PowerShell, use a [Pascal case][] name with an approved verb and a
+When naming your functions in PowerShell, use a [Pascal case][Pascal case] name with an approved verb and a
singular noun. I also recommend prefixing the noun. For example: `<ApprovedVerb>-<Prefix><SingularNoun>`.
I also recommend using the same case for your parameter names as the default cmd
cmdlets. People who are already familiar with PowerShell will feel right at home. The `param` statement allows you to define one or more parameters. The parameter definitions are
-separated by a comma (`,`). For more information, see [about_Functions_Advanced_Parameters][].
+separated by a comma (`,`). For more information, see [about_Functions_Advanced_Parameters][about_Functions_Advanced_Parameters].
## Advanced Functions
input, error handling, and comment based help.
## Recommended Reading -- [about_Functions][]-- [about_Functions_Advanced_Parameters][]-- [about_CommonParameters][]-- [about_Functions_CmdletBindingAttribute][]-- [about_Functions_Advanced][]-- [about_Try_Catch_Finally][]-- [about_Comment_Based_Help][]-- [Video: PowerShell Toolmaking with Advanced Functions and Script Modules][]
+- [about_Functions][about_Functions]
+- [about_Functions_Advanced_Parameters][about_Functions_Advanced_Parameters]
+- [about_CommonParameters][about_CommonParameters]
+- [about_Functions_CmdletBindingAttribute][about_Functions_CmdletBindingAttribute]
+- [about_Functions_Advanced][about_Functions_Advanced]
+- [about_Try_Catch_Finally][about_Try_Catch_Finally]
+- [about_Comment_Based_Help][about_Comment_Based_Help]
+- [Video: PowerShell Toolmaking with Advanced Functions and Script Modules][Video: PowerShell Toolmaking with Advanced Functions and Script Modules]
<!-- link references --> [about_Functions]: /powershell/module/microsoft.powershell.core/about/about_functions
learn 10 Script Modules https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/learn/ps101/10-script-modules.md
manifest for your script module.
## Recommended Reading -- [How to Create PowerShell Script Modules and Module Manifests][]-- [about_Modules][]-- [New-ModuleManifest][]-- [Export-ModuleMember][]
+- [How to Create PowerShell Script Modules and Module Manifests][How to Create PowerShell Script Modules and Module Manifests]
+- [about_Modules][about_Modules]
+- [New-ModuleManifest][New-ModuleManifest]
+- [Export-ModuleMember][Export-ModuleMember]
<!-- link references --> [How to Create PowerShell Script Modules and Module Manifests]: https://mikefrobbins.com/2013/07/04/how-to-create-powershell-script-modules-and-module-manifests/
overview Overview https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/overview.md
PowerShell is a modern command shell that includes the best features of other po
most shells that only accept and return text, PowerShell accepts and returns .NET objects. The shell includes the following features: -- Robust command-line [history][]-- Tab completion and command prediction (See [about_PSReadLine][])-- Supports command and parameter [aliases][]-- [Pipeline][] for chaining commands-- In-console [help][] system, similar to Unix `man` pages
+- Robust command-line [history][history]
+- Tab completion and command prediction (See [about_PSReadLine][about_PSReadLine])
+- Supports command and parameter [aliases][aliases]
+- [Pipeline][Pipeline] for chaining commands
+- In-console [help][help] system, similar to Unix `man` pages
## Scripting language
the .NET Common Language Runtime (CLR). All inputs and outputs are .NET objects.
text output to extract information from output. The PowerShell scripting language includes the following features: -- Extensible through [functions][], [classes][], [scripts][], and [modules][]
+- Extensible through [functions][functions], [classes][classes], [scripts][scripts], and [modules][modules]
- Extensible [formatting system][formatting] for easy output - Extensible [type system][types] for creating dynamic types-- Built-in support for common data formats like [CSV][], [JSON][], and [XML][]
+- Built-in support for common data formats like [CSV][CSV], [JSON][JSON], and [XML][XML]
## Configuration management
-PowerShell Desired State Configuration ([DSC][]) is a management framework in PowerShell that
+PowerShell Desired State Configuration ([DSC][DSC]) is a management framework in PowerShell that
enables you to manage your enterprise infrastructure with configuration as code. With DSC, you can: -- Create declarative [configurations][] and custom scripts for repeatable deployments
+- Create declarative [configurations][configurations] and custom scripts for repeatable deployments
- Enforce configuration settings and report on configuration drift - Deploy configuration using [push or pull][push-pull] models
samples Decode Powershell Command From A Running Process https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/samples/Decode-PowerShell-Command-from-a-Running-Process.md
description: This article shows how to decode a script block that a PowerShell p
# Decode a PowerShell command from a running process At times, you may have a PowerShell process running that is taking up a large amount of resources.
-This process could be running in the context of a [Task Scheduler][] job or a [SQL Server Agent][]
-job. Where there are multiple PowerShell processes running, it can be difficult to know
-which process represents the problem. This article shows how to decode a script block that a
-PowerShell process is currently running.
+This process could be running in the context of a [Task Scheduler][task] job or a
+[SQL Server Agent][sqlagent] job. Where there are multiple PowerShell processes running, it can be
+difficult to know which process represents the problem. This article shows how to decode a script
+block that a PowerShell process is currently running.
## Create a long running process
powershell.exe -Command {
## View the process
-The body of the command which PowerShell is executing is stored in the **CommandLine** property
-of the [Win32_Process][] class. If the command is an encoded command, the **CommandLine**
-property contains the string "EncodedCommand". Using this information, the encoded command can
-be de-obfuscated via the following process.
+The body of the command which PowerShell is executing is stored in the **CommandLine** property of
+the [Win32_Process][Win32_Process] class. If the command is an encoded command, the **CommandLine**
+property contains the string "EncodedCommand". Using this information, the encoded command can be
+de-obfuscated via the following process.
Start PowerShell as Administrator. It is vital that PowerShell is running as administrator, otherwise no results are returned when querying the running processes.
DecodedCommand :
} ```
-[Task Scheduler]: /windows/desktop/TaskSchd/task-scheduler-start-page
-[SQL Server Agent]: /sql/ssms/agent/sql-server-agent
+[task]: /windows/desktop/TaskSchd/task-scheduler-start-page
+[sqlagent]: /sql/ssms/agent/sql-server-agent
[Win32_Process]: /windows/desktop/CIMWin32Prov/win32-process
whats-new Differences From Windows Powershell https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/whats-new/differences-from-windows-powershell.md
support custom snap-ins in PowerShell.
### Experimental feature flags
-We enabled support for [Experimental Features][]. This allows PowerShell developers to deliver new
-features and get feedback before the design is complete. This way we avoid making breaking changes
-as the design evolves.
+We enabled support for [Experimental Features][exp]. This allows PowerShell developers to deliver
+new features and get feedback before the design is complete. This way we avoid making breaking
+changes as the design evolves.
Use `Get-ExperimentalFeature` to get a list of available experimental features. You can enable or disable these features with `Enable-ExperimentalFeature` and `Disable-ExperimentalFeature`.
disable these features with `Enable-ExperimentalFeature` and `Disable-Experiment
You can learn more about this feature in [PowerShell RFC0029](https://github.com/PowerShell/PowerShell-RFC/blob/master/5-Final/RFC0029-Support-Experimental-Features.md).
-[Experimental Features]: /powershell/module/Microsoft.PowerShell.Core/About/about_Experimental_Features
+[exp]: /powershell/module/Microsoft.PowerShell.Core/About/about_Experimental_Features
### Load assembly from module base path before trying to load from the GAC
whats-new Unix Support https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/whats-new/unix-support.md
specifying a path.
## Logging On macOS, PowerShell uses the native `os_log` APIs to log to Apple's
-[unified logging system][os_log]. On Linux, PowerShell uses [Syslog][], a ubiquitous logging
+[unified logging system][os_log]. On Linux, PowerShell uses [Syslog][Syslog], a ubiquitous logging
solution. [os_log]: https://developer.apple.com/documentation/os/logging
windows-powershell Starting The Windows Powershell 2.0 Engine https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/windows-powershell/Starting-the-Windows-PowerShell-2.0-Engine.md
instructions are included for the rare situations in which you need to start the
## Deprecation and security concerns Windows PowerShell 2.0 was deprecated in August, 2017. For more information, see the
-[announcement][] on the PowerShell blog.
+[announcement][announcement] on the PowerShell blog.
Windows PowerShell 2.0 is missing a significant amount of the hardening and security features added in versions 3, 4, and 5. We highly, highly recommend that users not use it if they can help it. For
-more information, see [A Comparison of Shell and Scripting Language Security][] and
+more information, see [A Comparison of Shell and Scripting Language Security][security] and
[PowerShell ΓÖÑ the Blue Team][blueteam]. ## Installing and Enabling Required Programs Before starting the Windows PowerShell 2.0 Engine, enable the Windows PowerShell 2.0 Engine and Microsoft .NET Framework 3.5 with Service Pack 1. For instructions, see
-[Installing Windows PowerShell][].
+[Installing Windows PowerShell][pssetup].
Systems on which Windows Management Framework 3.0 or higher is installed have all of the required components. No further configuration is necessary. For information about installing Windows
-Management Framework, see [Install and configure WMF][].
+Management Framework, see [Install and configure WMF][wmfsetup].
## How to start the Windows PowerShell 2.0 Engine
create sessions that use the Windows PowerShell 2.0 Engine.
This is an advanced task that is typically performed by a system administrator.
-The following procedure uses the **PSVersion** parameter of the [Register-PSSessionConfiguration][]
-cmdlet to create a session configuration that uses the Windows PowerShell 2.0 Engine. You can also
-use the **PowerShellVersion** parameter of the [New-PSSessionConfigurationFile][] cmdlet to create a
-session configuration file for a session that loads the Windows PowerShell 2.0 Engine and you can
-use the **PSVersion** parameter of the [Set-PSSessionConfiguration][] parameter to change a session
-configuration to use the Windows PowerShell 2.0 Engine.
+The following procedure uses the **PSVersion** parameter of the
+[Register-PSSessionConfiguration][Register-PSSessionConfiguration] cmdlet to create a session
+configuration that uses the Windows PowerShell 2.0 Engine. You can also use the
+**PowerShellVersion** parameter of the
+[New-PSSessionConfigurationFile][New-PSSessionConfigurationFile] cmdlet to create a session
+configuration file for a session that loads the Windows PowerShell 2.0 Engine and you can use the
+**PSVersion** parameter of the [Set-PSSessionConfiguration][Set-PSSessionConfiguration] parameter to
+change a session configuration to use the Windows PowerShell 2.0 Engine.
-For more information about session configuration files, see [about_Session_Configuration_Files][].
-For information about session configurations, including setup and security, see
-[about_Session_Configurations][].
+For more information about session configuration files, see
+[about_Session_Configuration_Files][about_Session_Configuration_Files]. For information about
+session configurations, including setup and security, see
+[about_Session_Configurations][about_Session_Configurations].
### To start a remote Windows PowerShell 2.0 session
For information about session configurations, including setup and security, see
## How to start a background job with the Windows PowerShell 2.0 Engine To start a background job with the Windows PowerShell 2.0 Engine, use the **PSVersion** parameter of
-the [Start-Job][] cmdlet.
+the [Start-Job][Start-Job] cmdlet.
The following command starts a background job with the Windows PowerShell 2.0 Engine
The following command starts a background job with the Windows PowerShell 2.0 En
Start-Job {Get-Process} -PSVersion 2.0 ```
-For more information about background jobs, see [about_Jobs][].
+For more information about background jobs, see [about_Jobs][about_Jobs].
<!-- link references --> [announcement]: https://devblogs.microsoft.com/powershell/windows-powershell-2-0-deprecation/
-[A Comparison of Shell and Scripting Language Security]: https://devblogs.microsoft.com/powershell/a-comparison-of-shell-and-scripting-language-security/
+[security]: https://devblogs.microsoft.com/powershell/a-comparison-of-shell-and-scripting-language-security/
[blueteam]: https://devblogs.microsoft.com/powershell/powershell-the-blue-team/
-[Installing Windows PowerShell]: install/Installing-Windows-PowerShell.md
-[Install and configure WMF]: wmf/setup/install-configure.md
+[pssetup]: install/Installing-Windows-PowerShell.md
+[wmfsetup]: wmf/setup/install-configure.md
[Register-PSSessionConfiguration]: /powershell/module/Microsoft.PowerShell.Core/Register-PSSessionConfiguration [New-PSSessionConfigurationFile]: /powershell/module/Microsoft.PowerShell.Core/New-PSSessionConfigurationFile [Set-PSSessionConfiguration]: /powershell/module/Microsoft.PowerShell.Core/Set-PSSessionConfiguration
windows-powershell Overview https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/windows-powershell/wmf/overview.md
to the links below to review the release notes:
## WMF Availability Across Windows Operating Systems
-| Operating System Version | [WMF 5.1][] | WMF 5.0<br>*Out of support* | [WMF 4.0][] | [WMF 3.0][] | [WMF 2.0][] |
-| --------------------------------------- | ------------ | --------------------------- | ------------ | ------------ | ------------ |
-| Windows Server 2019 | Ships in-box | | | | |
-| Windows Server 2016 | Ships in-box | | | | |
-| Windows 10 | Ships in-box | Ships in-box | | | |
-| Windows Server 2012 R2 | Yes | Yes | Ships in-box | | |
-| Windows 8.1 | Yes | Yes | Ships in-box | | |
-| Windows Server 2012 | Yes | Yes | Yes | Ships in-box | |
-| Windows 8<br>*Out of support* | | | | Ships in-box | |
-| Windows Server 2008 R2 SP1 | Yes | Yes | Yes | Yes | Ships in-box |
-| Windows 7 SP1 | Yes | Yes | Yes | Yes | Ships in-box |
-| Windows Server 2008 SP2 | | | | Yes | Yes |
-| Windows Vista<br>*Out of support* | | | | | Yes |
-| Windows Server 2003<br>*Out of support* | | | | | Yes |
-| Windows XP<br>*Out of support* | | | | Yes | Yes |
+| Operating System Version | [WMF 5.1][WMF 5.1] | WMF 5.0<br>*Out of support* | [WMF 4.0][WMF 4.0] | [WMF 3.0][WMF 3.0] | [WMF 2.0][WMF 2.0] |
+| --------------------------------------- | ------------------ | --------------------------- | ------------------ | ------------------ | ------------------ |
+| Windows Server 2019 | Ships in-box | | | | |
+| Windows Server 2016 | Ships in-box | | | | |
+| Windows 10 | Ships in-box | Ships in-box | | | |
+| Windows Server 2012 R2 | Yes | Yes | Ships in-box | | |
+| Windows 8.1 | Yes | Yes | Ships in-box | | |
+| Windows Server 2012 | Yes | Yes | Yes | Ships in-box | |
+| Windows 8<br>*Out of support* | | | | Ships in-box | |
+| Windows Server 2008 R2 SP1 | Yes | Yes | Yes | Yes | Ships in-box |
+| Windows 7 SP1 | Yes | Yes | Yes | Yes | Ships in-box |
+| Windows Server 2008 SP2 | | | | Yes | Yes |
+| Windows Vista<br>*Out of support* | | | | | Yes |
+| Windows Server 2003<br>*Out of support* | | | | | Yes |
+| Windows XP<br>*Out of support* | | | | Yes | Yes |
- **Ships in-box**: The features of the specified version of WMF were shipped in the indicated version of Windows client or Windows Server. - **Out of support**: These products are no longer supported by Microsoft. You must upgrade to a new
- version that is supported. For more information, see the [Microsoft Lifecycle Policy][] page.
+ version that is supported. For more information, see the [Microsoft Lifecycle Policy][Lifecycle]
+ page.
> [!NOTE] > The installer for WMF 5.0 is no longer available or supported. It has been replaced by WMF 5.1.
-[Microsoft Lifecycle Policy]: https://support.microsoft.com/lifecycle
+[Lifecycle]: https://support.microsoft.com/lifecycle
[WMF 5.1]: https://aka.ms/wmf51download [WMF 4.0]: https://aka.ms/wmf4download [WMF 3.0]: https://aka.ms/wmf3download
windows-powershell Install Configure https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/windows-powershell/wmf/setup/install-configure.md
description: This article describes how to install WMF 5.1 and its prerequisites
Download the WMF 5.1 package for the operating system and architecture you wish to install it on:
-| Operating System | Prerequisites | Package Links |
-|------------------------|-------------------------|----------------------------------------|
-| Windows Server 2012 R2 | | [Win8.1AndW2K12R2-KB3191564-x64.msu][] |
-| Windows Server 2012 | | [W2K12-KB3191565-x64.msu][] |
-| Windows Server 2008 R2 | [.NET Framework 4.5.2][]| [Win7AndW2K8R2-KB3191566-x64.ZIP][] |
-| Windows 8.1 | | **x64:** [Win8.1AndW2K12R2-KB3191564-x64.msu][]</br>**x86:** [Win8.1-KB3191564-x86.msu][] |
-| Windows 7 SP1 | [.NET Framework 4.5.2][]| **x64:** [Win7AndW2K8R2-KB3191566-x64.ZIP][]</br>**x86:** [Win7-KB3191566-x86.ZIP][] |
+| Operating System | Prerequisites | Package Links |
+| ---------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Windows Server 2012 R2 | | [Win8.1AndW2K12R2-KB3191564-x64.msu][Win8.1AndW2K12R2-KB3191564-x64.msu] |
+| Windows Server 2012 | | [W2K12-KB3191565-x64.msu][W2K12-KB3191565-x64.msu] |
+| Windows Server 2008 R2 | [.NET Framework 4.5.2][.NET Framework 4.5.2] | [Win7AndW2K8R2-KB3191566-x64.ZIP][Win7AndW2K8R2-KB3191566-x64.ZIP] |
+| Windows 8.1 | | **x64:** [Win8.1AndW2K12R2-KB3191564-x64.msu][Win8.1AndW2K12R2-KB3191564-x64.msu]</br>**x86:** [Win8.1-KB3191564-x86.msu][Win8.1-KB3191564-x86.msu] |
+| Windows 7 SP1 | [.NET Framework 4.5.2][.NET Framework 4.5.2] | **x64:** [Win7AndW2K8R2-KB3191566-x64.ZIP][Win7AndW2K8R2-KB3191566-x64.ZIP]</br>**x86:** [Win7-KB3191566-x86.ZIP][Win7-KB3191566-x86.ZIP] |
[.NET Framework 4.5.2]: https://www.microsoft.com/download/details.aspx?id=42642 [W2K12-KB3191565-x64.msu]: https://go.microsoft.com/fwlink/?linkid=839513