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