次の方法で共有

Windows PowerShell

  • [アーティクル]

まずはマニュアルを書く

Don Jones

RTFM は、(少なくとも英語圏の) IT 業界で好意的に使用されている略語の 1 つです。人によって使う単語は異なりますが、一般的に "Read the Fabulous Manual" (まずはマニュアルをお読みなさい) というような意味で受け取られていて、マニュアルを読めばすぐに理解できるような内容の質問に対してよく使用される言葉です。ですが、他のユーザーが使用するスクリプトや関数を Windows PowerShell で作成するとき、ユーザーが参照するためのマニュアルを用意していますか。つまり、"Writing the Fabulous Manual (WTFM)" (まずはマニュアルを書くということ) を実践していますか。

コメントは必ず残す

コンピューターでプログラムやスクリプトを作成したことがあれば、インライン コードのコメントを使用して、コードの特定の部分の機能について説明することには慣れていると思います。Windows PowerShell には、コメントを使用するのに便利な機能が備わっています。# で始まる行は無視されるので、どのような場所にもコメントを残せます。

困ったことに、そのコメントを読むには、メモ帳などのエディターでスクリプト ファイルを開く必要があります。ですが、ユーザーが、組み込みのヘルプ システムと統合されるシェル コマンドレットを使用して、そのような操作を行うことは、おそらくないでしょう。Windows PowerShell の設計概念には、どんなタスクについても、1 種類のスキルや動作を知っていれば十分というものがあります。つまり、Get-Help コマンドレットを使用して組み込みのコマンドレットについての説明を入手する方法を知っていれば、スクリプトや関数についても、それ以外の方法を把握しておく必要はないという考え方です。

Windows PowerShell 2.0 では、それ以外の方法が実際に必要なくなり、"コメント ベースのヘルプ" という、新しいドキュメント化の形式が導入されました。基本的に Windows PowerShell では、スクリプトや関数に含まれる特殊な形式のコメントを探すようになっていて、そのコメントを解析し、組み込みのコマンドレットと同じ形式のヘルプ情報を作成します。コマンドレットのヘルプは、XML 形式で記述されています。これに対してコメント ベースのヘルプは、手動で簡単に作成できるだけでなく、ヘルプを含めたスクリプトや関数に付いて回るので、スクリプトや関数が自己完結型になり配布しやすくなります。

図 1 のように、組み込みの Get-Help コマンドレットでヘルプ情報を表示するスクリプトや関数を作成して、そのヘルプ情報を組み込みのコマンドレットと同じ書式を設定することを目標にしましょう。

 

図 1 Windows PowerShell に組み込まれているコマンドレットと同じように書式設定されたヘルプ情報

マニュアルを書くには、マニュアルを読む

Windows PowerShell には、コメント ベースのヘルプを作成するための包括的なヘルプが用意されています。ヘルプは、help about_comment_based_help というコマンドを実行すると参照できます。基本的に、コメント ベースのヘルプの規則は単純です。

  • コメントは、スクリプト (スクリプト全体にかかわるヘルプの場合) または関数 (特定の関数にのみかかわるヘルプの場合) の先頭に配置する必要があります。
  • Windows PowerShell のヘルプ機能で適切に解析できるように、コメントには特定の書式とキーワードを使用する必要があります。

コメントの形式としては、# という文字で始まる 1 行のコメントも使用できますし、コメント ブロックも新しく使用できるようになりました。いちいち行頭に # を付けなくていいので、入力しやすさは、コメント ブロックに軍配が上がります。コメント ブロックは、<# という文字だけを入力した行で開始し、#> という文字だけを入力した行で終了できます。<# の行と #> の行間にあるものは、すべてコメントと見なされます。

ヘルプは、一連のブロックで作成します。どのブロックも .SYNOPSIS や .DESCRIPTION などのセクション キーワードで始まります。キーワードはピリオドで始まります。空白文字や # 文字を除き、ピリオドは行頭に来る必要があります。about_comment_based_help ファイルには、使用できるキーワードがすべて記載されていますが、主なものは次のとおりです。

  • .SYNOPSIS: スクリプトや関数の役割の概要。
  • .DESCRIPTION: スクリプトや関数の役割の詳細な説明。
  • .PARAMETER <名前>: 特定のパラメーターの説明。<名前> をパラメーター名に置き換えます。スクリプトや関数で使用する各パラメーターにつき、1 つの .PARAMETER セクションを使用できます。
  • .EXAMPLE: スクリプトや関数の使用例。複数の例を提示する場合は、複数の .EXAMPLE セクションを使用できます。
  • .NOTES: スクリプトや関数を使用するにあたってのさまざまな注釈。
  • .LINK: 他のヘルプ トピックとの相互参照。このセクションは複数配置できます。http:// や https:// で始まる URL を含めると、Windows PowerShell では、Help コマンドの -online パラメーターが使用されたときに、指定の URL を開きます。

どの場合も、まずキーワード名を単独で記載し、その後に 1 行以上のテキストが次の行に続きます。次に例を示します。

<#
.SYNOPSIS
Retrieves service pack and operating system information from one or more remote computers.

.DESCRIPTION
The Get-Inventory function uses Windows Management Instrumentation (WMI) toretrieve service pack version, operating system build number, and BIOS serial number from one or more remote computers. 
Computer names or IP addresses are expected as pipeline input, or may bepassed to the –computerName parameter. 
Each computer is contacted sequentially, not in parallel.

.PARAMETER computerNameAccepts 
a single computer name or an array of computer names. You mayalso provide IP addresses.

.PARAMETER path
The path and file name of a text file. Any computers that cannot be reached will be logged to this file. 
This is an optional parameter; if it is notincluded, no log file will be generated.

.EXAMPLE
Read computer names from Active Directory and retrieve their inventory information.
Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.

EXAMPLE 
Read computer names from a file (one name per line) and retrieve their inventory information
Get-Content c:\names.txt | Get-Inventory.

NOTES
You need to run this function as a member of the Domain Admins group; doing so is the only way to ensure you have permission to query WMI from the remote computers.
#>

図 2 に、このコメントが実際の関数でどのように表示されるかを示します。

 

図 2 関数に含めたヘルプ情報

以降も、Help コマンドでは、標準の規則に従ってどのヘルプの部分を表示するか判断します。たとえば、-example パラメーターを使用すると .EXAMPLE セクションのみが表示され、-full パラメーターを使用するとすべてのセクションの情報が表示されます。どのような場合でも、この関数のヘルプ情報は組み込みのコマンドレットのヘルプと同じように表示されます (図 3 参照)。

 

図 3 組み込みのコマンドレットと同じように表示される関数のヘルプ情報

コメント ベースのヘルプのベスト プラクティス

私は、すべてのスクリプトと関数に、最低でも .SYNOPSIS セクションと .DESCRIPTION セクションを含めるようにしています。また、スクリプトや関数で 1 つ以上のパラメーターを使用する場合は、そのパラメーターの情報を .PARAMETER セクションで提供します。このような情報を提供すると、スクリプトや関数を使用する必要があるユーザーが、パラメーターにどんな役割があるか簡単に理解できます。ついでに言うと、6 か月もたてば自分で記述したことでも忘れていると思うので、私がスクリプトと関数について、すぐに思い出せる手掛かりが必要です。そんなときも、コメント ベースのヘルプが役に立ちます。

適切に構造化されていて、何度も使えるコードほど、詳細なヘルプ情報を提供する必要があります。たとえば、私は自作の Get-Inventory 関数を "高度な関数" として構築しています。つまり、組み込みのコマンドレットとほぼ同じように表示され、機能する関数ということです。この "高度な関数" は、Windows PowerShell の世界の最高峰なので、例、注釈、相互参照、入力、出力などに関する情報を含めて、"本物の" コマンドレットと同じレベルの詳細なヘルプを提示する必要があります。

ヘルプを利用するサードパーティ製のユーティリティは増加の一途を辿っています。たとえば、サードパーティ製の統合スクリプト環境では、多くの場合、IntelliSense のようなコードのヒント機能やコード補完機能を編集環境に含めるために、ヘルプ情報を解析します。適切に書式設定された、包括なコメント ベースのヘルプを作成することで、スクリプトや関数がサードパーティ製のツールで簡単に使用できるようになります。

また、洗練されたヘルプの出力など、できる限り "本物の" コマンドレットに似たスクリプトや関数を使用すると、見栄えもよくなります。

関連コンテンツ