Use Regions in PowerShell ISE


Summary: Microsoft Scripting Guy, Ed Wilson, talks about using regions in the Windows PowerShell ISE.

Hey, Scripting Guy! Question Hey, Scripting Guy! I like using the Windows PowerShell ISE. The price is right I guess. There is one thing that kind of bugs me, however.  When I am writing a long script, there is too much scrolling, and things seem to slow down. I wish there was a way that I did not have to deal with lines and lines of script. I guess I can move the functions into a module, but that adds more complexity than I want in my life right now. Is there something that can help?

—RR

Hey, Scripting Guy! Answer Hello RR,

Microsoft Scripting Guy, Ed Wilson, is here. One of the features added to the Windows PowerShell ISE in Windows PowerShell 3.0 was the region feature. It permits me to mark sections of the script that will collapse or expand as I wish—depending on whether I turn on or turn off outlining mode. I can do this by selecting Show Outlining (Regions) from the View menu. But dude, that requires using a mouse. I prefer to use Windows PowerShell to control the Windows PowerShell ISE.

I can create a region in the Windows PowerShell ISE by doing two things. The first is to use the pound sign, the region keyword, and a description of the region. The second is to end the region section by using a pound sign and the endregion (all one word) keyword. This is shown here:

#region begin regiiin

#endregion

That is all there is to it. Begin and end the region. The following image shows s script with three regions marked in it:

Image of command output

The thing that is a bit confusing is that the #region and #endregion look like comments in the code. To collapse a region, I click the minus sign ( ) that appears beside the #region command:

Image of command output

When the region collapses, the minus sign changes to a plus sign ( + ). This change indicates that the region is collapsed, and that there is more code hidden in the region.

Note  It is important for readability of code that the region names make sense and describe what the region contains. This permits you to quickly find the code required.

I can quickly collapse or expand all regions by using the ToggleOutliningExpansion() method. This method is available from the Editor object of the current file. The command is shown here:

$psISE.CurrentFile.Editor.ToggleOutliningExpansion()

When I toggle all of the closed regions, the script still runs. In fact, toggling or expanding a region in a script has no effect on run ability—only on readability. The following image shows the command I used to collapse all of the regions. It also shows that when I run the script, the commands still execute.

Image of command output

Play around with regions. They should become a best practice added to your script repository. They make code easier to read, and therefore, easier to troubleshoot when the time comes. And for such a slight amount of work, it can pay great dividends.

RR, that is all there is to using regions in your Windows PowerShell ISE.  Join me tomorrow when I will talk about more cool stuff.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Comments (7)

  1. Tore Melberg says:

    As a sidenote, this command is Case sensitive, so [tag:Region] didnt work to well 😉

  2. Chris J Warwick says:

    I see that @Tore beat me to a comment about case sensitivity for #requires. This doesn’t fit well with the general approach in PowerShell of ignoring case for language elements.

    If you’d like to be able to use [tag:Region] and [tag:EndRegion] as nature intended you can vote for the suggestion here:
    https://connect.microsoft.com/PowerShell/Feedback/Details/743272

  3. Ed Wilson says:

    @Tore @Chris thanks for pointing this out.

  4. JonWalz says:

    You can use Ctrl+M to quickly collapse or expand in the ISE.

  5. Tim Cerling says:

    Thanks for this post. I had discovered the [tag:region] command by reading other’s scripts (enjoyable pastime), but I would manually toggle expansion back and forth. The CTRL+M is really handy.
    What is also nice is that it automatically expands/contracts anything contained with {}, such as function definitions or script blocks for If statements.
    Now if there were a ‘table of contents’ command within ISE that would create a Table of Contents at the beginning of the script of all the region statements that would allow you to click on an entry and be taken there in the script. Would really speed up navigation
    in large scripts.

  6. Simon Garratt says:

    I think combining collapsing user-defined regions and code blocks was a mistake. I want to be able to collapse all regions without collapsing the code inside or outside of them. It would have been more flexible to have code-collapsing and region-collapsing
    as separate functions.

  7. Any idea what category a “collapsed region” falls under when modifying the Colors and Fonts in Tools>Options? I use a dark theme, and collapsed regions are difficult to see. I’ve clicked all of the Script Pane Tokens, but I don’t see one that matches.

Skip to main content