Is module auto-loading meant to be reliable?

Question

Environment

I have the following folder structure where I keep powershell modules:

C:
  PsModules
     ...
     util
        util.psm1 (this contains implementation of 'Test-Function')
        util.test.ps1
     ftp
        ftp.psm1
        http.test.ps1
     ... 

There are about 50 folders and modules in c:\PsModules.

I have set environment variable PSModulePath to include c:\PsModules. This seems to meet the conditions for "well-formed modules" described in Microsoft's documentation and this answer.

Symptoms

Sometimes Test-Function is not found automatically when calling it from ISE. In fact, on any given fresh launch of ISE, there are always some (seemlingly unpredictable) modules that are not found automatically. The failure to automatically find Test-Function, for example, looks like this:

PS C:\> Test-Function
Test-Function : The term 'Test-Function' is not recognized as the name 
of a cmdlet, function, script file, or operable program. Check the 
spelling of the name, or if a path was included, verify that the path is 
correct and try again.
...
+ FullyQualifiedErrorId : CommandNotFoundException

At first glance, this seems to indicate that util.psm1 is not "well-formed". If it were not "well-formed", then ListAvailable shouldn't work. But it does work:

c:\> get-module -ListAvailable util
Directory: c:\PsModules\util

ModuleType Version    Name                 ExportedCommands
---------- -------    ----                 ----------------
Script     0.0        util

PS C:\> Test-Function
...
+ FullyQualifiedErrorId : CommandNotFoundException

Furthermore, after calling Get-Command for the module, the commands in the module are available for general use:

c:\> Get-Command -Module util
CommandType     Name                             ModuleName
-----------     ----                             ----------
Function        Test-Function                    util
c:\> Test-Function
Call to Test-Function succeeded!

Questions

1. Is automatic discovery and module auto-loading supposed to be reliable and predictable?

2. How do I troubleshoot why powershell is sometimes doesn't find a command until a call to Get-Command -module?

3. Is it bad practice to rely on powershell to automatically load modules? If so, what is the good practice for automatically loading modules?

Answer 1

I can't speak to whether module auto-loading is intended to be reliable, but I personally do not rely on it in finished code.

If I'm writing a script or module, I always use Import-Module TheModule -ErrorAction Stop, and often use #Requires -Module AciveDirectory,TheModule,SQLPs to ensure that the modules are available.

For interactive use in the PowerShell console or ISE, I do generally rely on auto-loading, but if it fails I just Import-Module manually for the session.

In situations where I always want a specific module loaded for an interactive session, I load it in a profile. To see the various profiles run this (from both ISE and Console):

$profile | Get-Member -MemberType NoteProperty

You can decide where you want to place the code for importing the module based on which user(s) and in which host(s) you want the module to be available.

So far I only do this for posh-git, but it seems like it would fit your use case well.

Answer 2

In case this is helpful to anyone else, I think this may be a problem exclusive to ISE. I could not repro but recently went around with MS on inconsistent ISE workflow behavior and after some effort the issue was closed without a solution, with the official answer being to not use ISE which is not approved for production and instead use the native shell. It was a realistic answer for us, never saw the issues in native shell. I wonder if it's the same on this symptom?

Answer 3

I have found that the FunctionsToExport section in the module manifest cannot be set to *

THIS IS BAD:

# Functions to export from this module, for best performance, do not use 
# wildcards and do not delete the entry, use an empty array if there are no 
# functions to export.
FunctionsToExport = '*'

THIS IS GOOD:

# Functions to export from this module...
FunctionsToExport = 'Test-Function, Test-Function2'