diff --git a/reference/7.0/Microsoft.PowerShell.Utility/Format-Table.md b/reference/7.0/Microsoft.PowerShell.Utility/Format-Table.md index 6a222bd5a176..1831af638392 100644 --- a/reference/7.0/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/7.0/Microsoft.PowerShell.Utility/Format-Table.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 08/10/2020 +ms.date: 11/11/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/format-table?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Format-Table @@ -414,6 +414,8 @@ Accept wildcard characters: True Repeats displaying the header of a table after every screen full. The repeated header is useful when the output is piped to a pager such as `less` or `more` or paging with a screen reader. +This parameter was added in PowerShell 6.2. + ```yaml Type: System.Management.Automation.SwitchParameter Parameter Sets: (All) diff --git a/reference/7.1/Microsoft.PowerShell.Utility/Format-Table.md b/reference/7.1/Microsoft.PowerShell.Utility/Format-Table.md index f62adc758091..0e71842c68bc 100644 --- a/reference/7.1/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/7.1/Microsoft.PowerShell.Utility/Format-Table.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 08/10/2020 +ms.date: 11/11/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/format-table?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Format-Table @@ -414,6 +414,8 @@ Accept wildcard characters: True Repeats displaying the header of a table after every screen full. The repeated header is useful when the output is piped to a pager such as `less` or `more` or paging with a screen reader. +This parameter was added in PowerShell 6.2. + ```yaml Type: System.Management.Automation.SwitchParameter Parameter Sets: (All) diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Format-Table.md b/reference/7.2/Microsoft.PowerShell.Utility/Format-Table.md index 7dd259152990..04cd2f42571d 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Format-Table.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Format-Table.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 08/10/2020 +ms.date: 11/11/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/format-table?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Format-Table @@ -414,6 +414,8 @@ Accept wildcard characters: True Repeats displaying the header of a table after every screen full. The repeated header is useful when the output is piped to a pager such as `less` or `more` or paging with a screen reader. +This parameter was added in PowerShell 6.2. + ```yaml Type: System.Management.Automation.SwitchParameter Parameter Sets: (All) diff --git a/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md b/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md index add51f1274e2..34f3a0d714af 100644 --- a/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md +++ b/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md @@ -1,6 +1,6 @@ --- description: Scripting for Performance in PowerShell -ms.date: 11/01/2021 +ms.date: 11/11/2021 title: PowerShell scripting performance considerations --- @@ -39,8 +39,29 @@ overhead though. $arrayList.Add($item) | Out-Null ``` -Piping to `Out-Null` has significant overhead when compared to the alternatives. It should be -avoiding in performance sensitive code. +You can also pipe to `Out-Null`. In PowerShell 7.x, this is a bit slower than redirection but +probably not noticeable for most scripts. However, calling `Out-Null` in a large loop is can be +significantly slower, even in PowerShell 7.x. + +```powershell +PS> $d = Get-Date; Measure-Command { for($i=0; $i -lt 1mb; $i++) { $null=$d } }| Select-Object TotalSeconds + +TotalSeconds +------------ + 1.0549325 + +PS> $d = Get-Date; Measure-Command { for($i=0; $i -lt 1mb; $i++) { $d | Out-Null } }| Select-Object TotalSeconds + +TotalSeconds +------------ + 5.9572186 +``` + +Windows PowerShell 5.1 does not have the same optimizations for `Out-Null` as PowerShell 7.x, so you +should avoid using `Out-Null` in performance sensitive code. + +Introducing a script block and calling it (using dot sourcing or otherwise) then assigning the +result to `$null` is a convenient technique for suppressing the output of a large block of script. ```powershell $null = . { @@ -49,8 +70,6 @@ $null = . { } ``` -Introducing a script block and calling it (using dot sourcing or otherwise) then assigning the -result to `$null` is a convenient technique for suppressing the output of a large block of script. This technique performs roughly as well as piping to `Out-Null` and should be avoided in performance sensitive script. The extra overhead in this example comes from the creation of and invoking a script block that was previously inline script. diff --git a/reference/docs-conceptual/dsc/reference/resources/windows/scriptResource.md b/reference/docs-conceptual/dsc/reference/resources/windows/scriptResource.md index 7a9b90ca1750..14e0628f0f3f 100644 --- a/reference/docs-conceptual/dsc/reference/resources/windows/scriptResource.md +++ b/reference/docs-conceptual/dsc/reference/resources/windows/scriptResource.md @@ -50,14 +50,16 @@ Script [string] #ResourceName > [!NOTE] > The **PsDscRunAsCredential** common property was added in WMF 5.0 to allow running any DSC -> resource in the context of other credentials. For more information, see [Use Credentials with DSC Resources](../../../configurations/runasuser.md). +> resource in the context of other credentials. For more information, see +> [Use Credentials with DSC Resources](../../../configurations/runasuser.md). ### Additional information #### GetScript -DSC does not use the output from `GetScript` The [Get-DscConfiguration](/powershell/module/PSDesiredStateConfiguration/Get-DscConfiguration) -cmdlet executes `GetScript` to retrieve a node's current state. A return value is not required from +DSC does not use the output from `GetScript` The +[Get-DscConfiguration](/powershell/module/PSDesiredStateConfiguration/Get-DscConfiguration) cmdlet +executes `GetScript` to retrieve a node's current state. A return value is not required from `GetScript` If you specify a return value, it must be a hashtable containing a **Result** key whose value is a String. @@ -136,7 +138,8 @@ Configuration ScriptTest return @{ 'Result' = "$currentVersion" } } TestScript = { - # Create and invoke a scriptblock using the $GetScript automatic variable, which contains a string representation of the GetScript. + # Create and invoke a scriptblock using the $GetScript automatic variable, + # which contains a string representation of the GetScript. $state = [scriptblock]::Create($GetScript).Invoke() if( $state.Result -eq $using:version ) @@ -185,12 +188,13 @@ Configuration ScriptTest return @{ 'Result' = "$currentVersion" } } TestScript = { - # Create and invoke a scriptblock using the $GetScript automatic variable, which contains a string representation of the GetScript. + # Create and invoke a scriptblock using the $GetScript automatic variable, + # which contains a string representation of the GetScript. $state = [scriptblock]::Create($GetScript).Invoke() - if( $state['Result'] -eq $using:Version ) + if( $state.Result -eq $using:Version ) { - Write-Verbose -Message ('{0} -eq {1}' -f $state['Result'],$using:version) + Write-Verbose -Message ('{0} -eq {1}' -f $state.Result,$using:version) return $true } diff --git a/reference/docs-conceptual/gallery/how-to/working-with-packages/deploy-to-azure-automation.md b/reference/docs-conceptual/gallery/how-to/working-with-packages/deploy-to-azure-automation.md index 6fbd427bc57f..1aad41d1cf2a 100644 --- a/reference/docs-conceptual/gallery/how-to/working-with-packages/deploy-to-azure-automation.md +++ b/reference/docs-conceptual/gallery/how-to/working-with-packages/deploy-to-azure-automation.md @@ -1,12 +1,12 @@ --- description: This article describes how to use the PowerShell Gallery to deploy a package to Azure Automation. -ms.date: 06/12/2017 +ms.date: 11/11/2021 title: Deploy to Azure Automation --- # Deploy to Azure Automation -The Deploy to Azure Automation button on the package details page will deploy the package from the -PowerShell Gallery to Azure Automation. +The **Deploy to Azure Automation** button on the package details page will deploy the package from +the PowerShell Gallery to Azure Automation. ![Deploy to Azure Automation Button](media/deploy-to-azure-automation/DeployToAzureAutomationButton.png) @@ -15,14 +15,22 @@ Azure account credentials. If the package includes dependencies, all the depende deployed to Azure Automation as well. > [!WARNING] -> If the same package and version already exist in your Automation account, deploying it again from -> the PowerShell Gallery will overwrite the package in your Automation account. +> If the same package and version already exists in your Automation account, deploying it again from +> the PowerShell Gallery overwrites the package in your Automation account. If you deploy a module, it will appear in the Modules section of Azure Automation. If you deploy a script, it will appear in the Runbooks section of Azure Automation. -The Deploy to Azure Automation button can be disabled by adding the AzureAutomationNotSupported tag -to the package metadata. +The **Deploy to Azure Automation** button can be disabled by adding the +**AzureAutomationNotSupported** tag to the package metadata. + +> [!IMPORTANT] +> The **Deploy to Azure Automation** feature does not work for sovereign (air-gapped) clouds like +> [Azure Government](/azure/azure-government/), [Azure Germany](/azure/germany/), or +> [Azure China 21Vianet](/azure/china/). +> +> We recommend setting up a private repository as described in +> [Working with private PowerShellGet repositories](../working-with-local-psrepositories.md). ## Require License Acceptance on Deploy to Azure Automation diff --git a/reference/docs-conceptual/how-to-use-docs.md b/reference/docs-conceptual/how-to-use-docs.md index 29fc7d852b17..c12fef91707e 100644 --- a/reference/docs-conceptual/how-to-use-docs.md +++ b/reference/docs-conceptual/how-to-use-docs.md @@ -1,6 +1,6 @@ --- description: This articles explains how to use the features of this site including search filtering and version selection. -ms.date: 10/04/2021 +ms.date: 11/11/2021 ms.topic: how-to title: How to use the PowerShell documentation --- @@ -9,8 +9,8 @@ title: How to use the PowerShell documentation Welcome to the PowerShell online documentation. This site contains cmdlet reference for the following versions of PowerShell: -- PowerShell 7.2 (prerelease) -- PowerShell 7.1 (current) +- PowerShell 7.2 (LTS) +- PowerShell 7.1 - PowerShell 7.0 (LTS) - PowerShell 5.1 @@ -21,11 +21,15 @@ the version selector. Just enter a word that appears in the title of an article. a list of matching articles. You can also select the option to search the entire site from that list. -By default, this site displays documentation for the latest released version of PowerShell. Some -cmdlets work differently in various versions of PowerShell. Be sure you are viewing the -documentation for the version of PowerShell you are using. +Use the version picker at the top of the page to select the version of PowerShell you want. By +default, the version selector is set to the most current release version of PowerShell. The version +selector controls what cmdlet reference appears in the Table of Contents under the **Reference** +node. Some cmdlets work differently in depending on the version of PowerShell you are using. Be sure +you are viewing the documentation for the correct version of PowerShell. -Use the version picker at the top of the page to select the version of PowerShell you want. +The version selector does not filter conceptual documentation. The conceptual documents appear above +the **Reference** node in the Table of Contents. The same documents appear for any version selected. +If there are version-specific differences, the documentation makes note of those differences. ![Using the version picker](media/how-to-use-docs/version-search.gif) diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md index f485edaff3c3..3ff66fd974a5 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md @@ -46,14 +46,14 @@ The installer creates a shortcut in the Windows Start Menu. - You can launch PowerShell via the Start Menu or `$env:ProgramFiles\PowerShell\\pwsh.exe` > [!NOTE] -> PowerShell 7.1 installs to a new directory and runs side-by-side with Windows PowerShell 5.1. -> PowerShell 7.1 is an in-place upgrade that replaces PowerShell 7.0 and lower. +> PowerShell 7.2 installs to a new directory and runs side-by-side with Windows PowerShell 5.1. +> PowerShell 7.2 is an in-place upgrade that replaces PowerShell 7.0 and lower. > -> - PowerShell 7.1 is installed to `$env:ProgramFiles\PowerShell\7` +> - PowerShell 7.2 is installed to `$env:ProgramFiles\PowerShell\7` > - The `$env:ProgramFiles\PowerShell\7` folder is added to `$env:PATH` > - Folders for previously released versions are deleted > -> If you need to run PowerShell 7.1 side-by-side with other versions, use the [ZIP install](#zip) +> If you need to run PowerShell 7.2 side-by-side with other versions, use the [ZIP install](#zip) > method to install the other version to a different folder. ### Administrative install from the command line @@ -146,7 +146,7 @@ winget install --id Microsoft.Powershell.Preview --source winget ## Installing from the Microsoft Store -PowerShell 7.1 has been published to the Microsoft Store. You can find the PowerShell release in the +PowerShell 7.2 has been published to the Microsoft Store. You can find the PowerShell release in the [Microsoft Store][store-app] site or in the Store application in Windows. Benefits of the Microsoft Store package: diff --git a/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md b/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md index 794e60e9240a..22519f281299 100644 --- a/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md +++ b/reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md @@ -1,7 +1,7 @@ --- description: Error handling is just part of life when it comes to writing code. ms.custom: contributor-KevinMarquette -ms.date: 10/05/2021 +ms.date: 11/11/2021 title: Everything you wanted to know about exceptions --- # Everything you wanted to know about exceptions @@ -119,6 +119,7 @@ try catch { Write-Output "Something threw an exception" + Write-Output $Error[0] } try @@ -128,11 +129,13 @@ try catch { Write-Output "Something threw an exception or used Write-Error" + Write-Output $Error[0] } ``` The `catch` script only runs if there's a terminating error. If the `try` executes correctly, then -it skips over the `catch`. +it skips over the `catch`. You can access the exception information in the `catch` block using the +`$Error` variable. ### Try/Finally diff --git a/reference/docs-conceptual/learn/security-features.md b/reference/docs-conceptual/learn/security-features.md index 16e9b317910f..0ab5525ce496 100644 --- a/reference/docs-conceptual/learn/security-features.md +++ b/reference/docs-conceptual/learn/security-features.md @@ -1,6 +1,6 @@ --- description: PowerShell has several features designed to improve the security of your scripting environment. -ms.date: 10/27/2021 +ms.date: 11/10/2021 title: PowerShell security features --- # PowerShell security features @@ -34,8 +34,8 @@ For more information, see the following articles: ## Constrained language mode -**ConstrainedLanguage** mode protects your system by limiting the cmdlets and .NET types that can be used -in a PowerShell session. For a full description, see [about_Language_Modes][lang-modes]. +**ConstrainedLanguage** mode protects your system by limiting the cmdlets and .NET types that can be +used in a PowerShell session. For a full description, see [about_Language_Modes][lang-modes]. ## Application Control @@ -89,6 +89,21 @@ The table below outlines the features that meet the servicing criteria and those - PowerShell 7.2 now disallows scripts from using COM objects in AppLocker system lock down conditions. Cmdlet that use COM or DCOM internally are not affected. +## Software Bill of Materials (SBOM) + +Beginning with PowerShell 7.2, all install packages contain a Software Bill of Materials (SBOM). The +SBOM is found at `$PSHOME/_manifest/spdx_2.2/manifest.spdx.json`. The creation and publishing of the +SBOM is the first step to modernize Federal Government cybersecurity and enhance software supply +chain security. + +The PowerShell team is also producing SBOMs for modules that they own but ship separately from +PowerShell. SBOMs will be added in the next release of the module. For modules, the SBOM is +installed in the module's folder under +`_manifest/spdx_2.2/manifest.spdx.json`. + +For more information about this initiative, see the blog post +[Generating Software Bills of Materials (SBOMs) with SPDX at Microsoft][sbomblog]. + [applocker]: /windows/security/threat-protection/windows-defender-application-control/applocker/what-is-applocker [availability]: /windows/security/threat-protection/windows-defender-application-control/feature-availability @@ -100,3 +115,4 @@ The table below outlines the features that meet the servicing criteria and those [logging]: /powershell/module/microsoft.powershell.core/about/about_group_policy_settings#turn-on-module-logging [mssec]: https://www.microsoft.com/msrc/windows-security-servicing-criteria [WDAC]: /windows/security/threat-protection/windows-defender-application-control/windows-defender-application-control +[sbomblog]: https://devblogs.microsoft.com/engineering-at-microsoft/generating-software-bills-of-materials-sboms-with-spdx-at-microsoft/