Troubleshooting writing help for my PowerShell modules in PowerShell

2
votes

I have an assortment of PowerShell modules written in PowerShell (as opposed to C#) and I include documentation-comments in the code so that users get a full API description from Get-Help.

As I was writing a new module the help text seemed to get stuck at some point in time; any subsequent updates I have done to the help text in that file have not shown up after I saved the file, re-imported the module, or even restarted PowerShell then re-imported the module.

I next created a test module to see if I could replicate the issue. I set up psm1 and psd1 files, imported the module, and ran get-help, seeing the help from the psm1 file. I then added one line of text to the psm1 file, saved it, re-imported it... and the new line appeared in get-help!

I vaguely recall reading some time ago that you must bump the version in the psd1 file for new help to be recognized but my test case showed that is not necessarily needed (and I really don't want to have to bump the version).

I also vaguely recall reading that imported modules are cached somewhere and one could just delete the cached files to get it to recognize the new text--but I cannot recall where to find these.

So my goal is to be able to see the revised help text saved in the psm1 file in my real module without incrementing the module version. Ideas?

2
cachingpowershellmodule

2 Answers

5
votes

I was having similar issues when renaming and updating functions in some of my modules. A bit of searching turned up http://www.powertheshell.com/how-module-command-discovery-works-in-psv3/. In particular, the last bit about outdated caches mentions

PS> Get-Module -ListAvailable -Refresh

Running that solved my caching woes

PS> Get-Help Get-Module -Parameter Refresh

-Refresh [<SwitchParameter>]
    Refreshes the cache of installed commands. The command cache is created when the session starts. It enables
    the Get-Command cmdlet to get commands from modules that are not imported into the session.

    This parameter is designed for development and testing scenarios in which the contents of modules have
    changed since the session started.

    When the Refresh parameter is used in a command, the ListAvailable parameter is required.
2
votes

If you import a module that was already imported, it won't replace the functions that were previously imported. You need to remove the module first with Remove-Module, then import it again. I find it convenient to have this function in my profile:

function reload {
  param(
    [parameter(Mandatory=$true)]$Module
  )
  Write-Host;
  try {
    Remove-Module $Module -ea Stop;
  } catch {
    Write-Warning $error[0].Exception.Message;
    Write-Host;
  } finally {
    Import-Module $Module -Verbose;
  }
  Write-Host;
}