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

1,055 views

Published on

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

Published in: Technology
  • accessibility Books Library allowing access to top content, including thousands of title from favorite author, plus the ability to read or download a huge selection of books for your pc or smartphone within minutes.........ACCESS WEBSITE Over for All Ebooks ..... (Unlimited) ......................................................................................................................... Download FULL PDF EBOOK here { http://bit.ly/2m6jJ5M } .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • ..............ACCESS that WEBSITE Over for All Ebooks ................ ......................................................................................................................... DOWNLOAD FULL PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full EPUB Ebook here { http://bit.ly/2m6jJ5M } .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • accessibility Books Library allowing access to top content, including thousands of title from favorite author, plus the ability to read or download a huge selection of books for your pc or smartphone within minutes DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... ...................................ALL FOR EBOOKS................................................. Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • (Unlimited)....ACCESS WEBSITE Over for All Ebooks ................ accessibility Books Library allowing access to top content, including thousands of title from favorite author, plus the ability to read or download a huge selection of books for your pc or smartphone within minutes ......................................................................................................................... DOWNLOAD FULL PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full PDF EBOOK here { http://bit.ly/2m6jJ5M }
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • accessibility Books Library allowing access to top content, including thousands of title from favorite author, plus the ability to read or download a huge selection of books for your pc or smartphone within minutes DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { http://bit.ly/2m6jJ5M } ......................................................................................................................... Download Full EPUB Ebook here { http://bit.ly/2m6jJ5M } ......................................................................................................................... ...................................ALL FOR EBOOKS................................................. Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

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 ご清聴ありがとうございました。

×