🎓 A1Learner
🔍
0 of 46 lessons completed

PowerShell Module Design

Module design is choosing what a module exports and how its code is organized. Only some functions are shared with callers, and the rest stay inside the module.

The manifest names the public functions

The helper works inside the module. The public function uses it to build its greeting.

Set-Content -Path (Join-Path $PSScriptRoot "NameTools.psm1") -Value 'function Get-Exclaim { param([string]$Text) "$Text!" }
function Get-Greeting { param([string]$Name = "friend") Get-Exclaim -Text "Hello, $Name" }'
New-ModuleManifest -Path (Join-Path $PSScriptRoot "NameTools.psd1") -RootModule "NameTools.psm1" -ModuleVersion "1.0.0" -Author "Ana" -Description "Name helpers." -FunctionsToExport "Get-Greeting"
Import-Module (Join-Path $PSScriptRoot "NameTools.psd1")
Get-Greeting -Name "Ana"

A helper outside the export list is not recognized

The helper is not in the export list. Calling it outside the module fails.

Set-Content -Path (Join-Path $PSScriptRoot "NameTools.psm1") -Value 'function Get-Exclaim { param([string]$Text) "$Text!" }
function Get-Greeting { param([string]$Name = "friend") Get-Exclaim -Text "Hello, $Name" }'
New-ModuleManifest -Path (Join-Path $PSScriptRoot "NameTools.psd1") -RootModule "NameTools.psm1" -ModuleVersion "1.0.0" -Author "Ana" -Description "Name helpers." -FunctionsToExport "Get-Greeting"
Import-Module (Join-Path $PSScriptRoot "NameTools.psd1")
try { Get-Exclaim -Text "Hi" -ErrorAction Stop } catch { "Caught: " + $_.Exception.Message }

One folder holds the code file and the manifest

One folder holds both module files. The listing shows the code file and the manifest file.

Set-Content -Path (Join-Path $PSScriptRoot "NameTools.psm1") -Value 'function Get-Exclaim { param([string]$Text) "$Text!" }
function Get-Greeting { param([string]$Name = "friend") Get-Exclaim -Text "Hello, $Name" }'
New-ModuleManifest -Path (Join-Path $PSScriptRoot "NameTools.psd1") -RootModule "NameTools.psm1" -ModuleVersion "1.0.0" -Author "Ana" -Description "Name helpers." -FunctionsToExport "Get-Greeting"
Get-ChildItem -Path $PSScriptRoot -Filter "NameTools*" -File | Sort-Object Name | Select-Object -ExpandProperty Name

Example

Set-Content -Path (Join-Path $PSScriptRoot "NameTools.psm1") -Value 'function Get-Exclaim { param([string]$Text) "$Text!" }
function Get-Greeting { param([string]$Name = "friend") Get-Exclaim -Text "Hello, $Name" }
function Get-Farewell { param([string]$Name = "friend") Get-Exclaim -Text "Goodbye, $Name" }'
New-ModuleManifest -Path (Join-Path $PSScriptRoot "NameTools.psd1") -RootModule "NameTools.psm1" -ModuleVersion "1.0.0" -Author "Ana" -Description "Name helpers." -FunctionsToExport "Get-Greeting", "Get-Farewell"
Import-Module (Join-Path $PSScriptRoot "NameTools.psd1")
Get-Greeting -Name "Ana"
Get-Farewell -Name "Ana"

Key points

  • Public function: a function listed in FunctionsToExport, so callers can use it.
  • Helper function: a function left out of FunctionsToExport, so only code inside the module uses it.
  • Use FunctionsToExport to name exactly the public functions.
  • Organization: one module folder holds the .psm1 code file and the .psd1 manifest file.
  • One job: each public function does one clear job, so callers can find it fast.

In this example, a name module holds one helper and two public functions. The manifest exports only the two public functions, and both greetings run after import.

Note

a helper name typed outside the module is not recognized, even though the module is loaded.

Try it Yourself

Edit the code, then press Run.

Running is simulated

Exercise

A module file holds Get-Greeting and Get-Exclaim, but FunctionsToExport lists only Get-Greeting. After import, which function can a caller use?