共用方式為

Windows PowerShell

  • 發行項

WTFM：撰寫無懈可擊的手冊

Don Jones

「 RTFM 」 是其中一個最愛的縮略字的 IT 產業 (至少其中的英文說話一部份)。 它拼出以不同方式的不同的人，但為東西像 「 讀取的高度手動 」，和它 ’s 通常以提供一個可能可能有已回答問題更快速的回應且完全如果發問者只需要有閱讀指示通常被接受。 不過，使用 Windows PowerShell，並開始建立指令碼和其他人使用的函式，您並確認有 ’s 實際上一組的指示為他們讀取嗎? 您亦即 書寫 是否在高度手動 (WTFM)?

‘ 沒有註解 ’ 永遠不會是正確的答案

如果有任何與電腦程式設計或指令碼處理經驗侷 ’re 熟悉的內嵌程式碼註解，以協助文件的特定程式碼的函式使用。 Windows PowerShell 自然提供支援的註解：殼層會忽略任何一行開頭是 [允許您將任何您喜歡的註解的 #。

不幸的是，為 讀取 這些註解您必須在 Windows 「 記事本 」 或另一個編輯器中開啟指令碼而且的 ’s 從什麼您可能使用與殼層 ’s 內建說明系統整合的殼層 Cmdlet 的不同的行為。 其中一個基礎概念，Windows PowerShell 中是您應該只需要學習單一組的技能和任何指定的工作 ； 的行為如果已經學會如何使用 Get 說明 指令來取得原生 Cmdlet 為何應該事情使用任何以不同方式的指令碼或函數的說明嗎?

在殼層 v2，事情 don’t 有 以不同方式運作。 Windows PowerShell v2 引入新的表單的文件稱為 *註解為基礎的說明。*基本上，命令介面知道要尋找特殊格式的註解內的指令碼或函式，它會剖析您就會看到以原生指令程式來建構相同類型的說明顯示這些註解。 Cmdlet 說明實際上以 XML 格式撰寫 ； 註解說明不是只更容易地建構手動，但它也跟著沿著任何指令碼或它附加至，使指令碼或函式，獨立且容易散佈的函式。

let’s 設定產生指令碼或函式，可以顯示其說明透過內建 Get 說明 指令，格式完全相同的原生的 Cmdlet 該說明設定成中所示 的 圖 1 的目標。

 

圖 1 說明格式化為原生 Cmdlet 中 Windows PowerShell。

以 WTFM RTFM

Windows PowerShell 包含註解說明的完整內建說明：只要執行 協助 about_comment_based_help 。 基本上，註解說明規則是簡單的：

  • 註解必須在指令碼 (如果說明適用於整個指令碼) 或函式內第一件事，(如果說明特定的函式)。
  • 註解必須使用特定的格式設定和關鍵字，讓殼層 ’s 說明功能可以正確地剖析。

您可以使用任一單行註解前使用 #，每一行，或者您可以使用新的區塊註解。 因為您 don’t 有停在每一行前面的 #，這些是容易輸入。 來鍵入啟動區塊註解 < # 本身，一行上的並結束以 # > 單獨一行上。 這些兩行之間的任何項目會被視為註解的一部分。

說明指示會建構以一系列的區塊。 每個區塊的開頭如.SYNOPSIS 或.DESCRIPTION 的區段關鍵字。 實際的關鍵字的前面是一段，而且在期限必須 excepting 空格或 # 字元列上的第一個字元。 about_comment_based_help 檔案會列出所有可能的關鍵字，但主要的是：

  • .SYNOPSIS –a 簡短說明的指令碼或函式會有什麼效果。
  • .DESCRIPTION – 更詳細的說明的指令碼或函式會有什麼效果。
  • .PARAMETER 名稱 – 特定參數的說明。 名稱 取代為參數名稱。 您可以讓這些區段中的每個參數的其中一個指令碼或函式使用。
  • .EXAMPLE – 如何使用指令碼或函式的範例。 如果您想要提供一個以上的範例，您可以有多個.EXAMPLE 區段。
  • .NOTES – 任何其他的筆記上使用指令碼或函式。
  • .LINK – 交互參照到另一個說明主題，您可以有一個以上的這些。 如果您包含起始與 http:// 或 https:// URL，殼層就會開啟該 URL， 說明 命令 ’s –online 參數使用時。

每個關鍵字就會執行一條線本身和後面跟著一個或多行文字。 以下為範例：

<#.SYNOPSISRetrieves service pack and operating system information from one or more remote computers..DESCRIPTIONThe 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 pathThe 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..EXAMPLERead computer names from Active Directory and retrieve their inventory information.Get-ADComputer –filter * | Select{Name="computerName";Expression={$_.Name}} | Get-Inventory.EXAMPLERead computer names from a file (one name per line) and retrieve their inventory informationGet-Content c:\names.txt | Get-Inventory.NOTESYou 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 Helpinstructions 內 函式。

說明 命令會繼續依照哪一個部分來顯示說明其一般規則。 比方就例如看到只.EXAMPLE 區段如果您使用 –example 參數，而如果您使用 –full 參數您看到所有的區段。  在任何情況下您看到 (如同在 圖 3 ) 這個函式 ’s 說明看起來與原生 Cmdlet ’s 相同。

 

圖 3 A 函式 ’s 說明，看起來像是 一個原生指令程式。

註解說明的最佳作法

我要含入至少一個.SYNOPSIS 與.DESCRIPTION] 區段中每個指令碼] 或 [我所撰寫的函式內。 如果指令碼或函式會使用一或多個參數，我的文件那些具.PARAMETER 區段。 這樣一來稍後進入，且需要使用指令碼或函式的人可以輕易地找出它的功用。 heck，該事務的六個月我可能忘了我寫的了，以及 我 ’ll 需要快速複習 — 它 handily 提供註解幫助。

更結構化且可重複使用您的程式碼、 更詳細應該是您的協助。 比方說我當作函 「 進階式，」 表示其外觀和運作方式幾乎像原生指令程式化我 Get 物品欄範例函式。 ’s 殼層 ’s 世界的生活的最高的形式，讓我應該提供相同的層級的詳細說明 「 真實 」 的指令程式 — 包括記載範例]、 [備忘稿]、 [交互參照]、 [輸入] 及 [輸出，等等。

越來越多的協力廠商公用程式開始依賴 「 幫助。 比方說協力廠商的整合式指令碼環境通常會剖析協助以提供類似 IntelliSense 的程式碼提示和-完成功能他們編輯環境內 ； 藉由包含正確格式化並完成註解為基礎的說明，啟用指令碼和函式，以更輕鬆地在中使用那些第三方廠商工具。

加號，它只是看起來酷有指令碼和函式就像是 「 真實 」 Cmdlet 盡可能的外觀該 — 包括 slick 尋找說明輸出。

相關的內容