We just published a new beta version (18.104.22.168). This beta version was also published to the PowerShell Gallery because it runs stable and is most likely to become the release version soon.
Note: HelpCache was restricted to cmdlet help files and did not work with functions. Many Microsoft modules contain functions, though. So beginning with version 22.214.171.124, function help is now also supported (typically comes in cdhelp.xml files). We also prepopulated the “HelpCache” folder with help for all typical Server 2012 R2 modules so you should get a great out-of-the-box help experience with 126.96.36.199.
Thanks for your reports, we fixed all reported issues. Details can be found on the version history page.
The beta also includes a bunch of exciting new features, partially inspired by your feedback:
- HelpCache: install module help without Administrator Privileges
- Vertical Guides with AutoIndent: use vertical guides to keep the caret indented
- Custom User Greeting: change the name used by ISESteroids to greet you when ISESteroids launches
Download the latest version here:
Let me quickly walk you through the new things.
HelpCache – Installing PowerShell Help Without Administrator Privileges
PowerShell help is great, and Get-Help provides you with a lot of information. However, PowerShell 3 and better does not come with help files preinstalled. You need to first download them from the Internet, or copy them manually to your module folders. Only then will you benefit from great documentation and lots of code samples.
This is a great concept – but is not available to everyone. Help files are stored inside PowerShell modules, and most PowerShell modules are stored in locations where regular users have no write permissions. So to update PowerShell help, you need Administrator privileges which you simply may not have. Unless an Administrator updates help for you, you won’t get it. In addition, you may work at a customers site, and you may not be allowed to change their machines.
ISESteroids introduces the concept of “HelpCache” to overcome these limitations, and provide an “out of the box” experience where full documentation for all of your modules is available.
“HelpCache” is a set of bailout locations where you can store all of your module help files. When you use Get-Help, ISESteroids checks to see if the original help files are present. If so, nothing special occurs, and you continue to use the latest help files you may have updated.
If ISESteroids detects that help files are missing, though, it bails out and searches the “HelpCache” locations to see if the help files are available there. If so, it loads the help files from the “HelpCache” location instead, and you are fine. You dont’t even notice. You simply can use all the great help features provided by Get-Help. Internally, you are using help files from the “HelpCache” location.
Here are the three “HelpCache” locations supported by ISESteroids:
- ISESteroids Module Base Folder\HelpCache (prepopulated with a number of help files from popular Microsoft modules)
- $env:profile\Documents\WindowsPowerShell\HelpCache (always writeable for a user)
- $env:appdata\ISESteroids\HelpCache (always writeable for a user)
There are strong benefits from this:
- “HelpCache” locations are located in places where regular users have write permissions. There are three locations available, and two of them are per user. So a user can privately collect all the help files he or she needs, and use them completely independent of the official module help locations. No special Administrator privileges required, either.
- One “HelpCache” location resides inside the ISESteroids module folder. So you can preload this location with all the help files important to you, and wherever you take ISESteroids, help is available. You do not need to touch the machine you are working with. In fact, ISESteroids comes with preloaded help files for the most popular Microsoft PowerShell modules, so you can enjoy comprehensive help immediately without the need to do anything.
ISESteroids loads the missing help files into the PowerShell help system. You can continue to use PowerShell and Get-Help. As a user, you do not even notice “HelpCache”, except that you always have full help available.
Note that “HelpCache” loads help files on demand only. So the memory footprint is no different from the default behavior. Note also that “HelpCache” loads files only if the original help files are missing. So you always get the latest help files if you do update PowerShell help via Update-Help.
“HelpCache” works with MAML-based help files only. These are files that end with “-help.xml”. “HelpCache” is not designed to cache plaintext-based help files such as the “about_…txt” files. It is trivial to make these available so there is no need to integrate them with “HelpCache”: simply create a local module in a location where you have write permission, then copy the plaintext-based help files of your choice to this module.
There is a readme.txt file inside the “HelpCache” subfolder in the ISESteroids module that provides more detailed info:
Limited Help by Default =======================
By default, PowerShell 3 and better does not ship help files. When you use Get-Help, or when you click a command in the ISE editor and press F1, you will see only basic information like command syntax. You miss full documentation and code samples.
Updating PowerShell Help ========================
To enjoy a comprehensive PowerShell help experience, you can download and install the latest help files from the Internet for all of your PowerShell modules.
This requires two things that you may or may not have:
(a) Administrator privileges, and (b) Internet access.
If you are missing either one, skip the next steps and read on. Else, update PowerShell help with these simple steps:
1. Launch a PowerShell console (do not use the ISE editor in PSv3. There is a bug.) with Administrator privileges 2. Run this command: Update-Help -UICulture en-US -Force 3. If you are running PowerShell Version 3 on a non-US system, copy the contents of $pshome\en-us to the subfolder with your locale id (i.e. $pshome\de-de for German systems). This is not necessary when using PowerShell version 4 or better.
Using HelpCache Locations Instead =================================
If you cannot update your help files because of missing Administrator privileges, ISESteorids provides three alternative locations to store help files.
(a) ISESteroids Module Base Folder\HelpCache (THIS folder, prepopulated with a number of help files from popular Microsoft modules) (b) $env:profile\Documents\WindowsPowerShell\HelpCache (always writeable for a user) (c) $env:appdata\ISESteroids\HelpCache (always writeable for a user)
If ISESteroids detects that a help file is missing at the default location, it automatically looks up the help file in these three folders (if they exist):
Scope of HelpCache ==================
HelpCache is designed as a caching mechanism for for MAML-based help files. MAML-based help files typically contain help for cmdlets and functions. The file name looks like "Modulename-help.xml", and such help files can be found either in the root folder of modules, or in localized subfolders named "en-US", "de-de", etc.
HelpCache does not support plaintext-based help files (about_...txt files).
If you want to cache plaintext-based help files, simply copy these files to any module stored in a location where you have write access, i.e. $env:profile\Documents\WindowsPowerShell\[ModuleName]. You may want to create a dummy module simply for this purpose.
Vertical Guides With AutoIndent
When you press CTRL+SHIFT+G, you can add a temporary vertical guide to the editor column where your caret is in. These vertical guides are great to keep track of indentation across a long multipage script. Press CTRL+SHIFT+G again to toggle or set the guide to a different column.
Thanks to your suggestions, this vertical guide becomes even smarter. While the vertical guide is present, ISESteroids uses it as an indentation guide, too. So when you enter code on the right side of the guide and press ENTER, the caret will not move all the way back to the beginning of the next line, but instead to the column with the guide.
On popular request, ISESteroids now includes a way for you to adjust the personal greeting that appears on launch. The name is taken from your license by default, but if your boss ordered the license, or you would like to change your salutation for other reasons, you now can do that.
Simply place a text file “username.txt” into the root of the ISESteroids module folder, or into $env:appdata\ISESteroids for multiuser scenarios. In the file, enter the name you’d like to use instead.
Call to Action
For now, we’d ask you to test-drive this beta, check out the new HelpCache mechanism, and let us know what you think.
Please help us and check whether ISESteroids shuts down cleanly. When you close ISESteroids, open a PowerShell console and look for any lingering ISE processes, for example like this:
Should you come across scenarios where ISE does not completely shut down, please let us know.
And continue to provide feedback! As you see, we take your feedback serious and respond quickly, adding your feature requests asap. Should you have submitted a feature request that has not yet been implemented, rest assured it is on our roadmap.
When a particular feature request is implemented depends on a number of factors. If the feature request fits into an area that is currently worked on then it is frequently implemented in a matter of days. Other requests may take longer.