Get-Help 対応 .ps1 の書き方

PowerShell では、Get-Help でコマンドレットの使い方を表示させることができます。

PS C:\> Get-Help Get-Item

名前
    Get-Item

構文
    Get-Item [-Path]   []

    Get-Item  []


エイリアス
    gi


注釈
    Get-Help を実行しましたが、このコンピューターにこのコマンドレットのヘルプ ファイルは見つかりませんでした。ヘルプの
    一部だけが表示されています。
        -- このコマンドレットを含むモジュールのヘルプ ファイルをダウンロードしてインストールするには、Update-Help を使
    用してください。
        -- このコマンドレットのヘルプ トピックをオンラインで確認するには、「Get-Help Get-Item -Online」と入力するか、
           http://go.microsoft.com/fwlink/?LinkID=113319 を参照してください。

この仕様は、コマンドレットで馴染み深いのですが、.ps1 でも使うことができます。

about_Comment_Based_Help
https://technet.microsoft.com/ja-jp/library/hh847834.aspx

ここにあるように、.ps1 の先頭にヘルプを書きます。

構文

<#
.ヘルプキーワード
ヘルプコメント
#>

ヘルプキーワード	意味	備考
SYNOPSIS	概要
DESCRIPTION	説明
EXAMPLE	例	複数記述可能
PARAMETER	パラメーター	複数記述可能
LINK	関連するリンク

こんな感じで書きます。

<#
.SYNOPSIS
ここに概要を書きます

.DESCRIPTION
ここに説明を書きます

.EXAMPLE
ここに具体的な引数の例と解説を書きます(複数記述可)

.EXAMPLE
ここに具体的な引数の例と解説を書きます(複数記述可)

.PARAMETER 引数名
ここら引数の説明を書きます(複数記述可)

.PARAMETER 引数名
ここら引数の説明を書きます(複数記述可)

PARAMETER には CommonParameters について説明が勝手に追加されるので
「<CommonParameters> はサポートしていません」と書いておくと良いかもしれません。

.LINK
関連するリンクの URL を書きます
http://www.vwnet.jp/Windows/PowerShell/SupportGetHelp.htm
#>

自動生成されるヘルプ項目

名前	スクリプト名から生成される
注釈	スクリプト名と合成される
構文	param 定義から生成される

サンプル

<#
.SYNOPSIS
概要
ハイブリット暗号(公開鍵方式暗号+共通鍵暗号)を使用して、安全なファイル交換用の暗号化/復号化をします
公開鍵方式なので、復号パスワードを送る必要はありません

<CommonParameters> はサポートしていません

.DESCRIPTION
・暗号化(-Mode Encrypto)
    受信者の公開鍵を -PublicKeys で指定してファイルを暗号化します
    受信者以外は復号できないので、誤送によるリスクが大幅低減します
    送信者の秘密鍵で電子署名をします

・復号化(-Mode Decrypto)
    自分の秘密鍵を使って復号化します
    復号化する前に、送信者公開鍵を -PublicKeys で指定し電子署名を確認するので、なりすましや改ざんリスクが大幅に低減します

・鍵ペア作成(-Mode CreateKey)
    公開鍵と秘密鍵のセットを作成します
    作成した公開鍵は受信者に渡します
    受信者にも鍵ペアを作成してもらい、受信者の公開鍵も入手します
    公開鍵はキーコンテナを削除しない限り同じ公開鍵が出力されます

・キーコンテナのエクスポート(-Mode Export)
    秘密鍵を格納したキーコンテナをエクスポート(バックアップ)します

・キーコンテナエクスポートテスト(-Mode Test)
    エクスポートファイルがパスワードで復号できるかをテストします

・キーコンテナのインポート(-Mode Import)
    エクスポートファイルからキーコンテナをインポート(リストア)します

.EXAMPLE
PS C:\PSCrypto> .\PSCrypto.ps1 -Mode CreateKey
鍵ペア作成

スクリプトを置いた場所にサブフォルダ(PublicKeys)が作成され、公開鍵(ユーザー名_Publickey.xml)が出力される
-Outfile を指定すると公開鍵のフルパスが指定できる

.EXAMPLE
PS C:\PSCrypto> .\PSCrypto.ps1 -Mode Encrypto -PublicKeys .\PublicKey\UserName_Publickey.xml -Path C:\Data\SecretData.zip
暗号化

元ファイルと同一フォルダーに暗号化ファイル(.enc)が出力される
-Outfile を指定すると暗号化ファイルのフルパスが指定できる

.EXAMPLE
PS C:\PSCrypto> .\PSCrypto.ps1 -Mode Decrypto -PublicKeys .\PublicKey\UserName_Publickey.xml -Path C:\Data\SecretData.enc
復号化

暗号化ファイルと同一フォルダーに元ファイル名で復号化される
-Outfile を指定すると復号化ファイルのフルパスが指定できる

.EXAMPLE
PS C:\PSCrypto> .\PSCrypto.ps1 -Mode Export
エクスポート(バックアップ)

C:\Users\ユーザー名\Documents\PSCryptography\Export\PSCryptoExport.dat が出力される

.EXAMPLE
PS C:\PSCrypto> .\PSCrypto.ps1 -Mode Import
インポート(リストア)

C:\Users\ユーザー名\Documents\PSCryptography\Export\PSCryptoExport.dat からインポートする
エクスポートファイルが存在しない時は、スクリプトと同じフォルダにある PSCryptoExport.dat をセットしてからインポートする

.EXAMPLE
PS C:\PSCrypto> .\PSCrypto.ps1 -Mode Test
テスト

エクスポートしたキーコンテナが復号できるかテストする
C:\Users\ユーザー名\Documents\PSCryptography\Export\PSCryptoExport.dat をテストする
エクスポートファイルが存在しない時は、スクリプトと同じフォルダにある PSCryptoExport.dat をセットしてテストする

.PARAMETER Mode
操作モード
    鍵ペア作成: CreateKey
    暗号化: Encrypto
    復号化: Decrypto
    Export: Export
    Test: Test
    Import: Import

.PARAMETER PublicKeys
公開鍵
    複数指定する場合はカンマで区切る

.PARAMETER Path
暗号/復号するファイル

.PARAMETER Outfile
出力ファイル(省略可)

<CommonParameters> はサポートしていません

.LINK
http://www.vwnet.jp/Windows/PowerShell/PublicKeyCrypto.htm
#>

#################################################################################

param(
    [ValidateSet("Decrypto", "Encrypto", "CreateKey", "Export", "Test", "Import")]
    [string]$Mode,      # モード
    [string[]]$PublicKeys,  # 公開鍵
    [string]$Path,          # 入力ファイル名
    [string]$Outfile        # 出力ファイル名
    )

ヘルプを表示させたい場合は、Get-Help で自分自身を呼ぶようにしておけば OK です。

$ScriptFullName = $MyInvocation.MyCommand.Path
Get-Help $ScriptFullName

ヘルプを埋め込んだスクリプトを公開していますので、こちらからスクリプトをダウンロードして書き方を見るのもいいかもしれませんね。

PowerShell で公開鍵方式暗号ファイルを交換をする
http://www.vwnet.jp/Windows/PowerShell/PublicKeyCrypto.htm

Get-Help 対応 .ps1 の書き方

関連情報