How to document your Powershell Scripts

Andres Bohren

2011-06-16

Hallo zusammen,

Fügt man einem Powershell Script den PARAM Bloch hinzu, so kann man die Parameter mit den Tabs auswählen und mit help [scriptfile.ps1] wird die Synthax ausgegeben.

PARAM
(
[string]$Domain = "test.com",
[string]$Email = "@test.com"
)

Fügt man noch die folgenden Zeilen hinzu, so hat man eine vollständige Online Dokumentation.

<#
.SYNOPSIS
    A summary of what this script does
    Appears in all basic, -detailed, -full, -examples
.DESCRIPTION
    A more in depth description of the script
    Should give script developer more things to talk about
    Becomes: "DETAILED DESCRIPTION"
    Appears in basic, -full and -detailed
.NOTES
    Additional Notes, eg
    File Name : Get-AutoHelp.ps1
    Author     : Thomas Lee - tfl@psp.co.uk
    Appears in -full
.LINK
    A hyper link, eg
    http://www.pshscripts.blogspot.com
    Becomes: "RELATED LINKS"
    Appears in basic and -Full
.EXAMPLE
    The first example - just text documentation
    You should provide a way of calling the script, plus expected output
    Appears in -detailed and -full
.COMPONENT
   Not sure how to specify or use
   Does not appear in basic, -full, or -detailed
   Should appear in -component
.ROLE
   Not sure How to specify or use
   Does not appear in basic, -full, or -detailed
   Should appear with -role
.FUNCTIONALITY
   Not sure How to specify or use
   Does not appear in basic, -full, or -detailed
   Should appear with -functionality
.PARAMETER foo
   The .Parameter area in the script is used to derive the contents of the PARAMETERS in Get-Help output which
   documents the parameters in the param block. The section takes a value (in this case foo,
   the name of the first actual parameter), and only appears if there is parameter of that name in the
   params block. Having a section for a parameter that does not exist generate no extra output of this section
   Appears in -det, -full (with more info than in -det) and -Parameter (need to specify the parameter name)
.PARAMETER bar
   Example of a parameter definition for a parameter that does not exist.
   Does not appear at all.
#>

Hier also eine Vorlage für ein Powershell Script

###############################################################################
# Vorlage für Powershell Scripts
# Version 1.0 / 15.06.2011
# Andres Bohren / www.icewolf.ch / blog.icewolf.ch / info@icewolf.ch
###############################################################################

###############################################################################
#Script Input Parameters
###############################################################################
PARAM
(
[string]$Domain = "test.com",
[string]$Email = "@test.com"
)

###############################################################################
# Function YX
###############################################################################
Function Get-XY {
PARAM (
[string]$myDomain,
[string]$myEmail
)

write-host $mydomain, $myEmail
}

###############################################################################
# Start Script
###############################################################################
Get-XY ($Domain, $Email)

Grüsse

Andres Bohren