Operations Lab.

PowerShell スクリプトのコマンドヘルプの書き方(簡易版)

leave a comment »

PowerShell では Get-Help コマンドレットでコマンドのヘルプを出力できます。自作したスクリプト(モジュール化などはしていない、単純な ps1 スクリプトファイル)であっても、ヘルプ情報を埋め込むことができます。

書き方

ヘルプ トピックの作成方法は、about_Comment_Based_Help に記載されています。

スクリプトファイルの先頭(Requires の直後)に、ブロックコメントで必要な情報を記載します。(ブロックコメントではなく 1 行ずつコメント化しても認識しますが、複数行に渡ることが多いため通常はブロックコメントを使用します。)

記述方法のサンプルは以下の通りです。

<#
    .SYNOPSIS
        Windows Server 2016 RTM の NanoServerImageGenerator を修正し、インターフェース名が ASCII 以外の場合にもアドレスを設定できるようにします。
    
    .DESCRIPTION
        Windows Server 2016 RTM の NanoServerImageGenerator は、インターフェース名が ASCII 文字列以外で表現されることを想定していません。そのため、デフォルトインターフェース名が ASCII 外の環境、例えば "イーサネット" となっている日本語環境では、IP アドレスを正しく設定できません。

        このスクリプトは、NanoServerImageGenerator モジュールを修正し、インターフェース名が ASCII 以外の環境においても、New-NanoServerImage で指定した IP アドレスが正しく設定されるよう、モジュールを修正します。
    
    .PARAMETER Path
        NanoServerImageGenerator モジュールのフォルダーを指定します。指定したフォルダー内のモジュールファイルが直接修正されます。
    
    .INPUTS
        なし。パイプラインからの入力には対応していません。
    
    .OUTPUTS
        System.Int32
        正常終了した場合は 0 を、それ以外の場合は 1 を返します。
    
    .EXAMPLE
        .\Modify-NanoServerImageGenerator.ps1 -Path C:\Temp\NanoServer\NanoServerImageGenerator
        C:\Temp にインストールメディアの NanoServer フォルダーをコピーした場合、NanoServer フォルダー内の NanoServerImageGenerator フォルダーを指定してください。
    
    .NOTES
        This script is only for Windows Server 2016 RTM (10.0.14393).
        This script is tested with Windows Server 2016 Evaluation 10.0.14393.0 JA-JP only.
        Use this at your own risk!
#>

ヘルプ キーワード

ヘルプ キーワードはドット(.)で始まります。

  • .SYNOPSIS
    関数またはスクリプトの簡単な説明。
  • .DESCRIPTION
    関数またはスクリプトの詳細な説明。
  • .PARAMETER <パラメーター名>
    パラメーターの説明。
  • .EXAMPLE
    関数またはスクリプトの使用方法(使用例)。
  • .INPUTS
    入力オブジェクトの .NET Framework 型。
  • .OUTPUTS
    出力オブジェクトの .NET Framework 型。
  • .NOTES
    関数またはスクリプトに関する追加情報。
  • .LINK
    「関連リンク」セクションに表示される内容。

キーワードは他にもありますが、簡単なスクリプトであれば上記以外を使用するシーンは少ないと思います。

スクリプトの説明を、通常のコメントとしてスクリプト内に埋め込むのもよいですが、PowerShell として用意されている方法がありますので、なるべくスクリプトのヘルプ トピックを記述するくせをつけると良さそうです。

広告

Written by kazu

2016/09/29 @ 03:24

コメントを残す

以下に詳細を記入するか、アイコンをクリックしてログインしてください。

WordPress.com ロゴ

WordPress.com アカウントを使ってコメントしています。 ログアウト / 変更 )

Twitter 画像

Twitter アカウントを使ってコメントしています。 ログアウト / 変更 )

Facebook の写真

Facebook アカウントを使ってコメントしています。 ログアウト / 変更 )

Google+ フォト

Google+ アカウントを使ってコメントしています。 ログアウト / 変更 )

%s と連携中

%d人のブロガーが「いいね」をつけました。