Over the last few weeks I've posted articles on the different parameter validation options in Windows PowerShell. More than one person suggested consolidating the articles. That seemed like a good idea. There were a variety of ways to handle this but I wanted something more PowerShell-oriented. Then I realized, why not produce PowerShell About topics? I could create a module that primarily was a collection of about topics on scripting in PowerShell. Import the module and you get the documentation.
ManageEngine ADManager Plus - Download Free Trial
Exclusive offer on ADManager Plus for US and UK regions. Claim now!
In fact, this is a slick idea you might want to take advantage of: create a PowerShell module with nothing but documentation delivered via About_* files. If you are spending a lot of time in the shell, stay there! But before I get sidetracked, let's look at the module I'm calling ScriptingHelp.
As I said the module is mostly a collection of About_* topics based on some of my blog articles. Then I realized I wanted to make it easier to expose them so I threw together a brief function called Get-ScriptingHelp.
The About topics are edited and revised versions of material previously posted on my blog.
I plan on contributing additional content over time based on previous blog articles, suggestions or anything that comes to mind that I think can help you write more effective PowerShell scripts and functions.
To that end, I have also included a function to help you start scripting even faster. It is a new function wizard called Invoke-FunctionWizard. When you run the wizard, you will be prompted for information about your new function such as its name and parameter information. The wizard will then write a string object with the skeletal outline of your new function, complete with comment-based help. If you run the wizard in the ISE it will automatically insert the text into the currently open file.
But perhaps you'd like to see all of this in action.
I hope you'll let me know what you think and if you find this useful or worthy of continued development. You can download a zip file of ScriptingHelp_0_9. Extract the folder as a subfolder under C:\Users\
I am having some trouble with the Invoke-FunctionWizard. Probably becuase I have never really understood a few things. If I use:
[cmdletBinding()]
Param(
#TODO ADD PARAMETER REQUIREMENTS
[Parameter()]
[string]$Module
)
How do I call the function? and what exactly does [cmdletBinding()] do?
I created a function using you Get-HelpExamples from the other day. I write it out to an HTML file to share with my team. Note: I had to fiddle with it a bit to get it to work for me.
Function Get-Examples($Module) {
.\Get-Examples.ps1 “webadministration”
TODO: COMPLETE THIS EXAMPLE
.NOTES
Name: Get-Examples
Version: 0.1
Author: Samurai\Mike
LastEdit: 5/16/2012
.LINK
TODO: INCLUDE ANY LINKS
.INPUTS
[string]
.OUTPUTS
HTTP
#>
#[cmdletBinding()]
# Param(
# #TODO ADD PARAMETER REQUIREMENTS
# [Parameter()]
# [string]$Module
# )
Begin
{
Write-Verbose -Message “$(Get-Date) Starting $($myinvocation.mycommand)”
} #close Begin
Process
{
$font = “”
$newline = “”
$strFile = “C:\scripts\” + $Module + “.htm”
$oLogFile = New-Item -ItemType file $strFile -Force
$Header = $Module + ” Commands”
$strDate = Get-Date -format g
Add-Content -Path $strFile “$font $Header $strDate $newline”
Get-Command -Module $Module | sort Name | foreach {
$Examples = Get-Help $_ -Examples
$Name = $examples.Name.ToString()
Add-Content -Path $strFile “$font $newline”
Add-Content -Path $strFile “############################# $newline $newline”
Add-Content -Path $strFile “$font`$Name $newline”
$examples.examples.Example | foreach {
$Remarks = $_.Remarks | select -ExpandProperty Text
$Code = $_ | select -ExpandProperty Code
Add-Content -Path $strFile “$font`# $($Remarks)$newline”
Add-Content -Path $strFile “$font $Code $newline”
Add-Content -Path $strFile “$newLine”
}
Write-Host $examples.Name
}
} #close process
End
{
Write-Verbose -Message “$(Get-Date) Ending $($myinvocation.mycommand)”
} #close End
} #end Function
Get-Examples($args)
The Invoke-FunctionWizard creates the outline of advanced function that you have to complete. I made an assumption that you have some idea about what the wizard is asking when it comes to object types, arrays and parameters. Once you create the function in a script file, you need to dot source the script, and make sure your execution policy permits running scripts. If none of that makes sense, then I suggest grabbing a copy of Windows PowerShell 2.0: TFM or Learn PowerShell in a Month of Lunches.
Cmdletbinding tells PowerShell to treat your function as a cmdlet, which gets you extra bells and whistles like automatic support for common parameters and things like -Verbose. You might want to take a look at a Prof. PowerShell column (.) I wrote on this topic.
Jeff, This is the error I’m getting:
PS D:\trond.hindenes\Documents\Scripts\Powershell\PSapt> Get-Module -ListAvailable -Verbose
VERBOSE: Loading module from path
‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\Add-on.ScriptSigning\Add-on.ScriptSigning.psm1’.
VERBOSE: Loading module from path
‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\Add-on.SnippetManager\Add-on.SnippetManager.psm1’.
VERBOSE: Loading module from path ‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\DotNet\DotNet.psm1’.
VERBOSE: Loading module from path
‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\ExcelReporting\ExcelReporting.psm1’.
VERBOSE: Loading module from path ‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\FileSystem\FileSystem.psm1’.
VERBOSE: Loading module from path ‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\IsePack\IsePack.psm1’.
VERBOSE: Loading module from path
‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\MessageOps-Exchange\MessageOps-Exchange-Powershell-Module.dll’.
VERBOSE: Loading module from path
‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\PowerShellPack\PowerShellPack.psm1’.
VERBOSE: Loading module from path ‘D:\trond.hindenes\Documents\WindowsPowerShell\Modules\PowerTab\PowerTab.psm1’.
Get-Module : Cannot process argument because the value of argument “name” is invalid. Change the value of the “name” ar
gument and run the operation again.
At line:1 char:1
+ Get-Module -ListAvailable -Verbose
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidArgument: (:) [Get-Module], PSArgumentException
+ FullyQualifiedErrorId : Argument,Microsoft.PowerShell.Commands.GetModuleCommand
If I just delete the “scriptinghelp” folder from my documents\windowspowershell\modules folder, all is good. Also, I can add the scriptinghelp module without problems using Import-Module ScriptingHelp, it’s just the get-module -listavailable command that’s giving grief. I’ve never seen this error before, maybe you have?
regards,
Trond
You must be doing this in some v3 beta. I think you have already figured this out, although I still don’t know what the exact error is. PowerShell searches for modules in the paths stored in $env:PSModulePath.