Updates from: 05/05/2021 03:16:54
Service Microsoft Docs article Related commit history on GitHub Change details
Microsoft.PowerShell.Core About Redirection (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md
--- description: Explains how to redirect output from PowerShell to text files. Locale: en-US Previously updated : 03/18/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about_Redirection
There is also a **Progress** stream in PowerShell, but it does not support
redirection. > [!IMPORTANT]
-> The **Success** and **Error** streams are similar to the stdin and stderr
+> The **Success** and **Error** streams are similar to the stdout and stderr
> streams of other shells. However, stdin is not connected to the PowerShell > pipeline for input.
Microsoft.PowerShell.Utility Convertto Json (5.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/5.1/Microsoft.PowerShell.Utility/ConvertTo-Json.md
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility Previously updated : 06/09/2017 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: ConvertTo-Json
Accept wildcard characters: False
### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value
-can be any number from `1` to `[Int]::MaxValue`. The default value is `2`. `ConvertTo-Json` emits a
+can be any number from `1` to `100`. The default value is `2`. `ConvertTo-Json` emits a
warning if the number of levels in an input object exceeds this number. ```yaml
Microsoft.PowerShell.Core About Redirection (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Core/About/about_Redirection.md
--- description: Explains how to redirect output from PowerShell to text files. Locale: en-US Previously updated : 03/18/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about_Redirection
There is also a **Progress** stream in PowerShell, but it does not support
redirection. > [!IMPORTANT]
-> The **Success** and **Error** streams are similar to the stdin and stderr
+> The **Success** and **Error** streams are similar to the stdout and stderr
> streams of other shells. However, stdin is not connected to the PowerShell > pipeline for input.
Microsoft.PowerShell.Utility Convertto Json (7.0) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.0/Microsoft.PowerShell.Utility/ConvertTo-Json.md
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility Previously updated : 04/19/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 Title: ConvertTo-Json
Accept wildcard characters: False
### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value
-can be any number from `1` to `[Int]::MaxValue`. The default value is `2`. `ConvertTo-Json` emits a
+can be any number from `1` to `100`. The default value is `2`. `ConvertTo-Json` emits a
warning if the number of levels in an input object exceeds this number. ```yaml
Microsoft.PowerShell.Core About Redirection (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Core/About/about_Redirection.md
--- description: Explains how to redirect output from PowerShell to text files. Locale: en-US Previously updated : 03/18/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about_Redirection
There is also a **Progress** stream in PowerShell, but it does not support
redirection. > [!IMPORTANT]
-> The **Success** and **Error** streams are similar to the stdin and stderr
+> The **Success** and **Error** streams are similar to the stdout and stderr
> streams of other shells. However, stdin is not connected to the PowerShell > pipeline for input.
Microsoft.PowerShell.Utility Convertto Json (7.1) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.1/Microsoft.PowerShell.Utility/ConvertTo-Json.md
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility Previously updated : 04/19/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 Title: ConvertTo-Json
Accept wildcard characters: False
### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value
-can be any number from `1` to `[Int]::MaxValue`. The default value is `2`. `ConvertTo-Json` emits a
+can be any number from `1` to `100`. The default value is `2`. `ConvertTo-Json` emits a
warning if the number of levels in an input object exceeds this number. ```yaml
Microsoft.PowerShell.Core About Redirection (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md
--- description: Explains how to redirect output from PowerShell to text files. Locale: en-US Previously updated : 03/18/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: about_Redirection
There is also a **Progress** stream in PowerShell, but it does not support
redirection. > [!IMPORTANT]
-> The **Success** and **Error** streams are similar to the stdin and stderr
+> The **Success** and **Error** streams are similar to the stdout and stderr
> streams of other shells. However, stdin is not connected to the PowerShell > pipeline for input.
Microsoft.PowerShell.Utility Convertto Json (7.2) https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/7.2/Microsoft.PowerShell.Utility/ConvertTo-Json.md
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility Previously updated : 04/19/2021 Last updated : 05/04/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/convertto-json?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 Title: ConvertTo-Json
Accept wildcard characters: False
### -Depth Specifies how many levels of contained objects are included in the JSON representation. The value
-can be any number from `0` to `[Int]::MaxValue`. The default value is `2`. `ConvertTo-Json` emits a
+can be any number from `1` to `100`. The default value is `2`. `ConvertTo-Json` emits a
warning if the number of levels in an input object exceeds this number. ```yaml
dev-cross-plat Module Authoring Considerations https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/performance/module-authoring-considerations.md
+---
+ Title: PowerShell module authoring considerations
+description: PowerShell module authoring considerations
Last updated : 10/16/2017
+---
+
+# PowerShell module authoring considerations
+
+This document includes some guidelines related to how a module is authored for best performance.
+
+## Module Manifest Authoring
+
+A module manifest that does not use the following guidelines can have a noticeable impact on general
+PowerShell performance even if the module is not used in a session.
+
+Command auto-discovery analyzes each module to determine which commands the module exports and this
+analysis can be expensive. The results of module analysis are cached per user, but the cache isn't
+available on first run, which is a typical scenario with containers. During module analysis, if the
+exported commands can be fully determined from the manifest, more expensive analysis of the module
+can be avoided.
+
+### Guidelines
+
+- In the module manifest, do not use wildcards in the `AliasesToExport`, `CmdletsToExport`, and
+ `FunctionsToExport` entries.
+
+- If the module does not export commands of a particular type, specify this explicitly in the
+ manifest by specifying `@()`. A missing or `$null` entry is equivalent to specifying the wildcard
+ `*`.
+
+The following should be avoided where possible:
+
+```powershell
+@{
+ FunctionsToExport = '*'
+
+ # Also avoid omitting an entry, it is equivalent to using a wildcard
+ # CmdletsToExport = '*'
+ # AliasesToExport = '*'
+}
+```
+
+Instead, use:
+
+```powershell
+@{
+ FunctionsToExport = 'Format-Hex', 'Format-Octal'
+ CmdletsToExport = @() # Specify an empty array, not $null
+ AliasesToExport = @() # Also ensure all three entries are present
+}
+```
+
+## Avoid CDXML
+
+When deciding how to implement your module, there are three primary choices:
+
+- Binary (usually C#)
+- Script (PowerShell)
+- CDXML (an XML file wrapping CIM)
+
+If the speed of loading your module is important, CDXML is roughly an order of magnitude slower than
+a binary module.
+
+A binary module loads the fastest because it is compiled ahead of time and can use NGen to JIT
+compile once per machine.
+
+A script module typically loads a bit more slowly than a binary module because PowerShell must parse
+the script before compiling and executing it.
+
+A CDXML module is typically much slower than a script module because it must first parse an XML file
+which then generates quite a bit of PowerShell script that is then parsed and compiled.
dev-cross-plat Script Authoring Considerations https://github.com/MicrosoftDocs/PowerShell-Docs/commits/staging/reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md
+---
+ Title: PowerShell scripting performance considerations
+description: Scripting for Performance in PowerShell
Last updated : 10/16/2017
+---
+
+# PowerShell scripting performance considerations
+
+PowerShell scripts that leverage .NET directly and avoid the pipeline tend to be faster than
+idiomatic PowerShell. Idiomatic PowerShell typically uses cmdlets and PowerShell functions heavily,
+often leveraging the pipeline, and dropping down into .NET only when necessary.
+
+>[!NOTE]
+> Many of the techniques described here are not idiomatic PowerShell and may reduce the readability
+> of a PowerShell script. Script authors are advised to use idiomatic PowerShell unless performance
+> dictates otherwise.
+
+## Suppressing Output
+
+There are many ways to avoid writing objects to the pipeline:
+
+```powershell
+$null = $arrayList.Add($item)
+[void]$arrayList.Add($item)
+```
+
+Assignment to `$null` or casting to `[void]` are roughly equivalent and should generally be
+preferred where performance matters.
+
+```powershell
+$arrayList.Add($item) > $null
+```
+
+File redirection to `$null` is nearly as good as the previous alternatives, most scripts would never
+notice the difference. Depending on the scenario, file redirection does introduce a little bit of
+overhead though.
+
+```powershell
+$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.
+
+```powershell
+$null = . {
+ $arrayList.Add($item)
+ $arrayList.Add(42)
+}
+```
+
+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.
++
+## Array Addition
+
+Generating a list of items is often done using an array with the addition operator:
+
+```powershell
+$results = @()
+$results += Do-Something
+$results += Do-SomethingElse
+$results
+```
+
+This can be very inefficent because arrays are immutable. Each addition to the array actually
+creates a new array big enough to hold all elements of both the left and right operands, then copies
+the elements of both operands into the new array. For small collections, this overhead may not
+matter. For large collections, this can definitely be an issue.
+
+There are a couple of alternatives. If you don't actually require an array, instead consider using
+an ArrayList:
+
+```powershell
+$results = [System.Collections.ArrayList]::new()
+$results.AddRange((Do-Something))
+$results.AddRange((Do-SomethingElse))
+$results
+```
+
+If you do require an array, you can use your own `ArrayList` and simply call `ArrayList.ToArray`
+when you want the array. Alternatively, you can let PowerShell create the `ArrayList` and `Array`
+for you:
+
+```powershell
+$results = @(
+ Do-Something
+ Do-SomethingElse
+)
+```
+
+In this example, PowerShell creates an `ArrayList` to hold the results written to the pipeline
+inside the array expression. Just before assigning to `$results`, PowerShell converts the
+`ArrayList` to an `object[]`.
+
+## Processing Large Files
+
+The idiomatic way to process a file in PowerShell might look something like:
+
+```powershell
+Get-Content $path | Where-Object { $_.Length -gt 10 }
+```
+
+This can be nearly an order of magnitude slower than using .NET APIs directly:
+
+```powershell
+try
+{
+ $stream = [System.IO.StreamReader]::new($path)
+ while ($line = $stream.ReadLine())
+ {
+ if ($line.Length -gt 10)
+ {
+ $line
+ }
+ }
+}
+finally
+{
+ $stream.Dispose()
+}
+```
+
+## Avoid Write-Host
+
+It is generally considered poor practice to write output directly to the console, but when it makes
+sense, many scripts use `Write-Host`.
+
+If you must write many messages to the console, `Write-Host` can be an order of magnitude slower
+than `[Console]::WriteLine()`. However, be aware that `[Console]::WriteLine()` is only a suitable
+alternative for specific hosts like `pwsh.exe`, `powershell.exe`, or `powershell_ise.exe`. It's not
+guaranteed to work in all hosts.
+
+Instead of using `Write-Host`, consider using
+[Write-Output](/powershell/module/Microsoft.PowerShell.Utility/Write-Output).