{"id":1428,"date":"2009-05-19T05:45:49","date_gmt":"2009-05-19T13:45:49","guid":{"rendered":"http:\/\/www.sapien.com\/blog\/2009\/05\/19\/can-i-get-a-little-help-here\/"},"modified":"2009-05-19T05:45:49","modified_gmt":"2009-05-19T13:45:49","slug":"can-i-get-a-little-help-here","status":"publish","type":"post","link":"https:\/\/dev.sapien.com\/blog\/2009\/05\/19\/can-i-get-a-little-help-here\/","title":{"rendered":"Can I Get a Little Help Here?"},"content":{"rendered":"

One of my favorite features in PowerShell v2.0 is the ability to add help scripts and functions. The help system with cmdlets is terrific. Type help<\/em> and the name of a cmdlet and you get syntax, parameters, a description and examples.  In PowerShell v2 you can get this same functionality for your scripts and functions. The example I want to show you will work with PowerShell v2.0 that ships with WIndows 7 Release Candidate. There have been some changes since PowerShell CTP3 so if you want the absolute latest PowerShell bits you’ll need Windows 7. Here’s what you can look forward to.<\/p>\n

At the beginning of your script or function you can create a special here string comment block with special “headings”. Here’s an example.<\/p>\n

\n
\n
<#<\/span><\/pre>\n
.Synopsis<\/pre>\n
    This does something really cool<\/pre>\n
.Description<\/pre>\n
    Let me explain in<\/span> a little more detail how cool this really is<\/pre>\n
    and why you want to use it.<\/pre>\n
.Parameter Foo<\/pre>\n
    Describe the first parameter<\/pre>\n
.Parameter Bar<\/pre>\n
    Describe the second parameter<\/pre>\n
 <\/pre>\n
.Example<\/pre>\n
    PS C:\\> this -foo goober<\/pre>\n
    <\/pre>\n
    This will do something amazing<\/pre>\n
.Example<\/pre>\n
    PS C:\\> something | this -bar testing | somethingelse<\/pre>\n
    <\/pre>\n
    In this example, objects are piped from something, piped to this which<\/pre>\n
    then pipes to somethingelse.<\/pre>\n
.Inputs<\/pre>\n
    Accepts strings as pipelined input<\/pre>\n
.Outputs<\/pre>\n
    [object]   <\/pre>\n
           <\/pre>\n
.Link<\/pre>\n
   Get-Something<\/pre>\n
   Get-Another<\/pre>\n
   Set-Something<\/pre>\n
      <\/pre>\n
.Notes<\/pre>\n
 NAME:      Do-Something<\/pre>\n
 VERSION:   1.0<\/pre>\n
 AUTHOR:    You<\/pre>\n
 LASTEDIT:  today<\/pre>\n
 <\/pre>\n
 <\/pre>\n
#><\/pre>\n<\/div>\n<\/div>\n
The dotted headings should be self-explanatory. With this information in my script, I can run help .\\myscript.ps1 and get output like this:<\/p>\n
NAME
    C:\\scripts\\posh\\v2Template.ps1 <\/font><\/p>\n
SYNOPSIS
    This does something really cool <\/font><\/p>\n
SYNTAX
    C:\\scripts\\posh\\v2Template.ps1 [-Foo] <String[]> [[-bar] <String>] [<CommonParameters>] <\/font><\/p>\n
DESCRIPTION
    Let me explain in a little more detail how cool this really is
    and why you want to use it. <\/font><\/p>\n
RELATED LINKS
    Get-Something
    Get-Another
    Set-Something <\/font><\/p>\n
REMARKS
    To see the examples, type: “get-help C:\\scripts\\posh\\v2Template.ps1 -examples”.
    For more information, type: “get-help C:\\scripts\\posh\\v2Template.ps1 -detailed”.
    For technical information, type: “get-help C:\\scripts\\posh\\v2Template.ps1 -full”.<\/font> <\/p>\n
 <\/p>\n
How cool is that? Using the -full, -detailed and -examples parameters work as well.<\/p>\n
PS C:\\scripts\\posh> help .\\v2Template.ps1 -ex <\/font><\/p>\n
NAME
    C:\\scripts\\posh\\v2Template.ps1 <\/font><\/p>\n
SYNOPSIS
    This does something really cool <\/font><\/p>\n
    ————————– EXAMPLE 1 ————————– <\/font><\/p>\n
    PS C:\\>this -foo goober <\/font><\/p>\n
    This will do something amazing <\/font><\/p>\n
    ————————– EXAMPLE 2 ————————– <\/font><\/p>\n
    PS C:\\>something | this -bar testing | somethingelse <\/font><\/p>\n
    In this example, objects are piped from something, piped to this which
    then pipes to somethingelse.<\/font> <\/p>\n
 <\/p>\n
The comment block must go at the very beginning of your script. If you have a header or other comments, there must be at least one blank line before the help section.<\/p>\n
\n
\n
   1:<\/span> #requires -version 2.0<\/span><\/pre>\n
   2:<\/span> #you need at least one blank line before the help<\/span><\/pre>\n
   3:<\/span>  <\/pre>\n
   4:<\/span> <#<\/span><\/pre>\n
   5:<\/span> .Synopsis<\/pre>\n
   6:<\/span>     This does something really cool<\/pre>\n
   7:<\/span> .Description<\/pre>\n
   8:<\/span>     Let me explain in<\/span> a little more detail how cool this really is<\/pre>\n
   9:<\/span>     and why you want to use it.<\/pre>\n<\/div>\n<\/div>\n
In Windows 7 take a look at about_Comment_Based_Help to get all the details. <\/p>\n
\n
In the meantime, you can download a sample script here.<\/a><\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
One of my favorite features in PowerShell v2.0 is the ability to add help scripts and functions. The help system with cmdlets is terrific. Type help and the name of a cmdlet and you get syntax, parameters, a description and examples.  In PowerShell v2 you can get this same functionality for your scripts and functions. The example I want to show you will work with PowerShell v2.0 that ships with WIndows 7 Release Candidate. There have been some changes since PowerShell CTP3 so if you want the absolute latest PowerShell bits you’ll need Windows 7. Here’s what you can look forward to.<\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_monsterinsights_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[25],"tags":[282,450,28,57,439],"class_list":["post-1428","post","type-post","status-publish","format-standard","hentry","category-windows-powershell","tag-functions","tag-help","tag-powershell","tag-scripting","tag-windows-7"],"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/1428","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/comments?post=1428"}],"version-history":[{"count":0,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/posts\/1428\/revisions"}],"wp:attachment":[{"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/media?parent=1428"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/categories?post=1428"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dev.sapien.com\/blog\/wp-json\/wp\/v2\/tags?post=1428"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}