How do you create help files when you have multiple functions in a .psm1 file?

PowerShell Help
1

Every script I’ve written so far has had 1 function, and I’ve saved it in a .psm1 file with the exact same name, ran import-module and ran the command.

How do you create help files when you have a bunch of functions?
Are you supposed to separate the files into a bunch of .psm1 or .ps1 files?

Look at this example:

How would you make a help file for each of these? Do you just have one big .psm1 file?

Function Get-Something {
[CmdletBinding()]
param(
[Parameter(Mandatory = $false)]
[string] $UserPrincipalName
)

Write-Output "The Get-Something function was called"

}

Function Set-Something {
[CmdletBinding()]
param(
[Parameter(Mandatory = $false)]
[string] $UserPrincipalName
)

Write-Output "The Set-Something function was called"

}

Function New-Something {
[CmdletBinding()]
param(
[Parameter(Mandatory = $false)]
[string] $UserPrincipalName
)

Write-Output "The New-Something function was called"

}

2

That confuses me. Du you really save every script in a .psm1 file? Why? Why not simply .ps1?

If I want to write a module with more than one function in it I place every single function in a separate .ps1 file with their according names and use in my .psm1 file only this snippet:

Get-ChildItem $psscriptroot\*.ps1 | 
    ForEach-Object { . $_.FullName }

IMHO this way it is easier to maintain than a big .psm1 file with a lot of functions in it. :man_shrugging:t3: And of course I create an according .psd1 file for the module.

I use comment based help …

3

I see

I guess my issue is when I save my scripts as a .ps1 file they don’t ever run, no errors just nothing happens.

They work when they’re .psm1 files - I run import-module then type the function name and all the parameters out, but with a .ps1 file nothing happens

I try running . .\my-script.ps1 -computername “mypc”
Nothing happens

I try running .\my-script.ps1 -computername “mypc”
Nothing happens

i try running my-script.ps1 -computername “mypc” and again nothing happens. I’ve set bypass to the execution policy…

4

You may show one of those scripts. You may have a missconception about how a script works.

If you only have function definitions in your scripts that’s expected. Anyway you could run them “scoped” for your current console session with “dot sourcing”. Then the contained functions exist in your current scope.
Here you can read more about:

Again … when you only have function definitions in your scripts that’s expected. You can add a param block diorectly to a script just like you’d do for a function. Then it will process provided parameters just like a function. :man_shrugging:t3:

5

Ok thank you I will read that link - here is an example. It’s a .psm1 I can import-module and it runs perfectly at the command line with Clear-Drivespace -Computername “mylaptop”

But when I save as a .ps1 and do .\Clear-DriveSpace -ComputerName “mylaptop” nothing happens?

6

And once again … you have a missconception about how scripts work in your head. Remove the first and the last line of code in your script and name it *.ps1. Then you can run it like a function providing parameter values to it. :man_shrugging:t3:

7

Ok I see!

I just don’t understand what the point of functions is then ?

Cause if you have a bunch of .ps1 files, none of them can have functions in them? I just removed the function from that file and renamed to .ps1 and it ran

It’s best practice to do it like this? Just write .ps1 scripts and use a module to import all the .ps1 files?

It’s bad practice to write multiple functions in one .psm1 file?

8

Update: I tried your thing with the Get-ChildItem in the .psm1 file and it works!!!

Is it safe to say this is best practice for modules ?
ModuleName # Folder
ModuleName.psm1 # Module file
ModuleName.psd1 # Manifest file
Function.ps1 # Next .ps1 script
Function2.ps1 # Next .ps1 script
Function3.ps1 # Next .ps1 script

9

:man_shrugging:t3: :man_shrugging:t3: … you use them just like any other cmdlet of PowerShell either interactively in the console or in scripts. :man_shrugging:t3:

It is totally up to you how you use them and what your actual job is.

Great. Now you learned another way how to use PowerShell. :+1:t3:

Again … it is up to you. If that’s the best way for you to make you life easier … great.

No. Not at all. .ps1 files are scripts and .psm1 files are modules and usually contain more than one function.

You may read some more about modules …

… and maybe this blog post …

10

I actually don’t know if it’s best practice. I just know that it makes it easier for me to maintain a module with more than just 2 or 3 functions in it. And I know some people do it this way.

You may read more about best practice for PowerShell here:

And again … at the end of the day it depends on your job and the requirements and maybe your team or your department or your company. Some companies or IT departments have a set of rules you may follow or you create some for yourself if you’re lucky enough to be in such a position. Especially when there are other colleagues working with your code it is nice when you make their work as easy as possible. :wink:

11

Man you are amazing. I really appreciate your input. Thanks for all the pointers!

12

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.