{"id":546,"date":"2021-11-05T10:52:22","date_gmt":"2021-11-05T17:52:22","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/powershell-community\/?p=546"},"modified":"2021-11-05T10:52:22","modified_gmt":"2021-11-05T17:52:22","slug":"how-to-use-formatenumerationlimit","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell-community\/how-to-use-formatenumerationlimit\/","title":{"rendered":"How to Use $FormatEnumerationLimit"},"content":{"rendered":"

Q:<\/strong> When I format an object where a property contains more than 4 objects, I never see the extra property values. How can I fix that?<\/p>\n

A:<\/strong> Use the $FormatEnumerationLimit<\/code> variable.<\/p>\n

This query is one I hear in many PowerShell support forums, and I have encountered this issue a lot over the years. What happens is that you issue a command to return objects, for example Get-Process<\/code>. The Get-*<\/code> cmdlets return objects which can contain properties that are arrays of values, not just a single value. When you pipe those objects to Format-Table<\/code>, by default, PowerShell only shows you the first four.<\/p>\n

Let me illustrate what this looks like (by default):<\/p>\n

PS> Get-Process -Name pwsh | Format-Table -Property ProcessName, Modules  \n\nProcessName Modules  \n----------- -------  \npwsh        {System.Diagnostics.ProcessModule (pwsh.exe), \n             System.Diagnostics.ProcessModule (ntdll.dll),\n             System.Diagnostics.ProcessModule (KERNEL32.DLL), \n             System.Diagnostics.ProcessModule (KERNELBASE.dll)\u2026}<\/code><\/pre>\n
This output shows PowerShell getting the process object for Pwsh.exe<\/code> and then passing it to Format-Table<\/code>, which outputs the process name and the modules used by that process. However, as you can see, PowerShell shows only four modules shown followed by “\u2026” (also known as an ellipsis). The ellipsis tells you that there are more values in this property, except PowerShell does not show them.<\/p>\n
If you know the Format-Table<\/code> command, you might be tempted to use the -Wrap<\/code> or the -AutoSize<\/code> parameters, but these would not help. It turns out there is no parameter for Format-Table<\/code> or Format-List<\/code> to control this. The trick is to use the $FormatEnumerationLimit<\/code> variable and assign it a higher value.<\/p>\n
The $FormatEnumerationLimit<\/code> preference variable tells PowerShell and the formatting cmdlets how many occurrences to include in the formatted output. By default, PowerShell sets this variable to four at startup. And that is why you see just four processes in output (by default).<\/p>\n
With PowerShell, you can adjust this limit in a script or a profile file. When you change the value, PowerShell outputs more occurrences, up to the limit you set in $FormatEnumerationLimit<\/code>. Like this:<\/p>\n
PS > $FormatEnumerationLimit = 8\nPS > Get-Process -Name PWSH | Format-Table -Property ProcessName, Modules\n\nProcessName Modules\n----------- -------\npwsh        {System.Diagnostics.ProcessModule (pwsh.exe), \n             System.Diagnostics.ProcessModule (ntdll.dll),\n             System.Diagnostics.ProcessModule (KERNEL32.DLL),\n             System.Diagnostics.ProcessModule (KERNELBASE.dll),\n             System.Diagnostics.ProcessModule (apphelp.dll),\n             System.Diagnostics.ProcessModule (USER32.dll),\n             System.Diagnostics.ProcessModule (win32u.dll),\n             System.Diagnostics.ProcessModule (GDI32.dll)\u2026}   <\/code><\/pre>\n
In the above output, you can see output for eight modules. In writing this, there are actually 239 actual modules for the PowerShell process. If you need to see all the modules, you could set $FormatEnumerationLimit<\/code> to a larger number (e.g. 999) in the shell. Alternatively, if you set $FormatEnumerationLimit<\/code> to -1, PowerShell displays all occurrences, which may be more than you want in most cases! I set the limit to 99 in my profile file and that is usually more than sufficient.<\/p>\n
Scoping of $FormatEnumerationLimit<\/h2>\n
One interesting thing I found is that $FormatEnumerationLimit<\/code> is scoped differently to my expectations. If you use a format command within a function or script (a child of the global scope), the command only uses the value from the global scope.<\/p>\n
The following code contains a function to illustrate the issue:<\/p>\n
function Test-FormatLimitLocal\n{\n  # Change format enum limit\n  \"In Function, limit is: [$FormatEnumerationLimit]\"\n  $FormatEnumerationLimit = 1\n  \"After changing: [$FormatEnumerationLimit]\"\n  Get-Process | Select-Object -Property Name, Threads -First 4\n}<\/code><\/pre>\n
You might think that this code would display the first thread in each of the first four processes. You might, but you would be wrong, as you can see here:<\/p>\n
PS> # Here show the value and call the functin\nPS> \"Before calling: [$FormatEnumerationLimit]\"\nBefore calling: [4]\nPS> Test-FormatLimitLocal\nIn Function, limit is: [4]\nAfter changing: [1]\n\nName                    Threads\n----                    -------\nAggregatorHost          {5240}\nApplicationFrameHost    {16968, 2848}\nAppVShNotify            {9164}\nAtom.SDK.WindowsService {4064, 4908, 4912, 19144\u2026}<\/code><\/pre>\n
As you can see from this output, the final process shows FOUR threads not ONE. This is because PowerShell seems to only use the globally scoped value, not the locally scoped copy. To get around this curious scoping, you can re-write the function like this:<\/p>\n
\nfunction Test-FormatLimitGlobal\n{\n  # Change format enum limit Globally\n  $Old = $Global:FormatEnumerationLimit\n  $Global:FormatEnumerationLimit = 1\n  \"After changing: [$Global:FormatEnumerationLimit]\"\n  Get-Process | Select-Object -Property Name, Threads -First 4\n  # Change it back\n  $Global:FormatEnumerationLimit = $Old\n}<\/code><\/pre>\n
When you call the updated function, it now operates more as you might wish, like this:<\/p>\n
PS> # View the value\nPS> \"Before calling: [$FormatEnumerationLimit]\"\nBefore calling: [4]#\nPS> # Now call the updated function\nPS> Test-FormatLimitGlobal\nAfter changing: [1]\n\nName                    Threads\n----                    -------\nAggregatorHost          {5240}\nApplicationFrameHost    {16968\u2026}\nAppVShNotify            {9164}\nAtom.SDK.WindowsService {4064\u2026}<\/code><\/pre>\n
So, with some careful updating of the global variable, you can get the desired result. In general, I teach my students to avoid manipulating global variables from within a script or a function (unless you know what you are doing). If you need to make changes to any global variable to make a function or script do what you want, ensure you know how to revert the variable to its original value.<\/p>\n
I am unclear whether this is a bug or a feature! To that end, I submitted a feature request<\/a> in the PowerShell source repository. Feel free to add your opinion in the comments or upvote it if you want to see it added.<\/p>\n
Summary<\/h2>\n
The $FormatEnumerationLimit<\/code> variable is a neat feature of PowerShell that allows you to see more occurrences when using Format-Table<\/code>. But remember: if you are using this variable in a function or a script, you should be aware of the scoping issue.<\/p>\n
You can read more about $FormatEnumerationLimit<\/code>, and other preference variables in about_Preference_Variables<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Q: When I format an object where a property contains more than 4 objects, I never see the extra property values. How can I fix that? A: Use the $FormatEnumerationLimit variable. This query is one I hear in many PowerShell support forums, and I have encountered this issue a lot over the years. What happens […]<\/p>\n","protected":false},"author":4034,"featured_media":77,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[13],"tags":[57,58],"class_list":["post-546","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-format","tag-formatenumerationlimit-variable"],"acf":[],"blog_post_summary":"
Q: When I format an object where a property contains more than 4 objects, I never see the extra property values. How can I fix that? A: Use the $FormatEnumerationLimit variable. This query is one I hear in many PowerShell support forums, and I have encountered this issue a lot over the years. What happens […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/posts\/546","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/users\/4034"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/comments?post=546"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/posts\/546\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/media\/77"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/media?parent=546"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/categories?post=546"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell-community\/wp-json\/wp\/v2\/tags?post=546"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}