Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Write-Help
コマンドのヘルプの書き方徹底解説
自己紹介
• 大鷲 和紀
• あえとす
• @aetos382
• http://aerie.hatenablog.jp/
• いたって正常なロリコン
• 最近すっかり PowerShell-er
2014-07-12#JPPOSH 3rd
ヘルプを書こう
• PowerShell で最も使われるコマンドは Get-Help(たぶん)
• 自分向けにも書いておいて損はない
• PowerShell コマンドを書く方法は2つ
• スクリプト (*.ps1)
• バイナリ (*.dll...
ヘルプの多言語対応
• 対応するかどうかは人それぞれだけど…
• PowerShellGet で対応の重要性は増しそう
• 対応するなら PSMAML 一択。
• もしくはオンラインヘルプのみ…?
• Get-Help -Online
2014...
Agenda
• 属性ベースのヘルプ
• コメント ベースのヘルプ
• PSMAML によるヘルプ
• オンライン ヘルプ
• 更新可能なヘルプ
• おまけ
2014-07-12#JPPOSH 3rd
属性ベースのヘルプ
簡単に書けるが、やや難あり
2014-07-12#JPPOSH 3rd
ヘルプに使えそうな属性
• Cmdlet 属性
• CmdletBinding 属性
• HelpUri プロパティ
• Parameter 属性
• HelpMessage プロパティ
• HelpMessageBaseName プロパティ
...
Cmdlet 属性/CmdletBinding 属性
• Cmdlet 属性はバイナリ、CmdletBinding 属性はスクリプト
• HelpUri プロパティに指定した URL は Get-Help –Online で使用さ
れる
201...
Parameter 属性
• HelpMessage プロパティ
• メッセージ文字列をそのまま指定
• Get-Help と必須パラメーターのプロンプトで使われる
• HelpMessageBaseName プロパティ
• HelpMessa...
PSDefaultValue 属性
• パラメーターの既定値に関する情報
• Help プロパティが優先、無ければ Value プロパティが使われる
• コメントベースのヘルプが書かれている場合のみ使われる
2014-07-12#JPPOSH ...
属性ベースの特徴
• スクリプトでもバイナリでも使用可能
• 簡単に使える分、機能は少ない
• 必須パラメーターのプロンプトに対応できるのは属性ベースだけ
• (Get-Help は)多言語対応できない
• 優先度は低い
• バイナリで使用する...
コメント ベースのヘルプ
まずはここから
2014-07-12#JPPOSH 3rd
なにはなくとも
• about_Comment_Based_Help
2014-07-12#JPPOSH 3rd
位置に注意
• ヘルプ コメントを書ける位置にはいくつかルールがあります。
• 個人的に推奨する位置は
• 関数のヘルプであれば関数の {} 内の先頭
• スクリプトのヘルプであればスクリプト ファイルの先頭
• ヘルプとコードの間には2行以上...
キーワード (1)
• .SYNOPSIS
• コマンドの概要
• .DESCRIPTION
• コマンドの詳細
• .PARAMETER
• パラメーターの型や解説
• .EXAMPLE
• 例
2014-07-12#JPPOSH 3rd
キーワード (2)
• .INPUTS
• パイプライン入力のデータ型や解説
• .OUTPUTS
• コマンドの出力のデータ型や解説
• .NOTES
• コマンドの補足説明など
• .LINK
• 参照すべきコマンド名や URL
• htt...
キーワード (3)
• .FORWARDHELPTARGETNAME
• 他のコマンドのヘルプに転送するときの転送先
• .FORWARDHELPCATEGORY
• 転送先のカテゴリー
• 同名の転送先がある場合の競合回避用
• .EXTER...
キーワード (4)
• .COMPONENT
• .ROLE
• .FUNCTIONALITY
• 謎
• .REMOTEHELPRUNSPACE
• パス
2014-07-12#JPPOSH 3rd
コメント ベースの特徴
• スクリプト専用
• とっつきやすいので、まずこれから書いてみよう
• 多言語対応できない
2014-07-12#JPPOSH 3rd
PSMAML によるヘルプ
正直めんどくさい
2014-07-12#JPPOSH 3rd
MAML
• Microsoft Assistance Markup Language の略
• XML ベース
• Windows Vista の組み込みヘルプ向けの記法
2014-07-12#JPPOSH 3rd
PSMAML
• MAML のサブセット+PowerShell の独自要素
• スキーマは巨大
• $PSHOMESchemasPSMaml
• Visual Studio で見るといいかも
• DeveloperCommand.xsd
• P...
スクリプトでも PSMAML
• .EXTERNALHELP キーワードを使う
• 他のキーワードは使えない
• 多言語対応が可能
2014-07-12#JPPOSH 3rd
プロバイダーのヘルプ
• Writing Help for Windows PowerShell Providers
• ひどい…
• プロバイダー自体のヘルプ
• Get-Help FileSystem
• ProviderHelp 要素
•...
プロバイダーコマンド?
• PowerShell のコマンドは大きく 2 つに分けられる
• モジュールやスクリプトが提供する普通のコマンド
• Get-Help とか Import-Module とか…
• PSProvider が提供するコ...
ツールを使おう
• PowerShell Cmdlet Help Editor
• https://pscmdlethelpeditor.codeplex.com/
2014-07-12#JPPOSH 3rd
PSMAML の特徴
• スクリプトでもバイナリでも使用可能
• バイナリの場合はこれを使うしかない
• 多言語対応するなら唯一の選択肢
• 正直めんどくさい
• 手書きとかやってらんない
2014-07-12#JPPOSH 3rd
オンライン ヘルプ
GET-HELP -ONLINE
2014-07-12#JPPOSH 3rd
オンラインヘルプ
• Get-Help foo-bar –Online でブラウザーが開く
• ただの HTML
• 1 つのコマンドにつき、1 つの URL
• 多言語対応について、PowerShell は何も面倒を見てはくれない
• コンテ...
コマンドに URL を割り当てる(復習)
• CmdletAttribute.HelpUri プロパティ
• CmdletBindingAttribute.HelpUri プロパティ
• .LINK キーワード
• <maml:navigati...
PSMAML から HTML を作る
• XSLT を使う
• PowerShell Cmdlet Help Editor でも可能
2014-07-12#JPPOSH 3rd
更新可能なヘルプ
意外な需要が…?
2014-07-12#JPPOSH 3rd
#とは
• Update-Help コマンドで、インターネットから最新のヘルプを取って来れる
• モジュールとは独立して、ヘルプだけを更新できる
2014-07-12#JPPOSH 3rd
だけど…
• 要る?
• モジュールの初公開時や、機能追加等の時は、ヘルプも一緒に配布され
る。
• ヘルプだけ更新されるケースは稀では?
• 誤字や表現の修正、サンプルの追加、言語の追加
• そういった場合であっても、モジュールごと公開してし...
というわけで
• 更新可能なヘルプの作り方は今日は割愛
• 後日ブログで採り上げます。
• たぶん。
2014-07-12#JPPOSH 3rd
作り方より使い方
• Save-Help で、モジュールのヘルプを任意の場所に保存できる
• 更新可能なヘルプに対応しているモジュールのみ
• 現在インストールされているものではなく、改めてダウンロードする
• それを書き換えて、再度 Upda...
勝手ヘルプ
• モジュール作者が書かないヘルプを他人が勝手に書くこともできる
• 某 M$ 社が書いてくれない日本語ヘルプとか。
• 技術的には可能だが、著作権とかの問題が厄介かも。
2014-07-12#JPPOSH 3rd
おまけ
重箱の隅
2014-07-12#JPPOSH 3rd
about ヘルプ
• Get-Help about_XXX というヘルプ
• モジュールの概要説明とか、概念の説明とか
• 中身はただのテキストファイル
• オンライン版は Get-Help –Online では表示できない
• ただのテキス...
Undocumented (1)
• $VerboseHelpErrors = $true としておくと、ヘルプに関するエラーを
報告してくれる。
• 便利…?
2014-07-12#JPPOSH 3rd
Undocumented (2)
• PSMAML で
• Component
• Functionality
• Role
• UserDefinedData 要素で定
義
• 階層構造は持てない
2014-07-12#JPPOSH 3rd
Undocumented (3)
• Get-Help の –Category パラメーターに指定できる謎の値
• FAQ
• General
• Glossary
• それぞれ、モジュールのヘルプ ディレクトリに所定の形式で XML ファイル...
参考資料
またの名をリンク集
2014-07-12#JPPOSH 3rd
MSDN と TechNet にだいたい書いてある
• about_Comment_Based_Help
• Writing Help for Windows PowerShell Modules
• Writing Help for Wind...
最後に
これだけは言っておかねば
2014-07-12#JPPOSH 3rd
お願いしますよホント
•Microsoft | Write-Help
•-UICulture ja-JP
•-Verbose
•-Quickly
•-AsSoonAsPossible
•-Force
2014-07-12#JPPOSH 3rd
2014-07-12#JPPOSH 3rd
ご清聴ありがとうございました。
Upcoming SlideShare
Loading in …5
×

Write-Help

846 views

Published on

PowerShell のコマンドのヘルプの書き方

Published in: Technology
  • Be the first to comment

Write-Help

  1. 1. Write-Help コマンドのヘルプの書き方徹底解説
  2. 2. 自己紹介 • 大鷲 和紀 • あえとす • @aetos382 • http://aerie.hatenablog.jp/ • いたって正常なロリコン • 最近すっかり PowerShell-er 2014-07-12#JPPOSH 3rd
  3. 3. ヘルプを書こう • PowerShell で最も使われるコマンドは Get-Help(たぶん) • 自分向けにも書いておいて損はない • PowerShell コマンドを書く方法は2つ • スクリプト (*.ps1) • バイナリ (*.dll) • ヘルプを書く方法は3つ • 属性ベース • コメントベース • スクリプトのみ • PSMAML (XML) • デモ多めでお届けします 2014-07-12#JPPOSH 3rd
  4. 4. ヘルプの多言語対応 • 対応するかどうかは人それぞれだけど… • PowerShellGet で対応の重要性は増しそう • 対応するなら PSMAML 一択。 • もしくはオンラインヘルプのみ…? • Get-Help -Online 2014-07-12#JPPOSH 3rd
  5. 5. Agenda • 属性ベースのヘルプ • コメント ベースのヘルプ • PSMAML によるヘルプ • オンライン ヘルプ • 更新可能なヘルプ • おまけ 2014-07-12#JPPOSH 3rd
  6. 6. 属性ベースのヘルプ 簡単に書けるが、やや難あり 2014-07-12#JPPOSH 3rd
  7. 7. ヘルプに使えそうな属性 • Cmdlet 属性 • CmdletBinding 属性 • HelpUri プロパティ • Parameter 属性 • HelpMessage プロパティ • HelpMessageBaseName プロパティ • HelpMessageResourceId プロパティ • PSDefaultValue 属性 • Value プロパティ • Help プロパティ 2014-07-12#JPPOSH 3rd
  8. 8. Cmdlet 属性/CmdletBinding 属性 • Cmdlet 属性はバイナリ、CmdletBinding 属性はスクリプト • HelpUri プロパティに指定した URL は Get-Help –Online で使用さ れる 2014-07-12#JPPOSH 3rd
  9. 9. Parameter 属性 • HelpMessage プロパティ • メッセージ文字列をそのまま指定 • Get-Help と必須パラメーターのプロンプトで使われる • HelpMessageBaseName プロパティ • HelpMessageResourceId プロパティ • リソース名とリソース ID のペアを指定 • 多言語対応可能 • 必須パラメーターのプロンプトのみ 2014-07-12#JPPOSH 3rd
  10. 10. PSDefaultValue 属性 • パラメーターの既定値に関する情報 • Help プロパティが優先、無ければ Value プロパティが使われる • コメントベースのヘルプが書かれている場合のみ使われる 2014-07-12#JPPOSH 3rd
  11. 11. 属性ベースの特徴 • スクリプトでもバイナリでも使用可能 • 簡単に使える分、機能は少ない • 必須パラメーターのプロンプトに対応できるのは属性ベースだけ • (Get-Help は)多言語対応できない • 優先度は低い • バイナリで使用すると、ヘルプを書き換えるたびにコンパイルが必要 2014-07-12#JPPOSH 3rd
  12. 12. コメント ベースのヘルプ まずはここから 2014-07-12#JPPOSH 3rd
  13. 13. なにはなくとも • about_Comment_Based_Help 2014-07-12#JPPOSH 3rd
  14. 14. 位置に注意 • ヘルプ コメントを書ける位置にはいくつかルールがあります。 • 個人的に推奨する位置は • 関数のヘルプであれば関数の {} 内の先頭 • スクリプトのヘルプであればスクリプト ファイルの先頭 • ヘルプとコードの間には2行以上の空行が必要 2014-07-12#JPPOSH 3rd
  15. 15. キーワード (1) • .SYNOPSIS • コマンドの概要 • .DESCRIPTION • コマンドの詳細 • .PARAMETER • パラメーターの型や解説 • .EXAMPLE • 例 2014-07-12#JPPOSH 3rd
  16. 16. キーワード (2) • .INPUTS • パイプライン入力のデータ型や解説 • .OUTPUTS • コマンドの出力のデータ型や解説 • .NOTES • コマンドの補足説明など • .LINK • 参照すべきコマンド名や URL • http または https で始まる最初の URL はオンライン ヘルプとして扱われる 2014-07-12#JPPOSH 3rd
  17. 17. キーワード (3) • .FORWARDHELPTARGETNAME • 他のコマンドのヘルプに転送するときの転送先 • .FORWARDHELPCATEGORY • 転送先のカテゴリー • 同名の転送先がある場合の競合回避用 • .EXTERNALHELP • PSMAML ヘルプのファイル名 • このキーワードを利用する場合は他のキーワードは利用できない 2014-07-12#JPPOSH 3rd
  18. 18. キーワード (4) • .COMPONENT • .ROLE • .FUNCTIONALITY • 謎 • .REMOTEHELPRUNSPACE • パス 2014-07-12#JPPOSH 3rd
  19. 19. コメント ベースの特徴 • スクリプト専用 • とっつきやすいので、まずこれから書いてみよう • 多言語対応できない 2014-07-12#JPPOSH 3rd
  20. 20. PSMAML によるヘルプ 正直めんどくさい 2014-07-12#JPPOSH 3rd
  21. 21. MAML • Microsoft Assistance Markup Language の略 • XML ベース • Windows Vista の組み込みヘルプ向けの記法 2014-07-12#JPPOSH 3rd
  22. 22. PSMAML • MAML のサブセット+PowerShell の独自要素 • スキーマは巨大 • $PSHOMESchemasPSMaml • Visual Studio で見るといいかも • DeveloperCommand.xsd • ProviderHelp.xsd • 多言語対応するなら唯一の選択肢 2014-07-12#JPPOSH 3rd
  23. 23. スクリプトでも PSMAML • .EXTERNALHELP キーワードを使う • 他のキーワードは使えない • 多言語対応が可能 2014-07-12#JPPOSH 3rd
  24. 24. プロバイダーのヘルプ • Writing Help for Windows PowerShell Providers • ひどい… • プロバイダー自体のヘルプ • Get-Help FileSystem • ProviderHelp 要素 • コマンドとは微妙に違う独自のスキーマ • 名前空間プリフィックスがついていると認識しない… ( ゚Д゚)ハァ? • プロバイダーコマンドのヘルプ 2014-07-12#JPPOSH 3rd
  25. 25. プロバイダーコマンド? • PowerShell のコマンドは大きく 2 つに分けられる • モジュールやスクリプトが提供する普通のコマンド • Get-Help とか Import-Module とか… • PSProvider が提供するコマンド • Get-Item とか Get-Content とか… • 基本的なヘルプは PowerShell が用意しているが、プロバイダーによって、また、パスに よって、カスタマイズすることもできる • Get-Help Get-Item –Path C:Foo • CmdletHelpPath 要素 • ICmdletProviderSupportsHelp インターフェイスを実装 2014-07-12#JPPOSH 3rd
  26. 26. ツールを使おう • PowerShell Cmdlet Help Editor • https://pscmdlethelpeditor.codeplex.com/ 2014-07-12#JPPOSH 3rd
  27. 27. PSMAML の特徴 • スクリプトでもバイナリでも使用可能 • バイナリの場合はこれを使うしかない • 多言語対応するなら唯一の選択肢 • 正直めんどくさい • 手書きとかやってらんない 2014-07-12#JPPOSH 3rd
  28. 28. オンライン ヘルプ GET-HELP -ONLINE 2014-07-12#JPPOSH 3rd
  29. 29. オンラインヘルプ • Get-Help foo-bar –Online でブラウザーが開く • ただの HTML • 1 つのコマンドにつき、1 つの URL • 多言語対応について、PowerShell は何も面倒を見てはくれない • コンテント ネゴシエーション 2014-07-12#JPPOSH 3rd
  30. 30. コマンドに URL を割り当てる(復習) • CmdletAttribute.HelpUri プロパティ • CmdletBindingAttribute.HelpUri プロパティ • .LINK キーワード • <maml:navigationLink> 要素 2014-07-12#JPPOSH 3rd
  31. 31. PSMAML から HTML を作る • XSLT を使う • PowerShell Cmdlet Help Editor でも可能 2014-07-12#JPPOSH 3rd
  32. 32. 更新可能なヘルプ 意外な需要が…? 2014-07-12#JPPOSH 3rd
  33. 33. #とは • Update-Help コマンドで、インターネットから最新のヘルプを取って来れる • モジュールとは独立して、ヘルプだけを更新できる 2014-07-12#JPPOSH 3rd
  34. 34. だけど… • 要る? • モジュールの初公開時や、機能追加等の時は、ヘルプも一緒に配布され る。 • ヘルプだけ更新されるケースは稀では? • 誤字や表現の修正、サンプルの追加、言語の追加 • そういった場合であっても、モジュールごと公開してしまってもいいのでは? • 世はまさに大 PowerShellGet 時代 #まだです • 更新可能なヘルプを作るのは、それなりに面倒くさい 2014-07-12#JPPOSH 3rd
  35. 35. というわけで • 更新可能なヘルプの作り方は今日は割愛 • 後日ブログで採り上げます。 • たぶん。 2014-07-12#JPPOSH 3rd
  36. 36. 作り方より使い方 • Save-Help で、モジュールのヘルプを任意の場所に保存できる • 更新可能なヘルプに対応しているモジュールのみ • 現在インストールされているものではなく、改めてダウンロードする • それを書き換えて、再度 Update-Help で取り込むと… 2014-07-12#JPPOSH 3rd
  37. 37. 勝手ヘルプ • モジュール作者が書かないヘルプを他人が勝手に書くこともできる • 某 M$ 社が書いてくれない日本語ヘルプとか。 • 技術的には可能だが、著作権とかの問題が厄介かも。 2014-07-12#JPPOSH 3rd
  38. 38. おまけ 重箱の隅 2014-07-12#JPPOSH 3rd
  39. 39. about ヘルプ • Get-Help about_XXX というヘルプ • モジュールの概要説明とか、概念の説明とか • 中身はただのテキストファイル • オンライン版は Get-Help –Online では表示できない • ただのテキストファイルなので URL を割り当てる方法がない 2014-07-12#JPPOSH 3rd
  40. 40. Undocumented (1) • $VerboseHelpErrors = $true としておくと、ヘルプに関するエラーを 報告してくれる。 • 便利…? 2014-07-12#JPPOSH 3rd
  41. 41. Undocumented (2) • PSMAML で • Component • Functionality • Role • UserDefinedData 要素で定 義 • 階層構造は持てない 2014-07-12#JPPOSH 3rd
  42. 42. Undocumented (3) • Get-Help の –Category パラメーターに指定できる謎の値 • FAQ • General • Glossary • それぞれ、モジュールのヘルプ ディレクトリに所定の形式で XML ファイルを 作っておくことで参照可能 • 標準で用意されていないので、使い方の指針が不明 • 直接参照するよりは、他のコマンドのヘルプから関連リンクとして参照したほ うがよさそう 2014-07-12#JPPOSH 3rd
  43. 43. 参考資料 またの名をリンク集 2014-07-12#JPPOSH 3rd
  44. 44. MSDN と TechNet にだいたい書いてある • about_Comment_Based_Help • Writing Help for Windows PowerShell Modules • Writing Help for Windows PowerShell Cmdlets • Adding Custom Cmdlet Help for Providers • Provider Cmdlet Help • How to Add a See Also Section to a Provider Help Topic • How to Add Dynamic Parameters to a Provider Help Topic 2014-07-12#JPPOSH 3rd
  45. 45. 最後に これだけは言っておかねば 2014-07-12#JPPOSH 3rd
  46. 46. お願いしますよホント •Microsoft | Write-Help •-UICulture ja-JP •-Verbose •-Quickly •-AsSoonAsPossible •-Force 2014-07-12#JPPOSH 3rd
  47. 47. 2014-07-12#JPPOSH 3rd ご清聴ありがとうございました。

×